edit-spec

编辑 .spec.ts 文件以更新项目的指令文件。spec 是事实来源；CLAUDE.md 和 AGENTS.md 是编译生成的构建产物，不得直接编辑。

参数

$ARGUMENTS — 用户想要更改的内容。示例：

• “添加一条始终使用自定义日志记录器的规则”
• “更新架构部分”
• “将身份验证规则指向 src/services/auth.ts”
• “将 npm run lint 添加到命令中”
• “更改测试指南”

说明

第 1 步：查找 Spec

在仓库根目录中查找 spec 文件：

• CLAUDE.md.spec.ts — CLAUDE.md 的源文件
• AGENTS.md.spec.ts — AGENTS.md 的源文件
• 与指令文件匹配的任何 *.spec.ts

如果不存在 spec：如果有手写的 CLAUDE.md，请建议使用 adopt-spec 技能；否则建议使用 npx vigiles init 来搭建一个。

第 2 步：阅读并理解 Spec

阅读 spec 文件。这是一个导出 claude() 调用的 TypeScript 文件，其中包含以下字段：

import { claude, enforce, guidance, check, every } from "vigiles/spec";

export default claude({
  // Optional: output target (defaults to "CLAUDE.md")
  target: "CLAUDE.md",
  // or multi-target:
  // target: ["CLAUDE.md", "AGENTS.md"],

  // Prose sections — become ## headings in compiled output
  sections: {
    positioning: "What this project does...",
    architecture: "How the codebase is structured...",
  },

  // (No `keyFiles` — deprecated; see "A pointer to a file" in Step 3.)

  // Commands verified against package.json
  commands: {
    "npm run build": "Compile the project",
    "npm test": "Run all tests",
  },

  // Rules — three types
  rules: {
    // enforce() — backed by a linter rule, verified to exist AND be enabled
    "no-any": enforce(
      "@typescript-eslint/no-explicit-any",
      "Use unknown and narrow with type guards.",
    ),

    // check() — filesystem assertion run by vigiles
    "test-pairing": check(
      every("src/**/*.service.ts").has("{name}.test.ts"),
      "Every service must have tests.",
    ),

    // guidance() — prose only, no enforcement
    "research-first": guidance("Google unfamiliar APIs before implementing."),
  },
});

第 3 步：进行更改

根据用户的要求：

添加规则（取代旧的 generate-rule 技能）：

• 对规则进行分类：
  • enforce() — 可由代码检查工具规则实现。检查项目的代码检查配置（ESLint、Ruff、Clippy、Pylint、RuboCop、Stylelint），看是否有匹配的规则；也要考虑架构工具（ast-grep、Dependency Cruiser、Steiger）。如果不确定是否存在某条规则，请询问用户，不要猜测。
  • check() — 文件系统结构约定（“每个 X 都需要一个 Y”）。仅用于文件配对；绝不能用于代码内容。
  • guidance() — 无法通过机械方式执行（主观约定、流程规则、迁移背景）。
• 对于 enforce()：使用实际的代码检查规则名称（例如 eslint/no-console、 @typescript-eslint/no-explicit-any、ruff/T201）。
• 使用意图衍生的 kebab-case 键添加到 rules 对象中；如果现有规则按字母顺序排列，则保持字母顺序。导入所需的任何新构建器（例如，第一个 check() 所需的 check 和 every）。

更新章节：

• 编辑 sections 中的字符串。章节是普通字符串或带标签的模板字面量，可使用 file()、cmd()、ref() 表示已验证的引用
• 不要在章节中添加 # 或 ## 标题——这会破坏文档结构

添加命令：

• 添加到 commands。编译器会根据 package.json 脚本验证命令。
• 描述保持为一行（目标长度为 120 个字符，绝不要超过约 200 个字符）： 指令文件在每次请求时都会加载。

指向文件的指针（以前称为“关键文件”）：

• 🔴 绝不要添加 keyFiles 条目——一个也不行，即使是已经有该字段的规范也不行。 它已弃用（vigiles lint 会报告为 deprecated-key-files），并将在下一个主版本中移除：它会将文件映射编译到每次请求都会加载的指令文件中，而 Agent 会自行查找文件。
• 用户要求添加文件？按以下顺序，放到第一个适用的位置，并说明原因：
  1. 文件自身的头部、文档或路径已说明此信息 → 不添加任何内容；
  2. 关于该文件的事实 → 写在文件的头部注释中；
  3. Agent 在某个文件夹中工作时必须遵守的规则 → 放在该文件夹的嵌套 CLAUDE.md 中（对应的 <folder>/CLAUDE.md.spec.ts 会编译它）；
  4. 只有在其他方式都无法引导 Agent 找到该文件时 → 添加一个单行指针，写在记录相关决策的 prose 章节中：${file("src/services/auth.ts")} — 编译时会验证文件是否存在，与验证 keyFiles 路径的方式完全相同。（guidance() 接收普通字符串，因此其中填写的路径不会经过验证。）
• 打开的规范仍包含 keyFiles？ 在同一条回复中提议移除它：按相同的四个步骤逐一处理条目（完整流程见 vigiles 仓库中的 docs/rules/deprecated-key-files.md；不再存在的路径应删除），并逐条说明应放到哪里以及原因。每个条目的去向由用户决定；用户确认后再应用更改。

第 4 步：编译

编辑规范后，运行：

npx vigiles compile

这会重新生成编译后的指令文件。检查输出中是否有错误：

• stale-file — file()（或已弃用的 keyFiles）路径不存在
• stale-command — 命令不在 package.json 中
• invalid-rule — 代码检查规则不存在或已禁用
• section-has-header — 章节包含 # 标题（拆分为多个带名称的章节）

第 5 步：验证

npx vigiles lint

如果已安装 vigiles 插件（/plugin marketplace add zernie/vigiles，然后运行 /plugin install vigiles@vigiles，或运行 npx vigiles init），保存规范后，PostToolUse hook 会自动重新编译。

重要事项

• 按要求行事；不要擅自升级强制级别。 添加用户要求的规则。如果要将其设为 enforce()，需要编辑 linter 配置或安装插件（这会产生成本），或者可能导致干净的 CI 失败，请说明情况并让用户选择——不要擅自更改 linter 配置，也不要启用严格模式或 workflow 门控。对于纯收益（已启用的规则），可直接应用。strengthen 技能负责将 guidance() 升级为 enforce()。
• 绝不要直接编辑 CLAUDE.md 或 AGENTS.md——它们包含 vigiles 哈希注释，且属于构建产物。
• 规范使用 TypeScript 编写——你可以获得类型检查、自动补全和经过验证的引用。
• enforce() 规则均经过验证——编译器会检查规则是否存在，以及是否在 linter 配置中启用。
• 各章节不得包含 # 或 ## 标题——请改用单独的命名章节。