Feishin 领域文档消费约定：Agent 如何基于 CONTEXT 与 ADR 探索代码库

桌面应用音视频前端【免费下载链接】feishinA modern self-hosted music player.项目地址https://gitcode.com/gh_mirrors/fe/feishin点击查看免费下载Feishin 仓库在 docs/agents/domain.md 中为工程 Agent 定义了一套领域文档消费规范在深入代码库之前先读取CONTEXT.md、CONTEXT-MAP.md与docs/adr/用术语表统一措辞并在输出与既有 ADR 冲突时显式标记。读完本文你将掌握这套约定的完整工作流、单上下文与多上下文两种目录布局的判别方法以及在本仓库当前尚无上述领域文件中如何正确静默前进避免误报或擅自新建文件。文档定位Agent 工作流中的领域知识入口docs/agents/domain.md是 Feishin 仓库面向 AI 协作的工程文档体系docs/agents/目录中的一员其职责是回答一个具体问题当 Agent 需要理解某个业务领域的术语与既定技术决策时应该去哪里读取、以什么顺序读取、以及如何用这些知识约束自己的输出。仓库根目录的 AGENTS.md 明确引用了这份文档Domain docsSingle-context: rootCONTEXT.mddocs/adr/. Seedocs/agents/domain.md.可见当前仓库自身即被 AGENTS.md 按单上下文single-context模型对待。与之并列的还有 docs/agents/architecture.md进程与构建边界、docs/agents/api.md服务端数据层、docs/agents/commits.md提交规范等共同构成 Agent 开工前的必读导航。探索代码库之前三份必读文件文档规定Agent 在动手探索任何业务代码之前应按优先级读取以下材料顺序文件作用1仓库根目录的CONTEXT.md单上下文仓库的领域总述包含术语表glossary与关键决策2仓库根目录的CONTEXT-MAP.md若存在多上下文仓库的地图指向每个上下文各自的CONTEXT.md需要逐个阅读与任务主题相关的条目3docs/adr/架构决策记录Architecture Decision Records。只读与当前工作区域相关的 ADR在多上下文仓库中还须检查src/context/docs/adr/下的上下文级决策关键的设计意图在于领域知识被显式地沉淀为CONTEXT.md与 ADR 两类文件Agent 不需要靠猜测还原业务意图而是直接读取项目维护者已经固化下来的语义。缺失即静默不报错、不擅建这是整套约定中最容易被误读的一条。文档明确要求若上述任一文件不存在静默继续proceed silently不要标记缺失、不要建议预先创建/domain-modeling技能通过/grill-with-docs与/improve-codebase-architecture两个入口触达会在术语或决策真正被解析时惰性创建这些文件。也就是说领域文档是按需生长的只有当任务真正涉及新的领域概念或需要固化某项决策时才由专门技能落地生成而不是在开工前为了形式而补齐。对 Agent 而言这一条避免了把文档缺失误判为阻断性错误也防止了在没有真实语义依据时凭空捏造领域文件。就当前仓库而言本文作者已核实根目录下并不存在CONTEXT.md或CONTEXT-MAP.md也不存在docs/adr/目录因此按上述规范应静默前进同时这也在客观上印证了该约定在本仓库的适用前提。另外skills-lock.json 中锁定的技能仅有caveman-commit、caveman-review、ponytail三项并未包含文档提到的/domain-modeling技能说明该技能属于仓库外的技能体系在本地按文档描述理解其职责即可。目录结构约定两种仓库形态的判别文档给出了两种可复现的目录形态用于 Agent 快速判断当前仓库属于哪一类单上下文仓库大多数仓库/ ├── CONTEXT.md ├── docs/adr/ │ ├── 0001-event-sourced-orders.md │ └── 0002-postgres-for-write-model.md └── src/多上下文仓库根目录存在CONTEXT-MAP.md/ ├── CONTEXT-MAP.md ├── docs/adr/ ← system-wide decisions └── src/ ├── ordering/ │ ├── CONTEXT.md │ └── docs/adr/ ← context-specific decisions └── billing/ ├── CONTEXT.md └── docs/adr/判别要点一目了然根目录是否存在CONTEXT-MAP.md。存在即为多上下文形态此时决策分两级存放——docs/adr/存放系统级决策src/context/docs/adr/存放上下文级决策不存在则为单上下文形态所有领域信息集中在根CONTEXT.md与docs/adr/。对照本仓库根目录既无CONTEXT-MAP.mdAGENTS.md 又明确按Single-context描述因此 Feishin 当前属于典型的单上下文形态其领域文档模型即为CONTEXT.mddocs/adr/。词汇纪律只使用术语表定义的领域概念文档要求当 Agent 的输出中涉及领域概念时——无论是一张 issue 标题、一份重构提案、一个假设还是一条测试命名——必须使用CONTEXT.md中定义的术语不得漂移到术语表明确回避的同义词。这条规则的深层意义在于维护领域语言的单一事实来源single source of truth如果每个 Agent 各自发明近义表述领域术语会迅速碎片化issue、代码、测试之间的可追溯性随之瓦解。文档还给出了一个重要的信号灯判断如果所需概念尚未出现在术语表中这本身就是一种信号——要么是 Agent 正在发明项目并未使用的语言此时应重新考虑要么确实存在真实的术语空缺此时应记录下来交给/domain-modeling处理。ADR 冲突必须显式标记而非静默覆盖当 Agent 的输出与既有 ADR 相矛盾时规范要求显式浮出而不是默默推翻。文档给出了标准的标注句式Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…这种提出质疑但标注出处的写法把冲突转化为可讨论的开放问题既保留了 ADR 作为既定决策的权威性又为合理的重新开放reopen留出了空间同时让人类维护者能一眼定位到被影响的决策编号与议题背景。落地建议在 Feishin 仓库中执行本约定将上述规范落到 Feishin 仓库的实际操作中可以整理为一份可执行的检查清单开工前检查根目录是否存在CONTEXT.md或CONTEXT-MAP.md并扫描docs/adr/若存在中与任务区域相关的 ADR缺失处理若上述文件不存在当前 Feishin 正是如此不报错、不新建直接进入正常探索流程由领域建模相关技能在真实解析到术语或决策时再惰性创建写作纪律在 issue 标题、重构提案、假设与测试命名中使用已固化的领域术语遇到术语空缺时记录而非发明冲突处理当改动与既有 ADR 冲突时在输出中显式引用决策编号如 Contradicts ADR-xxxx并说明值得重新讨论的理由。这套约定本身独立于 Feishin 的音乐播放器业务代码属于仓库工程协作层的通用规范可同样复用于任何以Agent 友好为目标的开源仓库领域文档的消费顺序、静默降级策略、术语纪律与 ADR 冲突协议四者共同构成了 Agent 与人类开发者之间稳定、可审计的语义协作框架。赞分享桌面应用音视频前端【免费下载链接】feishinA modern self-hosted music player.项目地址https://gitcode.com/gh_mirrors/fe/feishin点击查看免费下载相关推荐Reactive Resume 多上下文领域文档体系Agent Skills 如何消费 CONTEXT-MAP.md、CONTEXT.md 与 ADRReactive Resume 多上下文领域文档体系Agent Skills 如何消费 CONTEXT MAP.md、CONTEXT.md 与 ADR Rea前端后端AI 应用MCP 服务dsh-pluginVoiceStudio 领域文档消费规范Agent 如何读取 CONTEXT.md 与 ADRVoiceStudio 领域文档消费规范Agent 如何读取 CONTEXT.md 与 ADR VoiceStudio 是一个体量庞大的本地优先开源语音工作室人工智能语音音频本地部署MCP 服务桌面应用Bytebase 领域文档体系CONTEXT.md 术语表与 ADR 如何约束代码 Agent 的协作方式Bytebase 领域文档体系CONTEXT.md 术语表与 ADR 如何约束代码 Agent 的协作方式 Bytebase 仓库为参与开发的编码 Agent后端数据库数据治理认证鉴权数据库客户端上一篇EZSwipeController性能优化避免内存泄漏的3个关键点下一篇ESP32低功耗技巧yoRadio电池供电方案设计终极指南 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考