Menu
务实的编码标准—— 简洁、直接、不做过度设计、不写无用注释（Pragmatic coding standards）
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
性能分析原则。测量、分析与优化技术。
API design principles and decision-making（API 设计原则与决策逻辑）。REST vs GraphQL vs tRPC selection（选择）、response formats（响应格式）、versioning（版本控制）、pagination（分页）。
App Builder（应用构建编排器）主编排器。根据自然语言请求创建全栈应用，确定项目类型、选择技术栈并协调智能体。
Project scaffolding templates（项目脚手架模板）。用于从零创建新项目。包含 12 个技术栈模板。
Architectural decision-making framework（架构决策框架）。Requirements analysis（需求分析）、trade-off evaluation（权衡评估）、ADR documentation（架构决策记录）。Use when making architecture decisions or analyzing system design（用于架构决策与系统设计分析）。
AI（人工智能）运行模式（BRAINSTORM、IMPLEMENT、DEBUG、REVIEW、TEACH、SHIP、ORCHESTRATE）。用于根据任务类型自动调整 AI 行为逻辑。
| name | clean-code |
| description | 务实的编码标准—— 简洁、直接、不做过度设计、不写无用注释（Pragmatic coding standards） |
| allowed-tools | Read, Write, Edit |
| version | 2 |
| priority | CRITICAL |
Clean Code（整洁代码）是核心技能—— 保持简洁、直接并专注于解决方案。
| 原则 | 规则 |
|---|---|
| SRP | 单一职责（Single Responsibility）—— 每个函数/类只做一件事 |
| DRY | 不要重复（Don't Repeat Yourself）—— 提取重复项并复用 |
| KISS | 保持简单（Keep It Simple）—— 采用能跑通的最简单方案 |
| YAGNI | 你不会需要它（You Aren't Gonna Need It）—— 不构建未被要求的功能 |
| Boy Scout | 离开时让代码比你来时更整洁 |
| 元素 | 规范 |
|---|---|
| 变量（Variables） | 揭示意图：userCount 而非 n |
| 函数（Functions） | 动词 + 名词：getUserById() 而非 user() |
| 布尔值（Booleans） | 提问形式：isActive, hasPermission, canEdit |
| 常量（Constants） | SCREAMING_SNAKE：MAX_RETRY_COUNT |
准则： 如果需要注释解释命名，请直接重命名。
| 规则 | 描述 |
|---|---|
| 短小（Small） | 最多 20 行，理想 5-10 行 |
| 专注（One Thing） | 只做一件事，并把它做好 |
| 层次（One Level） | 每个函数只包含一个抽象层级 |
| 参数少（Few Args） | 最多 3 个参数，优先 0-2 个 |
| 无副作用（No Side Effects） | 不要产生预期之外的输入状态改变 |
| 模式 | 应用建议 |
|---|---|
| 卫语句（Guard Clauses） | 针对边缘情况及早返回 |
| 扁平化优先（Flat > Nested） | 避免深度嵌套（最多 2 层） |
| 组合（Composition） | 将短小函数组合使用 |
| 就近原则（Colocation） | 相关代码尽量放近 |
| 场景 | 行动建议 |
|---|---|
| 用户要求功能 | 直接编写实现 |
| 用户报告问题 | 修复，不做多余解释 |
| 需求不明确 | 先询问，不做假设 |
| [FAIL] 错误模式 | [OK] 推荐修复 |
|---|---|
| 每一行都写注释 | 删除显而易见的注释 |
| 为单行逻辑封装 helper | 直接内联 |
| 为 2 个对象写工厂模式 | 直接实例化 |
| 只有 1 个函数的 utils.ts | 代码放在被使用处 |
| “First we import...” | 直接写代码 |
| 深度嵌套 | 使用卫语句 |
| 使用魔术数字 | 使用具名常量 |
| 万能函数 | 按职责拆分 |
修改文件前先问自己：
| 提问 | 为什么 |
|---|---|
| 谁引用了这个文件？ | 修改可能会破坏它们 |
| 这个文件引用了谁？ | 接口可能需要变更 |
| 有哪些测试覆盖了这里？ | 测试可能会失败 |
| 这是共享组件吗？ | 可能影响多个地方 |
快速检查：
File to edit: UserService.ts
+-- Who imports this? -> UserController.ts, AuthController.ts
+-- Do they need changes too? -> Check function signatures
[CRITICAL] 准则： 同一任务内同时编辑该文件与所有受影响的依赖文件。 [CRITICAL] 禁止： 遗留断裂引用或缺失更新。
| 推荐做法 | 不要做 |
|---|---|
| 直接编写代码 | 编写教程式引导 |
| 让代码自文档化 | 添加显而易见的注释 |
| 立即修复问题 | 先解释修复方案 |
| 内联短小逻辑 | 创建不必要的文件 |
| 命名清晰准确 | 使用缩写 |
| 保持函数短小 | 编写超过 100 行的函数 |
谨记： 用户想要的是能运行的代码，而不是一堂编程课。
在说“任务完成”前请验证：
| 检查项 | 确认问题 |
|---|---|
| [OK] 目标达成了吗？ | 是否精准完成用户要求？ |
| [OK] 文件都改了吗？ | 是否修改了所有必要文件？ |
| [OK] 代码能跑吗？ | 是否测试/验证该变更？ |
| [OK] 没有报错吗？ | Lint 和 TypeScript 是否通过？ |
| [OK] 没遗漏什么吗？ | 是否遗漏边缘情况？ |
[CRITICAL] 准则： 任一检查未通过，必须先修复再结束。
[CRITICAL] 核心要求： 每个代理完成后仅运行所属技能脚本。
下表中的 <skills_root> 代表 Skills 根目录，常见取值：
.agents/skills.agent/skills~/.codex/skills~/.gemini/skills~/.gemini/antigravity/skills| 代理 | 脚本 | 命令 |
|---|---|---|
| frontend-specialist | UX Audit | python <skills_root>/frontend-design/scripts/ux_audit.py . |
| frontend-specialist | A11y Check | python <skills_root>/frontend-design/scripts/accessibility_checker.py . |
| backend-specialist | API Validator | python <skills_root>/api-patterns/scripts/api_validator.py . |
| mobile-developer | Mobile Audit | python <skills_root>/mobile-design/scripts/mobile_audit.py . |
| database-architect | Schema Validate | python <skills_root>/database-design/scripts/schema_validator.py . |
| security-auditor | Security Scan | python <skills_root>/vulnerability-scanner/scripts/security_scan.py . |
| seo-specialist | SEO Check | python <skills_root>/seo-fundamentals/scripts/seo_checker.py . |
| seo-specialist | GEO Check | python <skills_root>/geo-fundamentals/scripts/geo_checker.py . |
| performance-optimizer | Lighthouse | python <skills_root>/performance-profiling/scripts/lighthouse_audit.py <url> |
| test-engineer | Test Runner | python <skills_root>/testing-patterns/scripts/test_runner.py . |
| test-engineer | Playwright | python <skills_root>/webapp-testing/scripts/playwright_runner.py <url> |
| Any agent | Lint Check | python <skills_root>/lint-and-validate/scripts/lint_runner.py . |
| Any agent | Type Coverage | python <skills_root>/lint-and-validate/scripts/type_coverage.py . |
| Any agent | i18n Check | python <skills_root>/i18n-localization/scripts/i18n_checker.py . |
[FAIL] 错误做法：
test-engineer运行ux_audit.py[OK] 正确做法：frontend-specialist运行ux_audit.py
运行验证脚本时必须：
## Script Results: [script_name.py]
### [FAIL] Errors Found (X items)
- [File:Line] Error description 1
- [File:Line] Error description 2
### [WARN] Warnings (Y items)
- [File:Line] Warning description
### [OK] Passed (Z items)
- Check 1 passed
- Check 2 passed
**Should I fix the X errors?**
[CRITICAL] VIOLATION: Running script and ignoring output = FAILED task. [CRITICAL] VIOLATION: Auto-fixing without asking = Not allowed. [CRITICAL] Rule: Always READ output -> SUMMARIZE -> ASK -> then fix.