目录

在缺乏明确约束或充分审查的情况下，将功能实现交给Claude Code，可能会产生难以修改的代码。即使委托它完成实现，也要为设计决策、验证和最终合并指定负责人。

要点#

  • 即使功能单独运行正常，也可能与应用的API契约、权限和数据模型不一致。
  • 在要求Claude Code修改代码前，请提供具体的参考实现和明确的约束。
  • 设计一致性本身无法保证代码的正确性和安全性，因此要同时审查结构与行为。
  • 原文中“1～2个月”的警告应视为经验之谈，而非基于测量得出的期限。

不一致如何逐渐累积#

所提供的ゆうき的文章描述了一种常见的失败模式：开发者逐个提出功能需求，接受能运行的成果，后来才发现各个实现无法相互配合。某个端点的响应结构不同，另一个端点的错误处理方式又不同。每项任务都加入各自的实现，类似的辅助函数也越来越多。

这些差异增加了下一次修改所需的工作量。开发者必须先查明适用哪些规范、重复函数的行为是否相同，以及哪些调用方依赖现有响应。单项功能的成功，就这样变成了维护问题。

文章称，这种恶化会在1～2个月内发生，但未提供支持数据。关于有多少比例的团队会遇到这一问题的说法，也需要验证。可以借此警告检查工作方式，但不要将这段时间视为预测。

委托之前先明确要求#

在委托实现之前，先写一份简短的任务说明。对于小改动，先花5分钟。对于涉及身份验证、支付、数据库迁移或公共接口的工作，请留出更多时间。

说明应包含以下4点。

1. 预期行为： 说明用户将能做什么，以及操作失败时应如何处理。 2. 参考文件： 指定遵循预期模式的现有实现。 3. 约束： 明确权限、响应格式、依赖关系和兼容性要求。 4. 验收检查： 描述可观察到的结果，以证明修改能够正确运行。

例如，可以这样要求：“请参考商品搜索端点，添加订单搜索功能。保持现有的分页格式。用户只能搜索自己所属组织的订单。请验证搜索结果为空，以及尝试访问其他组织订单时的情况。”

这样可以为Claude Code提供具体目标，也更容易评估成果。

让决策依据可追溯#

原文主张，人类应负责判断，AI应负责执行。作为明确责任归属的规则，这很有用；但作为能力边界的划分，则过于严格。Claude Code可以查看仓库中的文件、提出设计方案并解释权衡。不过，这些建议需要根据项目的实际约束进行验证。

请要求它列出查看过的文件、说明现有模式，并为偏离这些模式的建议提供理由。仅仅说“遵循了架构”，不足以构成依据。基于具体文件名和接口契约的比较更有帮助。

请将重要决策记录在仓库中。哪怕只是简短说明端点为何采用某种错误格式，也能避免重复讨论。请写得具体，让审查者能够确认实现是否遵循了该决策。

不仅审查结构，也要审查行为#

原文暗示，只要结构正确，实现细节大体上就值得信任。但这一建议过于绝对。即使函数组织清晰，也可能遗漏授权检查、错误处理事务，或泄露敏感信息。

请从以下两个角度审查提出的修改。

  • 设计： 是否应该放在这个模块中，是否复用了适当的抽象，是否保持了现有契约。
  • 行为： 是否正确执行权限控制，是否妥善处理失败，是否在相关边界条件下产生预期结果。

请将测试作为判断依据，而非判断的替代品。AI生成的测试可能会重复实现中的相同假设。请独立定义预期行为，并确认测试能否发现可能出现的缺陷。对于订单搜索，检查一个组织是否能够获取另一个组织的记录，就很有帮助。

添加功能之前先纠正偏差#

如果规范已经不统一，请在委托下一个功能之前，先检查一个经常修改的领域。比较响应格式、错误处理和重复的辅助函数。选择参考实现之前，请先确认其行为正确。

然后，进行范围有限的修正。统一一项契约，或合并一处重复逻辑，验证调用方，再单独合并这次修改。请避免难以审查影响的大规模整理。

在随后的几次修改中，请跟踪反映维护状况的指标，例如回归问题、审查返工、确定正确模式所需的时间，以及为一个小功能修改的模块数量。这些观察比生成的代码行数或信心十足的完成报告更能说明问题。

下一步#

下次向Claude Code提出任务之前，请先写一份包含预期行为、参考文件、约束和验收检查的任务说明，并用它审查生成的差异。

来源: https://note.com/yukiedu/n/n4d25f5e1d590

目录