migrate-to-spec

既存の手書きの CLAUDE.md（または AGENTS.md）を、型付きの CLAUDE.md.spec.ts ファイルに変換します。これは段階的な導入方法です。既存の指示ファイルを出発点として維持し、以降は型安全性を確保できます。

TypeScript を全面的に導入する必要はありませんか？ 型付き spec は、最も踏み込んだ導入レベルです。ビルド手順なしでルールの検証だけを行いたい場合は、まず Markdown モードを案内してください。インラインの `` コメント（レベル 0）、またはエディターの自動補完用に vigiles generate-schema を使う vigiles: YAML フロントマターブロック（レベル 1）があります。どちらも spec と同じエンジンを使う vigiles lint で検証できます。詳しくは docs/markdown-mode.md を参照してください。コンパイラーによる厳密な保証が必要になった場合にのみ、spec に移行してください。

手順

ステップ 1：既存のファイルを読む

対象の指示ファイルを読みます（既定値：リポジトリのルートにある CLAUDE.md）。ユーザーがパスを指定した場合は、そのパスを使用してください。

また、vigiles がインストールされているか確認します。package.json の devDependencies に vigiles があるかを調べてください。ない場合は、次を提案します。

npm install -D vigiles

ステップ 2：構成を解析する

Markdown 内の次のセクションを特定します。

• コマンド — `npm run build` — 説明 や - `command` — 説明 のような行
• 主要なファイル — 重要なファイルを列挙した `src/foo.ts` — 説明 のような行
• ルール — **Enforced by:** または **Guidance only** の注記がある ### 見出し
• 説明文のセクション — その他すべて（位置付け、アーキテクチャ、原則など）

各ルールを次のように分類します。

• **Enforced by:** \linter/rule`がある →enforce("linter/rule", "理由")`
• **Enforced by:** \code-review`など、リンター以外の指定がある →guidance("...")`
• **Guidance only** がある → guidance("...")
• 注記がない → ユーザーが分類できるよう TODO を付ける

ステップ 3：Spec ファイルを生成する

CLAUDE.md.spec.ts（またはソースファイルに応じた適切な名前）を、次の構成で作成します。

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

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

  keyFiles: {
    // Key files here
  },

  commands: {
    // Commands here
  },

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

重要なガイドライン：

• バッククォート内にファイルパスがあるセクションでは file() 参照を使用します。これにより、古くなった参照を検出できます
• セクションで言及されている npm run コマンドには cmd() 参照を使用します
• **Enforced by:** \code-review`ルールはguidance()` に変換します。コードレビューは機械的な強制ではないためです
• 注記のないルールには、// TODO: classify as enforce() or guidance() コメントを追加します
• ルール ID は、見出しのテキストを kebab-case にしたものにします
• **Why:** のテキストは、enforce() または guidance() の第 2 引数として保持します
• セクションが他のファイルやスキルを参照している場合は、相互参照に ref() を使用します

ステップ 4：Spec がコンパイルできることを確認する

次を実行します。

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

コンパイル後の出力と元のファイルを比較します。書式やセクションの順序などに違いが生じるのは想定内ですが、すべてのルール、コマンド、主要なファイル、説明文の内容は保持されている必要があります。

ステップ 5：結果を提示する

ユーザーに次の内容を示します。

1. 生成した spec ファイル
2. 変換したルールの数（enforce、guidance、TODO の内訳）
3. 古くなった参照を検出するために追加した file/cmd 参照の数
4. コンパイルするコマンド：npx vigiles compile
5. 検証するコマンド：npx vigiles check

ファイルを書き込むかどうかを尋ねます。書き込む場合は、.gitignore に追加するか、CI を更新して vigiles compile と vigiles check を実行することも提案してください。

ステップ 6：任意 — CI を設定する

ユーザーが CI との統合を希望する場合は、GitHub Actions ワークフローへの追加を提案します。

- name: Compile specs
  run: npx vigiles compile
- name: Verify integrity
  run: npx vigiles check

または、vigiles GitHub Action を使用します。

- uses: zernie/vigiles@main
  with:
    command: check