人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载本文以 docs/agents/domain.md 为核心讲解 gsd-2 仓库中工程 Agent / Skill 在探索代码库之前应如何消费领域文档先读哪些文件、缺失时如何静默处理、如何用词汇表约束输出语言、以及何时必须显式标记与 ADR 的冲突。读完本文你将掌握一套可复制的领域文档阅读协议并能在 issue 标题、重构提案、假设与测试命名中保持与项目领域词汇严格一致避免自造语言导致的语义漂移。领域文档消费的第一原则先读文档再探代码gsd-2 是一个元提示meta-prompting、上下文工程与规格驱动开发spec-driven development系统其代码库横跨packages/pi-coding-agentauto-mode 编排、packages/daemon、src/web等多个模块领域术语密集且语义精确。domain.md的定位非常明确它不是写给人类阅读者的入门教程而是写给**工程 Skillengineering 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 youre 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. 定位要工作的区域阅读与之相关的 ADRdocs/dev/ADR-*.md 3. 在 CONTEXT.md 词汇表的约束下进行探索、命名与提案 4. 输出若与既有 ADR 冲突显式标记而非静默覆盖缺失文件的静默策略不报错、不预设交给 producer skill 惰性补齐一个反直觉但极其重要的协议条款是如果上述文件不存在静默继续proceed silently不要标记缺失也不要主动建议立刻创建它们。If any of these files dont exist, proceed silently. Dont flag their absence; dont 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. Dont drift to synonyms the glossary explicitly avoids.落地到本仓库CONTEXT.md 的Domain glossary定义了诸如以下的高精度术语术语定义要点Auto Orchestrationauto-mode 单元从启动到完成的运行时协调包括派发与停止/恢复行为单元执行失败恢复由 Recovery Classification 模块分类Unit最小的可执行工作流步骤如 plan slice、execute task、complete sliceDispatch decision选择下一个 Unit 及其理由与前置条件Recovery decision运行时失败后的 retry / escalate / abort 选择Closeout Boundary Stop前台运行在第一个 task、slice 或 milestone 收尾边界后停止并在终端留下持久的收尾面DriftDB 行、磁盘产物与内存状态之间的状态形状不匹配且有已知修复与需要人工介入的终端条件blocker相区分DriftRecord类型化、可被机器处理的单个 drift 实例信号这些术语不是随意选定的标签而是与具体模块实现一一对应。例如CONTEXT.md的 Architecture terms adopted for this area 明确写出了术语到模块的映射State Reconciliation module拥有 drift catalog检测器与幂等修复在每次 Dispatch 决策或 worker 生成之前运行reconcileBeforeDispatch持久性或修复失败的 drift 会抛出ReconciliationFailedError交给 Recovery Classificationkindreconciliation-drift。在 ADR-017-state-reconciliation-drift-driven.md 中可以看到这一设计的完整推演。domain.md还给出了一个重要的信号判据如果你需要的概念尚未进入词汇表那有两种可能——你在发明项目并不使用的语言此时应重新考虑因为新词无法被仓库中的既有代码与文档检索到词汇表确实存在空缺此时应记录缺口交给/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.mdWorktree Safety 对源码写入型单元应 fail-closed工作树缺失/未注册/分支不符/租约不持有等场景不得静默降级为项目根目录写源——见 ADR-016-worktree-safety-fail-closed.mdState Reconciliation 应 drift-drivenreconcileBeforeDispatch在所有 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.mdghCLI 操作约定共同构成 gsd-2 的领域文档 → 三诊 → 问题追踪完整链路先按词汇表写出语义正确的 issue 标题与标签再按gh issue create -R gsd-build/gsd-2等命令落入追踪器。落地检查清单如何执行这份领域文档协议将domain.md的规则压缩为可在每次探索任务前执行的清单先读文档读仓库根 CONTEXT.md再读与目标区域相关的 docs/dev/ 下 ADR本仓库 ADR 实际位于docs/dev/docs/adr/为空缺失即静默文档不存在时不报错、不主动建议创建仅在真正解析出术语/决策时由 producer skill如grill-me惰性沉淀命名先用词汇表issue 标题、重构提案、假设、测试名中的领域概念一律使用CONTEXT.md定义的术语不发明同义词缺口双通道概念未入词汇表时判断是自造语言重新考虑还是真实缺口记给/grill-with-docs冲突显式标记输出与既有 ADR 相抵触时用 _Contradicts ADR-xxx (…) — but worth reopening because…_的格式显式声明而非静默覆盖用检查清单自审以CONTEXT.md的 Standing review checklist 逐条验证方案确保对账、工作树安全、重试计数、策略对齐、退出原因等维度全部闭合。遵循这份协议工程 Skill 才能在探索 gsd-2 这样术语密度高、决策链长的代码库时既保持术语上的领域一致又保持决策上的架构可审计——这正是domain.md作为领域文档消费规范的全部价值所在。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐Saleor 领域文档治理指南如何为 AI 工程 Agent 组织 CONTEXT.md 与 ADR 文档Saleor 领域文档治理指南如何为 AI 工程 Agent 组织 CONTEXT.md 与 ADR 文档 Saleor 是一个高性能、可组合的无头电商 AP后端电商MAS 免费激活 Windows 与 Office 完整指南从下载到完成只需 3 步MAS 免费激活 Windows 与 Office 完整指南从下载到完成只需 3 步 Microsoft Activation ScriptsMAS是一个操作系统Reactive Resume 多上下文领域文档体系Agent Skills 如何消费 CONTEXT-MAP.md、CONTEXT.md 与 ADRReactive Resume 多上下文领域文档体系Agent Skills 如何消费 CONTEXT MAP.md、CONTEXT.md 与 ADR Rea前端后端AI 应用MCP 服务dsh-plugin上一篇RPA-Python与radon集成代码复杂度分析自动化的完整指南下一篇CANN ops-transformer 中 MoeFinalizeRoutingV2 算子MoE 专家输出加权合并的实现与调用全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
