CLAUDE.md 编码准则#

1
### 1. Think Before Coding
2

3
**Don't assume. Don't hide confusion. Surface tradeoffs.**
4

5
Before implementing:
6

7
- State your assumptions explicitly. If uncertain, ask.
8
- If multiple interpretations exist, present them - don't pick silently.
9
- If a simpler approach exists, say so. Push back when warranted.
10
- If something is unclear, stop. Name what's confusing. Ask.
11

12
### 2. Simplicity First
13

14
**Minimum code that solves the problem. Nothing speculative.**
15

16
- No features beyond what was asked.
17
- No abstractions for single-use code.
18
- No "flexibility" or "configurability" that wasn't requested.
19
- No error handling for impossible scenarios.
20
- If you write 200 lines and it could be 50, rewrite it.
21

22
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
23

24
### 3. Surgical Changes
25

26
**Touch only what you must. Clean up only your own mess.**
27

28
When editing existing code:
29

30
- Don't "improve" adjacent code, comments, or formatting.
31
- Don't refactor things that aren't broken.
32
- Match existing style, even if you'd do it differently.
33
- If you notice unrelated dead code, mention it - don't delete it.
34

35
When your changes create orphans:
36

37
- Remove imports/variables/functions that YOUR changes made unused.
38
- Don't remove pre-existing dead code unless asked.
39

40
The test: Every changed line should trace directly to the user's request.
41

42
### 4. Goal-Driven Execution
43

44
**Define success criteria. Loop until verified.**
45

46
Transform tasks into verifiable goals:
47

48
- "Add validation" → "Write tests for invalid inputs, then make them pass"
49
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
50
- "Refactor X" → "Ensure tests pass before and after"
51

52
For multi-step tasks, state a brief plan:
53

54
1. [Step] → verify: [check]
55
2. [Step] → verify: [check]
56
3. [Step] → verify: [check]
57

58
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
59

60
### 5. Language & Step Comments
61

62
**Language:** All comments must be in **Simplified Chinese (简体中文)**.
63

64
**Step Comments:** Every critical logic block must be preceded by a single-line step comment that explicitly identifies the execution phase. The format is fixed as: # 1. [Action], # 2. [Action], # 3. [Action].
65

66
---
67

68
**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

1
### 1. 先思考，再编码
2

3
**不要假设。不要掩盖困惑。明确呈现权衡方案。**
4

5
在实现之前：
6

7
- 明确陈述你的假设。如果不确定，就提问。
8
- 如果存在多种解释，呈现它们——不要默默选择一种。
9
- 如果有更简单的方法，就说出来。在必要时提出异议。
10
- 如果有不清楚的地方，停下来。指出困惑所在。然后提问。
11

12
### 2. 简单至上
13

14
**用最少的代码解决问题。不写任何推测性代码。**
15

16
- 不添加超出需求的功能。
17
- 不为仅使用一次的代码创建抽象。
18
- 不添加未被要求的"灵活性"或"可配置性"。
19
- 不为不可能发生的场景编写错误处理。
20
- 如果你写了 200 行代码而 50 行就能解决，那就重写。
21

22
扪心自问："资深工程师会认为这过于复杂吗？"如果答案是肯定的，就简化它。
23

24
### 3. 精准修改
25

26
**只触碰必须改的。只清理你自己弄乱的。**
27

28
编辑已有代码时：
29

30
- 不要"改进"相邻的代码、注释或格式。
31
- 不要重构没有坏的东西。
32
- 匹配现有风格，即使你倾向不同的写法。
33
- 如果你注意到不相关的死代码，提出来——但不要删掉它。
34

35
当你的改动产生了孤立代码时：
36

37
- 移除因你的改动而不再使用的 import、变量或函数。
38
- 除非被要求，否则不要移除之前就存在的死代码。
39

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

42
### 4. 目标驱动执行
43

44
**定义成功标准。循环执行直到验证通过。**
45

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

48
- "添加验证" → "为无效输入编写测试，然后让它们通过"
49
- "修复 bug" → "编写一个能复现 bug 的测试，然后让它通过"
50
- "重构 X" → "确保测试在重构前后都通过"
51

52
对于多步骤任务，陈述一个简要计划：
53

54
1. [步骤] → 验证: [检查项]
55
2. [步骤] → 验证: [检查项]
56
3. [步骤] → 验证: [检查项]
57

58
强有力的成功标准能让你独立循环推进。薄弱的标准（"让它能用"）则需要不断澄清。
59

60
### 5. 语言与步骤注释
61

62
**语言:** 所有注释必须使用简体中文。
63

64
**步骤注释:** 每个关键逻辑块之前必须有一行步骤注释，明确指出执行阶段。格式固定为：# 1. [动作]、# 2. [动作]、# 3. [动作]。
65

66
---
67

68
**这些准则生效的标志是：** diff 中的不必要改动减少，因过度复杂而导致的重写减少，并且澄清性问题在实现之前被提出，而非在犯错之后。