edit-spec

プロジェクトの指示ファイルを更新するには、.spec.ts ファイルを編集します。仕様ファイルが信頼できる唯一の情報源です。CLAUDE.md と AGENTS.md はビルド時に生成される成果物であり、直接編集してはいけません。

引数

$ARGUMENTS — ユーザーが変更したい内容です。例：

• 「カスタムロガーを常に使うルールを追加」
• 「アーキテクチャのセクションを更新」
• 「認証ルールの参照先を src/services/auth.ts に変更」
• 「コマンドに npm run lint を追加」
• 「テストのガイダンスを変更」

手順

Step 1: 仕様ファイルを見つける

リポジトリのルートにある仕様ファイルを探します。

• CLAUDE.md.spec.ts — CLAUDE.md のソース
• AGENTS.md.spec.ts — AGENTS.md のソース
• 指示ファイルに対応するその他の *.spec.ts

仕様ファイルがない場合、手書きの CLAUDE.md があれば adopt-spec スキルを提案します。なければ、仕様ファイルを生成するために npx vigiles init を提案します。

Step 2: 仕様を読み、内容を理解する

仕様ファイルを読みます。これは、次のフィールドを持つ 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）を使用します。
• rules オブジェクトに、意図から導いたケバブケースのキーを追加します。既存のルールがアルファベット順なら、その順序を維持してください。必要なビルダー（最初の check() には check と every など）をインポートします。

セクションの更新：

• sections 内の文字列を編集します。セクションは通常の文字列か、検証済みの参照を示す file()、cmd()、ref() を使ったタグ付きテンプレートリテラルです。
• セクション内に # や ## の見出しを追加しないでください。ドキュメントの構造が壊れます。

コマンドの追加：

• commands に追加します。コンパイラーは package.json のスクリプトと照合して検証します。
• 説明は 1 行に収めてください（120 文字を目安にし、約 200 文字を超えないようにします）。指示ファイルはリクエストのたびに読み込まれます。

ファイルへのポインター（以前の「key file」）：

• 🔴 keyFiles エントリーは、既存の仕様にそのフィールドがある場合も含め、決して追加しないでください。 非推奨であり（vigiles lint で deprecated-key-files と報告されます）、次のメジャーバージョンで削除されます。リクエストのたびに読み込まれる指示ファイルへファイルマップをコンパイルしてしまいますが、エージェントは自分でファイルを見つけられます。
• ファイルの追加を依頼された場合は、該当する最初の方法を選び、その理由を説明してください。
  1. ファイル自身のヘッダー、ドキュメント、またはパスにすでに記載されている → 何も追加しません。
  2. そのファイル固有の情報 → ファイルのヘッダーコメントに記載します。
  3. あるフォルダー内で作業する際にエージェントが従うべきルール → そのフォルダーのネストされた CLAUDE.md（コンパイル対象の <folder>/CLAUDE.md.spec.ts）に記載します。
  4. ほかの方法ではエージェントがそのファイルにたどり着けない場合に限り、判断が必要な内容を記載した prose セクション内に、${file("src/services/auth.ts")} の形式で1 行のポインターを記載します。コンパイル時にファイルの存在が検証されます。これは keyFiles のパスが検証されるのと同じです。（guidance() は通常の文字列を受け取るため、そこに入力したパスは検証されません。）
• 開いた仕様にまだ keyFiles が含まれていますか？ 同じ返信で削除を提案してください。上記と同じ 4 つの手順で各エントリーを確認します（詳細な手順は 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 フックが仕様の保存後に自動で再コンパイルします。

重要

• 依頼されたことを行い、黙って適用範囲を拡大しないでください。 ユーザーが求めたルールを追加してください。enforce() にするためにリンター設定の編集やプラグインのインストール（コスト）が必要な場合、またはクリーンな CI が失敗する可能性がある場合は、その旨を伝えて、ユーザーに選択してもらってください。リンター設定を変更したり、厳格な設定や workflow ゲーティングを独断で有効にしたりしないでください。すでに有効になっているルールを適用するだけで確実に改善するなら、そのまま適用して構いません。guidance() → enforce() のアップグレードは strengthen スキルが担当します。
• CLAUDE.md や AGENTS.md を直接編集しないでください。vigiles のハッシュコメントが付いており、ビルド成果物です。
• 仕様は TypeScript です。型チェック、自動補完、参照の検証を利用できます。
• enforce() ルールは検証済みです。コンパイラーが、ルールが存在し、リンター設定で有効になっていることを確認します。
• セクションに # や ## の見出しを含めないでください。代わりに、名前を付けたセクションを個別に作成してください。