adopt-spec

从现有手写的 CLAUDE.md（或 AGENTS.md）开始创建类型安全的 CLAUDE.md.spec.ts。这是非破坏性的采用方式——保留现有指令文件作为起点，并在今后获得类型安全。

采用规则

采用是**安全、忠实的入门方式，绝不是变相升级。**以下规则不可妥协：

• **忠实。**原样保留每条规则、命令和正文部分。不要凭空添加内容——规范文件编译后的内容必须与用户现有文件大致一致。唯一的例外是文件映射（“Key Files”）：绝不生成已弃用的 keyFiles 字段；参见步骤 3 中的指南。
• **非破坏性。**绝不编辑原始的 CLAUDE.md / AGENTS.md。只写入新的 .spec.ts。绝不自动在原文件上运行 compile——切换为由规范文件管理是单独的明确步骤，需由用户执行并审查差异。
• 不要提高强制级别。保留 guidance()，不要改成 enforce()。升级会带来成本（配置/插件，可能出现误报），这是单独选择启用的步骤——strengthen 技能。采用不代表启用严格模式或 workflow 门控。
• **可逆。**随时可以用 vigiles eject <file> 将文件恢复为由用户直接管理的纯 Markdown——这绝不是单向操作。请告知用户这一点。
• **写入前先征求同意。**先展示生成的规范文件和转换摘要；只有在用户同意后才写入。
• **还有更轻量的方式。**如果完全不使用规范文件，内联 `` 注释也可以通过 vigiles lint 使用相同的引擎进行验证。

说明

步骤 1：读取现有文件

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

另请检查是否已安装 vigiles：查看 package.json 的 devDependencies 中是否有 vigiles。如果没有，请建议：

npm install -D vigiles

步骤 2：解析结构

识别 Markdown 中的以下部分：

• 命令——类似 `npm run build` — description 或 - `command` — description 的行
• 文件映射（“Key Files”）——类似 `src/foo.ts` — description、列出重要文件的行。绝不能转换为 keyFiles（已弃用）；参见步骤 3 中的指南
• 规则——带有 **Enforced by:** 或 **Guidance only** 注释的 ### 标题
• 正文部分——其他所有内容（定位、架构、原则等）

对每条规则进行分类：

• 带有 **Enforced by:** \linter/rule`→enforce("linter/rule", "why")`
• 带有 **Enforced by:** \code-review` 或类似的非 linter 标注 →guidance("...")`
• 带有 **Guidance only** → guidance("...")
• 没有注释 → 标记为 TODO，留给用户分类

步骤 3：生成规范文件

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

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

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

  // No `keyFiles`: the field is deprecated (removed next major). A "Key Files"
  // list in the original file is NOT carried over as a map — see the
  // guideline below.

  commands: {
    // Commands here
  },

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

重要指南：

• 在出现反引号包裹的文件路径的章节中使用 file() 引用，以便检测过时引用
• 🔴 绝不要输出 keyFiles。 该字段已弃用，并将在下一个大版本中移除（vigiles lint 会发出 deprecated-key-files 警告）。如果原文件中有“关键文件”/文件映射章节，请按照迁移方案（vigiles 仓库中的 docs/rules/deprecated-key-files.md），逐条向用户说明每项内容的归处，按以下顺序选择最合适的位置：(1) 文件头、文档或路径已说明该内容（或路径已不存在）→ 删除；(2) 关于该文件本身的事实 → 写入该文件的头部注释；(3) 在某个文件夹中工作的规则 → 写入该文件夹的嵌套 CLAUDE.md（其自身的 <folder>/CLAUDE.md.spec.ts）；(4) 没有其他内容能引导 Agent 找到该文件 → 在写明相关决策的章节中添加一行 file() 指针。每项内容的归处由用户决定；文件映射不能变成 keyFiles 则是必须遵守的。用户尚未决定前，将列表作为普通文本章节保留，以忠实保留原有内容
• 在章节中提及任何 npm run 命令时，使用 cmd() 引用
• 将 **Enforced by:** \code-review`规则转换为guidance()`——代码审查并非机械式强制措施
• 对于没有注释的规则，添加 // TODO: classify as enforce() or guidance() 注释
• 将规则 ID 保留为标题文本对应的 kebab-case 形式
• 将 **Why:** 文本保留为 enforce() 或 guidance() 的第二个参数
• 如果章节引用其他文件或技能，请使用 ref() 进行交叉引用

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

运行：

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

将编译后的输出与原文件进行比较。预计会有一些差异（格式、章节顺序），但所有规则、命令和正文内容都应保留（文件映射例外，见上文 keyFiles 指南）。

步骤 5：展示结果

向用户展示：

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

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

步骤 6：可选——设置 CI

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

- name: Compile specs
  run: npx vigiles compile
- name: Verify references + integrity
  run: npx vigiles lint

或者使用 vigiles GitHub Action：

- uses: zernie/vigiles@v1
  with:
    command: lint