repo文档如何治理? 我目前是做一个功能验证写一个临时spec,存放在spec下 并把实现功能,实习过程中的确实 确实存在的缺陷 待补充的功能作为md标记日期放到ADR目录中 实现完功能后就删掉spec

回复 群友 2236： 你这套做法有个明显的问题：spec 用完就删，然后靠 ADR 记录“确实存在的缺陷、待补充的功能”。这等于把两件性质不同的事混在同一个目录里，而且丢掉的是最有价值的那份材料。 先拆清楚三个东西的定位： spec 是“打算怎么做”，有生命周期，功能落地后它就该失效——这点你删得对，但删之前要留一份快照。因为三个月后有人问“为什么这个接口长这样”，答案往往在 spec 的取舍段落里，ADR 只记了拍板结果，没记当时的候选方案。 ADR 是“为什么这么选”，一条 ADR 只说一个决策，不可变，只能被新 ADR 取代（superseded），不能改内容。它有严格的适用条件：存在多个可选方案、影响后续架构、事后回看会有人问“为什么不选另一个”。如果一个决定换个工程师也会做同样选择，那不需要 ADR。 你写的“确实存在的缺陷、待补充的功能”不是 ADR。那是待办和已知问题，应该进 issue 或者一个 KNOWN_ISSUES / TODO 文件，带日期和出处。塞进 ADR 目录会让 ADR 变成大杂烩，半年后就没人看了。ADR 数量膨胀到几十条且质量参差，这个目录就失去检索价值。 然后是“临时 spec”这个说法里的风险。功能验证阶段写 spec 是对的，但你要区分验证型（spike）和实现型。spike 的目的是回答“这条路能不能走通”，它的产出是结论不是文档，做完记一段结论进决策记录就行，spec 本身确实可以删。实现型的 spec 才需要留档，而且要留“实现完成后回填的版本”——实际交付和原计划差在哪，这是最不容易重建的信息。 给你一套可落地的目录结构： docs/ adr/ 编号-标题.md，只放决策，带 status（proposed/accepted/superseded）和 supersedes 字段 specs/ 进行中的 spec；完成的移到 specs/archive/ 并在文件头标注已实现 + 实际差异 rfcs/ 可选，跨模块的变更提案，需要 review KNOWN_ISSUES.md 或直接开 issue，别放 docs README.md 里一句话说清每个目录放什么、什么时候写 几条治理规则，比目录结构更重要： 一是准入标准写在 README 里。什么算需要写 ADR，什么算需要写 spec，给三个判断句，别让人靠感觉。没有准入标准，最后就是有人什么都写、有人什么都不写。 二是编号和 supersede 关系必须显式。新 ADR 头部写 supersedes: 0007，旧的那条只改 status 字段，正文一个字不动。这样任何时候都能沿链条回溯，这是 ADR 唯一不可妥协的部分。 三是别让文档跟着代码一起腐烂。spec 里贴的代码片段一定会过时，所以 spec 只写接口契约和取舍，不贴实现。要贴就贴调用示例，且标明对应的 commit。 四是决策记录的粒度匹配你的项目规模。你一个人做 PA，ADR 不用走 RFC 流程，但每条控制在半页内，写清背景、候选方案、决定、后果。超过一页说明你在写设计文档，应该拆到 specs。 最后说个你现在的实际情况：你在做单人项目，文档治理的收益不在“给别人看”，在“给三个月后的自己看”和“给 agent 看”。你有 trace 和 eval 那套东西，其实可以把 badcase 和对应的决策打通——某条 ADR 是因为哪类失败才做的，记下来源，这比抽象的设计说明有用得多。 另外如果你想让 ca 长期在这个 repo 上工作，文档的写法要更“可被检索”：标题里带关键词，每条 ADR 第一段就是结论句，别写“随着业务发展我们逐渐发现”这种铺垫。这直接决定 agent 检索到之后能不能用。