架构决策与文档

为什么代码注释解决不了架构问题

当你在三个月后翻看旧代码，看到一段用 Redis 做缓存的实现，你能轻易看懂它做了什么。但你很难从代码本身得知，当时为什么选择 Redis 而不是 Memcached，或者当时遇到了哪些网络延迟的约束。这种「背景上下文」的丢失，会导致新加入的工程师或者 AI Agent 重复讨论已经定论的问题，甚至推翻当初精心设计的决策。

此外，团队常犯的另一个错误是文档与代码脱节。如果文档只是重复代码的逻辑，它很快就会变成噪音。真正有价值的文档应当解释意图（Intent）和约束，而不仅仅是复述实现细节。

这个技能如何工作

该技能的核心在于建立一套「决策记录」与「上下文说明」的规范，具体包含以下关键步骤：

• 识别决策点：并非所有代码都需要文档。该技能会指导你识别何时需要撰写 Architecture Decision Record (ADR)，例如选择核心依赖、设计数据模型或确定 API 架构时。
• 遵循现有约定：在创建 ADR 之前，技能会先检查仓库中是否已有既定规范（如 .adr-dir 配置或现有文档结构）。遵循 docs/decisions/ 或特定的编号惯例，比引入一套全新的标准更重要。
• 记录生命周期：旧的 ADR 不会被删除，它们代表了历史事实。当决策发生改变时，你需要写一个新的 ADR 来引用并取代旧的记录。
• 编写面向 Agent 的说明：通过更新 CLAUDE.md 或类似的规则文件，确保 AI 代理能理解项目约定和已知的「坑」（Gotchas），从而避免重复犯错。

适用边界与注意点

虽然文档极其重要，但滥用会适得其反。该技能明确区分了「解释原因」和「复述代码」的界限。不要为简单的逻辑编写冗长的注释，也不要试图为一次性的原型代码撰写详尽的 ADR。如果代码本身已经不言自明，过度的文档反而会增加维护负担。