先用一个 Agent
任务单一、路径开放、一个责任人即可完成。
Agent 决策,Skill 复用,Workflow 编排,Hook 把门,Eval 证明。
一份讲清 Claude Code 与 Codex 配置路径、参数和团队案例的可复制教程。
目标、判断、工具、循环
独立上下文、窄职责、交回
并发、通信、共享状态
方法、知识、脚本、资产
顺序、并发、Gate、产物
事件、校验、阻断、记录
任务、轨迹、评分、回归
市场上没有唯一词典,但边界已经相当稳定:责任主体、专业委派、协作系统、可复用能力、预设编排、事件控制、质量评估。
事实模型 + 指令 + 工具 + 环境反馈循环。它根据状态动态决定下一步。
事实由主 Agent 委派、独立上下文、较窄职责,完成后把结果交回 caller。
事实多个 Agent 在并发、交接、通信或共享状态下完成同一目标。
事实`SKILL.md` + 可选 scripts / references / assets;按需加载。
事实输入、步骤、并发、Gate、产物、重试、超时、审批和审计。
事实生命周期事件触发的确定性处理器,用于校验、记录、阻断或唤醒。
事实Agent harness 让模型行动;Eval harness 跑任务、记 trajectory、评分和聚合。
任务单一、路径开放、一个责任人即可完成。
研究、审查、数据、UI 等任务值得隔离上下文。
不把同一套设计规范复制到每个角色 Prompt。
把 Gate、交付物与失败处理显式化。
确定性检查放事件层,不靠模型“记得”。
先定阈值,再运行;持续做回归而非看 Demo。
最容易记错的两件事:Codex 的角色在 `.codex/agents`,Skill 在 `.agents/skills`;两端都没有官方 Eval 目录,`evals/` 是团队约定。
./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./.claude/skills/<name>/SKILL.md./.agents/skills/<name>/SKILL.md~/.claude/skills/<name>/SKILL.md~/.agents/skills/<name>/SKILL.md./.claude/workflows/*.js 或 Skillcodex exec / SDKsettings.json / Skill / Agenthooks.json 或 config.toml./.mcp.jsonconfig.toml [mcp_servers.*]evals/ + claude -pevals/ + codex exec
日常产品团队优先用主 Agent + Subagents + Skills。Agent Teams 只解决需要直接协作的复杂问题;Dynamic Workflows 解决规模化编排。
YAML frontmatter 管模型、工具、权限与预加载 Skill;Markdown body 写角色 contract。
独立 sessions、shared task list、mailbox、teammate 直接通信。成本与协调复杂度更高。
--- 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 或文件所有权 |

事实Agent Teams 仍为 experimental。不要为了“像组织架构”就开启;先证明 direct communication 与 shared state 确有必要。
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
`AGENTS.md` 管主 Agent;`.codex/agents` 管 Subagents;`.agents/skills` 管能力与 Workflow。严格编排再用 `codex exec` / SDK / CI。
从 user scope 与 Git root 到 CWD 逐层加载;越靠近当前目录,优先级越高。
内置 default / worker / explorer;自定义角色定义职责、sandbox、模型、MCP 与 Skills。
name = "requirement_analyst" description = "把模糊问题转成目标、用户、范围、路径、规则和验收。" sandbox_mode = "read-only" nickname_candidates = ["Scope", "Path", "Spec"] developer_instructions = """ 只做需求澄清与证据整理。 缺少目标用户或成功指标时,返回 action_required,不猜测。 """
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 |
--- 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



这个例子合理,因为产品工作天然包含目标判断、需求澄清、设计表达、运营落地和数据反馈。但它应是责任与能力模型,不是机械复制真实组织架构。
公开案例是教学抽象。不得出现真实人员、内部指标、私有仓库、客户数据、私有 Prompt 或生产凭证。
不是把角色排成队列,而是明确哪些工作并行、哪些 Gate 必须串行、失败时退回哪里。
把运行时与评估拆开:权限、sandbox、MCP、Hook 控制“能做什么”;Eval 数据集与 graders 证明“做得多稳定”。
事实Agent harness:处理输入、组织 tool calls、维护状态并返回结果。
事实Eval harness:并发运行 tasks,记录 trajectory,执行 graders,聚合 pass / fail 与成本。
STD-003 · Anthropic, Demystifying evals for AI agents
`exit 2` 可在多个事件形成 blocking error;异步 hook 无法阻断已发生动作。agent handler experimental。
当前只执行 command handler,且 Pre/PostToolUse 只覆盖部分工具路径。不是完整 enforcement boundary。
{
"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。
本教程把完整文件放进 Starter Kit。不要复制网页里的零散代码后就认为完成;先运行,再做最小改造和 Eval。
复制 Starter Kit;检查 CLI 版本与认证。
读主 Agent、一个 Subagent、一个 Skill。
启动 CLI,只列出角色、能力与权限。
执行“新用户首次体验”教学案例。
检查事实 / 假设、路径、指标与验收。
删角色、改 Skills、加一条 Workflow 与 Eval。
共 41 个文件。角色、Skills、3 条 Workflow、Hooks、Eval、README 与排错说明均已通过语法与结构自检。
Claude Code + Codex。适合并排学习、迁移与团队标准化。
27 KB · 21 FILES6 Agents · 4 Skills · 3 Dynamic Workflows · Hook · Eval
25 KB · 20 FILESAGENTS.md · 5 Subagents · 7 Skills · Hooks · Eval
先在新练习目录解压。不要覆盖现有 `CLAUDE.md`、`AGENTS.md`、`.claude/`、`.codex/` 或 `.agents/`;已有项目必须人工合并。
规范性结论使用官方资料;本机验证只证明当前版本与环境。完整机器可读 claim ledger 位于 `sources/evidence.json`。
STD-001 Anthropic, Building effective agentsSTD-002 Agent Skills, SpecificationSTD-003 Anthropic, Demystifying evals for AI agentsSTD-004 OpenAI Agents SDK, Agent orchestrationCCL-001 Anthropic, Create custom subagentsCCL-003 Anthropic, Agent TeamsCCL-004 Anthropic, Extend Claude with skillsCCL-005 Anthropic, Dynamic workflowsCCL-006 Anthropic, Hooks referenceCCL-065 Anthropic, Configure permissionsCDX-010 OpenAI, AGENTS.mdCDX-014 OpenAI, SubagentsCDX-020 OpenAI, Build skillsCDX-050 OpenAI, HooksCDX-040 OpenAI, Configuration ReferenceCDX-070 OpenAI, Scheduled tasks事实验证基线:Claude Code `2.1.199`;Codex CLI `0.133.0`;2026-07-14。两端迭代快,升级后应重新运行 Starter Kit 自检与 Eval 基线。
事实官方资料采集阶段 Chrome CDP 未连接。本报告没有伪造登录浏览器截图;页面使用官方静态资源、本机 CLI 实测证据与官方文档链接。