原文：https://addyosmani.com/blog/automated-decision-logs/
作者：Addy Osmani
译者：ChatGPT 4 Turbo
像 Bolt、v0、Replit Agents、Cursor、甚至 GitHub Copilot 这样的 AI 代码生成工具承诺提升生产力。但将它们视为黑箱是长期痛苦的配方。特别是在复杂项目中，我们需要理解 AI 做出某些选择的 原因，而不仅仅是它输出了什么代码。这就是自动化决策日志的用武之地。
自动化决策日志（ADL）是一种针对性的、低开销的机制，用于捕捉重要的 AI 驱动代码修改背后的原因。把它想象成不那么全面的日志，更像是一套结构化的笔记，自动生成的。
实现：
设置并维护决策日志相对直接：
- 项目本地日志： 在你的仓库中加入像
fyi.md或ai_decisions.log这样的文件。 - 明确提示： 明确指导你的 AI。比如：
确保在 fyi.md 中记录你做了什么、为什么以及怎么做的。保持更新。
Make sure to keep a log of what, why and how you did what you did in fyi.md. Keep it updated.
- 核查是关键： 不要盲信，要核查。定期审查日志。确保其准确性是你的责任。你可能需要调整提示，以获得所需的细节级别和清晰度。
以下是为我的一个 Bolt 项目生成此类日志的示例：
为什么麻烦？实际好处
记录 AI 编码决策的假设优点有几个，但让我们带着批判的眼光来审视它们：
- 加速入门（潜在）： 这个想法是，新团队成员可以审查日志来理解项目的历史和逻辑。这 可能 比挖掘代码要快，特别是对于了解 AI 选用的不寻常的架构选择或库的上下文。然而，这在很大程度上依赖于 AI 提供 有用的 解释，而不仅仅是冗长的总结。
- 调试辅助（如果做得正确）： 当某些东西出故障时，拥有为什么生成特定代码片段的日志可能会有帮助。假设这个意图一开始就是连贯的，这可能会节省你反向工程 AI 意图的时间。
- 可追溯性（有注意事项）： 将代码更改与最初的需求或用户故事相链接是有价值的。一个维护良好的日志能够帮助展示这种链接。但手动验证日志的准确性仍然至关重要；盲目信任 AI 的输出是一个灾难的食谱。
- 工具切换 / 模型升级（可能较少痛苦）： 如果你更改 AI 工具或底层模型，拥有决策历史可能有助于维持一致性。然而，这假设了不同系统之间日志的一定程度的互操作性，这在当前的景观中可能过于乐观。
- 细化提示（迭代改进）： 分析日志可以揭示你的提示在哪里不清楚，或 AI 如何一致地误解了你的意图。这 可能 随时间导致更有效的提示，使 AI 成为一个更有用的工具。
为什么 AI 生成的日志 可能 有所不同
让 AI 本身管理日志有潜在的优势：
- 格式一致性： AI 工具擅长于结构化输出，这应该会导致更容易解析和搜索的日志。
- 实时更新（大部分）： 日志应当随着 AI 的工作而更新，最小化忘记关键决策的机会。然而，这依赖于 AI 工具的能力。
- 潜在更深的上下文： AI 可能 会捕捉到人在快速编码时可能忽视的细微差别和考虑的替代方案。它 实际 是否这样做是另一个问题。
结论
根据我的经验，拥有一个自动化的决策日志在实践中是非常有用的。
它增强了透明度，促进了知识分享，并作为未来项目的可靠参考。这种做法不仅有助于教育，还加强了整个工程过程，从而导致了更加明智和高效的成果。