Skill first: claude-agents-bootstrap.
弄丢了制作 claude-agents-bootstrap.
That sounds like a small accident, but it proves exactly why this skill should exist: important experience cannot live only in chat history. It needs to become a repository asset that can be checked, pushed, and reused.
Losing the session does not mean losing the experience. As long as the artifact remains, the process can be reconstructed.
Root Docs Are a Map, Not an Encyclopedia
The core of this skill is not "write a longer CLAUDE.md". Instead, it reduces noise in resident context.
Root documents should contain only stable, frequent rules that affect every agent run: project contracts, files to read first, commands, verification, update rules, prohibitions, and compact instructions. Low-frequency details go into docs/AI_REFERENCE.md, docs/ai/*.md or module documentation.
Root docs are the map. Code and versioned documents are the record system.
Let the Agent Find Evidence Before Writing Rules
claude-agents-bootstrap deliberately adds friction: it cannot immediately edit AGENTS.md. It first reads existing root docs, README, and key docs, then checks high-risk facts in the code: role boundaries, route boundaries, auth/session, database sources, upload/export, security boundaries, commands, and verification surfaces.
If the repo already states the facts, it does not ask form-filling questions. It only asks one short question when a key policy gap would change the output.
Asking less is not laziness. It is respect for existing evidence.
Active Queues Need Clear Lifecycles
Many projects' AI docs slowly turn into junk drawers: one bug today, one tech debt tomorrow, one release blocker the next day. There is no completion evidence, no archive rule, and no boundary for when to ask the user if uncertain.
This skill requires queue-style supporting docs to state their lifecycle: what counts as active, what evidence counts as done, where completed items go, when an agent may clean them up, and when it must ask a focused question.
A queue needs to release work. Otherwise it is just another 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，各有各的位置。
Judgment Preserved This Time
- When writing agent instruction docs, short root docs are more valuable than long encyclopedias.
- Only facts backed by the repo, commands, tests, CI, scripts, or explicit user confirmation should enter rules.
- 子目录
AGENTS.md是重要工具，但它不是扩写 root 的借口。每一层都要通过 resident-budget test。 - 能被项目读到的 mirror，不等于被 agent loader 安装。source、mirror、install root 必须分开写。
- 生命周期报告能提高信任，但要诚实标注剩余 warning。不要把 AI 盲审说成人工盲审。
Skill again at the bottom:claude-agents-bootstrap. The article explains why it exists; the repository operating doc is what should actually be reused.