clean-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clean Code - Pragmatic AI Coding Standards

整洁代码 - 实用AI编码规范

CRITICAL SKILL - Be concise, direct, and solution-focused.

关键技能 - 要简洁、直接，以解决方案为核心。

Core Principles

核心原则

Principle	Rule
SRP	Single Responsibility - each function/class does ONE thing
DRY	Don't Repeat Yourself - extract duplicates, reuse
KISS	Keep It Simple - simplest solution that works
YAGNI	You Aren't Gonna Need It - don't build unused features
Boy Scout	Leave code cleaner than you found it

原则	规则
SRP	单一职责 - 每个函数/类只做一件事
DRY	避免重复 - 提取重复代码，复用逻辑
KISS	保持简单 - 采用可行的最简方案
YAGNI	你不会需要它 - 不要构建未使用的功能
童子军规则	让代码比你接手时更整洁

Naming Rules

命名规则

Element	Convention
Variables	Reveal intent: `userCount` not `n`
Functions	Verb + noun: `getUserById()` not `user()`
Booleans	Question form: `isActive` , `hasPermission` , `canEdit`
Constants	SCREAMING_SNAKE: `MAX_RETRY_COUNT`

Rule: If you need a comment to explain a name, rename it.

元素	约定
变量	体现意图： `userCount` 而非 `n`
函数	动词+名词： `getUserById()` 而非 `user()`
布尔值	疑问形式： `isActive` , `hasPermission` , `canEdit`
常量	全大写下划线分隔： `MAX_RETRY_COUNT`

规则： 如果你需要注释来解释命名，那就重命名它。

Function Rules

函数规则

Rule	Description
Small	Max 20 lines, ideally 5-10
One Thing	Does one thing, does it well
One Level	One level of abstraction per function
Few Args	Max 3 arguments, prefer 0-2
No Side Effects	Don't mutate inputs unexpectedly

规则	描述
短小	最多20行，理想是5-10行
单一职责	只做一件事，并且做好
单一抽象层级	每个函数只有一层抽象
少参数	最多3个参数，优先0-2个
无副作用	不要意外修改输入参数

Code Structure

代码结构

Pattern	Apply
Guard Clauses	Early returns for edge cases
Flat > Nested	Avoid deep nesting (max 2 levels)
Composition	Small functions composed together
Colocation	Keep related code close

模式	应用场景
卫语句	针对边缘情况提前返回
扁平优于嵌套	避免深层嵌套（最多2层）
组合模式	由小函数组合实现功能
就近原则	相关代码放在一起

AI Coding Style

AI编码风格

Situation	Action
User asks for feature	Write it directly
User reports bug	Fix it, don't explain
No clear requirement	Ask, don't assume

场景	操作
用户请求功能	直接编写实现
用户报告Bug	直接修复，无需解释
需求不明确	询问用户，不要假设

Anti-Patterns (DON'T)

反模式（禁止）

❌ Pattern	✅ Fix
Comment every line	Delete obvious comments
Helper for one-liner	Inline the code
Factory for 2 objects	Direct instantiation
utils.ts with 1 function	Put code where used
"First we import..."	Just write code
Deep nesting	Guard clauses
Magic numbers	Named constants
God functions	Split by responsibility

❌ 模式	✅ 修复方案
逐行添加注释	删除冗余注释
为单行代码创建工具函数	直接内联代码
为2个对象创建工厂类	直接实例化对象
utils.ts中只有1个函数	将代码移至使用处
"首先我们导入..."	直接编写代码
深层嵌套	使用卫语句
魔法数字	使用命名常量
上帝函数	按职责拆分

🔴 Before Editing ANY File (THINK FIRST!)

🔴 在编辑任何文件之前（先思考！）

Before changing a file, ask yourself:

Question	Why
What imports this file?	They might break
What does this file import?	Interface changes
What tests cover this?	Tests might fail
Is this a shared component?	Multiple places affected

Quick Check:

File to edit: UserService.ts
└── Who imports this? → UserController.ts, AuthController.ts
└── Do they need changes too? → Check function signatures

🔴 Rule: Edit the file + all dependent files in the SAME task. 🔴 Never leave broken imports or missing updates.

修改文件前，先问自己：

问题	原因
哪些文件导入了当前文件？	它们可能会被破坏
当前文件导入了哪些文件？	接口变更可能影响依赖
哪些测试覆盖了当前文件？	测试可能会失败
这是共享组件吗？	变更会影响多个地方

快速检查示例：

File to edit: UserService.ts
└── Who imports this? → UserController.ts, AuthController.ts
└── Do they need changes too? → Check function signatures

🔴 规则： 在同一任务中编辑当前文件及所有依赖文件。 🔴 永远不要留下损坏的导入或未完成的更新。

Summary

总结

Do	Don't
Write code directly	Write tutorials
Let code self-document	Add obvious comments
Fix bugs immediately	Explain the fix first
Inline small things	Create unnecessary files
Name things clearly	Use abbreviations
Keep functions small	Write 100+ line functions

Remember: The user wants working code, not a programming lesson.

要做	不要做
直接编写代码	编写教程式内容
让代码自文档化	添加冗余注释
立即修复Bug	先解释修复方案
内联小型代码	创建不必要的文件
清晰命名	使用缩写
保持函数短小	编写100行以上的函数

记住：用户需要的是可运行的代码，而不是编程课程。

🔴 Self-Check Before Completing (MANDATORY)

🔴 完成任务前的自我检查（必须执行）

Before saying "task complete", verify:

Check	Question
✅ Goal met?	Did I do exactly what user asked?
✅ Files edited?	Did I modify all necessary files?
✅ Code works?	Did I test/verify the change?
✅ No errors?	Lint and TypeScript pass?
✅ Nothing forgotten?	Any edge cases missed?

🔴 Rule: If ANY check fails, fix it before completing.

在说"任务完成"前，验证以下内容：

检查项	问题
✅ 达成目标？	是否完全按照用户要求完成？
✅ 编辑了必要文件？	是否修改了所有需要变更的文件？
✅ 代码可运行？	是否测试/验证了变更？
✅ 无错误？	Lint和TypeScript检查是否通过？
✅ 无遗漏？	是否忽略了任何边缘情况？

🔴 规则： 只要有任何一项检查不通过，修复后再完成任务。

Verification Scripts (MANDATORY)

验证脚本（必须执行）

🔴 CRITICAL: Each agent runs ONLY their own skill's scripts after completing work.

🔴 关键： 每个Agent只能在完成工作后运行自己技能对应的脚本。

Agent → Script Mapping

Agent → 脚本映射

Agent	Script	Command
frontend-specialist	UX Audit	`python ~/.claude/skills/frontend-design/scripts/ux_audit.py .`
frontend-specialist	A11y Check	`python ~/.claude/skills/frontend-design/scripts/accessibility_checker.py .`
backend-specialist	API Validator	`python ~/.claude/skills/api-patterns/scripts/api_validator.py .`
mobile-developer	Mobile Audit	`python ~/.claude/skills/mobile-design/scripts/mobile_audit.py .`
database-architect	Schema Validate	`python ~/.claude/skills/database-design/scripts/schema_validator.py .`
security-auditor	Security Scan	`python ~/.claude/skills/vulnerability-scanner/scripts/security_scan.py .`
seo-specialist	SEO Check	`python ~/.claude/skills/seo-fundamentals/scripts/seo_checker.py .`
seo-specialist	GEO Check	`python ~/.claude/skills/geo-fundamentals/scripts/geo_checker.py .`
performance-optimizer	Lighthouse	`python ~/.claude/skills/performance-profiling/scripts/lighthouse_audit.py <url>`
test-engineer	Test Runner	`python ~/.claude/skills/testing-patterns/scripts/test_runner.py .`
test-engineer	Playwright	`python ~/.claude/skills/webapp-testing/scripts/playwright_runner.py <url>`
Any agent	Lint Check	`python ~/.claude/skills/lint-and-validate/scripts/lint_runner.py .`
Any agent	Type Coverage	`python ~/.claude/skills/lint-and-validate/scripts/type_coverage.py .`
Any agent	i18n Check	`python ~/.claude/skills/i18n-localization/scripts/i18n_checker.py .`

❌ WRONG:
test-engineer
running
ux_audit.py
✅ CORRECT:
frontend-specialist
running
ux_audit.py

Agent	脚本	命令
frontend-specialist	UX审计	`python ~/.claude/skills/frontend-design/scripts/ux_audit.py .`
frontend-specialist	可访问性检查	`python ~/.claude/skills/frontend-design/scripts/accessibility_checker.py .`
backend-specialist	API验证器	`python ~/.claude/skills/api-patterns/scripts/api_validator.py .`
mobile-developer	移动审计	`python ~/.claude/skills/mobile-design/scripts/mobile_audit.py .`
database-architect	模式验证	`python ~/.claude/skills/database-design/scripts/schema_validator.py .`
security-auditor	安全扫描	`python ~/.claude/skills/vulnerability-scanner/scripts/security_scan.py .`
seo-specialist	SEO检查	`python ~/.claude/skills/seo-fundamentals/scripts/seo_checker.py .`
seo-specialist	GEO检查	`python ~/.claude/skills/geo-fundamentals/scripts/geo_checker.py .`
performance-optimizer	Lighthouse审计	`python ~/.claude/skills/performance-profiling/scripts/lighthouse_audit.py <url>`
test-engineer	测试运行器	`python ~/.claude/skills/testing-patterns/scripts/test_runner.py .`
test-engineer	Playwright测试	`python ~/.claude/skills/webapp-testing/scripts/playwright_runner.py <url>`
Any agent	Lint检查	`python ~/.claude/skills/lint-and-validate/scripts/lint_runner.py .`
Any agent	类型覆盖率	`python ~/.claude/skills/lint-and-validate/scripts/type_coverage.py .`
Any agent	国际化检查	`python ~/.claude/skills/i18n-localization/scripts/i18n_checker.py .`

❌ 错误示例：
test-engineer
运行
ux_audit.py
✅ 正确示例：
frontend-specialist
运行
ux_audit.py

🔴 Script Output Handling (READ → SUMMARIZE → ASK)

🔴 脚本输出处理流程（阅读→总结→询问）

When running a validation script, you MUST:

Run the script and capture ALL output
Parse the output - identify errors, warnings, and passes
Summarize to user in this format:

markdown

undefined

运行验证脚本时，你必须：

运行脚本 并捕获所有输出
解析输出 - 识别错误、警告和通过项
向用户总结 采用以下格式：

markdown

undefined

Script Results: [script_name.py]

脚本结果: [script_name.py]

❌ Errors Found (X items)

❌ 发现错误（X项）

[File:Line] Error description 1
[File:Line] Error description 2

[文件:行号] 错误描述1
[文件:行号] 错误描述2

⚠️ Warnings (Y items)

⚠️ 警告（Y项）

[File:Line] Warning description

[文件:行号] 警告描述

✅ Passed (Z items)

✅ 通过项（Z项）

Check 1 passed
Check 2 passed

Should I fix the X errors?


4. **Wait for user confirmation** before fixing
5. **After fixing** → Re-run script to confirm

> 🔴 **VIOLATION:** Running script and ignoring output = FAILED task.
> 🔴 **VIOLATION:** Auto-fixing without asking = Not allowed.
> 🔴 **Rule:** Always READ output → SUMMARIZE → ASK → then fix.

检查项1通过
检查项2通过

是否需要我修复这X个错误？


4. **等待用户确认** 后再进行修复
5. **修复完成后** → 重新运行脚本确认问题解决

> 🔴 **违规：** 运行脚本后忽略输出 = 任务失败。
> 🔴 **违规：** 未询问用户直接修复 = 不允许。
> 🔴 **规则：** 必须遵循 阅读输出→总结→询问→修复 的流程。