Back to Details

code-quality

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Quality

代码质量

Systematic code improvement through review, refactoring, and debugging with verification gates.
通过评审、重构、调试及验证关卡实现系统化的代码改进。

Module Selection

模块选择

NeedModuleReference
Receive FeedbackReview
references/code-review-reception.md
Request ReviewReview
references/requesting-code-review.md
Verify Before ClaimReview
references/verification-before-completion.md
Reduce ComplexityRefactoring
references/oop-refactoring-catalog.md
Functional PatternsRefactoring
references/functional-refactoring-patterns.md
Find Code SmellsRefactoring
references/code-smells-reference.md
Test StrategiesRefactoring
references/testing-strategies.md
Investigate BugsDebugging
references/systematic-debugging.md
Trace Root CauseDebugging
references/root-cause-tracing.md
Add ValidationDebugging
references/defense-in-depth.md
Verify FixDebugging
references/verification.md
需求模块参考资料
接收反馈Review
references/code-review-reception.md
请求评审Review
references/requesting-code-review.md
完成声明前验证Review
references/verification-before-completion.md
降低复杂度Refactoring
references/oop-refactoring-catalog.md
函数式模式Refactoring
references/functional-refactoring-patterns.md
识别代码坏味道Refactoring
references/code-smells-reference.md
测试策略Refactoring
references/testing-strategies.md
缺陷排查Debugging
references/systematic-debugging.md
根因追溯Debugging
references/root-cause-tracing.md
添加验证Debugging
references/defense-in-depth.md
验证修复结果Debugging
references/verification.md

Core Principles

核心原则

YAGNI, KISS, DRY - Always honor these.
Be honest, be brutal, straight to the point, and be concise.
Technical correctness over social comfort. Verify before implementing. Ask before assuming. Evidence before claims.
YAGNI, KISS, DRY - 始终遵循这些原则。
保持坦诚、直接、简明扼要。
技术正确性优先于社交情面。 先验证再实现。先询问再假设。先拿证据再声明。

Code Review

代码评审

Receiving Feedback

接收反馈

Pattern: READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
Rules:
  • ❌ No performative agreement ("You're right!", "Great point!")
  • ❌ No implementation before verification
  • ✅ Restate requirement, ask questions, push back with reasoning
  • ✅ YAGNI check: grep for usage before implementing suggestions
Sources:
  • Human partner → Implement after understanding
  • External reviewer → Verify technically before implementing
流程： 阅读 → 理解 → 验证 → 评估 → 回应 → 实现
规则：
  • ❌ 不要敷衍式同意（“你说得对！”、“好点子！”）
  • ❌ 不要未验证就实现
  • ✅ 重述需求、提出问题、有理有据地反驳
  • ✅ YAGNI检查：在实现建议前先搜索相关用法
来源：
  • 内部伙伴 → 理解后再实现
  • 外部评审者 → 先做技术验证再实现

Requesting Review

请求评审

When: After major features, before merge, after complex fixes
Process:
  1. Get SHAs: 
    BASE_SHA=$(git rev-parse HEAD~1)
    , 
    HEAD_SHA=$(git rev-parse HEAD)
  2. Dispatch code-reviewer subagent with: WHAT, PLAN, SHAs, DESCRIPTION
  3. Fix Critical immediately, Important before proceeding, note Minor
时机： 完成重大功能后、合并前、复杂修复完成后
流程：
  1. 获取SHA值：
    BASE_SHA=$(git rev-parse HEAD~1)
    , 
    HEAD_SHA=$(git rev-parse HEAD)
  2. 向code-reviewer子Agent发送信息：内容、计划、SHA值、描述
  3. 立即修复严重问题，在推进前修复重要问题，记录次要问题

Verification Gates

验证关卡

Iron Law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
Gate: IDENTIFY → RUN → READ → VERIFY → THEN claim
Skip any step = lying, not verifying.
铁律： 没有新鲜的验证证据，不得声明完成
流程： 识别 → 执行 → 读取 → 验证 → 再声明
跳过任何步骤 = 不实陈述，未完成验证

Refactoring

代码重构

Mindset

思维模式

Simplify relentlessly. Preserve behavior religiously. Measure everything.
Every refactoring: small and safe, tested immediately, measurably better.
持续简化。严格保留原有行为。量化所有指标。
每次重构：小步、安全、即时测试、可衡量地优化。

Protocol

流程

  1. Assessment - Baseline metrics, identify smells, classify debt
  2. Safety Net - Verify test coverage, add characterization tests
  3. Red-Green-Refactor - Write failing test, minimal pass, improve design
  4. Pattern Application - SOLID, design patterns, functional transforms
  5. Validation - Measure improvements, verify behavior preserved
  1. 评估 - 基准指标、识别坏味道、分类技术债务
  2. 安全网 - 验证测试覆盖率、添加特征测试
  3. 红-绿-重构 - 编写失败测试、最小化修复通过、优化设计
  4. 模式应用 - SOLID、设计模式、函数式转换
  5. 验证 - 衡量改进效果、确认行为未改变

Code Smells (5 Categories)

代码坏味道（5大类）

  1. Bloaters: Long Method, Large Class, Long Parameter List
  2. OO Abusers: Switch Statements, Temporary Field
  3. Change Preventers: Divergent Change, Shotgun Surgery
  4. Dispensables: Duplicate Code, Dead Code, Lazy Class
  5. Couplers: Feature Envy, Inappropriate Intimacy
  1. 臃肿类： 长方法、大类、长参数列表
  2. 面向对象滥用： 分支语句、临时字段
  3. 变更阻碍： 发散式变更、霰弹式修改
  4. 冗余类： 重复代码、死代码、懒加载类
  5. 耦合类： 特性羡慕、过度亲密

Quick Patterns

快速模式

OOP: Extract Method, Inline, Replace Temp with Query, Guard Clauses Functional: Map/Filter/Reduce, Pure Functions, Composition, Immutability
面向对象： 提取方法、内联、用查询替换临时变量、卫语句 函数式： Map/Filter/Reduce、纯函数、组合、不可变性

Debugging

调试

Core Principle

核心原则

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
Random fixes waste time and create new bugs.
未排查根因，不得修复
随机修复只会浪费时间并引入新缺陷。

The Four Techniques

四种技巧

1. Systematic Debugging (
references/systematic-debugging.md
)
  • Phase 1: Root Cause Investigation
  • Phase 2: Pattern Analysis
  • Phase 3: Hypothesis Testing
  • Phase 4: Implementation
2. Root Cause Tracing (
references/root-cause-tracing.md
) Trace backward through call stack to find original trigger.
3. Defense-in-Depth (
references/defense-in-depth.md
) Validate at every layer: Entry → Business logic → Environment → Debug
4. Verification (
references/verification.md
) Run command. Read output. Then claim result.
1. 系统化调试 (
references/systematic-debugging.md
)
  • 阶段1：根因排查
  • 阶段2：模式分析
  • 阶段3：假设测试
  • 阶段4：实现修复
2. 根因追溯 (
references/root-cause-tracing.md
) 通过调用栈反向追踪找到原始触发点。
3. 纵深防御 (
references/defense-in-depth.md
) 在每一层做验证：入口 → 业务逻辑 → 环境 → 调试
4. 验证 (
references/verification.md
) 执行命令。读取输出。再声明结果。

Quick Reference

快速参考

Bug → systematic-debugging.md (Phase 1-4)
  Error deep in stack? → root-cause-tracing.md
  Found root cause? → defense-in-depth.md
  About to claim success? → verification.md
缺陷 → systematic-debugging.md（阶段1-4）
  栈深层报错？→ root-cause-tracing.md
  找到根因？→ defense-in-depth.md
  即将声明成功？→ verification.md

Red Flags

危险信号

Stop if thinking:
  • "Quick fix for now, investigate later"
  • "Just try changing X and see"
  • "It's probably X, let me fix that"
  • "Should work now" / "Seems fixed"
如果出现以下想法，请立即停止：
  • “先临时修复，之后再排查”
  • “试试改X看看行不行”
  • “可能是X的问题，我来修复”
  • “现在应该好了” / “看起来修复了”

References

参考资料

Code Review

代码评审

  • references/code-review-reception.md
    - Response protocols
  • references/requesting-code-review.md
    - Request process
  • references/verification-before-completion.md
    - Verification gates
  • references/code-review-reception.md
    - 回应流程
  • references/requesting-code-review.md
    - 请求流程
  • references/verification-before-completion.md
    - 验证关卡

Refactoring

代码重构

  • references/oop-refactoring-catalog.md
    - Martin Fowler's patterns
  • references/functional-refactoring-patterns.md
    - FP transformations
  • references/code-smells-reference.md
    - 23 smells, 5 categories
  • references/testing-strategies.md
    - Characterization tests, TDD
  • references/oop-refactoring-catalog.md
    - Martin Fowler的设计模式
  • references/functional-refactoring-patterns.md
    - 函数式转换
  • references/code-smells-reference.md
    - 23种坏味道，5大分类
  • references/testing-strategies.md
    - 特征测试、测试驱动开发

Debugging

调试

  • references/systematic-debugging.md
    - Four-phase framework
  • references/root-cause-tracing.md
    - Call stack analysis
  • references/defense-in-depth.md
    - Multi-layer validation
  • references/verification.md
    - Verification protocols
  • references/systematic-debugging.md
    - 四阶段框架
  • references/root-cause-tracing.md
    - 调用栈分析
  • references/defense-in-depth.md
    - 多层验证
  • references/verification.md
    - 验证流程

Bottom Line

底线

  1. Review: Technical rigor over social performance
  2. Refactor: Small, safe, tested, measurable
  3. Debug: Root cause first, fix once
  4. Always: Evidence before claims
Verify. Question. Then implement. Evidence. Then claim.
  1. 评审： 技术严谨优先于社交表现
  2. 重构： 小步、安全、可测试、可衡量
  3. 调试： 先找根因，一次修复到位
  4. 始终： 先拿证据再声明
验证。质疑。再实现。有证据。再声明。