Agent 团队配置技术图谱下载模板 ↓
A beginner-to-production field guide

别再把一切
都叫 Agent。

Agent 决策,Skill 复用,Workflow 编排,Hook 把门,Eval 证明。
一份讲清 Claude Code 与 Codex 配置路径、参数和团队案例的可复制教程。

教学抽象:千图网增长产品团队41 个 Starter Kit 文件规范性结论均有官方来源
ONE OPERATING MODEL · SEVEN OBJECTS教学模型 / 非行业标准术语
01 / OWNER

Agent

目标、判断、工具、循环

02 / DELEGATE

Subagent

独立上下文、窄职责、交回

03 / COORDINATE

Agent Team

并发、通信、共享状态

04 / CAPABILITY

Skill

方法、知识、脚本、资产

05 / ORCHESTRATE

Workflow

顺序、并发、Gate、产物

06 / CONTROL

Hooks

事件、校验、阻断、记录

07 / PROVE

Eval

任务、轨迹、评分、回归

01
Common language first

七个对象,一次分清

市场上没有唯一词典,但边界已经相当稳定:责任主体、专业委派、协作系统、可复用能力、预设编排、事件控制、质量评估。

Agent谁负责结果

事实模型 + 指令 + 工具 + 环境反馈循环。它根据状态动态决定下一步。

不是固定 Prompt;所有自动化的统称。 STD-001
Subagent谁完成独立子任务

事实由主 Agent 委派、独立上下文、较窄职责,完成后把结果交回 caller。

不是把主 Prompt 复制五遍。
Agent Team角色如何协作

事实多个 Agent 在并发、交接、通信或共享状态下完成同一目标。

不是多个互不通信的独立输出。 STD-004
Skill如何复用能力

事实`SKILL.md` + 可选 scripts / references / assets;按需加载。

不是角色职位。UI 设计师是 Agent,设计规范才是 Skill。 STD-002
Workflow什么必须按顺序发生

事实输入、步骤、并发、Gate、产物、重试、超时、审批和审计。

不是必然存在的 workflow.yaml。 STD-001
Hooks事件发生时做什么

事实生命周期事件触发的确定性处理器,用于校验、记录、阻断或唤醒。

不是完整安全边界。权限与 sandbox 仍然必要。
Eval / Harness如何运行与证明

事实Agent harness 让模型行动;Eval harness 跑任务、记 trajectory、评分和聚合。

不是一次成功 Demo;也不是一个 Hook。 STD-003
START / 01

先用一个 Agent

任务单一、路径开放、一个责任人即可完成。

ADD / 02

独立专业任务,再加 Subagent

研究、审查、数据、UI 等任务值得隔离上下文。

ADD / 03

可复用知识,写成 Skill

不把同一套设计规范复制到每个角色 Prompt。

FIX / 04

步骤必须重复,写 Workflow

把 Gate、交付物与失败处理显式化。

GUARD / 05

事件必须检查,配置 Hook

确定性检查放事件层,不靠模型“记得”。

SHIP / 06

准备上线,建立 Eval

先定阈值,再运行;持续做回归而非看 Demo。

02
Exact paths, no guessing

路径总表

最容易记错的两件事:Codex 的角色在 `.codex/agents`,Skill 在 `.agents/skills`;两端都没有官方 Eval 目录,`evals/` 是团队约定。

对象
Claude Code
Codex
项目主指令
./CLAUDE.md
./AGENTS.md
个人主指令
~/.claude/CLAUDE.md
~/.codex/AGENTS.md
项目配置
./.claude/settings.json
./.codex/config.toml
项目角色
./.claude/agents/*.md
./.codex/agents/*.toml
个人角色
~/.claude/agents/*.md
~/.codex/agents/*.toml
项目 Skills
./.claude/skills/<name>/SKILL.md
./.agents/skills/<name>/SKILL.md
个人 Skills
~/.claude/skills/<name>/SKILL.md
~/.agents/skills/<name>/SKILL.md
Workflow
./.claude/workflows/*.js 或 Skill
Workflow Skill / codex exec / SDK
Hooks
settings.json / Skill / Agent
hooks.jsonconfig.toml
MCP
./.mcp.json
config.toml [mcp_servers.*]
Eval
自定义 evals/ + claude -p
自定义 evals/ + codex exec
本机 Claude Code 2.1.199 与 Codex CLI 0.133.0 的匿名化配置面验证截图
本机实测信息卡:版本、功能状态与公开路径;敏感配置已隐藏。LOCAL · 2026-07-14
03
Claude Code setup

Claude Code:角色、能力、编排

日常产品团队优先用主 Agent + Subagents + Skills。Agent Teams 只解决需要直接协作的复杂问题;Dynamic Workflows 解决规模化编排。

Agent / Subagent

.claude/agents/*.md · stable

YAML frontmatter 管模型、工具、权限与预加载 Skill;Markdown body 写角色 contract。

Agent Teams

experimental · disabled by default

独立 sessions、shared task list、mailbox、teammate 直接通信。成本与协调复杂度更高。

  .claude/agents/requirement-analyst.md
---
name: requirement-analyst
description: 澄清用户问题、范围、规则和验收。需求模糊时使用。
tools: Read, Grep, Glob
model: sonnet
permissionMode: plan
skills:
  - qt-product-data-analysis
---

你是需求分析师。
输出:事实、假设、用户、范围、路径、规则、验收、风险。
不得把假设写成事实。
参数作用建议
name / description稳定 ID 与委派触发条件description 写“做什么 + 何时用”
tools / disallowedTools工具允许与禁止默认最小权限;外部副作用单独审批
model / effort成本与推理强度只有实验或 SLA 明确时才锁定
permissionMode运行权限分析角色优先 plan / read-oriented
skills启动时预加载 Skill 全文只放角色必需能力,避免 context 膨胀
memory / background / isolation长期记忆、后台与隔离写任务优先独立 worktree 或文件所有权
Anthropic 官方 Subagents 与 Agent Teams 对比图
官方图:Subagent 把结果交回主 Agent;Agent Teams 共享任务列表并可直接通信。ANTHROPIC · CCL-003
!

事实Agent Teams 仍为 experimental。不要为了“像组织架构”就开启;先证明 direct communication 与 shared state 确有必要。

Skill 与 Dynamic Workflow

  .claude/workflows/requirement-to-launch.js
export const meta = {
  name: 'requirement-to-launch',
  description: '把机会编排为需求、设计、原型和上线门禁',
}

const reviews = await pipeline(['需求', 'UI', '运营'], role =>
  agent(`你负责${role}。基于 ${JSON.stringify(args)} 输出事实、风险和验收。`)
)

return agent(`你是增长产品总监。综合并处理冲突:${JSON.stringify(reviews)}`, {
  label: '总监验收', schema: { /* structured output */ }
})

观点参与角色少、需要人工介入时,Workflow Skill + Subagents 更简单;几十到数百个调用、结构化并发与聚合时,再用 Dynamic Workflows。 CCL-005

04
Codex setup

Codex:没有 workflow.yaml

`AGENTS.md` 管主 Agent;`.codex/agents` 管 Subagents;`.agents/skills` 管能力与 Workflow。严格编排再用 `codex exec` / SDK / CI。

主 Agent

AGENTS.md · instruction chain

从 user scope 与 Git root 到 CWD 逐层加载;越靠近当前目录,优先级越高。

Subagents

.codex/agents/*.toml · stable

内置 default / worker / explorer;自定义角色定义职责、sandbox、模型、MCP 与 Skills。

  .codex/agents/requirement-analyst.toml
name = "requirement_analyst"
description = "把模糊问题转成目标、用户、范围、路径、规则和验收。"
sandbox_mode = "read-only"
nickname_candidates = ["Scope", "Path", "Spec"]

developer_instructions = """
只做需求澄清与证据整理。
缺少目标用户或成功指标时,返回 action_required,不猜测。
"""
  .codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800

[features]
multi_agent = true
hooks = true

[sandbox_workspace_write]
network_access = false
参数作用安全建议
approval_policy何时要求人工批准教程默认 on-request;不把 never 当通用生产值
sandbox_mode文件与命令边界分析 read-only;实现 workspace-write
agents.max_threads全局并发默认 6;先测冲突与成本再提高
agents.max_depth嵌套委派深度从 1 开始;深层委派会降低可见性
mcp_servers.*工具连接、超时、审批凭证来自 env;启用工具 allowlist

Workflow Skill:Codex 的正确落点

  .agents/skills/product-to-launch/SKILL.md
---
name: product-to-launch
description: 从业务问题到需求、设计、原型、上线准备与复盘。
---

1. 总监建立目标、范围和成功指标。
2. 并行委派需求分析与数据分析。
3. Gate 1:目标、主路径、范围和指标明确才继续。
4. 委派 UI 与原型;可能写冲突时改为串行。
5. 运营与内容补齐发布和教育材料。
6. Eval 未通过则退回对应角色,不得跳过 Gate。

事实Codex 官方把 Skill 定义为 reusable workflow 的 authoring format。周期触发属于 Scheduled tasks;确定性运行属于 `codex exec` / SDK;不要自造一个假装“原生”的 Workflow DSL。 CDX-030 · CDX-070

OpenAI Codex Subagents 官方文档封面
OPENAI DOCS · SUBAGENTS
OpenAI Codex Build Skills 官方文档封面
OPENAI DOCS · BUILD SKILLS
OpenAI Codex Hooks 官方文档封面
OPENAI DOCS · HOOKS
05
Teaching case, not org chart

一套增长产品 Agent 团队

这个例子合理,因为产品工作天然包含目标判断、需求澄清、设计表达、运营落地和数据反馈。但它应是责任与能力模型,不是机械复制真实组织架构。

增长产品总监 · Main Agent目标 · 优先级 · 调度 · 冲突处理 · 最终验收
需求分析师范围 / 路径 / 规则 / 验收
UI 设计师层级 / 组件 / 状态 / 走查
原型设计师交互 / 状态流 / 异常 / 测试
产品运营人群 / 灰度 / 指标 / 复盘
内容运营内容矩阵 / 文案 / 渠道 / 素材
千图设计系统UI / 交互能力
千图品牌设计品牌 / 语气能力
运营营销设计活动 / 转化能力
产品数据分析指标 / 实验能力

Agent contract 必写 8 项

  1. 目标
  2. 输入
  3. 输出 schema
  4. 工具
  5. 权限
  6. 上下文边界
  7. 交接规则
  8. 失败升级

四个必须人工审批的动作

  1. 正式发布
  2. 预算与投放
  3. 生产数据写入
  4. 群发或外部消息
!

公开案例是教学抽象。不得出现真实人员、内部指标、私有仓库、客户数据、私有 Prompt 或生产凭证。

06
Orchestration with gates

三条基础 Workflow

不是把角色排成队列,而是明确哪些工作并行、哪些 Gate 必须串行、失败时退回哪里。

01 / TRIGGER机会信号目标、用户、证据、限制
02 / PARALLEL需求 ∥ 数据范围、路径、基线、指标
03 / GATE 1问题可验收不清楚就退回,不进入设计
04 / PARALLELUI ∥ 运营状态、组件、上线策略
05 / INTEGRATE原型整合主路径、异常、测试脚本
06 / GATE 2Eval + 审批一致性、安全、人工发布
TRIGGER何时启动
ARTIFACT必须交付什么
GATE什么条件才能继续
RETRY失败退回哪里
AUDIT谁在何时决定了什么
07
Runtime control × quality proof

Hook 把门,Eval 证明

把运行时与评估拆开:权限、sandbox、MCP、Hook 控制“能做什么”;Eval 数据集与 graders 证明“做得多稳定”。

Agent Harnessmodel + instructions + tools + loop
PERMISSIONSMCP / TOOLSTRACEHOOKSSANDBOX

两层 Harness

事实Agent harness:处理输入、组织 tool calls、维护状态并返回结果。

事实Eval harness:并发运行 tasks,记录 trajectory,执行 graders,聚合 pass / fail 与成本。

STD-003 · Anthropic, Demystifying evals for AI agents

Claude Hooks

command · http · mcp_tool · prompt · agent

`exit 2` 可在多个事件形成 blocking error;异步 hook 无法阻断已发生动作。agent handler experimental。

Codex Hooks

command only · trust required

当前只执行 command handler,且 Pre/PostToolUse 只覆盖部分工具路径。不是完整 enforcement boundary。

Anthropic 官方 Claude Code Hooks 生命周期图
官方图:Hook 贯穿 session、prompt、tool、subagent、compact 和 stop 生命周期。ANTHROPIC · CCL-006

Eval 配置先于结果

  evals/config.json · team convention
{
  "config_version": "qt-agent-eval-v1",
  "sample_count": 4,
  "metrics": [
    {"id":"task_success_rate", "formula":"passed / total", "threshold":0.75},
    {"id":"schema_compliance", "formula":"valid / total", "threshold":1.0},
    {"id":"safety_refusal", "formula":"correct / unsafe", "threshold":1.0}
  ],
  "overall_acceptance": "all_thresholds_must_pass"
}
Case要证明什么失败时怎么处理
normal正常任务形成目标、范围、路径、指标、验收定位缺失角色或 Gate
boundary信息不足时返回 action_required修订输入 contract
tool_failure工具失败时降级,不伪造结果补 fallback 与影响说明
safety_refusal发布、群发、生产写入保留审批收紧 permissions / approval / Hook

观点优先确定性 grader;开放性质量再用 LLM rubric;定期用专家人工校准。既看 outcome,也抽查 trajectory。

08
Copy, run, inspect

30 分钟上手,2 小时改成自己的

本教程把完整文件放进 Starter Kit。不要复制网页里的零散代码后就认为完成;先运行,再做最小改造和 Eval。

00–05ENV

复制 Starter Kit;检查 CLI 版本与认证。

05–10READ

读主 Agent、一个 Subagent、一个 Skill。

10–15DISCOVER

启动 CLI,只列出角色、能力与权限。

15–25RUN

执行“新用户首次体验”教学案例。

25–30CHECK

检查事实 / 假设、路径、指标与验收。

+90CUSTOMIZE

删角色、改 Skills、加一条 Workflow 与 Eval。

生产化检查

  • 主 Agent 只有一个最终责任边界
  • 每个 Subagent 有完整 contract
  • 只并行独立任务,写冲突已隔离
  • Skill description 不欠触发、不过触发
  • Workflow 有 Gate、retry、approval、audit
  • MCP 凭证不进仓库,工具有 allowlist
  • Eval 阈值运行前预设并版本化

八个高频误区

  • 把职位名称当 Skill
  • 把多个 Prompt 叫 Agent Team
  • 把 Workflow 等同于固定文件名
  • 每个 Agent 都开全部工具
  • 用 Prompt 代替权限系统
  • 用 Hook 代替 Eval
  • 一开始就锁模型和复杂 Team
  • 用一次 Demo 证明生产可靠
09
Ready-to-copy package

两套完整 Starter Kit

共 41 个文件。角色、Skills、3 条 Workflow、Hooks、Eval、README 与排错说明均已通过语法与结构自检。

i

先在新练习目录解压。不要覆盖现有 `CLAUDE.md`、`AGENTS.md`、`.claude/`、`.codex/` 或 `.agents/`;已有项目必须人工合并。

10
Evidence before confidence

官方来源与版本边界

规范性结论使用官方资料;本机验证只证明当前版本与环境。完整机器可读 claim ledger 位于 `sources/evidence.json`。

  1. STD-001 Anthropic, Building effective agents
  2. STD-002 Agent Skills, Specification
  3. STD-003 Anthropic, Demystifying evals for AI agents
  4. STD-004 OpenAI Agents SDK, Agent orchestration
  5. CCL-001 Anthropic, Create custom subagents
  6. CCL-003 Anthropic, Agent Teams
  7. CCL-004 Anthropic, Extend Claude with skills
  8. CCL-005 Anthropic, Dynamic workflows
  9. CCL-006 Anthropic, Hooks reference
  10. CCL-065 Anthropic, Configure permissions
  11. CDX-010 OpenAI, AGENTS.md
  12. CDX-014 OpenAI, Subagents
  13. CDX-020 OpenAI, Build skills
  14. CDX-050 OpenAI, Hooks
  15. CDX-040 OpenAI, Configuration Reference
  16. CDX-070 OpenAI, Scheduled tasks

事实验证基线:Claude Code `2.1.199`;Codex CLI `0.133.0`;2026-07-14。两端迭代快,升级后应重新运行 Starter Kit 自检与 Eval 基线。

事实官方资料采集阶段 Chrome CDP 未连接。本报告没有伪造登录浏览器截图;页面使用官方静态资源、本机 CLI 实测证据与官方文档链接。