文档锚定方案访谈

解决设计中的“语义漂移”与“文档脱节”

在复杂系统的架构设计中，开发者常陷入术语模糊、上下文缺失以及代码实现与设计意图相悖的泥潭。传统的方案评审往往流于表面，难以触及依赖项的底层逻辑。grill-with-docs 旨在通过严格的访谈机制，解决设计树中决策依赖未明确、领域术语不一致以及代码与文档脱节的具体痛点，迫使设计者在落地前理清所有边界。

核心能力与关键步骤

该技能将 Matt Pocock 的访谈纪律与标准库验证工具结合，形成一套确定性的工作流：

• 逐题深度追问：每次仅提出一个问题，深度遍历设计树的每个分支，逐一解决决策间的依赖关系，并给出推荐答案。
• 术语锐化与对齐：在对话中实时对照 CONTEXT.md。当用户使用的术语与既有定义冲突或过于模糊时，立即指出并提议精确的规范术语。
• 场景压测与代码交叉引用：通过构造边缘场景测试领域关系的边界，并直接检查代码库以验证用户的描述。若发现代码行为（如取消整个订单）与口头描述（支持部分取消）相悖，将立即暴露矛盾。
• 内联更新与谨慎 ADR：术语一旦确定，立即内联更新至 CONTEXT.md（严格作为词汇表，不存实现细节）。仅在满足“难以逆转”、“缺乏上下文会令人困惑”且“存在真实权衡”三个条件时，才建议编写 ADR。
• 标准库验证器：内置 context_md_linter.py、adr_scanner.py 和 glossary_code_consistency.py，用于校验词汇表格式、ADR 编号完整性以及词汇与代码库的一致性。

适用边界与注意点

该技能高度依赖清晰的领域模型和上下文边界，适合中大型复杂系统的设计阶段。需注意 CONTEXT.md 必须保持纯粹，绝不能将其用作规格说明书或草稿。对于简单的 CRUD 应用或一次性脚本，这种深度的访谈与文档约束可能会显得过于繁重。