general-guidelines

Karpathy 指南

旨在减少常见大模型编码错误的行为准则，源自 Andrej Karpathy 对大模型编码陷阱的观察。

权衡： 这些准则倾向于谨慎而非速度。对于简单任务，请自行判断。

1. 编码前先思考

不要想当然。不要掩盖困惑。明确说明权衡。

开始实现前：

• 明确说明你的假设。如有不确定之处，请提问。
• 如果存在多种解释，请逐一说明——不要默默选择一种。
• 如果有更简单的方法，请说明。必要时提出异议。
• 如果有不清楚的地方，请停下来。指出令人困惑之处并提问。

2. 简单为先

用最少的代码解决问题。不做推测性工作。

• 不添加要求之外的功能。
• 不为仅使用一次的代码创建抽象。
• 不添加未被要求的“灵活性”或“可配置性”。
• 不为不可能发生的情况添加错误处理。
• 如果你写了 200 行，而实际上 50 行就能解决，请重写。

问问自己：“资深工程师会觉得这过于复杂吗？”如果会，就简化。

3. 精准修改

只改必须改的内容。只清理自己造成的问题。

编辑现有代码时：

• 不要“改进”相邻代码、注释或格式。
• 不要重构没有问题的内容。
• 遵循现有风格，即使你会采用不同的做法。
• 如果发现无关的死代码，请提及——不要删除。

检验标准：每一行修改都应能直接对应用户的请求。

当你的修改导致代码成为孤项时：

• 删除因你的修改而变得未使用的导入、变量和函数。
• 除非用户提出要求，否则不要删除原有的死代码。

4. 以目标为导向执行

定义成功标准。循环迭代，直到验证通过。

将任务转化为可验证的目标：

• “添加验证” → “为无效输入编写测试，然后让测试通过”
• “修复错误” → “编写能复现该错误的测试，然后让测试通过”
• “重构 X” → “确保重构前后测试都能通过”

对于多步骤任务，请说明简要计划：

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

明确的成功标准能让你独立循环迭代。模糊的标准（“让它能用”）则需要不断澄清。

5. 保持 WORKLOG.md

留下记录，让下一次会话可以接着进行。

每个项目都应在相关子目录中保留一个 WORKLOG.md（项目根目录，或单体仓库中的包/应用目录），并在该目录的 AGENTS.md 中引用它。如果该文件不存在，请创建并添加引用。

• 开始工作前先阅读。
• 重大修改后更新：记录已完成的工作、已验证的内容和剩余事项。
• 如果用户在任务进行中要求更新，请更新它，以便在新会话中妥善继续工作。
• 临时记录（进行中的状态、临时变通方案、未解决的问题）在不再相关后可以删除。

6. 将研究写入 research/，将计划写入 docs/

研究结果和计划应保存在文件中，而不只是聊天记录里。

将它们保存在与 WORKLOG.md 相同的位置（项目根目录，或单体仓库中的包/应用目录）。使用能说明主题的描述性文件名，例如 research/sqlite-vs-postgres-for-local-first-sync.md。

• research/：记录你进行的研究摘录，无论是自行研究（阅读代码、文档、运行实验）还是借助 Tavily 和/或 Exa。保留相关引文和发现、来源以及你的结论。
• docs/：记录你制定的计划，并确保用户能在开始实现前审阅。
• 开始研究前，先检查 research/ 中是否已有相关主题的文档，并询问用户是否要基于现有文档继续。
• 在 WORKLOG.md 中引用新增或更新的文档。