需要改动被 vigiles 编译的…

当 CLAUDE.md/AGENTS.md 带有 vigiles hash、属于编译产物时，通过编辑 .spec.ts 来增删改其中的规则、章节、命令或关键文件

适用场景

解决思路

1. 在仓库根目录查找 spec 文件：`CLAUDE.md.spec.ts`（CLAUDE.md 的源）、`AGENTS.md.spec.ts`（AGENTS.md 的源），以及任何匹配指令文件的 `*.spec.ts`。
2. 如果不存在 spec：若仓库里有手写的 `CLAUDE.md`，建议使用 `adopt-spec` 技能纳管；否则建议运行 `npx vigiles init` 生成脚手架。
3. 阅读 spec 文件——它是导出 `claude()` 调用的 TypeScript 文件，识别其字段：`target`（默认 `"CLAUDE.md"`，也可写成数组多目标）、`sections`（散文段落，编译成 `##` 标题）、`keyFiles`（编译时校验存在的文件路径）、`commands`（对照 package.json 校验的命令）、`rules`（enforce/check/guidance 三类）。
4. 新增规则时先对规则分类：`enforce()` —— 有 linter 规则可以支撑；检查项目的 linter 配置（ESLint、Ruff、Clippy、Pylint、RuboCop、Stylelint）里是否有匹配规则，也考虑架构工具（ast-grep、Dependency Cruiser、Steiger）；如果不确定规则是否存在，直接问用户，不要猜。
5. `check()` —— 仅用于文件系统结构约定（“每个 X 都需要一个 Y”），只做文件配对，绝不用于代码内容。
6. `guidance()` —— 无法机械强制执行的（主观约定、流程规则、迁移上下文）。
7. `enforce()` 使用真实的 linter 规则名（例如 `eslint/no-console`、`@typescript-eslint/no-explicit-any`、`ruff/T201`）。
8. 把规则加进 `rules` 对象，key 用从意图派生的 kebab-case；若现有规则是字母序排列则保持字母序；导入新用到的 builder（例如第一个 `check()` 需要导入 `check` 和 `every`）。
9. 更新章节时：编辑 `sections` 里的字符串；章节可以是纯字符串，也可以是带 `file()`、`cmd()`、`ref()` 的标签模板字面量，用于生成经过校验的引用。
10. 不要在章节内部添加 `#` 或 `##` 标题——会破坏文档结构，应拆成单独的命名章节。
11. 新增关键文件或命令时，加入 `keyFiles` 或 `commands`；命令必须匹配 `package.json` 中的脚本，关键文件必须存在于磁盘上（编译器在编译期校验）。
12. keyFiles 的描述保持一行——目标 120 字符，绝不超过约 200 字符：一个 `keyFiles` 条目是“指针”，只说明这个文件是做什么的，让读者判断要不要打开；它如何工作的解释应放在该文件自己的头部注释里，等人真正进到那个文件时再读。指令文件每次请求都会加载，这里的段落会被每个读者、每一轮请求永久付费，包括那些从不碰该文件的人。
13. 这个列表只会增长，除非你主动精简：新增之前先检查邻近条目是否已经过期（文件移动了、职责变了、描述只是重复了它的头部注释），并在同一次编辑里一并修好。只增不减正是指令文件膨胀到其 harness 预算四倍的原因——`vigiles audit` 会把这个数字报告为 `Always-loaded instructions`，改动这份列表时顺手查看它。
14. 编辑完 spec 后运行 `npx vigiles compile` 重新生成编译后的指令文件，并检查报错：`stale-file`（关键文件路径不存在）、`stale-command`（命令不在 package.json 中）、`invalid-rule`（linter 规则不存在或被禁用）、`section-has-header`（章节内含有 `#` 标题，应拆成独立命名章节）。
15. 运行 `npx vigiles lint` 做验证。如果安装了 vigiles 插件（先 `/plugin marketplace add zernie/vigiles` 再 `/plugin install vigiles@vigiles`，或执行 `npx vigiles init`），PostToolUse 钩子会在你保存 spec 后自动重新编译。
16. 只做用户要求的事，不要悄悄升级强制级别：如果改成 `enforce()` 需要改 linter 配置或安装插件（有成本），或者可能让本来干净的 CI 失败，就明确说出来让用户选择——不要自行修改 linter 配置，也不要擅自打开 strict / `workflow` 门控。纯粹的收益（规则本来就已启用）可以直接应用。`guidance()` → `enforce()` 的升级由 `strengthen` 技能负责。
17. 绝不直接编辑 CLAUDE.md 或 AGENTS.md——它们带有 vigiles hash 注释，是构建产物。
18. 记住 spec 是 TypeScript：因此能获得类型检查、自动补全和经过校验的引用。
19. 记住 `enforce()` 规则是被校验过的：编译器会检查规则存在，并且在你的 linter 配置中已启用。

适用边界 · 注意事项

• 项目还没有被 vigiles 纳管（不存在 `*.spec.ts`）时不要直接套用此流程，应先 `npx vigiles init` 或用 `adopt-spec` 纳管手写文件。
• 不要绕过 spec 直接修改编译产物 CLAUDE.md / AGENTS.md。
• 不要在未征得用户同意的情况下把 `guidance()` 升级为 `enforce()` 或改动 linter 配置——这属于 `strengthen` 技能的职责，且可能影响 CI。