migrate-to-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Convert an existing hand-written CLAUDE.md (or AGENTS.md) into a typed

CLAUDE.md.spec.ts

file. This is the incremental adoption path — you keep your existing instruction file as the starting point and get type safety going forward.

Don't need full TypeScript? A typed spec is the deepest commitment level. If the user only wants verified rules without a build step, point them at markdown mode first: inline

comments (Level 0) or a
vigiles:
YAML frontmatter block with
vigiles generate-schema
for editor autocomplete (Level 1). Both are verified by
vigiles lint
with the same engine as a spec. See
docs/markdown-mode.md
. Migrate to a spec only when they want compiler-grade guarantees.

将现有的手写CLAUDE.md（或AGENTS.md）转换为带类型的

CLAUDE.md.spec.ts

文件。这是一条渐进式采用路径——你可以保留现有的指令文件作为起点，同时在后续获得类型安全性。

不需要完整的TypeScript？ 带类型的规范是最高级别的承诺。如果用户只想要无需构建步骤的已验证规则，先引导他们使用markdown模式：内嵌的

注释（0级），或是带有
vigiles:
的YAML前置块，配合
vigiles generate-schema
实现编辑器自动补全（1级）。这两种方式都能通过
vigiles lint
进行验证，使用的引擎与规范文件相同。详见
docs/markdown-mode.md
。只有当用户需要编译器级别的保障时，再迁移到规范文件。

Instructions

操作步骤

Step 1: Read the Existing File

步骤1：读取现有文件

Read the target instruction file (default:

CLAUDE.md

in the repo root). If the user specified a path, use that.

Also check if vigiles is installed: look for

vigiles

package.json

devDependencies. If not, suggest:

bash

npm install -D vigiles

读取目标指令文件（默认：仓库根目录下的

CLAUDE.md

）。如果用户指定了路径，则使用该路径。

同时检查是否已安装vigiles：查看

package.json

的devDependencies中是否有

vigiles

。如果没有，建议执行：

bash

npm install -D vigiles

Step 2: Parse the Structure

步骤2：解析结构

Identify these sections in the markdown:

Commands — lines like

`npm run build` — description

- `command` — description

Key files — lines like
```
`src/foo.ts` — description
```
listing important files
Rules —
```
###
```
headings with
```
**Enforced by:**
```
or
```
**Guidance only**
```
annotations
Prose sections — everything else (positioning, architecture, principles, etc.)

For each rule, classify it:

Has
```
**Enforced by:** \
```
linter/rule`
```
→
```
enforce("linter/rule", "why")`

Has

**Enforced by:** \

code-review`

or similar non-linter →

guidance("...")`

Has
```
**Guidance only**
```
→
```
guidance("...")
```
Has no annotation → mark as TODO for the user to classify

识别markdown中的以下部分：

命令 —— 类似

`npm run build` —— 描述

或

- `command` —— 描述

的行

关键文件 —— 类似
```
`src/foo.ts` —— 描述
```
的行，列出重要文件
规则 —— 带有
```
**Enforced by:**
```
或
```
**Guidance only**
```
注释的
```
###
```
标题
散文式章节 —— 其他所有内容（定位、架构、原则等）

对每条规则进行分类：

带有
```
**Enforced by:** \
```
linter/rule`
```
→
```
enforce("linter/rule", "why")`

带有

**Enforced by:** \

code-review`

或类似非linter的注释 →

guidance("...")`

带有
```
**Guidance only**
```
→
```
guidance("...")
```
无注释 → 标记为TODO，供用户后续分类

Step 3: Generate the Spec File

步骤3：生成规范文件

Create

CLAUDE.md.spec.ts

(or the appropriate name based on the source file) with this structure:

typescript

import {
  claude,
  enforce,
  guidance,
  check,
  every,
  file,
  cmd,
  ref,
  instructions,
} from "vigiles/spec";

export default claude({
  sections: {
    // Prose sections here
  },

  keyFiles: {
    // Key files here
  },

  commands: {
    // Commands here
  },

  rules: {
    // Rules here
  },
});

Important guidelines:

Use
```
file()
```
refs in sections where file paths appear in backticks — this enables stale reference detection
Use
```
cmd()
```
refs for any
```
npm run
```
commands mentioned in sections
Convert
```
**Enforced by:** \
```
code-review`
```
rules to
```
guidance()` — code review is not a mechanical enforcement

For rules with no annotation, add a

// TODO: classify as enforce() or guidance()

comment

Keep rule IDs as kebab-case versions of the heading text
Preserve the
```
**Why:**
```
text as the second argument to
```
enforce()
```
or
```
guidance()
```
If sections reference other files or skills, use
```
ref()
```
for cross-references

创建

CLAUDE.md.spec.ts

（或根据源文件命名的对应文件），结构如下：

typescript

import {
  claude,
  enforce,
  guidance,
  check,
  every,
  file,
  cmd,
  ref,
  instructions,
} from "vigiles/spec";

export default claude({
  sections: {
    // 散文式章节放在这里
  },

  keyFiles: {
    // 关键文件放在这里
  },

  commands: {
    // 命令放在这里
  },

  rules: {
    // 规则放在这里
  },
});

重要指南：

在包含反引号包裹的文件路径的章节中，使用
```
file()
```
引用——这能启用过时引用检测
对章节中提到的任何
```
npm run
```
命令，使用
```
cmd()
```
引用
将带有
```
**Enforced by:** \
```
code-review`
```
的规则转换为
```
guidance()`——代码审查不属于机械性强制执行

对无注释的规则，添加

// TODO: classify as enforce() or guidance()

注释

将规则ID保留为标题文本的kebab-case格式
保留
```
**Why:**
```
文本作为
```
enforce()
```
或
```
guidance()
```
的第二个参数
如果章节引用了其他文件或技能，使用
```
ref()
```
进行交叉引用

Step 4: Verify the Spec Compiles

步骤4：验证规范文件可编译

Run:

bash

npm run build
npx vigiles compile CLAUDE.md.spec.ts

Compare the compiled output against the original file. Key differences are expected (formatting, section ordering), but all rules, commands, key files, and prose content should be preserved.

运行：

bash

npm run build
npx vigiles compile CLAUDE.md.spec.ts

将编译输出与原始文件进行对比。格式、章节顺序等方面的差异是正常的，但所有规则、命令、关键文件和散文内容都应被保留。

Step 5: Present the Result

步骤5：呈现结果

Show the user:

The generated spec file
How many rules were converted (enforce vs guidance vs TODO)
How many file/cmd refs were added for stale reference detection
The command to compile:
```
npx vigiles compile
```
The command to verify:
```
npx vigiles check
```

Ask if they want you to write the file. If yes, also suggest adding to

.gitignore

or updating CI to run

vigiles compile

and

vigiles check

向用户展示：

生成的规范文件
已转换的规则数量（enforce、guidance、TODO分别有多少）
为过时引用检测添加的file/cmd引用数量
编译命令：
```
npx vigiles compile
```
验证命令：
```
npx vigiles check
```

询问用户是否需要写入该文件。如果需要，还建议添加到

.gitignore

或更新CI以运行

vigiles compile

和

vigiles check

。

Step 6: Optional — Set Up CI

步骤6：可选——设置CI

If the user wants CI integration, suggest adding to their GitHub Actions workflow:

yaml

- name: Compile specs
  run: npx vigiles compile
- name: Verify integrity
  run: npx vigiles check

Or using the vigiles GitHub Action:

yaml

- uses: zernie/vigiles@main
  with:
    command: check

如果用户需要CI集成，建议添加到GitHub Actions工作流中：

yaml

- name: Compile specs
  run: npx vigiles compile
- name: Verify integrity
  run: npx vigiles check

或使用vigiles GitHub Action：

yaml

- uses: zernie/vigiles@main
  with:
    command: check