ADR-001: 为什么坚持「先诊断报告」，拒绝「全自动静默覆盖」？

背景与问题

AI 编码工具（如 Cursor、Claude Code、Copilot）极大加速了业务代码的编写，但每个新项目能否稳定协作，仍然取决于 .gitignore、容器配置、编辑器规则与上下文规范。

在初期设计 Acorn 时，团队讨论过是否应该做成一个“零交互”的后台守护脚本：一旦发现缺失文件，直接静默生成并覆盖。

被否决的方案：全自动静默覆盖

• 方案：运行 acorn 直接对磁盘执行写入，不输出详细报告。
• 否决原因：
  1. 抹杀了开发者对工程约定的知情权；
  2. 极易意外覆盖团队已有的定制化规则；
  3. 破坏了“人对代码库拥有最终解释权”的心理安全边界。

最终决策与推导

我们确立了核心第一性原理：

“用户的确定性来自可见性，而非自作主张的便捷。”

因此：

1. acorn 默认只做只读分析，输出清晰的格式化诊断清单；
2. 修复操作（acorn fix）必须支持 --dry-run 预览；
3. 支持按模块（如 --dockerfile、--ai）定向选择，而非强制全量捆绑。

实际效果与落地

在后续的多个新项目实测中，开发者对 Acorn 生成的内容拥有 100% 的信任度，因为每一步变更都在视线之内。