介绍
# Clean Code - Pragmatic AI Coding Standards
> **核心技能** - 保持 **简洁、直接且以解决方案为导向**。
---
## 核心原则
| 原则 | 规则 | |-----------|------| | **SRP** | 单一职责 - 每个函数/类只做一件事 | | **DRY** | 不要重复自己 (Don't Repeat Yourself) - 提取重复项，复用代码 | | **KISS** | 保持简单 (Keep It Simple) - 使用最简单的可行方案 | | **YAGNI** | 你用不上它 (You Aren't Gonna Need It) - 不要构建未使用的功能 | | **童子军规则** | 离开时比你来时更整洁 (Leave code cleaner than you found it) |
---
## 命名规则
| 元素 | 约定 | |---------|------------| | **变量** | 揭示意图：使用 `userCount` 而非 `n` | | **函数** | 动词 + 名词：使用 `getUserById()` 而非 `user()` | | **布尔值** | 问句形式：`isActive`、`hasPermission`、`canEdit` | | **常量** | 全大写下划线 (SCREAMING_SNAKE)：`MAX_RETRY_COUNT` |
> **规则：** 如果你需要用注释来解释一个名字，请重命名它。
---
## 函数规则
| 规则 | 描述 | |------|-------------| | **短小** | 最多 20 行，理想情况为 5-10 行 | | **做一件事** | 只做一件事，并把它做好 | | **一层抽象** | 每个函数只包含一层抽象 | | **参数少** | 最多 3 个参数，首选 0-2 个 | | **无副作用** | 不要意外修改输入参数 |
---
## 代码结构
| 模式 | 应用 | |---------|-------| | **卫语句 (Guard Clauses)** | 针对边缘情况尽早返回 | | **扁平优于嵌套** | 避免深层嵌套（最多 2 层） | | **组合** | 将小函数组合在一起 | | **就近原则** | 将相关代码放在一起 |
---
## AI 编码风格
| 场景 | 动作 | |-----------|--------| | 用户请求功能 | 直接编写 | | 用户报告 Bug | 修复它，不要解释 | | 需求不明确 | 询问，不要假设 |
---
## 反模式 (DON'T)
| ❌ 模式 | ✅ 修正 | |-----------|-------| | 每行都注释 | 删除显而易见的注释 | | 为单行代码写辅助函数 | 内联代码 | | 为 2 个对象写工厂 | 直接实例化 | | 只有 1 个函数的 utils.ts | 将代码放在使用处 | | “首先我们导入...” | 直接写代码 | | 深层嵌套 | 使用卫语句 | | 魔法数字 | 使用命名常量 | | 上帝函数 | 按职责拆分 |
---
## 🔴 编辑任何文件之前 (先思考！)
**在更改文件之前，请问自己：**
| 问题 | 原因 | |----------|-----| | **什么引用了这个文件？** | 它们可能会出错 | | **这个文件引用了什么？** | 接口可能会变更 | | **什么测试覆盖了这里？** | 测试可能会失败 | | **这是共享组件吗？** | 多个地方会受影响 |
**快速检查：** ``` File to edit: UserService.ts └── Who imports this? → UserController.ts, AuthController.ts └── Do they need changes too? → Check function signatures ```
> 🔴 **规则：** 在同一任务中编辑文件及其所有依赖文件。 > 🔴 **永远不要留下损坏的导入或遗漏的更新。**
---
## 总结
| 要做 | 不要做 | |----|-------| | 直接编写代码 | 写教程 | | 让代码自我注释 | 添加显而易见的注释 | | 立即修复 Bug | 先解释修复方案 | | 内联琐碎内容 | 创建不必要的文件 | | 清晰命名 | 使用缩写 | | 保持函数短小 | 编写 100+ 行的函数 |
> **记住：用户想要能运行的代码，而不是编程课。**
---
## 🔴 完成前的自检 (强制)
**在说“任务完成”之前，请核实：**
| 检查项 | 问题 | |-------|----------| | ✅ **目标达成？** | 我是否完全按照用户要求做了？ | | ✅ **文件已编辑？** | 我是否修改了所有必要的文件？ | | ✅ **代码可行？** | 我是否测试/验证了更改？ | | ✅ **无错误？** | Lint 和 TypeScript 检查通过？ | | ✅ **无遗漏？** | 是否有遗漏的边缘情况？ |
> 🔴 **规则：** 如果有任何检查失败，请在完成前修复它。
---
## 验证脚本 (强制)
> 🔴 **关键：** 每个代理 在完成工作后仅运行其自身技能对应的脚本。
### 代理 → 脚本映射
| 代理 | 脚本 | 命令 | |-------|--------|---------| | **frontend-specialist** | UX 审计 | `python .agent/skills/frontend-design/scripts/ux_audit.py .` | | **frontend-specialist** | A11y 检查 | `python .agent/skills/frontend-design/scripts/accessibility_checker.py .` | | **backend-specialist** | API 验证器 | `python .agent/skills/api-patterns/scripts/api_validator.py .` | | **mobile-developer** | 移动端审计 | `python .agent/skills/mobile-design/scripts/mobile_audit.py .` | | **database-architect** | 模式验证 | `python .agent/skills/database-design/scripts/schema_validator.py .` | | **security-auditor** | 安全扫描 | `python .agent/skills/vulnerability-scanner/scripts/security_scan.py .` | | **seo-specialist** | SEO 检查 | `python .agent/skills/seo-fundamentals/scripts/seo_checker.py .` | | **seo-specialist** | GEO 检查 | `python .agent/skills/geo-fundamentals/scripts/geo_checker.py .` | | **performance-optimizer** | Lighthouse | `python .agent/skills/performance-profiling/scripts/lighthouse_audit.py <url>` | | **test-engineer** | 测试运行器 | `python .agent/skills/testing-patterns/scripts/test_runner.py .` | | **test-engineer** | Playwright | `python .agent/skills/webapp-testing/scripts/playwright_runner.py <url>` | | **Any agent** | Lint 检查 | `python .agent/skills/lint-and-validate/scripts/lint_runner.py .` | | **Any agent** | 类型覆盖率 | `python .agent/skills/lint-and-validate/scripts/type_coverage.py .` | | **Any agent** | i18n 检查 | `python .agent/skills/i18n-localization/scripts/i18n_checker.py .` |
> ❌ **错误：** `test-engineer` 运行 `ux_audit.py` > ✅ **正确：** `frontend-specialist` 运行 `ux_audit.py`
---
### 🔴 脚本输出处理 (阅读 → 总结 → 询问)
**运行验证脚本时，你必须：**
1. **运行脚本** 并捕获所有输出 2. **解析输出** - 识别错误、警告和通过项 3. **向用户总结**，格式如下：
```markdown ## 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. **等待用户确认** 然后再进行修复 5. **修复后** → 重新运行脚本以确认
> 🔴 **违规：** 运行脚本并忽略输出 = 任务失败。 > 🔴 **违规：** 未经询问自动修复 = 不被允许。 > 🔴 **规则：** 始终 阅读输出 → 总结 → 询问 → 然后修复。