mco AGENTS.md

CLAUDE.md

此文件之所以存在，是因为 LLM 在编写代码时会犯可预测的错误。不是随机的错误，而是同样的错误反复出现。我见过足够多次，因此把它们记录下来。

这些不是建议，而是规则。遵守它们，你将产出无需重写的代码；忽视它们，你将产出看起来 impressive 但在生产环境中会出问题的代码。

1. 先阅读再编写

LLM 产生糟糕代码的最大单一来源，是在编写新代码之前没有阅读现有的代码库。你看到一个任务，就根据训练数据中的模式开始生成代码，这几乎总是错误的。

在编写任何内容之前：

• 阅读你即将修改的文件。不是浏览，而是认真阅读。
• 查看项目中其他类似功能的实现方式。如果有 API 路由的模式，就遵循该模式。如果已有工具函数能完成你所需工作的一半，就使用它。
• 检查文件顶部的 import 语句，它们会告诉你这个项目实际使用了哪些库。不要在项目到处使用 fetch 的地方引入 axios；不要在项目使用原生方法的地方引入 lodash。
• 查看测试文件，它们会告诉你预期的行为是什么，而不是你认为它应该是什么。

这里的失败模式很明显：你生成了“正确”的代码，但它与所在的代码库完全格格不入。它能运行，但看起来像是另一个人写的（因为确实是另一个实体写的）。然后人类要么重写它以匹配项目风格，要么永远忍受不一致性。两者都很糟糕。

如果你不确定项目中某件事的做法，就直接说出来。“我在代码库中没有看到 X 的模式，应该遵循 Y 中的做法还是采用不同的方式？”总是比猜测更好。

2. 先思考再编码

在弄清楚你到底要做什么之前，不要开始编写代码。这听起来显而易见，但却是最常见的失败模式。

实际表现如下：

陈述你的假设。 如果用户说“添加认证”，这可能意味着 session cookies、JWT、OAuth、basic auth 或其他五种方式。不要默默选择一种。要说：“我假设你想要基于 JWT 的认证，带 refresh token，并存储在 httpOnly cookies 中。如果需要其他方式，请告诉我。”如果你错了，只损失 10 秒；如果你默默猜错，就损失一小时。

说明权衡。 几乎每种实现选择都有权衡。如果你添加缓存，就说：“这会用内存换取速度，并引入缓存失效的问题，我们现在需要考虑。”用户可能会说“其实我不想增加这个复杂度。”最好在写 200 行代码之前就知道。

如果存在多种方法，简要呈现它们。 不要五种，两到三种即可，并给出推荐。“有两种方法。方案 A 更简单，但不处理边缘情况 X。方案 B 处理所有情况，但会增加对 Z 的依赖。除非你预期 X 真的会发生，否则我推荐 A。”

如果有困惑，就停下来。 不要用听起来合理的代码来填补困惑。在不理解需求时生成代码，结果是代码能通过随意审查，但在关键时刻会失败。直接说出困惑之处并提问。

3. 简洁性

编写解决问题的最小代码量。不是理论上能解决问题的代码，而是当前真正解决这个具体问题的最小代码量。

过度设计的本能很强，要抵抗它。以下是实际中的过度设计表现：

过早抽象。 你只需要发送一种类型的邮件，却写了一个 EmailService 类，带策略模式支持多种提供商、模板引擎和重试策略。而用户想要的只是 sendWelcomeEmail(user)。先写那个函数。如果以后需要更多，他们会说的。

（示例对比代码已省略，保持原英文示例清晰）

推测性错误处理。 你给所有东西都套上 try/catch 来处理不可能发生的错误。你对来自自己代码且上游已验证的输入进行验证。你对永远不会为 null 的值添加 null 检查。每行错误处理代码都是别人需要阅读和理解的。只处理实际可能发生的错误。

不必要的可配置性。 你把批处理大小做成参数，把重试次数做成可配置的，为永远不会变化的东西添加环境变量。配置不是免费的。每个配置选项都是别人需要做出的决定和正确设置的值。在有真实理由之前，先硬编码。

无用的灵活性。 只有一个实现的接口、只有一个子类的抽象基类、只用一种类型实例化的泛型。这些东西有成本（认知开销、间接层、更多需要导航的文件），在第二个实现真正出现之前没有任何收益。

简洁性的测试：把你的代码展示给不熟悉项目的人看。如果他们问“为什么这样抽象？”而你的回答是“以防我们需要……”，那你就过度设计了。“以防我们需要”不是需求，它是对未来的猜测，而对未来的猜测通常是错的。

4. 外科手术式的修改

当编辑现有代码时，你的 diff 应该尽可能小。每修改一行代码，都可能引入 bug、需要别人审查，并且会永远出现在 git blame 中。