coding-guidelines

name	coding-guidelines
description	减少常见 LLM 编码失误的行为准则。Use when "写代码", "改代码", "重构", "code", "refactor", "implement", "review code", "编写/修改本仓库代码" — 即任何在本项目里写、改、重构、审查代码之前。 四条原则：先想后写 / 极简优先 / 外科手术式改动 / 目标驱动执行。 Derived from Andrej Karpathy's observations on LLM coding pitfalls.
license	MIT

Coding Guidelines

减少常见 LLM 编码失误的四条行为准则，源自 Andrej Karpathy 对 LLM 编码缺陷的观察。

权衡： 这些准则偏向「稳」而非「快」。琐碎任务（改错别字、明显的一行修复）用判断力即可，不必套用全套。

1. 先想后写 / Think Before Coding

不要默认假设，不要掩饰困惑，主动摆出权衡。

动手前：

• 把假设明说出来。不确定就问，别猜。
• 存在多种合理解读时，列出来让用户选，不要默默挑一个。
• 有更简单的做法时，直说；该顶回就顶回。
• 搞不清的地方，停下，指出哪里困惑，再问。

2. 极简优先 / Simplicity First

用解决问题的最少代码，不写任何投机性的东西。

• 不做没被要求的功能。
• 一次性代码不抽象。
• 不加没被要求的「灵活性」「可配置性」。
• 不为不可能发生的场景写错误处理。
• 200 行能写成 50 行，就重写。

自问：「资深工程师会不会觉得这过度复杂？」会，就简化。

3. 外科手术式改动 / Surgical Changes

只动该动的地方，只清理自己造成的烂摊子。

改已有代码时：

• 不「顺手优化」相邻的代码、注释、格式。
• 不重构没坏的东西。
• 沿用既有风格，哪怕你不会这么写。
• 发现无关的死代码，提一句，不要删。

自己的改动产生孤儿时：

• 删掉因你的改动而变得无用的 import / 变量 / 函数。
• 不删既有的死代码，除非被要求。

检验标准：每一行改动都能直接追溯到用户的请求。

4. 目标驱动执行 / Goal-Driven Execution

定义成功标准，循环到验证通过为止。

把任务转成可验证的目标：

• 「加校验」→「为非法输入写测试，再让测试通过」
• 「修 bug」→「写一个能复现的测试，再让它通过」
• 「重构 X」→「改动前后测试都通过」

多步任务先给简短计划：

1. [步骤] → 验证：[检查]
2. [步骤] → 验证：[检查]
3. [步骤] → 验证：[检查]

强成功标准让你能独立循环推进；弱标准（「让它能跑」）会逼着用户反复澄清。

---

准则生效的信号： diff 里没有多余的改动、不会因过度复杂而返工、澄清问题出现在动手前而非出错后。