把已有手写 CLAUDE.md 非破坏性地迁移为带类型的…

当你已有一份手写的 CLAUDE.md/AGENTS.md，想在不改动原文件的前提下获得类型安全与引用校验时使用。

适用场景

解决思路

1. 读取目标指令文件（默认仓库根目录的 CLAUDE.md，用户指定路径则用指定路径）。
2. 检查 vigiles 是否已安装：在 package.json 的 devDependencies 中查找 vigiles；若没有，建议运行 `npm install -D vigiles`。
3. 解析 markdown 结构，识别四类内容：Commands（形如 `` `npm run build` — description `` 或 ``- `command` — description`` 的行）、Key files（形如 `` `src/foo.ts` — description `` 的行）、Rules（带 `**Enforced by:**` 或 `**Guidance only**` 标注的 `###` 标题）、Prose sections（其余所有内容，如定位、架构、原则等）。
4. 对每条规则分类：有 `**Enforced by:** \`linter/rule\`` 的转为 `enforce("linter/rule", "why")`；有 `**Enforced by:** \`code-review\`` 或类似非 linter 的转为 `guidance("...")`；有 `**Guidance only**` 的转为 `guidance("...")`；无任何标注的标记为 TODO 交给用户分类。
5. 生成 CLAUDE.md.spec.ts（或按源文件名取相应名称），从 `vigiles/spec` 导入 `claude, enforce, guidance, file, cmd, ref, instructions`，并 `export default claude({ sections, keyFiles, commands, rules })`。
6. 在 sections 中，对以反引号出现的文件路径使用 `file()` 引用，以便检测失效引用。
7. 对 sections 中提到的任何 `npm run` 命令使用 `cmd()` 引用。
8. 把 `**Enforced by:** \`code-review\`` 的规则转成 `guidance()`——代码评审不是机械式强制。
9. 对无标注的规则加 `// TODO: classify as enforce() or guidance()` 注释。
10. 规则 ID 使用标题文本的 kebab-case 形式。
11. 把 `**Why:**` 文本保留为 `enforce()` 或 `guidance()` 的第二个参数。
12. 若 sections 引用了其他文件或技能，使用 `ref()` 做交叉引用。
13. keyFiles 中每个路径只对应一行说明该文件用途的文字，目标 120 字符、绝不超过约 200 字符；条目是指针而非摘要，文件如何工作应写在其自身的头部注释里；每次新增条目时顺手清理过时的相邻条目，`vigiles audit` 会打印 `Always-loaded instructions` 的累计总量。
14. 运行 `npm run build` 和 `npx vigiles compile CLAUDE.md.spec.ts` 验证 spec 能编译。
15. 将编译输出与原始文件对比：格式与章节顺序差异属预期，但所有规则、命令、关键文件和正文内容都应保留。
16. 向用户展示：生成的 spec 文件、转换的规则数量（enforce / guidance / TODO 各多少）、新增的 file/cmd 引用数量、编译命令 `npx vigiles compile`、校验命令 `npx vigiles lint`。
17. 询问用户是否要写入该文件；若同意，再建议加入 .gitignore 或在 CI 中运行 `vigiles compile` 与 `vigiles lint`。
18. 若用户需要 CI 集成，建议在 GitHub Actions 工作流中加入 `- name: Compile specs` / `run: npx vigiles compile` 与 `- name: Verify references + integrity` / `run: npx vigiles lint`，或使用 `- uses: zernie/vigiles@v1` 并设 `with: command: lint`。
19. 遵守不可协商的迁移规则：忠实保留每条规则、命令、关键文件和正文段落，不臆造内容，spec 应能编译回接近用户现有文件；绝不编辑原始 CLAUDE.md/AGENTS.md，只写新的 .spec.ts，绝不自动 compile 覆盖原文件；不升级强制级别，`guidance()` 保持为 `guidance()`，升级到 `enforce()` 是单独的 opt-in 步骤（strengthen 技能）；告知用户 `vigiles eject <file>` 可随时把文件交还为纯手写 markdown，这不是单向门；写入前先展示生成的 spec 和转换摘要，仅在用户同意后写入。
20. 若完全不想用 spec，可改用更轻量的方式：内联 `<!-- vigiles:enforce ... -->` 注释，由 `vigiles lint` 用同一引擎校验。

适用边界 · 注意事项

• 用户希望直接升级为强制（enforce）或开启 strict/workflow 门控时——那属于 strengthen 技能的单独 opt-in 步骤，不是迁移。
• 用户不愿保留原始手写文件、想要一次性替换时——本流程是非破坏性迁移，绝不自动 compile 覆盖原文件。
• 未安装 vigiles 且用户不愿安装时——需先 `npm install -D vigiles`。