migrate-to-spec

将现有的手写 CLAUDE.md（或 AGENTS.md）转换为类型化的 CLAUDE.md.spec.ts 文件。这是一种渐进式采用方式——保留现有指令文件作为起点，并从现在开始获得类型安全保障。

不需要完整的 TypeScript？ 类型化 spec 是承诺程度最高的方式。如果用户只想验证规则而不引入构建步骤，先推荐他们使用 Markdown 模式：内联 `` 注释（级别 0），或使用 vigiles: YAML frontmatter 块，并通过 vigiles generate-schema 启用编辑器自动补全（级别 1）。这两种方式都由 vigiles lint 使用与 spec 相同的引擎进行验证。参见 docs/markdown-mode.md。只有在需要编译器级别的保证时，才迁移到 spec。

操作说明

步骤 1：读取现有文件

读取目标指令文件（默认：仓库根目录中的 CLAUDE.md）。如果用户指定了路径，则使用该路径。

同时检查是否已安装 vigiles：查找 package.json 的 devDependencies 中是否包含 vigiles。如果没有，则建议：

npm install -D vigiles

步骤 2：解析结构

识别 Markdown 中的以下部分：

• 命令 — 类似 `npm run build` — 描述 或 - `command` — 描述 的行
• 关键文件 — 列出重要文件的行，类似 `src/foo.ts` — 描述
• 规则 — 带有 **Enforced by:** 或 **Guidance only** 注释的 ### 标题
• 说明性内容 — 其他所有内容（定位、架构、原则等）

对每条规则进行分类：

• 含有 **Enforced by:** \linter/rule`→enforce("linter/rule", "原因")`
• 含有 **Enforced by:** \code-review`或类似的非 linter 内容 →guidance("...")`
• 含有 **Guidance only** → guidance("...")
• 没有注释 → 标记为 TODO，交由用户分类

步骤 3：生成 Spec 文件

创建 CLAUDE.md.spec.ts（或根据源文件使用相应名称），并采用以下结构：

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

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

  keyFiles: {
    // Key files here
  },

  commands: {
    // Commands here
  },

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

重要指南：

• 在包含反引号括起的文件路径的部分使用 file() 引用，以便检测过期引用
• 在部分中提及任何 npm run 命令时，使用 cmd() 引用
• 将 **Enforced by:** \code-review`规则转换为guidance()`——代码审查不属于机械式强制检查
• 对于没有注释的规则，添加 // TODO: classify as enforce() or guidance() 注释
• 将规则 ID 保留为标题文本对应的 kebab-case 形式
• 将 **Why:** 文本保留为 enforce() 或 guidance() 的第二个参数
• 如果部分引用了其他文件或技能，使用 ref() 进行交叉引用

步骤 4：验证 Spec 能否编译

运行：

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

将编译输出与原始文件进行比较。预期会有一些差异（格式、部分顺序），但所有规则、命令、关键文件和说明性内容都应保留。

步骤 5：展示结果

向用户展示：

1. 生成的 spec 文件
2. 已转换规则的数量（enforce、guidance 和 TODO）
3. 为检测过期引用而添加的 file/cmd 引用数量
4. 编译命令：npx vigiles compile
5. 验证命令：npx vigiles check

询问用户是否希望你写入该文件。如果是，还应建议将其添加到 .gitignore，或更新 CI 以运行 vigiles compile 和 vigiles check。

步骤 6：可选——设置 CI

如果用户希望集成 CI，建议在其 GitHub Actions 工作流中添加：

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

或者使用 vigiles GitHub Action：

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