incremental-impl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Incremental Implementation

增量实现

Pairs with planning. Plan sets direction and constraints (what to build, acceptance criteria). This skill decides how to execute: size, slice, dispatch, verify.

与规划流程配合使用。规划用于确定方向与约束（要构建的内容、验收标准）。本技能负责决定执行方式：大小评估、切片策略、任务调度、验证流程。

When to Use

使用场景

Invoke for any non-trivial implementation work:

Multi-file feature implementation
Refactoring spanning multiple files
About to write more than ~100 lines
Executing a planned task (from any planning source — see Inputs)
Cross-cutting changes (analytics sweep, i18n pass, library migration)

Skip only for:

Single-file, single-function edits where slicing makes no sense
Pure documentation / config changes with no code logic

在进行任何非简单的代码实现工作时调用：

多文件功能实现
跨多文件的重构
将要编写超过约100行代码
执行已规划的任务（来自任意规划源——见输入部分）
跨切面修改（埋点梳理、i18n适配、库迁移）

仅在以下场景跳过：

单文件、单函数编辑，切片无意义的情况
纯文档/配置变更，无代码逻辑修改

Inputs

输入

A task or spec from any planning source — built-in Plan,
```
planning-with-files
```
's
```
task_plan.md
```
, a
```
brainstorming
```
spec under
```
docs/specs/
```
, or a task description from the user. The skill is agnostic to how the task was produced.
Acceptance criteria — what "done" looks like for this slice of work

If acceptance criteria are missing or vague, return control to planning before continuing. Implementation needs a target.

来自任意规划源的任务或规范：内置的Plan技能输出、
```
planning-with-files
```
生成的
```
task_plan.md
```
、
```
docs/specs/
```
下的
```
brainstorming
```
规范，或用户直接提供的任务描述。本技能对任务的生成方式无要求。
验收标准——当前切片工作的「完成」定义

如果验收标准缺失或模糊，需先返回规划流程补充信息。代码实现需要明确的目标。

Step 1: Size Gate

步骤1：大小评估 gate

Three axes, take the higher size when they disagree:

Size	Acceptance criteria	Distinct concerns	Est. diff lines	Skill behavior
XS	1	1	<30	Skip this skill; just write it
S	≤2	1–2	30–100	Apply execution discipline; do not slice
M	≤3	Multiple within 1 feature	100–300	Pick slicing strategy + single writer + execution discipline
L	4–6	Cross-component	300–800	Pick slicing strategy + evaluate parallel dispatch + execution discipline
XL	>6	Spans independent subsystems	>800	Return to plan. Too large to implement in one entry

A "concern" is one cohesive responsibility unit — a component, module, or single behavior.

Why take the higher size when axes disagree: under-categorizing (treating a real L as M) causes mid-flight merge conflicts and broken intermediate states. Over-categorizing wastes some ceremony. The asymmetric cost favors caution.

Examples:

"Add 12 analytics events, 2 lines each across 12 files" → AC=1, concerns=1 (analytics), <30 lines → XS
"One SwiftUI View, 400 lines, 5 subviews + state" → AC=3, concerns=1, >300 lines → M (diff lines escalate)
"Refactor auth middleware + update 3 callers + add tests" → AC=4, cross-component, ~400 lines → L

从三个维度评估，当维度结果不一致时取更高的等级：

大小	验收标准	独立关注点	预估代码变更行数	技能执行逻辑
XS	1项	1个	<30行	跳过本技能，直接编写代码
S	≤2项	1–2个	30–100行	执行规范流程，无需切片
M	≤3项	同一功能内的多个关注点	100–300行	选择切片策略 + 单人编写 + 执行规范流程
L	4–6项	跨组件	300–800行	选择切片策略 + 评估并行调度可行性 + 执行规范流程
XL	>6项	跨独立子系统	>800行	返回规划流程。规模过大，无法单次完成

「关注点」指一个内聚的责任单元——组件、模块或单一行为。

为什么维度不一致时取更高等级： 低估规模（将实际L级任务视为M级）会导致中途出现合并冲突和中间状态损坏。高估规模只会增加少量流程成本。不对称的成本风险倾向于谨慎评估。

示例：

"在12个文件中各添加2行代码，共12个埋点事件" → 验收标准=1，关注点=1（埋点），行数<30 → XS
"一个SwiftUI视图，400行代码，包含5个子视图+状态管理" → 验收标准=3，关注点=1，行数>300 → M（行数维度升级）
"重构认证中间件 + 更新3个调用方 + 添加测试" → 验收标准=4，跨组件，约400行 → L

Step 2: Pick Slicing Strategy

步骤2：选择切片策略

Run this decision tree top-to-bottom; first match wins.

Q1: Is this a greenfield 0→1 first cut? → Walking Skeleton. A single thin vertical path through every layer (data → service → UI → test), just enough to prove the architecture connects. Then thicken.

Q2: Is this "modify the same thing across many places" (analytics sweep, i18n, lint pass, mass refactor, design system rollout)? → Horizontal sweep. Single layer, many files, one cohesive change. One commit per logical group.

Q3: Is this a large architectural migration (UIKit→SwiftUI, sync→async, framework swap)? → Branch by Abstraction. Introduce a temporary abstraction layer, move implementations under it one at a time, retire the old path. Horizontal in shape but explicitly transitional.

Q4: Adding a new self-contained feature or fixing a bug? → Vertical slice. Model + business logic + view + tests in one cohesive change. Default for "add a new X" work in an existing codebase.

Fallback: Vertical slice.

Common confusion: "Vertical vs horizontal" is the slicing axis. "Serial vs parallel" is the writer count. They are orthogonal — vertical slices can be dispatched in parallel (three independent bug fixes across three files), and horizontal sweeps usually run serially.

按以下决策树从上到下判断，匹配到第一个选项即停止。

问题1：这是从0到1的全新项目首次实现吗？ → 行走骨架策略。构建一条贯穿所有层级的极简垂直路径（数据层→服务层→UI层→测试），仅需证明架构可连通，之后再逐步完善。

问题2：这是「在多个位置修改相同内容」的场景吗？（埋点梳理、i18n适配、代码规范检查、批量重构、设计系统落地） → 水平扫描策略。针对单一层级的多个文件，执行统一的修改。每个逻辑组对应一次提交。

问题3：这是大型架构迁移吗？（UIKit→SwiftUI、同步→异步、框架替换） → 抽象分支策略。引入临时抽象层，逐步将实现迁移到抽象层下，最终移除旧路径。形态上是水平的，但明确属于过渡性操作。

问题4：添加新的独立功能或修复Bug？ → 垂直切片策略。在一次内聚的变更中完成模型+业务逻辑+视图+测试。这是现有代码库中「新增X功能」工作的默认策略。

兜底策略： 垂直切片。

常见误区：「垂直vs水平」指的是切片的方向，「串行vs并行」指的是编写人数。二者是正交的——垂直切片可以并行调度（三个独立Bug分别在三个文件中修复），水平扫描通常串行执行。

Step 3: Parallel Dispatch (Conditional — L size only)

步骤3：并行调度（仅L级任务适用）

Skip this section for XS / S / M sizes. They run as a single writer.

For L size, decide whether to dispatch slices to parallel subagents.

XS/S/M级任务跳过此部分，由单人编写。

针对L级任务，判断是否将切片调度给并行子Agent。

The Iron Law

铁律

A slice plan is valid only when every slice has independent inputs and independent outputs. If two slices can collide — on the same file, on a shared data structure, or on shared mid-execution state — they are not parallel. Merge them into one writer, or serialize them.

切片计划仅在每个切片的输入和输出完全独立时才有效。如果两个切片可能发生冲突——修改同一文件、共享数据结构或共享执行中间状态——则无法并行执行。需合并为单人编写，或改为串行执行。

3.1 Slice-ability check

3.1 可切片性检查

Ask: can this task be cut into pieces whose inputs and outputs don't overlap?

✅ "Fix three independent bugs in three different files, each with its own test" — fully independent
✅ Greenfield: build store, service, ui as separate slices — only if no shared mid-execution state
❌ "Refactor utils.ts and update all callers" — cascading edits, serialize
❌ "Add retry to exec, then migrate callers to use it" — pipeline, not parallel

If no, terminate parallel dispatch and proceed as single writer.

提问：能否将任务拆分为输入和输出互不重叠的多个部分？

✅ "修复三个不同文件中的三个独立Bug，每个Bug都有对应的测试" ——完全独立
✅ 全新项目：将存储、服务、UI作为独立切片——仅当无共享执行中间状态时可行
❌ "重构utils.ts并更新所有调用方" ——连锁修改，需串行执行
❌ "为exec添加重试逻辑，然后迁移所有调用方使用该逻辑" ——流水线任务，无法并行

如果不可拆分，终止并行调度，改为单人编写。

3.2 Draft file assignments

3.2 草拟文件分配

For each candidate slice, list:

Files it creates / modifies / deletes
What it needs from other slices as input (paths, signatures, data shapes)
What it produces as output (diff, new files, state change)

针对每个候选切片，列出：

创建/修改/删除的文件
需要从其他切片获取的输入（路径、签名、数据结构）
产生的输出（代码差异、新文件、状态变更）

3.3 Collision check → merge

3.3 冲突检查 → 合并

For every file that appears in more than one slice:

Even append-only edits to the same file → merge to one writer (concurrent edits to adjacent lines produce conflicts)
Edits that overlap semantically → merge

对于出现在多个切片中的文件：

即使是对同一文件的追加式修改 → 合并为单人编写（相邻行的并发修改会产生冲突）
语义上重叠的修改 → 合并

3.4 Size filter

3.4 规模过滤

For each remaining slice, estimate diff lines:

<50 lines → drop from dispatch; main Agent handles inline. Dispatch overhead (worktree, context, merge) outweighs gain
50–150 lines → dispatch candidate
>150 lines or architectural → dispatch + note "stronger reasoning model at xhigh effort" on the slice

Minimum-slices gate: if fewer than 3 dispatchable slices remain after filtering, terminate parallel and serialize through the main Agent. Below 3 writers, ceremony cost > parallelism gain.

针对剩余的每个切片，预估代码变更行数：

<50行 → 取消调度；由主Agent直接处理。调度的开销（工作区、上下文、合并）大于收益
50–150行 → 候选调度切片
>150行或涉及架构 → 调度并标注「需使用更强推理模型，xhigh算力」

最小切片数限制： 如果过滤后可调度的切片少于3个，终止并行调度，改为主Agent串行执行。编写人数少于3时，流程成本大于并行收益。

3.5 Output contract + verify command per slice

3.5 输出约定 + 切片验证命令

For every dispatched slice, decide:

Output format the subagent must return (unified diff + rationale / full file + role / config section verbatim / test file + requirement map)
Verify command the main Agent will run when the diff comes back (
```
npm test -- path
```
,
```
tsc --noEmit
```
, build for affected package, minimal smoke test)

Without an output format, the subagent dumps verbose context and cancels the dispatch benefit. Without a verify command, the main Agent accepts whatever the subagent claims and merges blind.

针对每个调度切片，确定：

输出格式：子Agent必须返回的格式（统一差异+说明/完整文件+角色/配置段原文/测试文件+需求映射）
验证命令：主Agent在收到差异后将执行的命令（
```
npm test -- path
```
、
```
tsc --noEmit
```
、受影响包的构建、最小化冒烟测试）

没有输出格式，子Agent会输出冗余上下文，抵消调度收益。没有验证命令，主Agent会盲目接受子Agent的结果并合并。

3.6 Emit the dispatch plan

3.6 输出调度计划

Slice	Writer	Model	Files	Depends on	Output format	Verify
1	subagent	inherit	`src/x.ts`	—	diff + rationale	`npm test -- x`
2	subagent	inherit	`src/y.ts`	slice 1 signature	diff + rationale	`npm test -- y`
3	main Agent	—	`src/z.ts`	slice 1 complete	(inline)	`npm test`

Model column contract: default

inherit

— subagent uses the main Agent's current model. Override only when the caller has a reason: user named a specific model, slice is architectural and benefits from stronger reasoning at

xhigh

effort, or slice is mechanical and can drop to a cheaper model. Write overrides as neutral phrases (

stronger reasoning model, xhigh effort

) rather than specific model names unless the user named one.

The main Agent dispatches parallel slices in a single message with multiple

Agent

tool calls, each with

isolation: "worktree"

. Gated slices run after their deps complete.

切片	编写者	模型	文件	依赖	输出格式	验证命令
1	子Agent	继承	`src/x.ts`	—	差异+说明	`npm test -- x`
2	子Agent	继承	`src/y.ts`	切片1的签名	差异+说明	`npm test -- y`
3	主Agent	—	`src/z.ts`	切片1完成	（内联）	`npm test`

模型列约定： 默认

inherit

——子Agent使用主Agent的当前模型。仅当调用者有明确理由时才覆盖：用户指定了特定模型、切片涉及架构需使用更强推理模型（xhigh算力）、切片为机械性任务可使用更廉价模型。覆盖时使用中性表述（如「更强推理模型，xhigh算力」），除非用户指定了具体模型名称。

主Agent通过包含多个

Agent

工具调用的单条消息调度并行切片，每个调用设置

isolation: "worktree"

。有依赖的切片在其依赖完成后再执行。

Step 4: Execution Discipline (Per Slice)

步骤4：执行规范（每个切片适用）

Applies to every slice that runs through the skill — single-writer or dispatched. (XS work bypasses the skill entirely per Step 1, so 4.1's cycle is reached only for S size and above.)

适用于所有通过本技能执行的切片——无论是单人编写还是调度执行。（XS级任务在步骤1中直接跳过本技能，因此仅S级及以上任务会进入4.1的循环。）

4.1 Increment Cycle

4.1 增量循环

Implement → Test → Verify → Commit → Next slice

This is the core loop. Each slice runs the full cycle before moving on.

Implement the smallest complete piece of functionality for this slice
Test — run the relevant test suite, or write a failing test first per
```
test-driven-development
```
Verify — tests pass, build succeeds, type checks clean, manual check where applicable
Commit — one atomic commit per slice (see
```
git-workflow
```
for commit message rules)
Next slice — carry forward, don't restart

Each slice leaves the system in a working, testable state. No half-done slices.

实现 → 测试 → 验证 → 提交 → 下一切片

这是核心循环。每个切片在进入下一切片前必须完成完整循环。

实现：完成当前切片最小的完整功能
测试：运行相关测试套件，或按照
```
test-driven-development
```
技能先编写失败测试
验证：测试通过、构建成功、类型检查无问题，必要时进行人工检查
提交：每个切片对应一次原子提交（提交消息规则见
```
git-workflow
```
）
下一切片：继续推进，无需重启

每个切片完成后，系统必须处于可运行、可测试的状态。不允许存在未完成的切片。

4.2 Simplicity First

4.2 优先简洁

Before writing, ask "what is the simplest thing that could work?"

After writing, self-audit:

Could this be fewer lines?
Is each abstraction earning its complexity for this task, or for an imagined future?
Three similar lines is better than a premature abstraction

Aligns with the root principle "如无必要勿增实体 / don't add features, refactor, or introduce abstractions beyond what the task requires".

编写代码前，问自己**「最简单可行的方案是什么？」**

编写完成后，自我检查：

能否减少代码行数？
每个抽象是否为当前任务带来了足够的价值，还是为想象中的未来场景准备的？
三行相似代码优于过早的抽象

符合核心原则「如无必要勿增实体 / 不要添加超出任务需求的功能、重构或抽象」。

4.3 Scope Discipline

4.3 范围约束

Touch only what the task requires. Do not:

"Clean up" code adjacent to your change
Refactor imports in files you're not modifying
Modernize syntax in files you're only reading
Remove comments you don't fully understand

If you notice something worth improving outside the task scope, record it but don't fix it:

NOTICED BUT NOT TOUCHING:
- src/utils/format.ts has an unused import (unrelated to this task)
- Auth middleware could use better error messages (separate task)

Surface these to the user at the end of the slice; let them decide whether to spin off a task.

仅修改任务要求的内容。禁止：

「顺便清理」变更附近的代码
在未修改的文件中重构导入语句
在仅需读取的文件中更新语法
删除你不完全理解的注释

如果发现任务范围外值得改进的内容，记录但不要修改：

已注意但未处理：
- src/utils/format.ts存在未使用的导入（与当前任务无关）
- 认证中间件的错误消息可以优化（需单独任务）

在切片完成后告知用户，由用户决定是否创建新任务。

4.4 Keep Compilable Between Slices

4.4 切片间保持可编译

After each slice's commit, the project must build and existing tests must pass. Do not leave the codebase broken between slices. If a slice naturally produces an intermediate broken state, the slice boundary is wrong — re-cut it.

每个切片提交后，项目必须可构建且现有测试必须通过。不允许在切片间留下损坏的代码库状态。如果某个切片自然会产生中间损坏状态，说明切片边界划分错误——重新划分切片。

4.5 Rollback-Friendly

4.5 易于回滚

Each slice's commit should be independently revertable.

Additive changes (new files, new functions) revert easily
Modifications stay minimal and focused
DB migrations have rollback migrations
Never delete-and-replace in the same commit — split into two commits

See

git-workflow

for atomic commit rules; this rule extends them with the delete-replace constraint.

每个切片的提交必须可独立回滚。

增量变更（新文件、新函数）易于回滚
修改保持最小且聚焦
数据库迁移需包含回滚迁移
禁止在同一提交中删除并替换内容——拆分为两次提交

回滚规则是

git-workflow

中原子提交规则的延伸，增加了删除-替换的约束。

4.6 Risk-First Execution Order

4.6 风险优先的执行顺序

When multiple slices are non-blocking (no inter-slice dependency forcing order), do the most uncertain slice first. If the riskiest slice fails, you discover it before investing in dependents.

Examples:

WebSocket integration before features that ride on it
Third-party SDK adoption before features built on top
Untested platform API before production logic using it

Risk-first is execution order, not slicing axis. It composes with both vertical and horizontal slicing.

当多个切片无依赖（无强制执行顺序的切片间依赖）时，先执行最不确定的切片。如果风险最高的切片失败，可在投入依赖切片前及时发现问题。

示例：

先实现WebSocket集成，再开发基于它的功能
先接入第三方SDK，再开发基于它的功能
先验证未测试过的平台API，再开发使用它的生产逻辑

风险优先是执行顺序，而非切片方向。它可与垂直和水平切片策略结合使用。

4.7 Don't Repeat Useless Commands

4.7 避免重复执行无用命令

If a command (build, test, type check) ran successfully and the code hasn't changed since, don't re-run it. Re-running on unchanged code adds no information and burns context. Re-run only after edits that could affect the command's result.

如果某个命令（构建、测试、类型检查）已成功执行且代码未发生变化，不要重复执行。对未修改的代码重复执行命令无法获取新信息，只会浪费上下文。仅在代码修改可能影响命令结果时才重新执行。

Anti-patterns

反模式

❌ Starting implementation without checking size (Step 1) — leads to over-slicing trivial work or under-slicing L-sized features
❌ Forcing parallel dispatch on a task with cascading edits — Iron Law violation
❌ Picking horizontal sweep for "add a new feature" — sweep is for cross-cutting modifications, not greenfield additions
❌ Slicing too small to parallelize just to have more slices — Step 3.4 size filter is not optional
❌ Skipping verify between slices to move faster — bugs compound; a bug in slice 1 makes slices 2–5 wrong
❌ Mixing unrelated concerns in one commit — see
```
git-workflow
```
❌ "Cleaning up adjacent code while I'm here" — scope discipline violation (4.3)
❌ Dispatched slice without anti-hardcoding guard — subagent in isolation may hardcode values or weaken tests to turn green. The main Agent's dispatch prompt should carry: "implement the general logic; do not hardcode values or weaken tests; if a test looks wrong, surface it instead of patching around it"
❌ Attempting to coordinate subagents mid-flight via shared state — no current CLI runtime (Claude Code, Codex CLI, etc.) has an agent-to-agent channel; serialize through the main Agent or merge into a single-writer slice

❌ 未检查大小就开始实现（步骤1）——导致对简单任务过度切片或对L级任务切片不足
❌ 对存在连锁修改的任务强制并行调度——违反铁律
❌ 对「新增功能」使用水平扫描策略——扫描策略适用于跨切面修改，而非全新功能开发
❌ 为了增加切片数量而过度拆分——步骤3.4的规模过滤是强制要求
❌ 为了加快进度跳过切片间的验证——Bug会累积；切片1的Bug会导致切片2–5全部错误
❌ 在一次提交中混合无关关注点——见
```
git-workflow
```
❌ 「顺便清理附近的代码」——违反范围约束（4.3）
❌ 调度切片时未添加防硬编码约束——隔离的子Agent可能硬编码值或弱化测试以通过。主Agent的调度提示应包含：「实现通用逻辑；不要硬编码值或弱化测试；如果测试看起来有问题，应提出而非绕过」
❌ 尝试通过共享状态在执行中协调子Agent——当前CLI运行时（Claude Code、Codex CLI等）没有Agent间通信通道；需通过主Agent串行执行或合并为单人切片

Relationship to other skills

与其他技能的关联

Upstream planning sources (any of) — built-in Plan,
```
planning-with-files
```
,
```
brainstorming
```
, or a direct user-given task; this skill is agnostic to the source
```
test-driven-development
```
— governs the red→green cycle within Step 4.1
```
test-designer
```
— may produce the failing tests this skill's green phase satisfies
```
systematic-debugging
```
— runs if any slice's result breaks regression
```
verification-before-completion
```
— final gate after all slices merge
```
git-workflow
```
(auriga-git-guards plugin) — atomic commit rules referenced by 4.5

上游规划源（任意一种）——内置Plan技能、
```
planning-with-files
```
、
```
brainstorming
```
，或用户直接提供的任务；本技能对源无要求
```
test-driven-development
```
——规范步骤4.1中的红→绿循环
```
test-designer
```
——可能生成本技能绿色阶段需满足的失败测试
```
systematic-debugging
```
——如果任何切片的结果导致回归则触发
```
verification-before-completion
```
——所有切片合并后的最终检查
```
git-workflow
```
（auriga-git-guards插件）——4.5中引用的原子提交规则