AI-SDLC 实战 01:Claude Code 和 Codex 的六种能力该怎么用
搭工作流的时候,Claude Code 和 Codex 手里其实都握着六张牌:AGENTS.md/CLAUDE.md、Skill、Subagent、Hook、MCP,还有权限与沙箱。
这篇想把三件事讲透:
- 每张牌各管什么、在什么场合出牌;
- AI-SDLC 五个阶段里,这些牌分别被我们怎么打;
- 一套工程配置,怎样让两个宿主同时吃得下。
涉及平台行为的部分,统一以两家 2026 年 11 月版本的官方文档作为依据。
Agent = Model + Harness:上下文窗口听 Harness 的

任何一个 Coding Agent,都能劈成两半看:推理是 Model 的事;除此之外的一切——对话循环、工具调用、上下文的组装压缩、subagent 的派生回收、权限确认、外部连接——统统是 Harness 的事。
幸运的是,这两家宿主的 Harness 早就造得很完整,上面列举的每个环节都开箱即用。
因此我们的原则是:先盘清宿主有什么,能借的都借,缺口才自己动手补。缺口一共两个:
- CLI:一端推着工作流走,一端给 Agent 递辅助工具(它跟宿主、Agent 三者的分工,第 00 篇已经聊过);
- 知识库:把架构规范、编码规则长期沉淀下来,让 Agent 写代码时有的放矢。
Harness 真正的心脏,是替每一轮请求决定:送进模型的那扇上下文窗口里,到底装哪些东西。系统提示、AGENTS.md/CLAUDE.md、工具定义、skill 列表、历史消息、工具结果,全都挤在这一扇窗口里抢位置。
关于这块空间,两家文档都给出了明确的预算额度:
- Codex 这边:拼接
AGENTS.md后默认最多取前 32 KiB;skill 初始列表默认最多占窗口的 2%; - Claude Code 这边:官方建议一份
CLAUDE.md不超过 200 行;skill 描述一旦超过 1,536 字符,在列表里就会被砍掉。
连宿主本身,都在给窗口里的内容上紧箍咒。AI-SDLC 想达成的目标,就是顺着 Harness 提供的这些抓手,让每个环节的窗口里只出现该环节用得上的内容。
上个任务留下的编译日志,不该跟着进入需求理解阶段;开发角色一路的试错,也不该摊在评审角色眼前。窗口越干净,Agent 的注意力越集中,给出的判断就越靠谱。
六张牌,各自打在窗口的哪个位置

先给全景:AGENTS.md/CLAUDE.md 是常驻嘉宾;skill 平时不露面,用到才登台;subagent 自带一扇新窗口;hook 在固定的几个时点往窗口里塞内容;MCP 负责从窗外搬运内容进来;至于权限与沙箱,它们压根不进窗口,由宿主在模型外部强行把关。
AGENTS.md/CLAUDE.md:轮轮都在场
会话一启动,项目根目录的 AGENTS.md/CLAUDE.md 就装进窗口,之后每一轮请求都携带着它出发。
窗口压缩时,历史对话被总结成摘要,它却不参与总结,而是被完整地送回窗口:Claude Code 官方文档写明此时会从磁盘重新注入;Codex 的开源实现同样会在压缩完成后,把 AGENTS.md 重新插进上下文。
按需加载的部分是例外。Claude Code 中,子目录的 CLAUDE.md、带 paths: 的规则,都要等 Agent 真的去读写那个目录时才装载;一旦压缩,它们便随普通对话一起被摘要掉,等下次再碰到相关文件才重新装载。Codex 则是沿着仓库根目录到当前目录的链路,把一路上遇到的 AGENTS.md 逐级拼起来。
- 该放什么:每个会话都绕不开的少量硬规则,以及流程入口的位置;
- 别放什么:只有某个阶段才用得上的方法——轮轮占窗口,用不上时就是在白烧空间。
Skill:要用时才翻开全文
Agent Skills 是一个开放标准,两家的 skill 都照它实现。窗口里平时只挂名字加描述,等模型认定需要时,才会把 SKILL.md 全文读进来。
触发有两个入口:模型读了描述自己决定用哪个,或者人来点名——Claude Code 里打 /名字,Codex 里打 $名字。
- 该放什么:某个阶段专属的做法、模板、检查清单;
- 别放什么:必须轮轮生效的约束——模型没调用,等于没约束。
凡是流程的关键节点,都建议关掉自动触发,改由流程亲自点名:
- Claude Code:往 frontmatter 写一行
disable-model-invocation: true; - Codex:往
agents/openai.yaml写一行allow_implicit_invocation: false。
Subagent:让子任务用一扇全新的干净窗口
subagent 的全部阅读都发生在自己的窗口里,主会话只收它交回的结果;它翻过的成堆文件,一个也污染不到主窗口。
自定义角色两家都能玩:Claude Code 用 .claude/agents/ 下的 markdown 文件定义角色,Codex 用 .codex/agents/ 下的 TOML 文件,两者的 model 和 effort 都能按角色单配。
- 该派给谁:并行开发、独立评审,以及要海量翻文件的检索任务;
- 别派给谁:得跟主会话反复对表的活儿。
还有一点容易踩坑:subagent 最后那条回复只是摘要,拿它当产物是要出事的。角色文件只描述职责、输入、产出、禁止项;方法论一律留给 skill,别往角色文件里拷贝正文,不然两份拷贝迟早各走各路。
Hook:掐着固定时点补内容或踩刹车

所谓 hook,就是宿主在会话生命周期的几个固定时点自动跑起来的脚本。触发时,会话、工具名、参数这些现场信息会以 JSON 的形式交到脚本手里,宿主再依照脚本吐出的结果决定下一步。
两家都支持的时点,按一场会话的推进顺序是:
**会话开始(SessionStart)。**借机往窗口塞一段背景信息;
**用户提交(UserPromptSubmit)。**可以补上下文,也可以把这条提交拦在模型门外;
**工具调用前(PreToolUse)。**拦截、改参数、补上下文,三样都行;需要人确认时还有 PermissionRequest,可以代为放行或否决;
**工具调用后(PostToolUse)。**此时工具已经跑完,撤销无从谈起,能做的只剩补上下文、给模型递话;
**subagent 启动与结束(SubagentStart / SubagentStop)。**启动时递上下文,结束时还能要求它加跑一轮;
**回合结束(Stop)。**可以拒绝 Agent 收工,把它按回去继续干;
**压缩前后(PreCompact / PostCompact)。**压缩前能做记录,也能直接否决这次压缩;压缩后的事件则基本只承担记录职责。压缩完成后想补回内容,走的是来源标记为 compact 的会话开始事件。
数下来 hook 的本事只有三样:塞上下文、踩刹车、不许收工。它往窗口里塞的东西同样有额度,Codex 默认给每个 hook 约 2,500 token。
- 该干:会话启动后、压缩结束后补一份最小恢复索引;每轮提交时提醒所处阶段;拦下那些一看就危险的命令;
- 不该干:替 Agent 自动修代码、替流程推状态。
但 hook 的可靠度有上限。无论哪家,hook 出错或超时,默认都不影响工具继续执行。Codex 文档甚至明说:工具 hook 应被视作有用的护栏,而非完整的强制边界。
Claude Code 允许对单个 hook 设 onFailure: "block",让失败直接拦截;Codex 没有对应的开关。还有一条铁律:宿主不信任的 hook,根本轮不到运行。
MCP:从外面把事实搬进窗口
需求文档、设计稿、缺陷系统这类外部系统,通过 MCP 接进来;Agent 想看哪块,就按需调工具把那块读进窗口。
- 该干:把外部事实源里的内容读进来;
- 不该干:把它当成真相源本身。
注意 MCP 给出的是当下那一刻读到的快照,可能缺斤短两,也可能干脆读取失败。另外工具定义自己也吃窗口额度,用不上的就该关——Codex 提供了 enabled_tools、disabled_tools 两个开关来收窄。
权限与沙箱:不进窗口的硬闸门
这一对完全不进窗口:它们由宿主在模型之外直接执法,模型无从讨价还价。
Claude Code 靠 allow、ask、deny 三类规则,判定顺序是 deny、ask、allow,且 deny 说话最硬,allow 无法给它开口子。Codex 靠沙箱模式加审批策略圈定活动范围,沙箱之外的命令再交命令前缀规则管束。
- 该管:碰不得的红线,比如某些目录禁止写入、禁止推送、禁止联网;
- 不该管:教它「怎么做」的方法论。
六种能力摊开比较后,一条约束的去处就清楚了——看它需要多硬。口头提醒级别的,放进窗口,交给 AGENTS.md/CLAUDE.md 或 skill;必须强制拦下的,交给权限与沙箱,hook 只能当辅助;而必须拿出证据证明没被违反的,就轮到下一节的 Checker。
五个阶段,这六张牌我们怎么打

五个阶段各有各的窗口配方。这一节只说每个窗口由哪几张牌拼成,具体工艺留到后面的篇章细讲。
**需求理解(第 03 篇)。**阶段 skill 一律由流程亲自加载。需求文档、设计稿走 MCP 读取,落盘的结论必须标注来源;读不到就写「源不可用」继续往下走,禁止靠记忆脑补。
仓库里查得到的事实,Agent 自己动手查;只有那些会动摇目标、范围、授权或验收标准的问题,才值得去打扰人。
**方案设计与评审(第 04 篇)。**评审 subagent 接手方案评审。它的窗口只装方案本身,加上方案引用的接口合同、组件、设计材料;方案作者怎么想出来的,一概不给看——评审结论因此才能不偏袒作者。
**开发(第 05 篇)。**开发 subagent 按任务图逐个派出,每位手里的上下文清单只列两件事:读哪些文件、为何读;清单里还包含知识库中与这部分代码挂钩的架构规范、编码规则(知识库在第 08 篇)。
开几个 subagent、何时收兵,由 CLI 照着任务图算,skill 无权拍板。产物一律先落盘,然后才许报完成。
**验证与联调测试(第 06 篇)。**评审与测试并肩跑在同一个冻结候选版本上。评审 subagent 与流程门禁共用同一个 Checker,标准只有一套。
**交付(第 07 篇)。**两道闸把门:一道是宿主的权限规则,一道是流程的逐动作授权。推送、合并、提测一项一确认,上一项批了不代表下一项放行。
**跨阶段(第 02 篇)。**会话启动、压缩前后、每轮提交,hook 都会出场,补回三样东西:眼下处于哪个阶段、接下来做什么、必须翻哪些文件。它只给路径和摘要,流程状态一律不碰。
宿主没给的那一块:Checker
六张牌打完,Agent 只不过是更有可能做对;判定做没做对这件事,六种能力里没有一个能兜底。缺口由我们在 CLI 里补齐:每个阶段出口都设确定性检查,只输出 pass 或 blocked 两种结果,blocked 时附带 path:line。
Checker 的信息源只有磁盘上的产物,模型如何自述工作一概不听。编译过、测试过,也不足以抵消一次越界改动。
一套工程,喂饱 Claude Code 和 Codex 两个宿主

这套流程得在两个宿主上都能跑。若两边各养一套配置,用不了几个月就会长成两副面孔。
解法是:角色、skill、hook 统统用一种通用格式写且只写一份——后文称中立源;再让脚本从它生成两家各自的文件——后文称投影。
工程目录的骨架如下:
<仓库根目录>/
├── AGENTS.md # 两边共用的入口文件
├── CLAUDE.md # 只有一行 @AGENTS.md
├── agents/ # 中立源:角色定义
├── skills/ # 中立源:各阶段的 skill
├── docs/ # 知识库:架构规范、编码规则
├── .claude/ # Claude Code 投影
│ ├── agents/ # sync 生成
│ ├── skills/ # sync 生成
│ └── settings.json # hook 与权限规则,随仓库提交
├── .agents/
│ └── skills/ # Codex 读取的 skill,sync 生成
└── .codex/ # Codex 投影
├── agents/ # sync 生成
├── hooks.json # 随仓库提交
└── config.toml # MCP 等配置
人的手只碰 AGENTS.md、中立源、知识库三处。投影交给 CLI 生成;hook 配置两边都随仓库提交。
投影如何产出:会话开始的 hook 负责唤起 sync
真正干活的命令是 CLI 的 sync。两边会话开始 hook 配的是同一句命令——唤醒 sync:
- 读入中立源中的角色与 skill;
- 按各家的方言产出投影:角色分别落成 Claude Code 的 markdown、Codex 的 TOML,skill 则分流到
.claude/skills/与.agents/skills/; - 产出途中顺带查同名冲突,并把只有单边支持的能力的降级方案记下来。
于是每开一场会话,投影都自动追平中立源的最新版,谁也不必惦记手动同步。中立源里刚改的 skill,下一场会话立即生效。
落地时有三个细节绕不开:
**本场会话能否马上享用到。**Claude Code 扫 skill 的时间点通常比会话开始 hook 跑完更早,hook 刚写下的 skill 可能错过第一条提示;好在 hook 可以返回 reloadSkills: true,Claude Code 会在 hook 收尾后重扫一遍。角色文件一动,Claude Code 几秒内就有反应。Codex 对 skill 变化也是自动侦测。
**唤起 sync 的那条 hook 配置,绝不能出自 sync 之手。**它是整个同步链条的第一环,必须随仓库提交,内容钉死为一条调 CLI 的命令。配置纹丝不动,Codex 也就不会借某次同步为由要求重审这条 hook。
**sync 必须快,且失败不设卡。**它卡在会话启动的关键路径上,Claude Code 第一条回复得等它跑完。万一同步失败,会话照开不误,沿用上一轮的投影,过期的事由预检去说。
产出投影的过程中,sync 恪守三条纪律:
- 投影只许生成、不许手改:投影文件自带生成标记,每轮同步都从中立源整体重造,手改上去的字迹一概被冲掉;
- 撞名就报错:Codex 对同名 skill 不做合并,两个会同时出现;Claude Code 同一目录的同名角色只挑一个装载,挑谁全看运气。所以在 sync 层就拦下同名,绝不留给宿主裁决;
- 差异要明降、不许暗丢:单边独有的能力(例如下文的只读 subagent),投影时把降级路径、补位方案一并写进记录。
投影还得消化两边的下列差异:
| 能力 | Claude Code | Codex |
|---|---|---|
| AGENTS.md/CLAUDE.md | CLAUDE.md 与 .claude/rules/;缺 CLAUDE.md 时直接读 AGENTS.md | AGENTS.md 逐级拼接,默认上限 32 KiB |
| 权限 | allow / ask / deny 三类规则加权限模式 | 沙箱模式加审批策略,外加命令前缀规则 |
| Skill | .claude/skills/ | .agents/skills/ |
| 自定义角色 | .claude/agents/*.md | .codex/agents/*.toml |
| subagent 权限 | 角色可单独限工具与权限模式,还能放进独立 worktree | 继承主会话权限,角色文件只能关掉少数几项能力 |
| Hook | 项目目录获信任后即运行;单条可设失败即拦截 | 逐条审核 hook,配置一改须重审;同一时机的多条并行启动 |
| MCP | 项目级 .mcp.json,要人工批准 | config.toml 里的 [mcp_servers],项目级只对受信任项目生效 |
两边表现分叉的三个点
一、单个角色能否被单独锁成只读。
Claude Code 给得出答案:在角色的定义文件里写上 tools: Read, Grep, Glob,改文件的工具就到不了它手上,这是宿主层面的保证。
Codex 给不出:subagent 的权限完全继承自拉起它的主会话,主会话能写文件,它就能写。角色定义文件顶多关掉 shell 这几样,在角色说明里写一句「不要改文件」,实际只是一句劝告。
因此在 Codex 上要做货真价实的只读评审时,我们另起一个只读会话来执行,输出由 CLI 落成文件;若走 subagent,评审收尾后交给 Checker 核查:评审目录之外的文件有没有被动过。
二、hook 配置被改动后,还跑不跑。
Claude Code 的信任单位是项目目录。你确认过一次,这个目录里配的 hook 从此就跑。
Codex 的信任单位是单条 hook。它给每条 hook 配置记了指纹,指纹一变,这条 hook 就被搁置,直到有人再审一遍。同一时点的多条 hook 依旧并行起跑,不存在先后。
于是我们把 hook 配置钉死为一条调 CLI 的命令(会话开始时唤起 sync 的正是它),一个时点只挂这一条,真正的逻辑全在 CLI 里迭代。配置几乎不动,团队成员就不必一改一重审,多条 hook 的顺序问题也随之消失。两家的 hook 事件名高度一致,这条命令照事件名分发就行,细节第 02 篇讲。
三、skill 各自住在哪个目录。
skill 各回各家:Claude Code 只看 .claude/skills/,Codex 只看 .agents/skills/,谁也不翻对方的柜子。
AGENTS.md 是另一回事:项目里若没有 CLAUDE.md,Claude Code 会直接把它读了;若 CLAUDE.md 存在,也能在里面写一行 @AGENTS.md 把它引荐进来。
结论:AGENTS.md 全项目一份、两家共用;skill 在中立源里也只有一份,产出时分别送进两个目录。
同一个评审角色,两副投影长相
同一个方案评审角色,投到两边后长下面这样,出处都是中立源。它的评审结论需要落成文件,因此两份配置都留有写文件的本事。
Claude Code(.claude/agents/plan-reviewer.md):
---
name: plan-reviewer
description: 对照接口合同和设计材料评审技术方案,只写评审结论
tools: Read, Grep, Glob, Write
model: inherit
effort: high
maxTurns: 30
---
只读取方案及其引用的合同文件。
评审结论写入评审目录下的一个文件,不修改其他文件。
Codex(.codex/agents/plan-reviewer.toml):
name = "plan-reviewer"
description = "对照接口合同和设计材料评审技术方案,只写评审结论"
model_reasoning_effort = "high"
developer_instructions = """
只读取方案及其引用的合同文件。
评审结论写入评审目录下的一个文件,不修改其他文件。
"""
[features]
shell_tool = false
Claude Code 侧砍掉了 Bash 和 Edit;Codex 侧顶多关掉 shell 工具,具体能写哪儿,由父会话的沙箱说了算。谁也没法把写入范围圈死在评审目录里,「只改评审文件」这句承诺,最后靠 Checker 来对账。
已同步、已信任、已执行,是三码事
sync 跑完只证明投影落了地,离宿主点头还差一步:Claude Code 那边有工作区信任、项目 MCP 批准两道手续,Codex 那边有项目层信任、逐条 hook 审核。宿主点了头,也仍然不等于它在本次会话里真的跑过。
预检于是成了 CLI 的例行公事,逐项过:投影新不新、必需的 hook 与 MCP 有没有被信任、能不能用。会话散场后,还要翻会话日志,核对哪些真的触发了。
流程能不能跑对,绝不能押注在「hook 必然运行」这种假设上。第 02 篇顺着这里往下讲阶段合同、状态机与恢复:当 hook 没跑、会话中途被压缩或打断,流程凭什么叫得醒自己。
更多推荐


所有评论(0)