validator-setup

/validator-setup

プロジェクトをスキャンしてツールを検出し、agent-validator のチェックとレビューを構成します。

開始する前に、references/check-catalog.md を読んで、チェックカテゴリの詳細、YAML スキーマ、設定例を確認してください。

ステップ 1: 設定の存在確認

.validator/config.yml を読み取ります。ファイルが存在しない場合は、まず agent-validate init を実行するようユーザーに伝え、停止してください — 以降のステップを進めないでください。

ステップ 2: 既存の設定の確認

.validator/config.yml から entry_points フィールドを読み取ります。

このプロジェクトがすでに構成済みかどうかを判断する前に、.validator/ の git 状態を確認してください：

• これが git リポジトリの場合、git status --porcelain -- .validator を実行します。
• .validator/ または .validator/config.yml が未追跡または新しく追加されたものである場合、ディレクトリが存在していても、これは新規インストールとして扱ってください。agent-validate init はまずスキャフォールドを作成します。/validator-setup は引き続きチェックとエントリポイントを構成する必要があります。
• git が利用できない場合、プロジェクトが git リポジトリでない場合、または状態が不明確な場合は、Agent Validator が以前にセットアップされたと主張しないでください。これが新規インストールなのか、変更したい既存の設定なのかをユーザーに尋ねてください。

.validator/ が存在するというだけで「やることはない」とか「すでにセットアップ済み」と結論づけないでください。コミットされた設定にすでに意味のあるエントリポイントやチェックが含まれている場合、またはユーザーが既存であると確認した場合にのみ、プロジェクトを既存のセットアップとして扱ってください。

entry_points が空 ([]) であるか、生成されたルートエントリポイント (path: ".") のみを含み checks がない場合: これは新規セットアップです。ステップ 3 (プロジェクト構造の検出) に進んでください。ユーザーが明示的にレビューを再構成しない限り、その生成されたルートエントリポイントの既存の reviews を保持してください。

entry_points が設定されている場合: 現在の設定の概要をユーザーに表示します:

• 各エントリポイントをその path、checks、reviews とともに一覧表示します

• 次に、どのアクションを実行するかをユーザーに尋ねます:

  1. チェックの追加 — まだ構成されていないツールをスキャンします。ステップ 3 に進みますが、entry_points にすでに含まれているチェックは除外してください。
  2. カスタムの追加 — ユーザーが追加したい内容を説明します。ステップ 7 にスキップします。
  3. 再構成 — 最初からやり直します。まず既存の設定をバックアップしてください:
     • 各 .validator/checks/*.yml ファイルを .yml.bak にリネームします (以前の .bak ファイルがあれば上書きします) — これらはレガシーなファイルベースのチェックです
     • 各カスタム .validator/reviews/*.md ファイルを .md.bak にリネームします (以前の .bak ファイルがあれば上書きします)
     • .validator/reviews/*.yml ファイルはリネームしないでください (これらは組み込みのレビュー設定です)
     • config.yml の entry_points を [] にクリアします
     • ステップ 3 に進みます

ステップ 3: プロジェクト構造の検出

シグナルをスキャンして、プロジェクトを モノレポ、分割プロジェクト、または 単一プロジェクト に分類します。

モノレポのシグナル

• workspaces フィールドを持つ package.json
• pnpm-workspace.yaml
• lerna.json、nx.json、turbo.json
• [workspace] セクションを持つ Cargo.toml
• packages/、apps/、または services/ 配下の複数のサブディレクトリで、それぞれが独自のプロジェクトマニフェスト (package.json、go.mod、Cargo.toml、pyproject.toml) を含むもの

分割プロジェクトのシグナル

• frontend/ + backend/ (または client/ + server/、web/ + api/) ディレクトリで、それぞれがソースコードや独自のプロジェクトマニフェストを含むもの
• 共通の親ディレクトリ配下に同じ言語の複数のアプリやライブラリ (例: apps/web/、apps/api/、apps/worker/ がそれぞれ独自のソースと設定を持つ) — apps/* のようなワイルドカードエントリポイントを示唆します

単一プロジェクトのシグナル

• src/ または lib/ が唯一のソースディレクトリであるか、ソースファイルがプロジェクトルートにある
• モノレポや分割プロジェクトのシグナルが見つからない

モノレポまたは分割プロジェクトの場合: 詳細なマルチプロジェクトのエントリポイントガイダンスについて references/project-structure.md を読み、ステップ 4 から 8 までそれに従ってください。このファイルの残りの部分は単一プロジェクトのフローを扱います。

単一プロジェクトの場合: 検出した内容をユーザーに伝え、以下を続けてください。

ステップ 4: エントリポイントのパスを決定する

ソースディレクトリを推測します:

• src/ が存在し、ソースコードを含んでいる場合は src を提案します
• lib/ が存在し、ソースコードを含んでいる場合は lib を提案します
• それ以外の場合は . (プロジェクトルート — すべての変更を捕捉できるため、より安全なデフォルトです) を提案します

このステップをスキップするのは、すでにパスを持つ既存のエントリポイントにチェックを追加する場合です。

ステップ 5: ツールをスキャンする

references/check-catalog.md に記載されている 6 つのチェックカテゴリにわたって、プロジェクト内のツールの手がかりをスキャンします。

「チェックを追加」のパスの場合: entry_points ですでに設定されているチェックを除外します。

ツールが見つからない場合: カスタムフローを提案します (ステップ 7 にスキップ)。それでも code-quality レビューは含めてください。

ステップ 6: 検出結果を提示して確認する

検出されたチェックの表を表示します:

Category        | Tool            | Command                              | Confidence
----------------|-----------------|--------------------------------------|-----------
Build           | npm             | npm run build                        | High
Lint            | ESLint          | npx eslint .                         | High
Typecheck       | TypeScript      | npx tsc --noEmit                     | High
Test            | Jest            | npx jest                             | High
Security (deps) | npm audit       | npm audit --audit-level=moderate     | Medium
Security (code) | Semgrep         | semgrep scan --config auto --error . | Medium

信頼度:

• 高 — ツールの設定ファイルが見つかった、かつ/または package.json/Makefile に明示的なスクリプトがある
• 中 — devDependencies でツールが見つかった、または CI ワークフローから推測できるが、専用の設定がない
• 低 — 間接的な証拠のみ (例: テストディレクトリは存在するが、ランナーの設定が見つからない)

カテゴリにツールが検出されなかった場合は、コマンドと信頼度に — を付けて (not found) と表示します。

ユーザーに尋ねます:

1. どのチェックを有効にするか (デフォルト: すべて)
2. 調整が必要なコマンドがあるか

ユーザーがすべてのチェックを拒否した場合でも、code-quality レビューを含めて、カスタムフロー (ステップ 7) を提案します。

確認後、ステップ 8 (ファイルの作成) に進みます。

ステップ 7: カスタムを追加する

ユーザーに尋ねます: check (シェルコマンド) ですか、それとも review (AI コードレビュー) ですか?

チェックの場合: コマンド、名前、およびオプション設定 (run_in_ci、run_locally) を尋ねます。

レビューの場合: ビルトイン (code-quality) ですか、それともカスタムプロンプトですか? 名前を尋ね、レビュー内容を書きます。

ステップ 8: ファイルを作成して設定を更新する

チェック — エントリポイントの checks 配列にチェックをインラインで追加します。各インラインチェックは単一キーのオブジェクトです (チェック名 → 設定オブジェクト)。command を含めます。オプションのフィールド (run_in_ci、run_locally) は、デフォルトと異なる場合にのみ追加します。スキーマについては references/check-catalog.md を参照してください。トップレベルの checks マップを追加しないでください — インラインチェックは entry_points の下に属します。

カスタムレビュー — YAML frontmatter (num_reviews: 1) とレビュープロンプトを含む .validator/reviews/<name>.md を作成します。

ビルトインレビュー — エントリポイントの reviews 配列にビルトインレビューをインラインで追加します (例: - code-quality: { builtin: code-quality })。ビルトインレビュー用に別のファイルを作成しないでください。

.validator/config.yml の entry_points を更新します:

entry_points:
  - path: "<source_dir>"
    checks:
      - build:
          command: npm run build
      - lint:
          command: npx eslint .
    reviews:
      - code-quality:
          builtin: code-quality

新規セットアップでは、常に reviews に code-quality を含めてください。「チェックを追加」/「カスタムを追加」の場合: 該当するエントリポイントのリストに追加するか、必要に応じて新しいエントリポイントを追加します。あるエントリポイントでインライン定義されたチェックまたはレビューは、他のエントリポイントから名前 (文字列として) で参照できます。

ステップ 9: 「他に追加しますか?」

ユーザーに尋ねます。はいの場合、ステップ 7 にループします。いいえの場合、次に進みます。

ステップ 10: 検証する

agent-validate validate を実行します。失敗した場合は、修正を 1 回試みて再検証します。それでも失敗する場合は、停止してユーザーに尋ねます。

ステップ 11: 設定をコミットする

セットアップがバージョン管理に保存されるように、すべてのバリデータ設定とスキルをコミットします:

1. すべての新規/変更されたファイルをステージングします: .validator/、.claude/skills/validator-*/、.claude/settings.local.json、.gitignore
2. コミットを作成します: git commit -m "chore: configure agent-validator checks and reviews"

コミットする変更がない場合 (すべてすでにコミット済み)、このステップを静かにスキップします。

ステップ 12: バリデータのベースラインを進める

/validator-skip を実行して、実行状態のベースラインを現在の作業ツリーまで進めます。これにより、次回の実行では将来の変更のみが差分として扱われます。

ステップ 13: 次のステップを提案する

ユーザーに伝えます: 設定が完了しました。実行するには /validator-run を、さらに追加するには /validator-setup を再度実行してください。