ABOUT · 这是什么

有据可查的 agentic coding 实践手册 —— 只回答两个问题

每条断言都必须回答一个问题:出处在哪?答案是可以点开的官方文档,而不是口号。市面上关于 Claude Code、Codex、Cursor 的最佳实践合集不少,但绝大多数是没有出处的断言(「CLAUDE.md 要短」「先规划再写码」)。这个仓库只回答关于一个仓库的两个问题:agent 读得懂它吗(AGENTS.md、条件规则、hooks、skills、CI 门禁),agent 在里面验得动自己的工作成果吗(一条命令跑完全部验证、确定性、失败留下的证据)。第一个问题决定 agent 会不会一开始就走错,第二个决定你敢不敢让它自己合 PR。四件东西共用同一条规则:没有出处的断言不收,过期的条目删掉而不是留着加个注解。

• 逐格核实的跨工具对照表(rosetta)——把 Claude Code、OpenAI Codex、Cursor、GitHub Copilot 放在十个概念上对照:项目级 memory、用户级 memory、条件/路径规则、skills、hooks、子 agent、操作系统级沙箱、审批模式、MCP 配置、headless/CI。十行 × 四列共 40 格,每一格的文字本身就是对应官方文档页的链接,2026-09-11 逐格复核,方便任何人一键复核其中任意一格。
• 有出处的实践地图(practices)——十三章:一篇可跟做的 walkthrough,01–08 与 12 讲第一个问题(读得懂:配置写在哪、任务怎么框、上下文怎么管,以及接手陌生代码库时怎么把运行时和动机都问出来),09–11 讲第二个问题(验得动:把仓库改造成可被验证、把团队规矩下沉成能自动失败的硬约束、让 agent 对 UI 类工作产出截图/trace 级证据)。每条实践按「场景 → 做法(可复制的示例)→ 依据(官方链接)→ 边界」展开,标注适用工具与验证日期。
• 四个可执行的检查器(tools)——agentsmd-lint 给单个 memory 文件挑毛病:行数超标、模板占位符没填、含糊到 agent 无法执行的措辞、引用了不存在的 npm script、空的标题小节;agents-doctor 用 8 项检查看整个仓库的 agent 基建;agents-init 给还没有 AGENTS.md 的仓库写一份,只写它真的探测到的命令;verify-doctor 用 10 项检查按六个阶段报出验证回路的缺口(有没有一条命令跑完全部验证、测试是否确定、失败有没有留下可解析的证据与 artifact、UI 失败有没有留下截图/trace、跨模块引用会不会失败、逃逸口有没有被计数、flaky 有没有被清零或隔离)。verify-doctor 的探测是按生态写的,目前覆盖 JS/TS、Python、Go、Rust、Java/Kotlin 五个栈;其他语言上只有读 CI YAML 与仓库文件的那四项(单命令入口、失败证据与 artifact、模块边界、PR 证据模板)还能给结论,测试与逃逸口那五项一律报「不适用」并写明原因(ui-evidence 认的是框架配置而不是语言探针,无浏览器测试框架时同样报 info)——无可检之物时报 info 不报 ok,绿灯必须有信息量。四个都是零依赖的单文件 Node ESM 脚本(Node ≥ 20)。
• 给 agent 的接口——四个检查器都接受 --json,输出同一套结构(tool / target / summary / results),level 只有 ok、warn、error、info 四种,stdout 里只有一个 JSON 对象,没有人类输出行也没有 ANSI 转义。退出码:0 干净,当且仅当存在 error 级结果时为 1,用法错误为 2 —— 用法错误时只往 stderr 写一行用法、stdout 保持为空,解析方不会读到半个对象。都可以原样放进 CI。这个仓库的读者一半是 agent,让它去正则匹配人类报告行不是输出格式,是接口缺失。

先读哪几页

• 00 · 从零把一个仓库配成 agent-ready——AGENTS.md → 条件规则 → hook → lint 进 CI,每一步都能自己验证。
• 01 · Memory 文件——一份 AGENTS.md 该写什么、不该写什么,为什么它的每一行都在花掉每个会话的上下文预算;以及 Claude 的 auto memory:agent 自己写的笔记存在哪、怎么审。
• 05 · 权限与沙箱——四家的审批模式和操作系统级沙箱分别是什么,以及它们的边界在哪。
• 09 · 可验证的仓库——一条 dev 一条 check、六类不确定源、一份能直接喂给 agent 的失败报告、flaky 清零或隔离。
• 10 · 硬约束下沉——把团队规矩从文档搬到能自动失败的层:结构 > 类型 > 机械 > 提示,停在提示层等于承认没管住。
• 12 · 理解陌生代码库——接手不熟的模块时把「运行时怎么走」和「当初为什么这么写」问出来：/how / /why / /teach / /recall，并把这套问法固化成一份可提交的 skill。
• 11 · 验证技能——UI 类工作的失败断言文本说不清:失败留截图/trace、让 agent 驱动真实应用截图自证、视觉证据进 PR 流程。

上面的票根导航和正文由浏览器直接读取仓库里的 Markdown 原文渲染,内容永远跟仓库这一份事实源同步;这里列出的章节页则是已经渲染好的静态页面,不依赖 JavaScript 也能打开。这里刻意没有任何性能或效率数字:仓库只统计自己的产物(格数、规则数、检查项数、章节数),不声称某条实践能让 agent 更快或更准——因为没有测过,编一个数字会违反它自己的规则。代码 MIT,文档内容 CC BY 4.0。