documentation-and-adrs

Overview

收紧范围:ADR 只记重大架构决策(数据模型 / API 契约 / 依赖升降级 / 弃用 / 选型改变),不记日常文档 / README / 注释。这些走项目自己的 AGENTS.md 或 .omo/notepads/<plan>/decisions.md(短期日常记录),不进 ADR。

Why: 一个项目动辄 50+ ADRs 时,绝大多数是噪音,真正影响未来工程师的反而被埋住。一个 ADR 应当 5 年后回头看仍能让新人决策一致。

When to write an ADR:

• 选了 X 而非 Y,且未来人很可能再问"为什么不是 Y"(不可逆 + 跨时间 + 跨人)
• 影响 1+ 模块的契约 / 依赖 / 数据流

When NOT to write an ADR:

• 单文件改名
• 修 typo / 注释 / 文档格式
• 只是"今天做的改动" — 那是 git log + commit message 的活
• 临时决定,且文档里说"未来回头看再考虑" — 那就别写

When to Use