specalign

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Alignment

Spec 对齐

Principles (Always Active)

原则（始终生效）

These apply whenever a spec file and its corresponding implementation are both in context:

以下原则适用于同时存在Spec文件及其对应代码实现的场景：

Spec and Code Must Agree

Spec与代码必须保持一致

A spec describes intended behavior; code implements it. When they disagree, one is wrong.
Never silently tolerate drift - surface it immediately when noticed.
The user decides which is the source of truth for each discrepancy. Do not assume.

Spec描述预期行为，代码负责实现。当两者不一致时，必有一方存在错误。
绝不能默认容忍偏差——一旦发现需立即呈现。
由用户决定每一处差异的基准依据，切勿自行假设。

Drift Categories

偏差类别

Type drift: spec defines fields/types that don't match the implementation
Behavior drift: spec describes logic the code doesn't follow
Missing implementation: spec defines something with no corresponding code
Missing spec: code implements behavior not described in the spec
Constraint drift: spec states invariants the code doesn't enforce
Error handling drift: spec defines error cases the code doesn't handle (or vice versa)

类型偏差：Spec定义的字段/类型与代码实现不匹配
行为偏差：Spec描述的逻辑未被代码遵循
缺失实现：Spec定义了某项内容，但无对应代码实现
缺失Spec：代码实现了某项行为，但未在Spec中描述
约束偏差：Spec声明的约束条件未被代码执行
错误处理偏差：Spec定义的错误场景未被代码处理（反之亦然）

Mutation Policy

修改规则

Do not edit spec files unless the user explicitly chooses "update spec" for a discrepancy.
Do not change implementation logic unless the user explicitly chooses "update code".
When updating code, run lint/typecheck after changes.
When updating spec, preserve formatting and structure of unrelated sections.

除非用户明确针对某一差异选择"更新Spec"，否则不得编辑Spec文件。
除非用户明确针对某一差异选择"更新代码"，否则不得修改代码实现逻辑。
更新代码后，需运行lint/类型检查。
更新Spec时，需保留无关章节的格式与结构。

Bidirectional Awareness

双向校验

When reading code, check if a spec exists and note divergences. When reading a spec, check if the implementation matches and note divergences. This awareness should be passive - flag drift in your responses without interrupting the user's primary task, unless the drift is directly relevant.

阅读代码时，检查是否存在对应的Spec，并记录偏差。
阅读Spec时，检查代码实现是否匹配，并记录偏差。
该校验为被动式——在回复中标记偏差，但不得打断用户的主要任务，除非偏差与当前任务直接相关。

Workflow (When Explicitly Aligning)

工作流程（明确执行对齐操作时）

Step 1: Locate the Spec

步骤1：定位Spec文件

A spec file is required. Search for:

```
*.spec.md
```
,
```
*-spec.md
```
,
```
SPEC.md
```
```
spec/*.md
```
,
```
docs/*.spec.md
```

If multiple specs exist, ask which to align. If none exist, stop - this workflow requires an existing spec.

Read the spec file completely.

必须存在Spec文件。搜索以下类型的文件：

```
*.spec.md
```
、
```
*-spec.md
```
、
```
SPEC.md
```
```
spec/*.md
```
、
```
docs/*.spec.md
```

若存在多个Spec文件，询问用户需对齐哪一个。若不存在Spec文件，则终止流程——本工作流程需要已存在的Spec文件。

完整阅读Spec文件。

Step 2: Map Spec to Code

步骤2：映射Spec至代码

For each spec section, identify the corresponding implementation:

Spec Section	Source File(s)	Status
`## Types`	`src/types.ts:10-40`	aligned / drifted / missing-impl / missing-spec

Read each mapped source file before assessing.

针对Spec的每一个章节，确定对应的代码实现：

Spec章节	源文件	状态
`## Types`	`src/types.ts:10-40`	已对齐 / 存在偏差 / 缺失实现 / 缺失Spec

评估前需阅读每一个映射的源文件。

Step 3: Present Discrepancies

步骤3：呈现差异内容

For each discrepancy:

undefined

针对每一处差异，按以下格式呈现：

undefined

DRIFT-01: <short description>

DRIFT-01: <简短描述>

Spec says (spec-file.md:L42):

<quoted spec text>

Code does (src/module.ts:L87):

<summarized code behavior>

Impact: <what breaks or is inconsistent>


Number with stable IDs (`DRIFT-NN`). Batch related discrepancies that share a root cause.

Spec描述 (spec-file.md:L42):

<引用的Spec文本>

代码实现 (src/module.ts:L87):

<代码行为摘要>

影响：<会导致哪些功能异常或不一致>

使用稳定的ID编号（`DRIFT-NN`）。将存在同一根因的相关差异归为一组。

Step 4: User Decision

步骤4：用户决策

For each discrepancy, ask:

Update spec - the code is correct, update the spec to match
Update code - the spec is correct, update the code to match
Skip - defer this discrepancy

针对每一处差异，询问用户：

更新Spec - 代码实现正确，更新Spec以匹配代码
更新代码 - Spec描述正确，修改代码以匹配Spec
跳过 - 暂不处理该差异

Step 5: Apply Changes

步骤5：执行修改

Spec updates:

Edit the spec file with corrected text
Preserve formatting and structure of unrelated sections

Code updates:

Fix the implementation to match the spec
Run lint/typecheck after changes
If non-trivial, outline the change and confirm before editing
If unit tests exist for the affected code, run them
If unit tests don't exist and the spec defines testable behavior, flag it

Spec更新：

编辑Spec文件，修正对应文本
保留无关章节的格式与结构

代码更新：

修改代码实现以匹配Spec
更新后运行lint/类型检查
若修改内容较为复杂，需先概述修改内容并确认后再编辑
若受影响的代码存在单元测试，需运行测试
若不存在单元测试且Spec定义了可测试的行为，需标记该情况

Step 6: Summary

步骤6：总结

undefined

undefined

Spec Alignment: <file>

Spec对齐：<文件名>

Discrepancies found: N Resolved: X (spec: A, code: B, skipped: C)

发现差异数量：N 已解决数量：X（更新Spec：A，更新代码：B，跳过：C）

Remaining

剩余差异

DRIFT-04: <description> (skipped)

undefined

DRIFT-04: <描述>（已跳过）

undefined