name: clean-code description: 实用编码标准 - 简洁、直接、不过度工程化、无必要注释 allowed-tools: Read, Write, Edit version: 2.0 priority: CRITICAL
干净代码 - 实用AI编码标准
关键技能 - 要简洁、直接、聚焦解决方案。
核心原则
| 原则 | 规则 |
|---|---|
| SRP | 单一职责 - 每个函数/类做一件事 |
| DRY | 不要重复自己 - 提取重复、重用 |
| KISS | 保持简单 - 最简单的有效解决方案 |
| YAGNI | 你不会需要它 - 不要构建未使用的功能 |
| Boy Scout | 让代码比你找到时更干净 |
命名规则
| 元素 | 约定 |
|---|---|
| 变量 | 揭示意图：userCount 而不是 n |
| 函数 | 动词 + 名词：getUserById() 而不是 user() |
| 布尔值 | 问题形式：isActive、hasPermission、canEdit |
| 常量 | 大写蛇形：MAX_RETRY_COUNT |
规则： 如果需要注释来解释名称，请重命名。
函数规则
| 规则 | 描述 |
|---|---|
| 小 | 最大20行，理想5-10行 |
| 一件事 | 做一件事，做好它 |
| 一个级别 | 每个函数一个抽象级别 |
| 少参数 | 最大3个参数，偏好0-2个 |
| 无副作用 | 不要意外地改变输入 |
代码结构
| 模式 | 应用 |
|---|---|
| 保护子句 | 为边缘情况提前返回 |
| 扁平 > 嵌套 | 避免深层嵌套（最多2层） |
| 组合 | 小函数组合在一起 |
| 共置 | 保持相关代码靠近 |
AI编码风格
| 情况 | 行动 |
|---|---|
| 用户请求功能 | 直接编写它 |
| 用户报告错误 | 修复它，不要解释 |
| 没有明确要求 | 提问，不要假设 |
反模式（不要）
| ❌ 模式 | ✅ 修复 |
|---|---|
| 每行都注释 | 删除明显注释 |
| 为一行为写帮助函数 | 内联代码 |
| 为两个对象写工厂 | 直接实例化 |
| utils.ts 中只有一个函数 | 将代码放在使用处 |
| “首先我们导入…” | 直接写代码 |
| 深层嵌套 | 保护子句 |
| 魔术数字 | 命名常量 |
| 上帝函数 | 按职责拆分 |
🔴 在编辑任何文件之前（先思考！）
在更改文件前，问自己：
| 问题 | 原因 |
|---|---|
| 谁导入了这个文件？ | 它们可能会中断 |
| 这个文件导入了什么？ | 接口更改 |
| 哪些测试覆盖了它？ | 测试可能会失败 |
| 这是一个共享组件吗？ | 多个地方受影响 |
快速检查：
要编辑的文件：UserService.ts
└── 谁导入它？ → UserController.ts, AuthController.ts
└── 它们也需要更改吗？ → 检查函数签名
🔴 规则： 在同一任务中编辑文件 + 所有依赖文件。 🔴 永远不要留下中断的导入或缺失的更新。
总结
| 做 | 不要 |
|---|---|
| 直接写代码 | 写教程 |
| 让代码自文档化 | 添加明显注释 |
| 立即修复错误 | 先解释修复 |
| 内联小东西 | 创建不必要的文件 |
| 清晰地命名事物 | 使用缩写 |
| 保持函数小 | 写100+行的函数 |
记住：用户想要能工作的代码，不是编程课。
🔴 完成前自检（强制）
在说“任务完成”前，验证：
| 检查 | 问题 |
|---|---|
| ✅ 目标达到了吗？ | 我是否做了用户要求的事？ |
| ✅ 文件编辑了吗？ | 我是否修改了所有必要文件？ |
| ✅ 代码能工作吗？ | 我是否测试/验证了更改？ |
| ✅ 没有错误吗？ | Lint 和 TypeScript 通过了吗？ |
| ✅ 没有遗漏吗？ | 有遗漏的边缘情况吗？ |
🔴 规则： 如果有任何检查失败，在完成前修复它。
验证脚本（强制）
🔴 关键： 每个代理在完成工作后只运行自己技能的脚本。
代理 → 脚本映射
| 代理 | 脚本 | 命令 |
|---|---|---|
| frontend-specialist | UX 审计 | python ~/.claude/skills/frontend-design/scripts/ux_audit.py . |
| frontend-specialist | A11y 检查 | 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> |
| 任何代理 | Lint 检查 | python ~/.claude/skills/lint-and-validate/scripts/lint_runner.py . |
| 任何代理 | 类型覆盖率 | python ~/.claude/skills/lint-and-validate/scripts/type_coverage.py . |
| 任何代理 | 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 个错误吗？**
- 等待用户确认 在修复前
- 修复后 → 重新运行脚本以确认
🔴 违规： 运行脚本并忽略输出 = 任务失败。 🔴 违规： 自动修复而不询问 = 不允许。 🔴 规则： 总是读取输出 → 总结 → 询问 → 然后修复。