Skill first：claude-agents-bootstrap。
弄丢了制作 claude-agents-bootstrap 的那段 session。
这听起来像一件小事故，但它刚好证明了这个 skill 为什么应该存在：重要经验不能只活在聊天记录里。它要变成可检查、可推送、可复用的仓库资产。
丢 session 不等于丢经验。只要 artifact 还在，流程就能补回来。
root docs 是地图，不是百科全书
这个 skill 的核心不是“写一份更长的 CLAUDE.md”。相反，它要减少 resident context 里的噪音。
根文档只放稳定、高频、会影响每次 agent 行为的规则：项目契约、先读文件、命令、验证、更新规则、禁止事项、compact 指令。低频细节进入 docs/AI_REFERENCE.md、docs/ai/*.md 或模块文档。
根文档是地图。代码和版本化文档才是记录系统。
让 agent 先找证据，再写规则
claude-agents-bootstrap 的工作流有一个故意设置的摩擦：不能一上来就改 AGENTS.md。它要先读已有根文档、README、关键 docs，再检查代码里的高风险事实：角色边界、路由边界、auth/session、数据库来源、上传导出、安全边界、命令和验证面。
如果 repo 已经足够说明事实，就不问填表式问题。如果关键政策缺口会改变输出，才问一个短问题。
少问不是偷懒。少问是尊重已存在的证据。
主动队列要写清楚生命周期
很多项目的 AI docs 会慢慢变成垃圾桶：今天塞一个 bug，明天塞一个 tech debt，后天塞一个 release blocker。没有完成证据，没有归档规则，也没有“不确定时问用户”的边界。
这个 skill 强制队列类 supporting docs 写生命周期：什么算 active、什么证据算完成、完成后去哪里、什么时候 agent 可以清理、什么时候必须问一个聚焦问题。
队列要会释放。否则它只是另一个 backlog。
2026-06-23：这次 v0.2 真正补上的东西
后来我又拿一篇关于 AGENTS.md 的完整文章反查这个 skill。那篇文章里最刺眼的一点很简单：你不只有 root AGENTS.md。在 monorepo 或多应用仓库里，子目录也可以放 AGENTS.md，并和 root 指令一起进入 agent 上下文。
这迫使新版把“短 root docs”推进一步：root 只负责跨项目的 resident rules；apps/admin、apps/mobile、packages/api 这类子树自己的命令、风险和约定，应该进入 scoped AGENTS.md。每一层都要克制，因为 nested instructions 会合并。把所有东西塞回 root，只是换一种方式制造泥球。
新版也把工具兼容说清楚了。AGENTS.md 是开放约定，但不是所有 agent 都读；Claude Code 更常读 CLAUDE.md。所以 skill 不再只说“保持一致”，而是要求显式处理镜像、symlink 或有意分歧。同时，它会区分三种很容易被混淆的路径：canonical skill source、repo-local mirror、loader-visible install root。能读到一份副本，不等于这个 skill 已经被当前 harness 自动发现。
另一个补丁是分类。个人偏好、团队约定、项目事实、工具限制不能混在一起写。个人喜欢某种 commit 风格，不等于项目事实。某个 loader 不支持某种发现机制，也不等于所有 agent 都有这个限制。分类不清，文档就会把偏好伪装成真理。
文章还提醒了一个常见坏味道：初始化脚本生成的 AGENTS.md 不能原样信任。它们通常追求“多数场景有用”，但 root instruction budget 恰好最怕这种泛用内容。新版 workflow 要求先审计 generated draft：找 contradiction、stale path、generic default、deletion candidate，再决定什么留下。
这次我没有只改正文。新版 claude-agents-bootstrap 进入了一个更完整的 SkillOps 形态：有 manifest.json、agents/interface.yaml、trigger eval、output eval、security policy、registry、dist package 和 Review Studio 报告。它被推到 GitHub main 的 commit 是 52baeafe69776ef6a9d159b5f2ed316da4655358。旧版也保留了 tag：claude-agents-bootstrap-before-20260623。
验证数字也写在明处：resident 初始加载估算 994/1000；governance score 85；6 个 output eval case 的 with-skill pass rate 是 100%；5 个 runtime target conformance 通过。Review Studio 没有 blocker，但还有 6 个 warning。这里不能说“完全毕业”。AI 盲审只是 smoke evidence，不能冒充 human blind review。
这次更新后的判断更硬：AGENTS/CLAUDE bootstrap 不是写一份漂亮根文档，而是设计一套 context routing system。root、scoped AGENTS、supporting docs、skills、checks、handoff、archive，各有各的位置。
这次留下的判断
- 写 agent 指令文档时，短 root docs 比长百科更有价值。
- 只有被 repo、命令、测试、CI、脚本或用户明确确认支撑的事实，才应该进入规则。
- 子目录
AGENTS.md是重要工具，但它不是扩写 root 的借口。每一层都要通过 resident-budget test。 - 能被项目读到的 mirror，不等于被 agent loader 安装。source、mirror、install root 必须分开写。
- 生命周期报告能提高信任，但要诚实标注剩余 warning。不要把 AI 盲审说成人工盲审。
底部再放一次 skill：claude-agents-bootstrap。文章解释为什么它存在，真正要复用的是仓库里的操作文档。