improve-code-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Improve Code Quality

提升代码质量

Turn a working-but-untested vibe-coded prototype into a product you can ship and operate. This is an interactive, resumable journey of nine phases: the agent asks before every decision and records the outcome in your project's

docs/

folder, so you can stop after any phase and pick up later. A week-old prototype is already legacy code — so the first move is a safety net, and every phase after it is verifiable because of that net.

将一个可运行但未经测试的随性编写原型，转变为可交付、可运维的产品。这是一段交互式、可续接的九阶段流程：Agent会在每个决策前提问，并将结果记录在项目的

docs/

文件夹中，你可以在任意阶段暂停，之后继续推进。一周前的原型已属于遗留代码——因此第一步是搭建安全网，后续每个阶段都能基于这个安全网进行验证。

Core Principle

核心原则

A week-old untested prototype is already legacy code: flip tactical to strategic — safety net first, then readability, structure, and production hardening in order. This skill sequences the phases, asks the decision questions, and records every choice in

docs/

. The constituent skills carry the method — invoke them rather than improvising their frameworks. Skipping ahead (refactoring before tests, scaling before sizing) is the exact failure mode this ordering exists to prevent.

一周前的未经测试原型已属于遗留代码：从战术思维转向战略思维——先搭建安全网，再依次优化可读性、结构，最后进行生产环境加固。 该技能会按顺序编排各阶段，提出决策问题，并将所有选择记录在

docs/

文件夹中。各个子技能承载具体方法——请直接调用这些技能，而非自行摸索其框架。跳过前置步骤（比如先重构再写测试、先扩容再评估规模）正是这套顺序要避免的错误模式。

Journey Map

流程路线图

Phase	Skill	Question it answers	Artifact
1	working-with-legacy-code	Can I change this code without breaking it unknowingly?	Creates docs/TESTING.md + docs/TECH-DEBT.md — GATE
2	clean-code	Is this readable to the next person (and agent)?	Extends docs/TECH-DEBT.md
3	refactoring-patterns	Can I reshape structure without changing behavior?	Extends docs/TECH-DEBT.md
4	software-design-philosophy	Is complexity hidden behind deep modules?	Extends docs/TECH-DEBT.md
5	clean-architecture	Do business rules depend on the framework, or vice versa?	Extends docs/ARCHITECTURE.md
6	pragmatic-programmer	What habits keep it clean after we stop?	Extends docs/TECH-DEBT.md
7	release-it	Will it survive a hostile production?	Creates docs/RELIABILITY.md
8	system-design	Is it sized for the load we actually have?	Extends docs/ARCHITECTURE.md + docs/RELIABILITY.md
9	ddia-systems	Is the data layer correct and durable under concurrency?	Extends docs/ARCHITECTURE.md

阶段	技能	要解决的问题	产出物
1	working-with-legacy-code	我能否修改代码而不不知不觉地破坏它？	创建docs/TESTING.md + docs/TECH-DEBT.md —— 必经关卡
2	clean-code	代码对下一位开发者（或Agent）来说是否易读？	扩展docs/TECH-DEBT.md
3	refactoring-patterns	我能否在不改变行为的前提下调整代码结构？	扩展docs/TECH-DEBT.md
4	software-design-philosophy	复杂逻辑是否被隐藏在深层模块背后？	扩展docs/TECH-DEBT.md
5	clean-architecture	业务规则依赖框架，还是框架依赖业务规则？	扩展docs/ARCHITECTURE.md
6	pragmatic-programmer	我们停止优化后，哪些习惯能维持代码整洁？	扩展docs/TECH-DEBT.md
7	release-it	它能否在复杂的生产环境中稳定运行？	创建docs/RELIABILITY.md
8	system-design	它的规模是否匹配实际负载？	扩展docs/ARCHITECTURE.md + docs/RELIABILITY.md
9	ddia-systems	数据层在并发场景下是否正确且持久？	扩展docs/ARCHITECTURE.md

Operating Rules

操作规则

Resume first. Before anything else, read
```
docs/IMPROVE-CODE-QUALITY-PLAN.md
```
and every artifact in the Journey Map. If the tracker exists, summarize the journey state in 3-5 lines and ask which phase to enter. Done when the user has confirmed an entry point. A journey with a tracker is resumed, never restarted.
Intake on first run only. No tracker: run the Intake below, then create
```
docs/IMPROVE-CODE-QUALITY-PLAN.md
```
with every phase statused
```
pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason
```
. Done when the tracker exists and the user has confirmed the phase plan.
Phase entry. Announce: what the phase does, the decision it forces, the artifact it produces, rough effort. Offer proceed / skip / defer — phases marked GATE may be deferred, never skipped. Mark the phase
```
in-progress
```
on proceed. Done when the user chose.
Skill invocation and fallback. Load the phase's skill and use it: each phase's Invoke line names the skill by slug — use that skill to run the phase. If it is not available, offer:
```
npx skills add wondelai/skills/<slug> --global
```
. If the user declines, run the phase from its Brief — the minimum viable method. State which mode you are in.
In-phase decisions. Ask every question under "Decide with the user" — with concrete options and your recommendation. Record the choice in the tracker's Key Decisions. A decision made silently is a defect.
Phase exit. Present the draft artifact content for sign-off before writing. On approval: write or extend the docs/ files, update the tracker (status, Key Decisions, Next Actions). Done when the files are written and the phase row shows
```
done
```
.
Artifact discipline. Read before writing; create a file only if missing, otherwise extend — add or update your sections, preserve everyone else's. Files are UPPERCASE in
```
docs/
```
. Every recommendation lands as a checkbox or a table row with owner and priority. See references/artifact-templates.md when creating a docs/ file for the first time — create it from the full skeleton (all section headings), then fill the sections your phase names.
Phase 1 is a gate; commits stay single-purpose. No phase touches code absent from the Safety Net Map — pin it first (absent means not listed under Pinned behaviors; entries in the Gaps column are off-limits too). Structural and behavioral changes never share a commit: refactor with tests green in a structure-only commit, then change behavior in its own commit. A test that goes red mid-refactoring means revert and retry in smaller steps, not debug. Safety-net test additions and docs/ updates are single-purpose commits of their own.

优先续接流程。 首先读取
```
docs/IMPROVE-CODE-QUALITY-PLAN.md
```
和路线图中的所有产出物。如果存在追踪文件，用3-5行总结当前流程状态，并询问进入哪个阶段。当用户确认进入点后完成此步骤。已有追踪文件的流程只能续接，不能重启。
仅首次运行时收集信息。 无追踪文件：执行下方的信息收集步骤，然后创建
```
docs/IMPROVE-CODE-QUALITY-PLAN.md
```
，将每个阶段标记为
```
pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason
```
。当追踪文件创建完成且用户确认阶段计划后完成此步骤。
进入阶段。 告知用户：该阶段的作用、需要做出的决策、产出的文档、大致工作量。提供继续/跳过/推迟选项——标记为必经关卡的阶段可推迟，但不能跳过。选择继续则将阶段标记为
```
in-progress
```
。当用户做出选择后完成此步骤。
调用技能与备选方案。 加载该阶段的技能并使用：每个阶段的调用行以短名称指定技能——使用该技能推进阶段。若技能不可用，提供方案：
```
npx skills add wondelai/skills/<slug> --global
```
。若用户拒绝，则使用该技能的简要说明（最小可行方法）推进阶段，并告知当前使用的模式。
阶段内决策。 提出所有「与用户共同决策」的问题——提供具体选项和你的建议。将选择记录在追踪文件的「关键决策」部分。未明确做出的决策视为缺陷。
退出阶段。 在写入前展示文档草稿供用户确认。获得批准后：写入或扩展docs/文件夹中的文件，更新追踪文件（状态、关键决策、下一步行动）。当文件写入完成且阶段标记为
```
done
```
后完成此步骤。
文档规范。 先读后写；仅当文件不存在时创建，否则扩展——添加或更新你的部分，保留他人编写的内容。docs/文件夹中的文件均为大写。所有建议需以复选框或包含负责人、优先级的表格行呈现。首次创建docs/文件时，请参考references/artifact-templates.md——从完整框架（所有章节标题）创建，再填充当前阶段对应的章节。
阶段1是必经关卡；提交需保持单一目的。 任何阶段不得修改安全网映射中未列出的代码——先锁定代码（未列出指未在「锁定行为」下记录；「缺口」列中的内容也禁止修改）。结构变更和行为变更不得在同一提交中：在结构变更提交中保持测试全绿，然后在单独的提交中修改行为。重构过程中测试变红意味着回退并以更小步骤重试，而非调试。安全网测试新增和docs/文件更新需作为单独的提交。

Intake

信息收集

Ask these before creating the tracker:

What does the app do, and what is the worst thing that happens if it breaks? (frames risk and sets phase priority)
Which module are you changing next, and which has the highest churn (
```
git log
```
) or is core domain? (picks the Phase 1 starting module — the three-axis heuristic)
Do any automated tests exist today, and does a test command run green? (scopes the Phase 1 safety net)
What is the stack — framework, ORM, database? (gates Phases 5 and 9 — the boundary and data decisions)
Is this in production with real user data, and roughly how many active users or requests? (gates Phases 7-9 — resilience is requirements-driven)
What outbound dependencies does it call — third-party APIs, payments, email, queues? (gates Phase 7 — the integration-point audit)
How much of the journey do you want now? (Phases 1-3 before real users; Phase 7 before launch; Phases 8-9 track actual growth)

Phase-skip heuristics: skip Phases 8-9 when real load is far below any scaling threshold (start with requirements, not solutions — don't build for 50k users while at 50). Phase 7 is not optional once real users exist — timeouts and a circuit breaker are table stakes even at low traffic (it may stay

deferred: reason

, never

skipped

). Never skip Phase 1; it is the gate. Then create the tracker from the template and confirm the plan.

Done when

docs/IMPROVE-CODE-QUALITY-PLAN.md

exists with every phase statused and the user has confirmed the plan.

创建追踪文件前需询问以下问题：

应用的功能是什么？如果它崩溃，最严重的后果是什么？（定义风险并设置阶段优先级）
你接下来要修改哪个模块？哪个模块的变更频率最高（
```
git log
```
）或属于核心业务域？（选择阶段1的起始模块——三维启发式）
当前是否存在自动化测试？测试命令能否正常运行并通过？（确定阶段1安全网的范围）
技术栈是什么——框架、ORM、数据库？（为阶段5和9设置前提——边界和数据决策）
它是否已上线并处理真实用户数据？大致有多少活跃用户或请求量？（为阶段7-9设置前提——韧性由需求驱动）
它调用哪些外部依赖——第三方API、支付服务、邮件服务、队列？（为阶段7设置前提——集成点审计）
你现在想要推进流程的哪一部分？（真实用户使用前完成阶段1-3；上线前完成阶段7；阶段8-9跟踪实际增长）

阶段跳过规则：当实际负载远低于任何扩容阈值时，跳过阶段8-9（从需求出发，而非解决方案——不要在只有50个用户时为5万用户做架构）。一旦有真实用户，阶段7不可选——即使低流量下，超时和断路器也是必备项（可标记为

deferred: reason

，但不能标记为

skipped

）。永远不能跳过阶段1；它是必经关卡。然后从模板创建追踪文件并确认计划。

当

docs/IMPROVE-CODE-QUALITY-PLAN.md

创建完成，所有阶段已标记状态且用户确认计划后完成此步骤。

Phases

各阶段详情

Phases run in the listed order — each assumes the previous phase's artifact exists. Any phase can be entered, skipped, or deferred per the Operating Rules, but Phase 1 gates them all: nothing downstream touches unpinned code.

阶段按列出的顺序推进——每个阶段都假设前一阶段的产出物已存在。根据操作规则，任何阶段都可进入、跳过或推迟，但阶段1是所有后续阶段的前提：未锁定的代码不得进行任何后续操作。

Phase 1 — Build the safety net (working-with-legacy-code) — GATE

阶段1 — 搭建安全网（working-with-legacy-code）—— 必经关卡

Purpose: Pin current behavior at the change points so every later phase is verifiable. No phase may touch code absent from the Safety Net Map.

Brief (fallback): Legacy code is code without tests, so a week-old prototype qualifies. Cover and modify, never edit and pray: identify change points, break inline dependencies with the least-invasive seam (Parameterize Constructor with a production default; Extract and Override for one buried call), then write characterization tests that photograph actual behavior — assert something wrong, read the failure, pin the real value. When full coverage isn't feasible in time, Sprout/Wrap the new code and track the untested host as debt.

Invoke: Use the

working-with-legacy-code

skill with the starting module chosen at intake. Ask for an effect sketch from the entry method, the seams, and the smallest characterization-test set that pins current signup / billing / core behavior.

Decide with the user: (1) Confirm the starting module by the three-axis heuristic — changing next, high churn, core domain. (2) Bugs found while characterizing: pin the wrong behavior and file it in the Debt Ledger, never silently fix — callers may depend on the quirk. Confirm the user accepts this.

Artifact: Create docs/TESTING.md with

## Test Strategy

## Safety Net Map

(module | pinned behaviors | test files | gaps), and

## Characterization Backlog

; create docs/TECH-DEBT.md with

## Debt Ledger

## Sprout / Wrap Register

. Update the tracker.

Done when: the target module's behavior is pinned, the suite runs green, both files exist, and Phase 1 shows

done

— only then are later phases unlocked.

目标： 在变更点锁定当前行为，确保后续每个阶段都可验证。任何阶段不得修改安全网映射中未列出的代码。

简要说明（备选方案）： 遗留代码指没有测试的代码，因此一周前的原型符合定义。先覆盖再修改，而非直接编辑碰运气：识别变更点，用侵入性最小的方式打破内联依赖（带生产环境默认值的构造函数参数化；对隐藏调用使用提取与覆盖），然后编写特征测试记录实际行为——先断言错误结果，查看失败信息，再锁定真实值。若无法及时实现全覆盖，可新增/包裹新代码，并将未测试的主代码记录为技术债务。

调用： 使用

working-with-legacy-code

技能，针对信息收集阶段选定的起始模块。请求入口方法的效果草图、依赖切入点，以及能锁定当前注册/计费/核心行为的最小特征测试集。

与用户共同决策： (1) 通过三维启发式确认起始模块——即将修改、变更频率高、核心业务域。(2) 特征测试中发现的Bug：锁定错误行为并记录在债务台账中，不得悄悄修复——调用方可能依赖该异常行为。确认用户接受此方案。

产出物： 创建docs/TESTING.md，包含

## 测试策略

、

## 安全网映射

（模块 | 锁定行为 | 测试文件 | 缺口）和

## 特征测试待办

；创建docs/TECH-DEBT.md，包含

## 债务台账

（项 | 位置 | 类型 | 风险 | 工作量 | 优先级 | 状态）和

## 新增/包裹注册

。更新追踪文件。

完成标志： 目标模块的行为已锁定，测试套件全绿，两个文件已创建，阶段1标记为

done

——此时后续阶段才会解锁。

Phase 2 — Make the code readable (clean-code)

阶段2 — 提升代码可读性（clean-code）

Purpose: Optimize for the reader — names, small single-purpose functions, safe error handling — now that changes are verifiable.

Brief (fallback): Code is read far more than written. Names reveal intent (

elapsedTimeInDays

, not

); booleans read as predicates; functions do one thing at one level of abstraction with 0-2 arguments (a flag argument is two functions). Command-Query Separation: change state or return a value, never both. Error handling: prefer exceptions to return codes, catch specific types, never return or pass null (use an empty collection, Optional, or Null Object), and put operation + state context in every thrown error.

Invoke: Use the

clean-code

skill with a target module. Ask for a 0-10 score across the six disciplines plus the top ten fixes in priority order, and an error-handling audit (bare catches, null returns, contextless errors).

Decide with the user: Which fixes to apply now versus log as debt, the naming / error-handling conventions the team adopts going forward, and whether the clean-code score becomes a CI gate.

Artifact: Extend docs/TECH-DEBT.md: add rows to

## Smell Inventory

(smell | location | refactoring | status) for each name / function / error smell, and record the agreed rules under

## Adopted Conventions

. Update the tracker.

Done when: the module scores 8+ or every gap below 8 is a Smell Inventory row with a fix, conventions are recorded, and the Phase 1 tests still pass.

目标： 为代码阅读者优化——命名、小而单一职责的函数、安全的错误处理——现在变更已可验证。

简要说明（备选方案）： 代码的阅读次数远多于编写次数。命名需体现意图（

elapsedTimeInDays

，而非

）；布尔值需以谓词形式呈现；函数需单一职责、单一抽象层级，参数为0-2个（标志参数等同于两个函数）。命令查询分离：要么修改状态，要么返回值，不可两者兼具。错误处理：优先使用异常而非返回码，捕获特定类型，绝不返回或传递null（使用空集合、Optional或空对象），并在每个抛出的错误中包含操作和状态上下文。

调用： 使用

clean-code

技能处理目标模块。请求从六个维度给出0-10分的评分，以及优先级最高的十大修复项，同时进行错误处理审计（无捕获范围的catch、返回null、无上下文的错误）。

与用户共同决策： 哪些修复现在执行，哪些记录为债务；团队后续采用的命名/错误处理规范；代码整洁度评分是否成为CI关卡。

产出物： 扩展docs/TECH-DEBT.md：为每个命名/函数/错误问题在

## 问题清单

（问题 | 位置 | 重构方案 | 状态）中添加行，并在

## 已采用规范

下记录达成一致的规则。更新追踪文件。

完成标志： 模块评分达到8分以上，或8分以下的每个缺口都已在问题清单中记录修复方案，规范已记录，且阶段1的测试仍全绿。

Phase 3 — Apply named refactorings (refactoring-patterns)

阶段3 — 应用命名重构模式（refactoring-patterns）

Purpose: Turn "clean it up" into named, behavior-preserving transformations executed in small steps.

Brief (fallback): Each smell maps to a named refactoring. Extract Method is the workhorse — if you would write a comment to explain a block, extract it and name it after the comment. Also Replace Magic Number with Symbolic Constant, Replace Nested Conditional with Guard Clauses, Replace Conditional with Polymorphism, Introduce Parameter Object. Workflow: tests green, one transformation, tests green, commit; a red test means revert, not debug. Preparatory Refactoring (make the change easy, then make the easy change) and the Rule of Three guard against premature abstraction.

Invoke: Use the

refactoring-patterns

skill with a smelly function and the Phase 1 tests. Ask it to name each smell, cite the transformation, and apply one at a time with tests run between each.

Decide with the user: Scope — which smells to address this pass, whether an upcoming feature warrants a Preparatory Refactoring at its insertion point first, and whether the refactored module joins the CI gate list in TESTING.md.

Artifact: Extend docs/TECH-DEBT.md

## Smell Inventory

: for each smell, record the named refactoring applied and its status. Update the tracker.

Done when: targeted smells show a named refactoring and

done

ticketed

status, tests are green, and structural changes landed in structure-only commits.

目标： 将「整理代码」转化为命名明确、不改变行为的分步转换操作。

简要说明（备选方案）： 每个代码问题都对应一种命名重构模式。提取方法是核心工具——如果你需要写注释解释某块代码，就将其提取并以注释内容命名。还包括用符号常量替换魔法数字、用卫语句替换嵌套条件、用多态替换条件、引入参数对象。工作流程：测试全绿→执行一次转换→测试全绿→提交；测试变红意味着回退，而非调试。预备重构（先让变更变得容易，再进行变更）和三次原则可避免过早抽象。

调用： 使用

refactoring-patterns

技能处理存在问题的函数，并结合阶段1的测试。请求命名每个问题、引用对应的转换模式，并分步应用，每步后运行测试。

与用户共同决策： 范围——本次处理哪些问题；即将开发的功能是否需要先在插入点进行预备重构；重构后的模块是否加入TESTING.md中的CI关卡列表。

产出物： 扩展docs/TECH-DEBT.md的

## 问题清单

：为每个问题记录应用的命名重构模式及其状态。更新追踪文件。

完成标志： 目标问题已记录命名重构模式和

done

ticketed

状态，测试全绿，结构变更已提交到仅包含结构修改的提交中。

Phase 4 — Reduce complexity with deep modules (software-design-philosophy)

阶段4 — 用深层模块降低复杂度（software-design-philosophy）

Purpose: Fight the classitis an unsupervised agent creates — hide real machinery behind simple interfaces instead of multiplying shallow classes.

Brief (fallback): Complexity is the enemy; minimize what a module imposes on the rest of the system. Module depth = functionality ÷ interface complexity; deep modules hide machinery behind small interfaces, shallow ones don't (classitis). Merge shallow classes that always travel together and share state. Watch information leakage (one decision reflected in many modules) and temporal decomposition (organizing by order-of-execution, not by knowledge). This is the tactical→strategic flip: invest 10-20% to keep the design clean.

Invoke: Use the

software-design-philosophy

skill with the module set touched so far. Ask which classes are shallow, where information leaks across boundaries, and how to consolidate into deeper modules with simpler interfaces.

Decide with the user: Which consolidations to make now versus defer, guarding against over-merging unrelated concerns.

Artifact: Extend docs/TECH-DEBT.md

## Smell Inventory

with classitis / shallow-module / information-leakage entries and the consolidation applied. Update the tracker.

Done when: each shallow-module cluster is consolidated or logged with a fix, interface count did not grow for the sake of "modularity", and tests are green.

目标： 解决无监督Agent生成的「类爆炸」问题——将复杂逻辑隐藏在简单接口后，而非增加大量浅层类。

简要说明（备选方案）： 复杂度是敌人；尽量减少模块对系统其他部分的影响。模块深度=功能÷接口复杂度；深层模块通过小接口隐藏复杂逻辑，浅层模块则不然（类爆炸）。合并总是一起出现且共享状态的浅层类。注意信息泄漏（一个决策体现在多个模块中）和时间分解（按执行顺序而非知识领域组织）。这是从战术到战略的转变：投入10-20%的精力维持设计整洁。

调用： 使用

software-design-philosophy

技能处理目前涉及的模块集。请求指出哪些类是浅层的、跨边界的信息泄漏点，以及如何合并为接口更简单的深层模块。

与用户共同决策： 哪些合并现在执行，哪些推迟；避免合并无关的关注点。

产出物： 扩展docs/TECH-DEBT.md的

## 问题清单

，添加类爆炸/浅层模块/信息泄漏项及已应用的合并方案。更新追踪文件。

完成标志： 每个浅层模块集群已合并或记录修复方案，接口数量未为了「模块化」而增加，测试全绿。

Phase 5 — Draw the architecture boundary (clean-architecture)

阶段5 — 划定架构边界（clean-architecture）

Purpose: Make the framework and database depend on the business rules, not the reverse.

Brief (fallback): The Dependency Rule: source dependencies point inward — Entities, then Use Cases, then Interface Adapters, then Frameworks/Drivers; nothing inner names anything outer. The database and web are details, plugins to your rules. Enforce with Dependency Inversion: a Use Case owns a repository interface; the Postgres/Stripe implementation lives in an outer adapter. SOLID are the mid-level tools. Microservices sharing one data model are a distributed monolith — apply the rule inside the service first.

Invoke: Use the

clean-architecture

skill with the current module map and the stack from intake. Ask it to map the dependency graph, list every violation where business logic imports the ORM or framework, and show the extraction to framework-free Use Cases behind owned interfaces.

Decide with the user: How far to push the boundary this pass, which vendors (payments, storage) to wrap behind owned interfaces first, and whether any planned service split waits until the in-service boundary holds (avoid a distributed monolith).

Artifact: Extend docs/ARCHITECTURE.md: record layers and current violations under

## Layer Map & Dependency Rule

(violation | location | fix | status) and the boundary choices under

## Decision Log

. Update the tracker.

Done when: every Dependency Rule violation is a tracked row with a fix, at least the highest-risk vendor is wrapped, business-rule tests run with no framework, and tests are green.

目标： 让框架和数据库依赖业务规则，而非反过来。

简要说明（备选方案）： 依赖规则：源码依赖指向内部——实体层→用例层→接口适配器层→框架/驱动层；内部层不得引用外部层的任何内容。数据库和Web是细节，是业务规则的插件。通过依赖反转实现：用例层定义仓库接口；Postgres/Stripe的实现位于外部适配器中。SOLID是中层工具。共享同一数据模型的微服务是分布式单体——先在服务内部应用该规则。

调用： 使用

clean-architecture

技能处理当前模块映射和信息收集阶段的技术栈。请求绘制依赖图、列出所有业务逻辑引用ORM或框架的违规项，并展示如何将其提取为不依赖框架的用例，置于自有接口之后。

与用户共同决策： 本次推进边界划定的程度；优先将哪些供应商（支付、存储）包裹在自有接口后；是否等待服务内部边界稳定后再进行计划中的服务拆分（避免分布式单体）。

产出物： 扩展docs/ARCHITECTURE.md：在

## 层映射与依赖规则

（违规项 | 位置 | 修复方案 | 状态）下记录层级和当前违规项，在

## 决策日志

下记录边界选择。更新追踪文件。

完成标志： 每个依赖规则违规项都已记录修复方案，至少最高风险的供应商已被包裹，业务规则测试可在无框架环境下运行，测试全绿。

Phase 6 — Lock in the habits (pragmatic-programmer)

阶段6 — 固化良好习惯（pragmatic-programmer）

Purpose: Set the meta-principles that keep the codebase changeable after this journey ends.

Brief (fallback): DRY is about knowledge, not text — de-duplicate the same rule in two places (validation on client and server), leave coincidental look-alikes alone. Orthogonality: changing one component shouldn't affect another. Broken Window Theory: fix hacks immediately or board them up with a tracked ticket — never an untracked

// TODO

. Reversibility: wrap third-party vendors behind your own interfaces. Tracer bullets: build the next feature as one thin real end-to-end slice, not layer by layer.

Invoke: Use the

pragmatic-programmer

skill across the codebase. Ask it to flag duplicated knowledge (ignoring coincidental duplication) and any broken windows or untracked TODOs that need boarding up.

Decide with the user: The debt budget per iteration and the broken-windows policy — what gets fixed now versus ticketed.

Artifact: Extend docs/TECH-DEBT.md: record duplicated-knowledge and broken-window items in

## Debt Ledger

, and the agreed policy under

## Debt Budget & Broken-Windows Policy

and

## Adopted Conventions

. Update the tracker.

Done when: duplicated-knowledge hits are ledgered or fixed, no untracked hacks remain, and the debt-budget policy is written down.

目标： 设定元原则，确保流程结束后代码库仍可修改。

简要说明（备选方案）： DRY原则针对的是知识，而非文本——消除同一规则在两处的重复（客户端和服务端的验证），保留偶然的相似代码。正交性：修改一个组件不应影响另一个组件。破窗理论：立即修复临时方案，或用追踪工单记录——绝不留下未追踪的

// TODO

。可逆性：将第三方供应商包裹在自有接口后。示踪弹：将下一个功能作为端到端的薄切片构建，而非逐层构建。

调用： 使用

pragmatic-programmer

技能扫描整个代码库。请求指出重复的知识（忽略偶然重复）以及需要处理的破窗或未追踪TODO项。

与用户共同决策： 每次迭代的债务预算，以及破窗处理策略——哪些现在修复，哪些记录为工单。

产出物： 扩展docs/TECH-DEBT.md：在

## 债务台账

中记录重复知识和破窗项，在

## 债务预算与破窗策略

和

## 已采用规范

下记录达成一致的政策。更新追踪文件。

完成标志： 重复知识项已记录或修复，无未追踪的临时方案，债务预算政策已书面记录。

Phase 7 — Make it survive production (release-it)

阶段7 — 确保生产环境存活能力（release-it）

Purpose: Harden every integration point so a slow or failing dependency degrades gracefully instead of taking the whole app down.

Brief (fallback): The software that passes QA is not what survives production. Integration points are the number-one killer — a slow response is worse than none. Non-negotiables: connect + read timeouts on every outbound call; a Circuit Breaker on failing dependencies (trips open, fails fast, half-open recovery); Bulkheads to isolate resource pools; Retry with exponential backoff + jitter; Steady State cleanup of accumulating cruft. Decouple deploy from release with feature flags and expand-contract migrations. Add deep health checks, RED metrics, symptom-based alerts.

Invoke: Use the

release-it

skill with the outbound dependencies from intake. Ask for an audit of calls with no timeout, circuit-breaker + bulkhead placement, and a deep health check + RED metrics + alert design.

Decide with the user: Breaker thresholds, which dependencies get dedicated pools, and the alert symptoms and thresholds (error rate, latency).

Artifact: Create docs/RELIABILITY.md with

## Integration-Point Audit

## Health Checks & Metrics

, and

## Deploy vs Release

. Update the tracker.

Done when: every outbound call has a timeout, critical dependencies have breakers and bulkheads, a deep health check + RED metrics + symptom alerts exist, steady-state cleanup is scheduled for accumulating cruft, a release can be rolled back without a redeploy, and the audit table has no open rows for critical paths.

目标： 加固每个集成点，确保依赖变慢或失败时应用能优雅降级，而非整体崩溃。

简要说明（备选方案）： 通过QA的软件不一定能在生产环境存活。集成点是头号杀手——慢响应比无响应更糟。必备项：每个外部调用设置连接+读取超时；对失败的依赖使用断路器（触发后断开连接、快速失败、半开恢复）；使用隔离舱隔离资源池；带指数退避+抖动的重试机制；定期清理累积的冗余数据。用功能标志和扩缩容迁移解耦部署与发布。添加深度健康检查、RED指标、基于症状的告警。

调用： 使用

release-it

技能处理信息收集阶段的外部依赖。请求审计无超时的调用、断路器+隔离舱的部署位置，以及深度健康检查+RED指标+告警设计。

与用户共同决策： 断路器阈值、哪些依赖使用专用资源池、告警症状和阈值（错误率、延迟）。

产出物： 创建docs/RELIABILITY.md，包含

## 集成点审计

（依赖 | 超时 | 断路器 | 隔离舱 | 重试策略 | 状态）、

## 健康检查与指标

和

## 部署与发布解耦

。更新追踪文件。

完成标志： 每个外部调用都设置了超时，关键依赖配备了断路器和隔离舱，存在深度健康检查+RED指标+基于症状的告警，已计划定期清理累积冗余数据，无需重新部署即可回滚发布，审计表中关键路径无未完成项。

Phase 8 — Size for real load (system-design)

阶段8 — 匹配实际负载规模（system-design）

Purpose: Scale deliberately from requirements and numbers, not reactively — add machinery only when estimates justify it.

Brief (fallback): Start with requirements, not solutions. Back-of-envelope: QPS = daily-active-users × actions/day ÷ 86,400, peak 2-5× average; storage = records/day × size × retention. Scale in order: vertical first, then cache (cache-aside with a TTL and explicit invalidation) for read-heavy paths, then read replicas, and shard only as a last resort. Use a message queue to decouple slow work from the request path. Reach for known designs (rate limiter → token bucket returning

429 Retry-After

Invoke: Use the

system-design

skill with the load reality from intake. Ask for average and peak QPS, yearly storage, which component bottlenecks first, and a priority-ordered list of cache / queue / replica moves without over-engineering.

Decide with the user: Which scaling moves to make now versus defer, tied to the actual numbers (don't build for 50k users while at 50), and name the first slow workload to move behind a message queue, if any.

Artifact: Extend docs/ARCHITECTURE.md

## System Context

with the load reality and back-of-envelope numbers; extend docs/RELIABILITY.md

## Query & Resource Findings

with unbounded queries and bottlenecks. Update the tracker.

Done when: the QPS and storage numbers are recorded, the first bottleneck is named, and each scaling move is either applied or deferred with the triggering number written down.

目标： 根据需求和数据进行有计划的扩容，而非被动应对——仅当估算结果证明必要时才增加资源。

简要说明（备选方案）： 从需求出发，而非解决方案。粗略估算：QPS = 日活跃用户×每日操作数÷86400，峰值为平均值的2-5倍；存储量 = 每日记录数×单条大小×保留时长。扩容顺序：先垂直扩容，再为读密集路径添加缓存（带TTL和显式失效的旁路缓存），然后添加读副本，最后才考虑分片。使用消息队列将慢操作与请求路径解耦。采用成熟设计（限流→令牌桶返回

429 Retry-After

）。

调用： 使用

system-design

技能处理信息收集阶段的实际负载。请求给出平均和峰值QPS、年存储量、首个瓶颈组件，以及按优先级排序的缓存/队列/副本方案，避免过度设计。

与用户共同决策： 哪些扩容方案现在执行，哪些推迟，需结合实际数据（不要在只有50个用户时为5万用户做架构）；确定首个要迁移到消息队列后的慢操作（如有）。

产出物： 扩展docs/ARCHITECTURE.md的

## 系统上下文

，记录实际负载和粗略估算数据；扩展docs/RELIABILITY.md的

## 查询与资源发现

，记录无界查询和瓶颈。更新追踪文件。

完成标志： QPS和存储量已记录，首个瓶颈已明确，每个扩容方案要么已应用，要么已推迟并记录触发阈值。

Phase 9 — Get the data layer right (ddia-systems)

阶段9 — 优化数据层（ddia-systems）

Purpose: Protect the data that outlives the code — correctness under concurrency, and datastore choices made by requirement, not habit.

Brief (fallback): Data outlives code. Most databases default to read-committed or snapshot, not serializable — naive read-then-write triggers write skew (two requests both selling the last item). Fix explicitly with

SELECT ... FOR UPDATE

or a serializable transaction; know your actual default. Replication lag means read-your-writes and monotonic-reads must be deliberate once replicas exist. Match data model to access pattern; polyglot persistence is often correct; separate system-of-record from derived data (CDC / event sourcing) rather than dual writes.

Invoke: Use the

ddia-systems

skill with the database from intake and the replica plan from Phase 8. Ask it to find write-skew-prone read-then-write paths, state the actual default isolation level and its anomalies, and fix the risky paths.

Decide with the user: Which paths need locking versus a serializable transaction, and whether a new workload (search, feed) justifies a second datastore kept in sync by CDC.

Artifact: Extend docs/ARCHITECTURE.md

## Data & Storage Decisions

with the isolation level, locked paths, and any polyglot / derived-data choices; log the reasoning in

## Decision Log

. Update the tracker.

Done when: the default isolation level is documented, every write-skew-prone path is locked or made serializable, and any new datastore has a defined sync mechanism.

目标： 保护比代码生命周期更长的数据——确保并发场景下的正确性，根据需求而非习惯选择数据存储方案。

简要说明（备选方案）： 数据的生命周期比代码长。大多数数据库默认隔离级别为读已提交或快照，而非可串行化——简单的读-写操作会触发写倾斜（两个请求同时售出最后一件商品）。需显式修复：使用

SELECT ... FOR UPDATE

或可串行化事务；了解数据库的实际默认值。存在副本时，复制延迟意味着需刻意保证读己写和单调读。数据模型需匹配访问模式；多语言持久化通常是正确选择；将系统记录与衍生数据分离（CDC/事件溯源），而非双写。

调用： 使用

ddia-systems

技能处理信息收集阶段的数据库和阶段8的副本计划。请求找出易发生写倾斜的读-写路径、说明实际默认隔离级别及其异常，并修复高风险路径。

与用户共同决策： 哪些路径需要锁定，哪些使用可串行化事务；新工作负载（搜索、信息流）是否需要通过CDC同步的第二个数据存储。

产出物： 扩展docs/ARCHITECTURE.md的

## 数据与存储决策

，记录隔离级别、锁定路径，以及任何多语言/衍生数据选择；在

## 决策日志

中记录理由。更新追踪文件。

完成标志： 默认隔离级别已记录，每个易发生写倾斜的路径已锁定或设置为可串行化，任何新增数据存储已定义同步机制。

Optional Phases

可选阶段

Skill	Add when	Artifact
domain-driven-design	Business logic tangles because the code speaks no domain language	Extends docs/ARCHITECTURE.md ( `## Bounded Contexts & Context Map` , `## Domain Glossary (Ubiquitous Language)` )

Optional phases follow the same operating rules — load and use each listed skill exactly as a core phase would; insert where the Add-when condition first becomes true — here, right after Phase 5 once the boundary exists.

技能	适用场景	产出物
domain-driven-design	业务逻辑混乱，因为代码未使用领域语言	扩展docs/ARCHITECTURE.md（ `## 限界上下文与上下文映射` 、 `## 领域术语表（通用语言）` ）

可选阶段遵循相同操作规则——完全按照核心阶段的方式加载和使用列出的技能；在适用场景首次出现时插入——此处为阶段5之后，边界划定完成时。

Common Mistakes

常见错误

Mistake	Fix
Cleaning up before writing a single test	Pin behavior with characterization tests in Phase 1 (working-with-legacy-code) first; the safety net gates every later phase.
Letting the agent "modularize" into a swarm of tiny classes	Apply software-design-philosophy's deep-module rule — merge shallow classes that travel together; reduce interfaces, don't multiply them.
Calling external APIs with no timeout	In Phase 7 (release-it) add connect + read timeouts on every outbound call, plus a circuit breaker on critical dependencies.
Scaling before sizing anything	Do back-of-envelope estimation first (system-design); the numbers usually say a cache and a read replica are years of runway.
Mistaking microservices for architecture	Apply the Dependency Rule inside the service first (clean-architecture); services sharing one data model are a distributed monolith.
Assuming the database is serializable	Check the actual default isolation level and lock read-then-write paths (ddia-systems) — write skew passes every single-user test.

错误	修复方案
未写任何测试就整理代码	先在阶段1（working-with-legacy-code）用特征测试锁定行为；安全网是所有后续阶段的前提。
让Agent「模块化」成大量微小类	应用software-design-philosophy的深层模块规则——合并一起出现的浅层类；减少接口，而非增加。
调用外部API未设置超时	在阶段7（release-it）为每个外部调用添加连接+读取超时，为关键依赖添加断路器。
未评估规模就扩容	先进行粗略估算（system-design）；数据通常表明缓存和读副本能支撑多年的增长。
将微服务视为架构解决方案	先在服务内部应用依赖规则（clean-architecture）；共享同一数据模型的服务是分布式单体。
假设数据库默认是可串行化	检查实际默认隔离级别并锁定读-写路径（ddia-systems）——写倾斜能通过所有单用户测试。

Completing the Journey

完成流程

Ship in order, not all at once: Phases 1-3 (net, readability, refactoring) belong before real users arrive; the Phase 5 boundary pays off most before the codebase doubles again; harden Phase 7 before launch (timeouts and a breaker are not optional even at low traffic); let Phases 8-9 track your actual growth numbers.

Exit checklist — every box tied to an artifact:

Business rules have tests that run with no database or framework (TESTING.md Safety Net Map complete for changed modules).
Every outbound call has a timeout, critical dependencies have circuit breakers, and a deep health check + RED metrics are wired to symptom-based alerts (RELIABILITY.md Integration-Point Audit clear, Health Checks & Metrics filled).
Dependency Rule holds — business logic imports no framework or ORM (ARCHITECTURE.md Layer Map, violations closed).
Database isolation level known and read-then-write paths locked (ARCHITECTURE.md Data & Storage Decisions).
No untracked hacks remain; every deferred item is a Debt Ledger row with priority (TECH-DEBT.md).

Close the tracker: every phase

done

skipped: reason

, with remaining Next Actions carried into the TECH-DEBT.md Debt Ledger so nothing is lost. Then route forward: when the codebase is old and large rather than young and messy, continue with the

remove-technical-debt

skill; when the next system deserves deliberate structure from day one, continue with the

design-code-architecture

skill.

按顺序交付，而非一次性完成：阶段1-3（安全网、可读性、重构）应在真实用户使用前完成；阶段5的边界划定在代码库规模翻倍前收益最大；上线前需完成阶段7的加固（即使低流量下，超时和断路器也是必备项）；阶段8-9跟踪实际增长数据。

退出检查清单——每项都对应产出物：

业务规则测试可在无数据库或框架的环境下运行（TESTING.md中变更模块的安全网映射已完成）。
每个外部调用都设置了超时，关键依赖配备了断路器，深度健康检查+RED指标已关联基于症状的告警（RELIABILITY.md中集成点审计无未完成项，健康检查与指标已填充）。
依赖规则已生效——业务逻辑未引用任何框架或ORM（ARCHITECTURE.md中层映射的违规项已处理）。
数据库隔离级别已明确，读-写路径已锁定（ARCHITECTURE.md中数据与存储决策已记录）。
无未追踪的临时方案；每个推迟项都已在债务台账中记录优先级（TECH-DEBT.md）。

关闭追踪文件：每个阶段标记为

done

或

skipped: reason

，剩余下一步行动转入TECH-DEBT.md的债务台账，确保无遗漏。后续指引：若代码库是大型老旧项目而非年轻的混乱项目，继续使用

remove-technical-debt

技能；若下一个系统需要从第一天开始就有明确结构，继续使用

design-code-architecture

技能。