specalign规范对齐工具：自动检测代码与文档差异，确保开发一致性

specalign by 0xbigboss/claude-code

58 周安装量

41 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/0xbigboss/claude-code --skill specalign

🇨🇳中文介绍

规范对齐

原则（始终有效）

当规范文件及其对应的实现代码同时处于上下文中时，以下原则适用：

规范与代码必须一致

规范描述预期行为；代码实现该行为。当两者不一致时，必有一方是错误的。
绝不容忍无声的偏离——一旦发现，立即指出。
用户决定每个差异的真相来源。不要自行假设。

偏离类别

类型偏离：规范定义的字段/类型与实现不匹配
行为偏离：规范描述的逻辑代码未遵循
缺失实现：规范定义了某些内容，但没有对应的代码
缺失规范：代码实现了规范中未描述的行为
约束偏离：规范声明的约束条件代码未强制执行
错误处理偏离：规范定义的错误情况代码未处理（或反之）

修改策略

除非用户明确为某个差异选择“更新规范”，否则不要编辑规范文件。
除非用户明确选择“更新代码”，否则不要更改实现逻辑。
更新代码后，运行代码检查/类型检查。
更新规范时，保留无关部分的格式和结构。

双向感知

阅读代码时，检查是否存在规范并注意差异。阅读规范时，检查实现是否匹配并注意差异。这种感知应该是被动的——在你的回应中指出偏离，但不要打断用户的主要任务，除非该偏离直接相关。

工作流程（当明确进行对齐时）

步骤 1：定位规范文件

需要一个规范文件。搜索以下模式：

*.spec.md、*-spec.md、SPEC.md

🇺🇸English

Spec Alignment

Principles (Always Active)

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

Spec and Code Must Agree

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.

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)

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.

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.

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 2：将规范映射到代码

对于每个规范章节，识别对应的实现：

规范章节	源文件	状态
`## Types`	`src/types.ts:10-40`	已对齐 / 已偏离 / 缺失实现 / 缺失规范

在评估之前，阅读每个映射的源文件。

步骤 3：呈现差异

对于每个差异：

### DRIFT-01: <简短描述>

**规范说明** (spec-file.md:L42):
> <引用的规范文本>

**代码行为** (src/module.ts:L87):
> <总结的代码行为>

**影响**: <什么会出错或不一致>

使用稳定的 ID 编号 (DRIFT-NN)。将具有相同根本原因的相关差异进行批处理。

步骤 4：用户决策

对于每个差异，询问：

更新规范 - 代码是正确的，更新规范以匹配代码
更新代码 - 规范是正确的，更新代码以匹配规范
跳过 - 推迟处理此差异

步骤 5：应用更改

使用更正后的文本编辑规范文件
保留无关部分的格式和结构

修复实现以匹配规范
更改后运行代码检查/类型检查
如果改动不简单，在编辑前概述更改内容并确认
如果受影响代码存在单元测试，运行它们
如果不存在单元测试且规范定义了可测试的行为，请指出

## 规范对齐: <文件>

**发现的差异**: N
**已解决**: X (规范: A, 代码: B, 跳过: C)

### 剩余差异
- DRIFT-04: <描述> (已跳过)

Workflow (When Explicitly Aligning)

Step 1: Locate the 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.

Step 2: Map Spec to Code

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.

Step 3: Present Discrepancies

For each discrepancy:

### DRIFT-01: <short description>

**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.

Step 4: User Decision

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

Step 5: Apply Changes

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

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 Alignment: <file>

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

### Remaining
- DRIFT-04: <description> (skipped)

AI新闻播客制作技能：实时新闻转对话式播客脚本与音频生成