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 INLINECODE1 |
| 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:
CODEBLOCK0
🔴 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 | INLINECODE8 |
| frontend-specialist |
A11y Check |
python .agent/skills/frontend-design/scripts/accessibility_checker.py . |
|
backend-specialist | API Validator |
python .agent/skills/api-patterns/scripts/api_validator.py . |
|
mobile-developer | Mobile Audit |
python .agent/skills/mobile-design/scripts/mobile_audit.py . |
|
database-architect | Schema Validate |
python .agent/skills/database-design/scripts/schema_validator.py . |
|
security-auditor | Security Scan |
python .agent/skills/vulnerability-scanner/scripts/security_scan.py . |
|
seo-specialist | SEO Check |
python .agent/skills/seo-fundamentals/scripts/seo_checker.py . |
|
seo-specialist | GEO Check |
python .agent/skills/geo-fundamentals/scripts/geo_checker.py . |
|
performance-optimizer | Lighthouse |
python .agent/skills/performance-profiling/scripts/lighthouse_audit.py <url> |
|
test-engineer | Test Runner |
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 Check |
python .agent/skills/lint-and-validate/scripts/lint_runner.py . |
|
Any agent | Type Coverage |
python .agent/skills/lint-and-validate/scripts/type_coverage.py . |
|
Any agent | i18n Check |
python .agent/skills/i18n-localization/scripts/i18n_checker.py . |
❌ WRONG: test-engineer running ux_audit.py
✅ CORRECT: frontend-specialist running INLINECODE25
🔴 Script Output Handling (READ → SUMMARIZE → ASK)
When running a validation script, you MUST:
- 1. Run the script and capture ALL output
- Parse the output - identify errors, warnings, and passes
- Summarize to user in this format:
CODEBLOCK1
- 4. Wait for user confirmation before fixing
- 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.
整洁代码 - 务实的人工智能编码标准
关键技能 - 做到简洁、直接、以解决方案为核心。
核心原则
| 原则 | 规则 |
|---|
| 单一职责原则 | 每个函数/类只做一件事 |
| 不要重复自己 |
提取重复代码，复用 |
|
保持简单 | 选择最简单可行的解决方案 |
|
你不会需要它 | 不要构建未使用的功能 |
|
童子军规则 | 让代码比你发现时更整洁 |
命名规则
| 元素 | 约定 |
|---|
| 变量 | 揭示意图：userCount 而非 n |
| 函数 |
动词 + 名词：getUserById() 而非 user() |
|
布尔值 | 疑问形式：isActive、hasPermission、canEdit |
|
常量 | 全大写蛇形命名：MAX
RETRYCOUNT |
规则： 如果需要用注释解释名称，那就重命名它。
函数规则
只做一件事，并做好它 |
|
单一层级 | 每个函数保持单一抽象层级 |
|
少参数 | 最多3个参数，优先0-2个 |
|
无副作用 | 不要意外修改输入数据 |
代码结构
避免深层嵌套（最多2层） |
|
组合 | 小型函数组合使用 |
|
就近放置 | 保持相关代码靠近 |
人工智能编码风格
修复它，不要解释 |
| 需求不明确 | 询问，不要假设 |
反模式（不要做）
| ❌ 模式 | ✅ 修正 |
|---|
| 每行都加注释 | 删除显而易见的注释 |
| 为单行代码创建辅助函数 |
内联代码 |
| 为2个对象创建工厂 | 直接实例化 |
| 只有一个函数的utils.ts | 将代码放在使用处 |
| 首先我们导入... | 直接写代码 |
| 深层嵌套 | 使用守卫子句 |
| 魔法数字 | 使用命名常量 |
| 上帝函数 | 按职责拆分 |
🔴 编辑任何文件之前（先思考！）
在更改文件之前，问自己：
| 问题 | 原因 |
|---|
| 哪些文件导入了此文件？ | 它们可能会出错 |
| 此文件导入了什么？ |
接口可能发生变化 |
|
哪些测试覆盖了此文件？ | 测试可能会失败 |
|
这是共享组件吗？ | 可能影响多个地方 |
快速检查：
要编辑的文件：UserService.ts
└── 谁导入了此文件？→ UserController.ts, AuthController.ts
└── 它们也需要更改吗？→ 检查函数签名
🔴 规则： 在同一任务中编辑文件 + 所有依赖文件。
🔴 绝不要留下损坏的导入或缺失的更新。
总结
添加显而易见的注释 |
| 立即修复错误 | 先解释修复方法 |
| 内联小型代码 | 创建不必要的文件 |
| 清晰命名 | 使用缩写 |
| 保持函数小型 | 编写100+行的函数 |
记住：用户想要的是能运行的代码，而不是编程课。
🔴 完成前的自我检查（必须执行）
在说任务完成之前，验证：
| 检查项 | 问题 |
|---|
| ✅ 目标达成？ | 我是否完全按照用户的要求做了？ |
| ✅ 文件已编辑？ |
我是否修改了所有必要的文件？ |
| ✅
代码能运行？ | 我是否测试/验证了更改？ |
| ✅
没有错误？ | Lint和TypeScript检查通过了吗？ |
| ✅
没有遗漏？ | 是否有任何边界情况被遗漏？ |
🔴 规则： 如果任何检查项未通过，在完成前修复它。
验证脚本（必须执行）
🔴 关键： 每个代理在完成工作后只运行自己技能的脚本。
代理 → 脚本映射
| 代理 | 脚本 | 命令 |
|---|
| 前端专家 | UX审计 | python .agent/skills/frontend-design/scripts/uxaudit.py . |
| 前端专家 |
无障碍检查 | python .agent/skills/frontend-design/scripts/accessibilitychecker.py . |
|
后端专家 | API验证器 | python .agent/skills/api-patterns/scripts/api_validator.py . |
|
移动端开发者 | 移动端审计 | python .agent/skills/mobile-design/scripts/mobile_audit.py . |
|
数据库架构师 | 模式验证 | python .agent/skills/database-design/scripts/schema_validator.py . |
|
安全审计员 | 安全扫描 | python .agent/skills/vulnerability-scanner/scripts/security_scan.py . |
|
SEO专家 | SEO检查 | python .agent/skills/seo-fundamentals/scripts/seo_checker.py . |
|
SEO专家 | GEO检查 | python .agent/skills/geo-fundamentals/scripts/geo_checker.py . |
|
性能优化师 | Lighthouse | python .agent/skills/performance-profiling/scripts/lighthouse_audit.py
|
| 测试工程师 | 测试运行器 | python .agent/skills/testing-patterns/scripts/test_runner.py . |
| 测试工程师 | Playwright | python .agent/skills/webapp-testing/scripts/playwright_runner.py |
| 任何代理 | Lint检查 | python .agent/skills/lint-and-validate/scripts/lint_runner.py . |
| 任何代理 | 类型覆盖率 | python .agent/skills/lint-and-validate/scripts/type_coverage.py . |
| 任何代理 | i18n检查 | python .agent/skills/i18n-localization/scripts/i18n_checker.py . |
❌ 错误： test-engineer 运行 ux_audit.py
✅ 正确： frontend-specialist 运行 ux_audit.py
🔴 脚本输出处理（读取 → 总结 → 询问）
运行验证脚本时，你必须：
- 1. 运行脚本并捕获所有输出
- 解析输出 - 识别错误、警告和通过项
- 向用户总结，格式如下：
markdown
脚本结果：[script_name.py]
❌ 发现错误（X项）
- - [文件:行号] 错误描述1
- [文件:行号] 错误描述2
⚠️ 警告（Y项）
✅ 通过（Z项）
我应该修复这X个错误吗？
- 4. 等待用户确认后再修复
- 修复后 → 重新运行脚本确认
🔴 违规： 运行脚本但忽略输出 = 任务失败。
🔴 违规： 未经询问自动修复 = 不允许。
🔴 规则： 始终读取输出 → 总结 → 询问 → 然后修复。
