多表面工具约定

面向下游贡献者的规范性权威参考。 本文档镜像项目规范中的多表面工具约定章节（规范 §0.6 + §2.8 + §4.7）；它是随已发布仓库一同提供的独立参考。架构理由记录于 ADR-0003。

1. 为什么是复数Copy Anchor Link

现代工程表面会被多个工具触及——聊天控制台、IDE 内补全引擎、结对编程伙伴，以及拉取请求评审器。每个工具都读取自己的规范配置文件。如果项目只提供一个这样的文件，其余运行时就会依据未声明的约定悄然各行其是；缺失的仓库内记忆会立即泄漏。

缺失某个表面的代价是机器生成代码中的无声漂移——这是最糟糕的一类缺陷，因为它在无形中累积。每个机器生成的制品都会加剧分歧；等到人类评审者发现矛盾时，代码库已经承载了数周不一致的约定。

就部署现实而言，工具运行时配置是复数的。已发布的生态系统必须（MUST）提供 §3 中的三个强制表面：AGENTS.md、一份面向聊天控制台运行时的行为记忆文件（CLAUDE.md），以及一份面向 IDE 内补全运行时的仓库范围指令文件。这些表面必须（MUST）相互一致——没有矛盾，没有漂移——并且必须（MUST）共同编码相同的纪律。

2. 一致性契约Copy Anchor Link

范围内（§3）的每个约定表面都是表达项目单一约定规范的一个通道。该规范被分解为：

• 共享章节——计划纪律、结构化询问（或表面等价物）、作者署名头、命名、反模式、情态层级。这些章节必须（MUST）出现在每个必需的表面中，并且必须（MUST）在各表面之间语义等价。
• 表面专属章节——能力框定、工具调用模式、代码生成与聊天之间的差异。这些章节在各表面之间可以（MAY）不同，但不得（MUST NOT）与共享章节相矛盾。

multi-surface-coherence 校验器（§7）在每次 CI 运行和 pre-commit 时运行，以断言该契约。

这些表面是表达同一个规范的不同通道。共享章节必须（MUST）在各表面之间匹配——在语义上匹配，并在可能时也在词面上匹配。表面专属章节不得（MUST NOT）与共享章节相矛盾。

3. 范围内的表面Copy Anchor Link

对于本仓库，选择启用的表面是声明清单夹具（tests/fixtures/multi-surface-claims.yaml）在 optional-in 下列出的那些表面。未使用的厂商专属根配置是有意缺席的；只有当某个工具是本仓库的活跃编辑表面时，才会添加该工具专属的配置文件。

4. IDE 内指令文件的章节清单Copy Anchor Link

.github/ 下的仓库范围指令文件必须（MUST）按以下顺序包含下列章节（每个章节都使用下方给出的确切标题文本；章节正文是撰写而成的，而非由模板套印，但每个章节都必须（MUST）覆盖所列的声明）：

1. Project Context——一段话：本仓库是什么、谁在使用它、它的顶层形态。具体；不做营销。
2. Coding Conventions——命名、情态层级、frontmatter、Markdown 风格，以及在偏离默认值之处的语言专属风格要点。

3. File Headers——运行时生成的每个文件都必须（MUST）按照 site/content/docs/reference/authorship-header.mdx，以规范的单行 SPDX-License-Identifier: MIT 开头，并采用与文件类型匹配的注释变体。指向 scripts/inject-header.* 和 site/content/docs/reference/authorship-header.mdx 的指引。

4. Plans Discipline——运行时不得（MUST NOT）生成会写入工具配置目录（例如 ~/.claude/plans/ 或 ~/.codex/.plans/）或任何其他全局计划位置的代码或脚本。规划制品按照 site/content/docs/reference/plans-discipline.mdx 进入 <project-root>/.apothem/plans/（旧有的 <project-root>/.plans/ 树通过 apothem migrate-workspace 升级）。
5. Structured Inquiry Behavior——当运行时不确定时，它不得（MUST NOT）悄然捏造。它转而插入一个清晰标记的澄清块（例如一条 # TODO(clarify): <question> 注释），并在表面允许的地方于聊天中提出该问题。不发明 API，不发明模型名称，不发明文件路径。
6. Forbidden Patterns——明确的禁止事项：不用营销形容词，不用含糊的填充词，不留 console.log 调试残渣，不硬编码指向用户主目录的绝对路径，不提交机密，不提交 .apothem/plans/（或旧有的 .plans/）下的文件，不与规范的项目指令文件相矛盾。
7. Output Format——生成的代码/文字符合统一的对话式输出约定：确定性、统一分节、密度、摘要纪律、引用。对于代码：公共表面有文档，在语言支持类型之处带类型，在存在测试脚手架之处经过测试。
8. Review Checklist——评审者（人类，或处于 PR 评审模式的运行时）在批准之前必须（MUST）核实的内容：头部存在、命名合规、没有 .apothem/plans/ 写入、与规范的项目指令文件没有矛盾、校验器在本地为绿色。
9. Pointers——指向 AGENTS.md、CLAUDE.md、site/content/docs/reference/plans-discipline.mdx、site/content/docs/reference/authorship-header.mdx、本约定文档、src/apothem/schemas/ 和 CONTRIBUTING.md 的链接。

该文件以规范的作者署名头 SPDX 行（Markdown 变体）开头，依据 site/content/docs/reference/authorship-header.mdx §2——可见还是不可见，取决于项目所选的头部可见性策略。

IDE 内指令文件不是 AGENTS.md 或 CLAUDE.md 的逐字副本。AGENTS.md 是规范的项目指令表面，CLAUDE.md 为 Claude Code 镜像它，而 IDE 内指令文件则以编辑器内代码补全运行时的口吻撰写，该运行时发出由开发者接受或拒绝的建议。信息（纪律、约定、反模式）是相同的；框定则不同。

5. 声明清单参考Copy Anchor Link

位于 tests/fixtures/multi-surface-claims.yaml 的夹具列举了每个共享声明。示例条目：

- id: plans.location
  claim: "Planning artifacts live at <project-root>/.apothem/plans/, never inside a harness configuration directory."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
  optional-in: [site/content/docs/architecture/agents.mdx, .cursorrules]
- id: header.canonical
  claim: "Every applicable new file begins with the canonical SPDX-License-Identifier: MIT header line, in the comment family matching the filetype."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
- id: ambiguity.resolution
  claim: "Ambiguity is surfaced via the structured-inquiry channel or a clearly-marked TODO(clarify); never silently invented."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
# ... (one entry per shared claim)

校验器解析每个表面，尝试找出每个声明在该表面上的存在位置（通过标题层级 + 正文关键词提取），并在出现任何缺失或矛盾时失败。

6. 调和规则Copy Anchor Link

当检测到两个表面在某个共享声明上相互矛盾时，默认的调和方式是：

AGENTS.md 是规范的项目之声。任何与之矛盾的表面都会被重写，以适合该表面的框定方式镜像 AGENTS.md 的语义。

只有带有一个明确的文件内 <!-- coherence-override: <claim-id> --> 标记、且该标记指向一份解释这一刻意分歧的 ADR 时，才允许表面专属的覆盖。覆盖标记本身被列举在校验器的允许列表中，并出现在 CI 报告中。

对于本仓库，已批准的调和策略是 agents-md-wins：AGENTS.md 是规范的，每个活跃的工具镜像都保持语义等价。

7. 校验器Copy Anchor Link

三个校验器共同实现该一致性契约：

- in-IDE-instructions-presence    (src/apothem/conformity/copilot_instructions_presence_grep.py)
- multi-surface-coherence         (src/apothem/conformity/multi_surface_coherence_grep.py)
- license-author-consistency      (src/apothem/conformity/license_author_consistency_grep.py)

• 第一个断言 IDE 内指令文件存在、可解析、包含 §4 中列举的每个规范章节，并以规范的 SPDX-License-Identifier: MIT 行（Markdown 变体）开头。
• 第二个解析每个表面的规范章节；断言共享章节在一个规范化比较器下相互一致（不区分大小写、容忍空白差异、允许词面改写，但要求在夹具定义的声明清单上语义等价）。
• 第三个仅断言根目录的 LICENSE 带有一行可解析的 Copyright (c) <name>。它不读取逐文件头部，这些头部不带作者名。

8. 表面生命周期Copy Anchor Link

• 添加表面。 操作者通过结构化询问通道选择启用。生成器依据声明清单撰写该表面并运行校验器；如需表面专属覆盖，则提交一份 ADR。
• 移除表面。 结构化询问确认移除，ADR 记录理由，校验器的 required-in 列表随之修订。
• 漂移检测。 任何偏离声明清单的提交都会被 pre-commit / CI 拒绝；该提交的作者会重写该表面，以恢复一致性。

另请参阅Copy Anchor Link

• ADR-0003——架构理由、考虑过的替代方案。
• tests/fixtures/multi-surface-claims.yaml——规范的声明清单夹具。
• AGENTS.md——规范的项目之声。
• CLAUDE.md——Claude Code 镜像。
• site/content/docs/reference/plans-discipline.mdx——计划纪律共享声明的规范参考。
• site/content/docs/reference/authorship-header.mdx——作者署名头共享声明的规范参考。
• 项目规范 §0.6 + §2.8 + §4.7——此处所镜像的完整规范文本。