AI 编程 agent 手册

这不是工具功能索引，而是一套研发人员使用 coding agent 的工作手册：先理解 agent 的任务闭环，再把任务输入、标准流程、上下文管理、验证评审、项目规则、权限安全和复用扩展沉淀成自己的工程习惯。Codex 和 Claude Code 的机制不同，但最佳实践主线高度一致。

手册按这条闭环组织：给任务和上下文，先探索和计划，执行最小改动，用验证和 review 收尾，再把重复经验沉淀。

本章目标

知道 coding agent 与 chatbox 的根本区别，以及哪些任务适合交给它。
能把 agent 放进真实研发流程：探索、计划、实现、验证、评审、提交和复盘。
能判断哪些内容留在 prompt，哪些写进 AGENTS.md / CLAUDE.md，哪些做成 Skill、Hook、MCP 或子代理。

这份手册解决什么问题

很多教程从安装、命令和界面开始，但研发人员真正卡住的不是“怎么启动”，而是“怎么让它稳定交付一件工程任务”。一次靠谱协作至少包含：给清楚任务、让它读上下文、限制范围、要求验证、审查 diff、沉淀规则。

Codex 官方 best practices 强调 context、AGENTS.md、config、MCP、skills、automations 和 session 管理；Claude Code 官方 best practices 把 verification、explore-plan-code、context/session、subagents 和 automation 放得很重。这份手册把这些共性重排成一条研发工作流。

这里默认读者已经会 Git、lint、test、build 和代码 review。手册不重复这些常识，而是写 agent 接入后需要新增的判断：什么时候只读、什么时候计划、什么时候放权、什么时候清空上下文、什么时候必须独立评审。

不是 prompt 合集：重点是工程闭环和判断标准。
不是双工具横评：Codex 为主线，Claude Code 作为最佳实践对照。
不是面向纯小白：默认你能读 diff、能跑命令、能对改动负责。
是个人使用沉淀：案例、模板和规则都按真实研发任务组织。

建议阅读顺序

目录按“先建立协作方式，再跑通一次交付，再把经验沉淀”的顺序排。第一次读可以从 01 到 05 连着看；真正开始长期使用时，06 到 10 更重要。

01 工作方式与边界：先知道它适合做什么，不适合做什么。
02 任务输入：把模糊需求变成目标、上下文、约束和验收。
03 标准工作流：用一个真实站点改动走完探索、计划、实现、验证、复盘。
04 上下文与长任务：管理 compact、clear、fork、worktree、子代理和会话恢复。
05 验证与评审：用测试、构建、截图、review pane 和独立 reviewer 闭环。
06 项目规则：把反复纠正写进 AGENTS.md / CLAUDE.md，而不是每次重说。
07 权限与安全：审批、沙箱、secrets、不可信输入和硬约束。
08 扩展能力：什么时候用 Skill、Hook、MCP、命令、子代理和自动化。
09 Git、PR 与 CI：把本地改动整理成可评审、可回滚、可持续的交付。
10 案例库：把 transcript、diff 和复盘沉淀成自己的 playbook。
11 工具对照：最后再看 Codex 与 Claude Code 的机制差异。

如何使用官方文档

官方文档适合查机制：某个配置项叫什么、文件放哪里、权限怎么配、Skill 或 Hook 的语法是什么。手册适合查判断：这类事情到底该不该沉淀、该沉淀到哪一层、该怎么验收。

必要时可以打开每章顶部的官方来源链接对照。图片和流程如果来自官方文档，只作为理解机制的参考；本站手册里的主配图保持自绘统一风格，避免尺寸、视觉语言和授权边界混杂。

查机制：去官方文档。
定流程：看本手册。
写规则：优先写自己的项目事实，不直接复制官方示例。
做决策：以真实项目验证结果为准，而不是被工具功能列表牵着走。