AI 协同：仓库如何与 agent 一起写代码

示例本次示例：一次典型的 agent 改动

# ① agent 会话开始
#   agent-instructions 插件向上找 .git 定项目根 → 收集 AGENTS.md 链
#   → 作为 user/message 注入 inbox（08 页 preStep 的第一步）
#   根 AGENTS.md 175 行 = 「每次会话都要在上下文里的常备命令」
#
# ② agent 读代码 → 改 packages/core/agent-loop/src/agent.ts
#   packages/AGENTS.md（28 行）补充该子树的额外规则
#
# ③ 判定「这次改动是不是 non-trivial」
#   → 是 → 必须同时写一篇 Agent Note（.agents/notes/README.md 的硬规则）
#
# ④ 提交前：dsh-pre-push-checks skill 选最小的检查集
#   → 不跑全量测试（CI 负责穷尽性）
#
# ⑤ 推送 → CI 跑 55 个 verify-* 门
#   → verify-agent-note-format 检查笔记的段落骨架
#   → verify-doc-budgets 检查文档有没有超字数
#   → verify-md-links 检查相对链接
#
# ⑥ 合入。决策留在 .agents/notes/implemented/ 里，供后来者查「为什么」

# AGENTS.md 层级文件：22 个（根 + 各子树）
# Agent Notes：1182 篇英文正本
#   implemented/  487   proposed/ 39   rejected/ 14   archived/ 640
#   按月份：2026-06 = 68，2026-07 = 385，2026-08 = 372，2026-09 = 159
# 可复用 skill：14 个（.agents/skills/*/SKILL.md）
# 校验脚本：257 个（scripts/*.ts），其中 verify-* 门 55 个
# 文档门聚合（doc-sync）：约 35 个 leaf gate
#
# 换算：平均每天新增 ~10 篇决策记录。

§1分层指令：AGENTS.md 与它的符号链接

仓库的 agent 指令放在 AGENTS.md，按目录分层，共 22 个。切分依据写在根文件自己的规则里：

The launcher parses only what it owns… Root AGENTS.md = Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home.

CLAUDE.md 是符号链接

如果你用 Claude Code 打开这个仓库，它会读 CLAUDE.md——但那个文件只有 9 个字节，内容是 AGENTS.md。git 视角下它是一个符号链接（mode 120000）：

$ git ls-files -s CLAUDE.md packages/CLAUDE.md
120000 47dc3e3d86... 0	CLAUDE.md
120000 47dc3e3d86... 0	packages/CLAUDE.md

$ cat CLAUDE.md
AGENTS.md

根 AGENTS.md 的第 171 行把这条规则写明了：「CLAUDE.md symlinks AGENTS.md at root and packages/; edit the real file.」——不要编辑符号链接，编辑真身。这样同一份指令同时服务 Claude Code（读 CLAUDE.md）和其他遵循 AGENTS.md 约定的 agent，不存在两份需要同步的副本。这是「一个事实一个家」在工具兼容层面的应用。

§2Agent Notes：决策记录体系

这是整个协同基建里最有分量的一块。1182 篇英文正本（另有等量的 .zh.md 中文对照与 sidecar），放在 .agents/notes/。

两条轴：生命周期 × 类别

规则文件 .agents/notes/README.md 把它们编码进路径：{lifecycle}/{class}/yyyy-mm-dd-topic-title.md。

类别是闭集，定义在 scripts/agent-note-tree.ts：

11/** The closed set of active Agent Note lifecycles (top-level folders under .agents/notes/). */
12const AGENT_NOTE_LIFECYCLES = ['proposed', 'implemented', 'rejected'] as const
14/**
15 * The closed set of Agent Note classes (nested folder under each lifecycle). Adding a
16 * class is a deliberate act: extend this list AND the README's Classification
17 * section. The gate rejects any folder not listed here.
18 */
19export const AGENT_NOTE_CLASSES = ['feature', 'bug-fix', 'simplification', 'architecture', 'process', 'testing'] as const六类，加一类需同时改 README

段落骨架是强制的

每篇笔记的骨架由 scripts/verify-agent-note-format.ts（94 行）强制执行。这份门本身就是「把文档规则变成编译错误」的典范：

12/** The date these format rules took effect; the grandfather comment is valid only before it. */
13const FORMAT_ADOPTED = '2026-07-05'
15/** The exact comment a pre-format Agent Note carries in place of `## Alternatives considered`. */
16const GRANDFATHER = '<!-- agent-note-format: alternatives-not-recorded (pre-format Agent Note) -->'
18/** The retired debt marker that flagged pre-format bodies; banned so it cannot creep back. */
19const LEGACY_MARKERS = ['XXX: legacy ADR/RFC body format', ...]
21/** Status-line grammar per lifecycle folder. */
22const STATUS: Record<string, RegExp> = {
23  proposed: /^Status: proposed$/,
24  implemented: /^Status: implemented$/,
25  rejected: /^Status: rejected — .+$/,   // 唯一带内容的状态
26}
28/** Required `##` headings per lifecycle, beyond the universal `## Problem` opener. */
29const REQUIRED: Record<string, string[]> = {
30  proposed: ['## Proposal', '## Acceptance criteria', '## Risks'],
31  implemented: ['## Decision', '## Consequences'],
32  rejected: ['## Proposal'],
33}
35/** Headings banned in `implemented/` — proposal-era spec-speak per the slop checklist. */
36const BANNED_IMPLEMENTED = /^## (?:Proposal\b|Plan\b|Migration plan\b|Acceptance criteria\b)/i实现后不许再用「计划」语气

Alternatives considered 是必填的

归档是单向的

archived/ 树（640 篇）被永久冻结：不许编辑、翻译、重排版、更新、移动或删除。scripts/verify-archived-agent-notes.ts 强制一套追加式的内容清单（append-only frozen-content manifest）——归档时的哈希被记录下来，之后任何改动都会被发现。

归档本身有明确判据（README 的 Archiving 章节）：当已发布的决策已经完成、且其理由不太可能指导未来工作时。反面清单同样明确——如果「替代方案、所有权边界、否定性保证、持久或线上语义、安全规则、重新引入的条件」中任何一项仍然有用，就保持活跃。工具是 dsh-archive-agent-notes skill，README 特意强调：不要用字数、年龄或配额来判据。

§3Skill：可复用的工作流

.agents/skills/ 下有 14 个 skill。它们不是产品文档——按 docs/AGENTS.md 的分层表，skill 这个 tier 的职责是「可复用的工作流与专门的决策标准」，明确不放产品与运行时契约（那些属于 docs 或源码）。

一个 skill 长什么样

每个 skill 是一个目录，核心是 SKILL.md，带 YAML frontmatter。以 dsh-pre-push-checks 为例（136 行）：

1---
2name: dsh-pre-push-checks
3description: Use before pushing, force-pushing, marking ready for review, or claiming checks pass on a deepseek-harness branch, and immediately after gh stack sync publishes rewritten branches, to select the smallest tests and checks that cover the outgoing or just-published diff without reflexively running the full repository suite.「何时用」写在 description 里
4---
6# DSH Pre-Push Checks
10## Inspect the outgoing change
27## Select relevant evidence
52### Focus unit coverage on the affected source
75## Full local rehearsal
79## Protect history-rewriting pushes
96## Handle failures
107## Push procedure

14 个 skill 的全貌

形态差异值得注意：多数 skill 是纯 Markdown 流程，但 dsh-doc 配了模板库、record-browser-gif 配了 Python 编码脚本。skill 可以携带任意辅助资源——加载器只认 SKILL.md，目录里的其他文件由 skill 自己引用。

唯一带额外 frontmatter 的 skill

dsh-translate-docs 的 frontmatter 是 6 行而不是 4 行：

1---
2name: dsh-translate-docs
3description: Manually run the extended DeepSeek Harness bilingual-document workflow, ...
4disable-model-invocation: true模型不能自己调用它
5user-invocable: true只有用户能调用
6---

.claude/skills 也是符号链接

§1 提到 CLAUDE.md → AGENTS.md 的符号链接。同一招在这里又用了一次：

$ git ls-files -s .claude/skills
120000 2b7a412b8f... 0	.claude/skills

$ cat .claude/skills
../.agents/skills

Claude Code 从 .claude/skills/ 发现 skill，而这个仓库把整个目录链接到 .agents/skills/。同一份 skill 定义同时服务两个工具，不存在副本。这是「一个事实一个家」第三次出现（前两次是 CLAUDE.md 和文档分层）。

§4把文档规则变成校验门

这是整套基建里最工程化的一环。scripts/ 下有 257 个 TypeScript 脚本，其中 55 个是 verify-* 门。文档相关的约 35 个聚合在 pnpm run doc-sync 里。

文档标准的关键条目

docs/AGENTS.md（76 行）定义标准，其中几条被门直接执行：

字数预算是硬约束

scripts/doc-budgets.manifest.json 是一份很短的清单——它只约束「常备文档」：

1{
2  "AGENTS.md": 1950,
3  "docs/AGENTS.md": 1320,
4  "docs/architecture.md": 2400,
5  "docs/cordis-primer.md": 600,
6  "docs/defensive-patterns.md": 550,
7  "docs/testing.md": 1350,
8  "packages/AGENTS.md": 750,
9  "packages/README.md": 994
10}

门红了怎么办？docs/AGENTS.md 给的是一套有序的处置流程（第 52-58 行），顺序本身表达优先级：

1. Relocate——内容属于别的 tier，搬过去，必要时留一行链接
2. Condense——内容确实该在这，但可以更短
3. Raise——只有文字确实需要空间时才提高上限，且要在 PR 里论证

slop 清单：可执行的编辑标准

docs/AGENTS.md 的第 60-72 行是一份「slop 清单」——不是模糊的「写得好一点」，而是九条可检查的病症：

• 重复的规则：搜一个有辨识度的短语；只留一个家，其余改成链接
• 历史出现在不该出现的 tier：陈述当前事实 + 链接历史所有者
• 实现状态标注（「implemented!」「future: …」）：状态会腐烂，仓库布局和 manifest 才是权威
• 手工重述的目录：源码或生成器才是权威
• 推理记录：逐步实现叙述、显然分支的证明、测试走查、被否决的本地替代方案
• 段落墙：一段塞了好几条规则和插入语
• 强调膨胀：处处加粗 = 什么都不突出
• implemented/ 笔记里的规格语言：「should」、迁移计划、验收清单

dsh-doc skill 把这份清单当作审计流程来跑。

§5闭环：指令如何进入模型

前面四节讲的是「仓库里有什么」。这一节讲这些东西怎么真正到达模型——答案就在 dsh 自己的代码里。有两条独立的注入链路：一条送 AGENTS.md，一条送 skill 目录。

链路 A：AGENTS.md → 上下文

负责的插件是 packages/context/agent-instructions（360 行）。模块注释一句话说清职责：

Workspace instruction loader for AGENTS.md-compatible files.
…tool touches project nested, changed, and removed instructions into the inbox.

11const DEFAULT_PROJECT_ROOT_MARKERS = ['.git'] as const
12const DEFAULT_INSTRUCTION_FILE_CANDIDATES = ['AGENTS.md', 'CLAUDE.md'] as const同一目录里两个都读
13const DEFAULT_LOCAL_INSTRUCTION_FILE_CANDIDATES = ['AGENTS.local.md', 'CLAUDE.local.md'] as const
14const DEFAULT_MAX_SOURCE_BYTES = 1_048_576

它的 README 把完整行为讲清楚了，其中三条对理解协同很关键：

• 首次请求时加载适用的链；
• 不持续监听外部编辑——而是成功的文件系统操作（read/write/edit）发现新出现的嵌套文件、或让后续的修改/删除变得可见；session resume 时重新对齐基线；
• 字节预算限制注入内容：更宽泛的文件先被省略，最具体的文件才会被截断；空链不添加任何东西。

链路 B：skill 目录 → <available_skills>

skill 的发现与注入走另一条链，实现也在仓库自己的代码里（这正是 23 页的主题）。解析 .agents/skills/ 的那一行在：

250        { path: join(projectRoot, '.dsh/skills'), source: 'project-dsh', rank: PROJECT_DSH_RANK, projectRoot },
251        { path: join(projectRoot, '.agents/skills'), source: 'project-agents', rank: PROJECT_AGENTS_RANK, projectRoot },本仓库的 12 个 skill 从这里被发现

发现之后，每个 SKILL.md 被解析（parseSkillFile，index.ts:797）：frontmatter 缺 name 或 description 就忽略整个文件，正文作为 content。然后 tool-skill 把它们送进模型：

226    const skills = snapshot.skills.filter(isModelInvocable)不可模型调用的被滤掉
227    const entries = catalogSourceEntries(skills, catalogDescriptionMaxLength)

这段跑在 agent/pre-step 监听器里（index.ts:213），产出的是一个 <available_skills> 块作为 user message。模型看到的是 skill 的名称与 description，不是正文——它要按 description 匹配，然后显式调用 skill 工具才拿到内容。这正是 description 为什么要写成「何时用」的原因。

闭环

仓库根 AGENTS.md（175 行常备命令）
  → agent-instructions 插件首次请求时读入
  → 作为 user/message 注入 session inbox（08 页 preStep 的 claim）
  → 进入模型上下文

.agents/skills/*/SKILL.md（12 个）
  → skill-filesystem 扫描 .agents/skills/（source: 'project-agents'）
  → tool-skill 在 agent/pre-step 渲染 <available_skills> 块
  → 模型按 description 匹配 → 调 skill 工具读正文

  → agent 按指令改代码
  → 推送前跑 dsh-pre-push-checks skill 选检查集
  → CI 跑 55 个 verify-* 门
  → non-trivial 改动必须附一篇 Agent Note
  → 决策沉淀回 .agents/notes/，供下一个 agent 查「为什么」

还有个细节值得注意：packages/AGENTS.md 里有一条规则专门管这件事——「Write model-facing contracts from the model's perspective」。它要求 prompt、tool schema、结果、诊断里只出现任务相关的概念，不带 UI、传输层或实现词汇。而 agent-instructions 注入的正是「模型可见文本」，所以这套指令文件本身也要遵守那条规则。规则递归地适用于写规则的文件。

§6这套做法的取舍

把 1028 篇决策记录、12 个 skill、55 个校验门当作一个设计来读，它选择的是什么？