简洁代码规范指南 - 实用AI编码原则与最佳实践 | 提升代码质量

clean-code by davila7/claude-code-templates

542 周安装量

23,800 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/davila7/claude-code-templates --skill clean-code

AI/机器学习开发代码规范

🇨🇳中文介绍

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

关键技能 - 保持简洁、直接、以解决方案为中心。

核心原则

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

命名规则

元素	约定
变量	揭示意图：而非

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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

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

场景	操作
用户请求功能	直接编写代码
用户报告错误	修复它，不要解释
需求不明确	询问，不要假设

反模式（禁止）

❌ 模式	✅ 修复方案
每行都加注释	删除显而易见的注释
为一小段代码创建辅助函数	内联代码
仅为 2 个对象创建工厂	直接实例化
只有一个函数的 utils.ts	将代码放在使用处
"首先我们导入..."	直接写代码
深层嵌套	使用卫语句
魔法数字	使用命名常量
上帝函数	按职责拆分

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

修改文件前，问自己：

问题	原因
哪些文件导入了此文件？	它们可能会出错
此文件导入了哪些文件？	接口可能变更
哪些测试覆盖了此文件？	测试可能失败
这是共享组件吗？	多个地方会受影响

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

🔴 规则： 在同一任务中编辑文件 + 所有依赖文件。 🔴 切勿留下损坏的导入或缺失的更新。

应该做	不要做
直接编写代码	编写教程
让代码自我说明	添加显而易见的注释
立即修复错误	先解释修复方案
内联小功能	创建不必要的文件
命名清晰	使用缩写
保持函数短小	编写 100+ 行的函数

记住：用户想要的是可工作的代码，而不是编程课程。

🔴 完成前自检（强制）

在说"任务完成"前，验证：

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

🔴 规则： 如果任何检查失败，请在完成前修复。

验证脚本（强制）

🔴 关键： 每个代理在完成工作后仅运行自己技能的脚本。

代理 → 脚本映射

代理	脚本	命令
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	i18n 检查	`python ~/.claude/skills/i18n-localization/scripts/i18n_checker.py .`

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

🔴 脚本输出处理（读取 → 总结 → 询问）

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

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

## 脚本结果：[script_name.py]

### ❌ 发现错误（X 项）
- [文件:行号] 错误描述 1
- [文件:行号] 错误描述 2

### ⚠️ 警告（Y 项）
- [文件:行号] 警告描述

### ✅ 通过（Z 项）
- 检查 1 通过
- 检查 2 通过

**我应该修复这 X 个错误吗？**

4. 等待用户确认 后再修复 5. 修复后 → 重新运行脚本以确认

🔴 违规： 运行脚本但忽略输出 = 任务失败。 🔴 违规： 未经询问自动修复 = 不允许。 🔴 规则： 始终遵循读取输出 → 总结 → 询问 → 然后修复。

🇺🇸English

Clean Code - Pragmatic AI Coding Standards

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

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.

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

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

AI Coding Style

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

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

🔴 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.

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.

🔴 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.

Verification Scripts (MANDATORY)

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

Agent → Script Mapping

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 .`

❌ WRONG: test-engineer running ux_audit.py ✅ CORRECT: frontend-specialist running 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:

## Script Results: [script_name.py]

### ❌ Errors Found (X items)
- [File:Line] Error description 1
- [File:Line] Error description 2

### ⚠️ Warnings (Y items)
- [File:Line] Warning description

### ✅ Passed (Z items)
- 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.

Weekly Installs

505

Repository

davila7/claude-…emplates

GitHub Stars

23.4K

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykFail

Installed on

opencode435

codex418

gemini-cli415

github-copilot396

kimi-cli344

amp344

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

106,200 周安装