企业官网建设流程全解析

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

本文以 docs/agents/domain.md 为核心，讲解 gsd-2 仓库中工程 Agent / Skill 在探索代码库之前应如何消费领域文档：先读哪些文件、缺失时如何静默处理、如何用词汇表约束输出语言、以及何时必须显式标记与 ADR 的冲突。读完本文，你将掌握一套可复制的领域文档阅读协议，并能在 issue 标题、重构提案、假设与测试命名中保持与项目领域词汇严格一致，避免"自造语言"导致的语义漂移。

领域文档消费的第一原则：先读文档，再探代码

gsd-2 是一个元提示（meta-prompting）、上下文工程与规格驱动开发（spec-driven development）系统，其代码库横跨packages/pi-coding-agent（auto-mode 编排）、packages/daemon、src/web等多个模块，领域术语密集且语义精确。domain.md的定位非常明确：它不是写给人类阅读者的入门教程，而是写给**工程 Skill（engineering skills）**的消费协议——当 Agent 被派去探索代码库、写 issue、提重构方案或命名测试时，必须先按协议消费领域文档，否则很容易用错术语、踩到过期的架构假设、甚至无意中推翻既有决策。

该协议的第一条规则是两条前置阅读：

• CONTEXT.md（仓库根目录）——它是本仓库的领域词汇表与"当前决策在生效中"的档案，是后续所有工作的术语与约束来源；
• docs/adr/——阅读你即将工作的区域所涉及的 ADR（架构决策记录）。

domain.md原文写道："Before exploring, read these:CONTEXT.mdat the repo root;docs/adr/— read ADRs that touch the area you're about to work in."

需要特别说明的是：本仓库中 ADR 的实际存放位置是 docs/dev/ 目录（docs/adr/目前为空），例如 ADR-014-auto-orchestration-deep-module.md、ADR-015-runtime-invariant-modules.md、ADR-016-worktree-safety-fail-closed.md、ADR-017-state-reconciliation-drift-driven.md 等 23 份决策记录都存放在docs/dev/下。阅读 ADR 时应以仓库实际布局为准，不必拘泥于文档中的约定路径。

典型的消费流程如下：

1. 阅读 CONTEXT.md，掌握领域词汇表与当前生效决策 2. 定位要工作的区域，阅读与之相关的 ADR（docs/dev/ADR-*.md） 3. 在 CONTEXT.md 词汇表的约束下进行探索、命名与提案 4. 输出若与既有 ADR 冲突，显式标记而非静默覆盖

缺失文件的静默策略：不报错、不预设，交给 producer skill 惰性补齐

一个反直觉但极其重要的协议条款是：如果上述文件不存在，静默继续（proceed silently），不要标记缺失，也不要主动建议立刻创建它们。

If any of these files don't exist, proceed silently. Don't flag their absence; don't suggest creating them upfront.

这背后的设计动机在domain.md中交代得很清楚：生产者技能（producer skill）/grill-with-docs会在术语或决策真正被解析出来的时候惰性创建这些文档（"creates them lazily when terms or decisions actually get resolved"）。也就是说，文档是探索的产物，而不是探索的前提——如果探索过程中没有产生任何需要固化的术语或决策，就没有必要为流程而制造文档。这是一种"按需生成"的文档纪律，与仓库的 ADR-003-pipeline-simplification 系列文档一贯强调的简化取向一致。

仓库中可以找到与此技能族相关的实现佐证：src/resources/skills/grill-me/SKILL.md 定义了grill-me技能——"一次一个问题"的访谈式审问，用于在讨论/规划阶段把计划中的每个决策分支问透，并把已解析的决策沉淀到.gsd/DECISIONS.md、M###-CONTEXT.md或S##-CONTEXT.md。其核心原则包括：

• 每次只问一个问题：并行提问会破坏决策之间的依赖顺序；
• 每个问题附带推荐答案：用户的工作是确认、推翻或改道，而不是从零生成答案；
• 先查代码再提问：如果答案已存在于仓库的约定、既有模式或先前决策中，找到它并引用它，而不是发起提问。

此外，src/resources/extensions/gsd/skill-manifest.ts 中的单元类型技能白名单（per-unit-type skill allowlist）把grill-me挂载到research-milestone、plan-milestone、plan-slice、refine-slice、replan-slice等规划类单元上——也就是说，在 auto-mode 的规划热路径上，"追问决策"是被系统化支持的技能，与domain.md描述的"惰性补齐文档"形成闭环：先探索/审问出术语与决策，再视需要写入领域文档。

单上下文布局（single-context layout）：一份词汇表统摄全仓库

domain.md明确声明本仓库采用单上下文布局（single-context layout），而不是按模块拆分多份独立领域文档。这意味着全仓库共享一份CONTEXT.md作为唯一的领域事实来源：

/ ├── CONTEXT.md ├── docs/adr/ │ ├── 0001-...md │ └── 0002-...md └── src/

单上下文布局的直接推论是：术语定义只有一份，不存在"同一概念在不同模块各有说法"的双轨制。当你在 issue 标题、重构提案、假设或测试名中命名一个领域概念时，必须使用CONTEXT.md中定义的那个词，而不要漂移到词汇表明确回避的同义词。

词汇即契约：使用词汇表的词汇，而非自造语言

这是domain.md中最具操作性的条款：

When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined inCONTEXT.md. Don't drift to synonyms the glossary explicitly avoids.

落地到本仓库，CONTEXT.md 的Domain glossary定义了诸如以下的高精度术语：

这些术语不是随意选定的标签，而是与具体模块实现一一对应。例如CONTEXT.md的 "Architecture terms adopted for this area" 明确写出了术语到模块的映射：State Reconciliation module拥有 drift catalog（检测器与幂等修复），在每次 Dispatch 决策或 worker 生成之前运行reconcileBeforeDispatch，持久性或修复失败的 drift 会抛出ReconciliationFailedError交给 Recovery Classification（kindreconciliation-drift）。在 ADR-017-state-reconciliation-drift-driven.md 中可以看到这一设计的完整推演。

domain.md还给出了一个重要的信号判据：如果你需要的概念尚未进入词汇表，那有两种可能——

1. 你在发明项目并不使用的语言（此时应重新考虑，因为新词无法被仓库中的既有代码与文档检索到）；
2. 词汇表确实存在空缺（此时应记录缺口，交给/grill-with-docs处理）。

这两者的处理方式截然不同，区分它们本身就是领域文档消费能力的一部分。对 Agent 而言，命名先查词汇表、拿不准就检索CONTEXT.md中的对应模块术语，是避免"同名异义"的最有效手段。

ADR 冲突必须显式标记，而非静默覆盖

工程探索最危险的场景之一是：Agent 基于对现状的观察提出了一个方案，却没有意识到该方案与既有的架构决策相抵触。domain.md对此给出了硬性要求：

If your output contradicts an existing ADR, surface it explicitly rather than silently overriding.

并给出了推荐的标准格式（引用块标记冲突 + 说明值得重新讨论的理由）：

> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

这种"显式标记"在 gsd-2 的决策体系里具有实际约束力。CONTEXT.md的 "Current decision in force" 段落本身就是一连串 ADR 的强制引用，例如：

• Auto-mode 架构应围绕单一 Auto Orchestration 模块深化，接口为start(sessionContext)/advance()/resume()/stop(reason)/getStatus()——见 ADR-014-auto-orchestration-deep-module.md；
• 运行时不变式应深化为四个一等模块：State Reconciliation、Worktree Safety、Recovery Classification、Tool Contract——见 ADR-015-runtime-invariant-modules.md；
• Worktree Safety 对源码写入型单元应 fail-closed（工作树缺失/未注册/分支不符/租约不持有等场景不得静默降级为项目根目录写源）——见 ADR-016-worktree-safety-fail-closed.md；
• State Reconciliation 应 drift-driven，reconcileBeforeDispatch在所有 pre-dispatch 与 pre-spawn 站点严格闭包调用，re-derive 上限 2 轮——见 ADR-017-state-reconciliation-drift-driven.md。

如果你的输出与上述任何一条相抵触，domain.md的协议要求你把它作为冲突显式摆出来，而不是悄悄绕过——这正是 ADR-010-pi-clean-seam-architecture 等文档所倡导的"决策可审计、推翻需论证"工程文化的落地形态。

从源码看 CONTEXT.md：一份活的领域档案与三诊总结

CONTEXT.md并非静态词汇表，它同时记录了当前实现快照（Current implementation snapshot）与三诊综合（Triage synthesis），这两部分对工程 Skill 探索代码库极具指导价值：

• 实现快照确认了auto.ts已通过createWiredAutoOrchestrationModule(...)接入具体的 Auto Orchestration 模块，会话状态经AutoSession.orchestration携带编排状态，运行时快照导出orchestrationPhase、orchestrationTransitionCount、orchestrationLastTransitionAt遥测字段——这些字段名可以直接作为测试断言与问题诊断的关键字使用。
• 三诊综合（2026-05-05）则总结了反复出现的失败簇：编排状态一致性、工作树卫生与工具面契约。其中列出了常见问题族（DB 与磁盘产物状态漂移、幽灵/非法工作树根、恢复策略缺口、提示词/工具/schema 错位、平台集成边界、遥测盲点）和优先级审查焦点（派发与状态派生不变式、恢复与错误分类、工作树安全边界、提示词-策略-工具对齐、迁移与对账、可观测性完备性），并给出了重构顺序：先做 Auto Orchestration adapter depth pass，再实现 State Reconciliation 与 Worktree Safety，随后是 Recovery Classification，最后是 Tool Contract。

CONTEXT.md末尾的Standing review checklist是工程 Skill 在每次提出方案时都应自问的问题，例如：

• DB 状态是否权威？若是，磁盘→DB 的对账在哪里保证？
• 该单元能否派发到非法的 basePath/worktree 并仍能修改产物？
• retry/stuck-loop 计数器在 pause/resume 边界是否稳定、是否按单元身份一致键控？
• 提示词是否要求了当前策略禁止的工具或写入？
• 工具 schema/文档不匹配是否会诱发重复无效调用？
• 每个异常停止路径是否产生独立的 reason code 与可执行的修复建议？

这套检查清单与 docs/agents/triage-labels.md（五种三诊角色到 issue 标签的映射）和 docs/agents/issue-tracker.md（ghCLI 操作约定）共同构成 gsd-2 的"领域文档 → 三诊 → 问题追踪"完整链路：先按词汇表写出语义正确的 issue 标题与标签，再按gh issue create -R gsd-build/gsd-2等命令落入追踪器。

落地检查清单：如何执行这份领域文档协议

将domain.md的规则压缩为可在每次探索任务前执行的清单：

1. 先读文档：读仓库根 CONTEXT.md，再读与目标区域相关的 docs/dev/ 下 ADR（本仓库 ADR 实际位于docs/dev/，docs/adr/为空）；
2. 缺失即静默：文档不存在时不报错、不主动建议创建，仅在真正解析出术语/决策时由 producer skill（如grill-me）惰性沉淀；
3. 命名先用词汇表：issue 标题、重构提案、假设、测试名中的领域概念一律使用CONTEXT.md定义的术语，不发明同义词；
4. 缺口双通道：概念未入词汇表时，判断是自造语言（重新考虑）还是真实缺口（记给/grill-with-docs）；
5. 冲突显式标记：输出与既有 ADR 相抵触时，用> _Contradicts ADR-xxx (…) — but worth reopening because…_的格式显式声明，而非静默覆盖；
6. 用检查清单自审：以CONTEXT.md的 Standing review checklist 逐条验证方案，确保对账、工作树安全、重试计数、策略对齐、退出原因等维度全部闭合。

遵循这份协议，工程 Skill 才能在探索 gsd-2 这样术语密度高、决策链长的代码库时，既保持术语上的"领域一致"，又保持决策上的"架构可审计"——这正是domain.md作为领域文档消费规范的全部价值所在。

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用