mcpField
A
adopt-spec

adopt-spec

github.com/zernieエージェントワークフロー151.8k 回インストール2 日前に更新
リポジトリ

adopt-spec について

手書きの CLAUDE.md または AGENTS.md を、既存ファイルを保ったまま型付きの `CLAUDE.md.spec.ts` に変換するスキルです。導入は非破壊的で、生成した仕様ファイルを書き込む前に確認を求めます。

主な機能

  1. 01指示ファイルを型付き仕様に変換
  2. 02元ファイルを変更せず保持
  3. 03ルールを enforce() または guidance() に対応付け
  4. 04ファイルとコマンドの参照を追加
  5. 05仕様ファイルのコンパイルを確認

活用シーン

  1. 01既存の CLAUDE.md に型付き仕様を導入
  2. 02AGENTS.md のルールを元ファイルを置換せず変換
  3. 03参照チェック付きの指示仕様を準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/zernie/vigiles --skill adopt-spec

インストール後、Claude Code で/adopt-specを入力して読み込まれたか確認します。

詳細

既存の手書きの CLAUDE.md（または AGENTS.md）をもとに、型付きの CLAUDE.md.spec.ts を作成します。これは既存のファイルを出発点として維持し、今後の型安全性を確保する、非破壊的な導入方法です。

導入ルール

導入は安全で忠実な第一歩であり、偽装したアップグレードではありません。 以下は必ず守ってください。

  • 忠実であること。 すべてのルール、コマンド、説明文のセクションをそのまま保持します。何も作り出してはいけません。spec をコンパイルした結果は、ユーザーの既存ファイルとほぼ同一でなければなりません。唯一の例外はファイルマップ（「Key Files」）です。非推奨の keyFiles フィールドは絶対に出力しないでください。Step 3 のガイドラインを参照してください。
  • 非破壊的であること。 元の CLAUDE.md / AGENTS.md は編集しないでください。新しい .spec.ts のみを書き込みます。ファイルに対して自動で compile を実行してはいけません。spec 管理への切り替えは、ユーザーが差分を確認しながら実行する、別途明示的な手順です。
  • 適用を強化しないこと。 guidance() は guidance() のままにします。enforce() への引き上げには、設定やプラグインの追加、誤検知の可能性といったコストが伴うため、別途オプトインする手順である strengthen スキルに委ねます。導入とは、strict / workflow のゲートを有効にすることではありません。
  • 元に戻せること。 vigiles eject <file> を実行すれば、いつでもファイルを通常の手書き Markdown に戻せます。これは決して一方通行ではありません。このことをユーザーに伝えてください。
  • 書き込む前に確認すること。 生成した spec と変換の概要を先に提示し、ユーザーの同意があった場合にのみ書き込みます。
  • より軽い方法もあること。 spec をまったく使わない場合は、インラインの `` コメントを vigiles lint で同じエンジンを使って検証できます。

手順

Step 1：既存のファイルを読む

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

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

npm install -D vigiles
Step 2：構造を解析する

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

  • コマンド — `npm run build` — 説明 や - `command` — 説明 のような行
  • ファイルマップ（「Key Files」） — 重要なファイルを列挙した、`src/foo.ts` — 説明 のような行。非推奨の keyFiles にはなりません。Step 3 のガイドラインを参照してください。
  • ルール — **Enforced by:** または **Guidance only** の注記がある ### 見出し
  • 説明文のセクション — 上記以外すべて（位置付け、アーキテクチャ、原則など）

各ルールについて、次のように分類します。

  • **Enforced by:** \linter/rule`がある場合 →enforce("linter/rule", "why")`
  • **Enforced by:** \code-review`など、リンター以外の記載がある場合 →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 として警告します）。元のファイルに「Key Files」／ファイルマップのセクションがある場合は、移行手順（vigiles リポジトリの docs/rules/deprecated-key-files.md）を適用し、各エントリの移行先をユーザーに示してください。該当するもののうち、最初に当てはまるものを選びます。（1）ファイルのヘッダー、ドキュメント、またはパスにすでに記載されている（あるいはパスが存在しなくなっている）→ 削除する。（2）そのファイルだけに関する事実 → ファイルのヘッダーコメントに記載する。（3）特定のフォルダーで作業するためのルール → そのフォルダーのネストされた CLAUDE.md（独自の <folder>/CLAUDE.md.spec.ts）に記載する。（4）エージェントがそのファイルを見つけるための手がかりが他にない → そのファイルが必要となる判断を記述するセクションに、1 行の file() ポインターを追加する。各エントリの移行先はユーザーが決めますが、マップを keyFiles にしないことは必須です。ユーザーが決めるまでは、導入時の忠実性を保つため、リストを通常の文章のセクションとして引き継いでください
  • セクションで言及されている npm run コマンドには、cmd() 参照を使用します
  • **Enforced by:** \code-review`のルールはguidance()` に変換します。コードレビューは機械的な強制ではありません
  • 注釈のないルールには、// TODO: classify as enforce() or guidance() コメントを追加します
  • ルール ID は見出しテキストを kebab-case にしたものにします
  • **Why:** のテキストは、enforce() または guidance() の第 2 引数として保持します
  • セクションが他のファイルやスキルを参照している場合は、相互参照に 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 への追加、または vigiles compile と vigiles lint を実行するよう CI を更新することも提案してください。

ステップ 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

コメント

Markdown 対応