script-builder

script-builder

テスト／検証の意図を、対象プロジェクトの scripts/ ディレクトリにコミットする、長期的に使えて再実行可能なスクリプトに変換します。出力はコンテキスト効率を重視しています。成功時には PASS／FAIL の1行と /tmp のログパスだけを表示し、詳細な出力はすべてタイムスタンプ付きのログファイルにリダイレクトします。また、関連するテストの意図が再び生じたときに、後続のエージェントがスクリプトを見つけられるよう、CLAUDE.md／AGENTS.md に <important if> ブロックを追加します。

作業上の取り決め

以下の指示は、あなたとユーザーとの作業上の取り決めを定めるものです。主な原則は次のとおりです。

1. AskUserQuestion は主要なコミュニケーションツールです - 確認、希望、判断、承認など、ユーザーに何かを尋ねる必要がある場合は、必ず AskUserQuestion ツールを使用してください。質問をプレーンテキストで出力せず、ユーザーが効率よく回答できるよう、常に構造化されたツールを使用してください。

2. 希望は最初に確認してください - ユーザーの希望は、作業を終える間際ではなく、ワークフローの開始時に確認してください。

3. 自律性モードに応じて対話の頻度を調整してください - ユーザーが選んだ自律性レベルに基づいて確認の頻度を決めます。ただし、質問には常に AskUserQuestion を使用してください。

使用する場面

このスキルは、次の場合に有効になります。

• ユーザーが /script-builder コマンドを実行した場合
• 別のスキルが **OPTIONAL SUB-SKILL:** desplega:script-builder を参照している場合
• planning、qa、または verifying のフローで、まだ存在しない再実行可能な検証スクリプトが必要な場合
• 既存のスクリプトがない状況で、ユーザーが「X をスクリプト化したい」「この検証を再利用できる形にしたい」「X をエンドツーエンドでテストしたい」といった意図を示した場合

自律性モード

自律性モードに応じて動作を調整してください。

モード	動作
Autopilot	モードを判定し、ドラフトを作成して構文をチェックし、ドキュメントに記載します。エスカレーション段階の場合は、中間確認なしで実行と反復も行います。重大な障害や破壊的な副作用がある場合にのみ、一時停止します。
Critical（デフォルト）	各段階の境界で確認します（ドラフト作成後、ドキュメント編集前、実行前）。反復ループで修正を適用する際は AskUserQuestion を使用します。
Verbose	各手順の前に確認します。すべての差分を提示し、判定の根拠を逐一説明します。

自律性モードは呼び出し元のコマンドから渡されます。指定がない場合は、デフォルトの Critical を使用します。

手順

Step 1: モードの判定（事後宣言型と事前宣言型）

静かに判定してください。ユーザーに「どちらのモードですか？」と尋ねてはいけません。次のヒューリスティックを使用してください。

1. 最近のセッションでのツール使用履歴を確認する（現在の会話内の直近約20回のツール呼び出し）。テスト／検証に関連する活動として、curl／fetch の呼び出し、bun run／python／pytest、データベースクエリ、qa-use によるブラウザー操作、単一のエンドポイントやテーブルに対する grep／ログ確認の繰り返しを探します。同じ領域を対象とした該当する操作が2回以上あれば → 事後宣言型モードです。
2. ユーザーの呼び出しメッセージを解析する：
   • 叙述的な表現 → 事後宣言型：「今わかったことを」「これをスクリプトにして」「あれをスクリプトにまとめて」「さっきやったこと」
   • 意図を示す表現 → 事前宣言型：「テストしたい」「検証して」「スモークチェック」「デプロイ前に確認」
3. フォールバック：判定が難しい場合は、事前宣言型をデフォルトにします。

事後宣言型モードの最初のアクション：確認した内容を、プレーンテキストでユーザーに要約します（6行以内。何を、何に対して調べ、どのような成功シグナルがあったかを含めます）。その後、Q&A ではなく確認プロンプトを使って Step 3 に進みます。

事前宣言型モードの最初のアクション：そのまま Step 3 の Q&A に進みます。

Step 2: 既存のスクリプトをスキャンして重複を確認する

スクリプトディレクトリを次の順序で解決します。

1. CLAUDE.md に `` マーカーがあるか確認します。ある場合は、そのパスを使用します。
2. リポジトリのルートに scripts/ がある場合は、それを使用します。
3. 次の選択肢で AskUserQuestion を使用します：scripts/ (Recommended) | custom path | skip dir persistence for this run。

例外ケース — ディレクトリが存在しない場合：解決したパスが存在しない場合は、重複スキャンをスキップし、1 行のメモ（No existing scripts directory at <path> — proceeding to intent gathering）を表示します。また、Step 5 の前にディレクトリの作成を任意で提案することを覚えておきます。

ディレクトリが存在する場合：

1. スクリプトディレクトリ内のファイルを一覧表示します（v1 ではトップレベルのみ）。
2. 各ファイルの先頭（ヘッダーコメント）を読み、ファイル名のトークンを記録します。
3. CLAUDE.md/AGENTS.md を読み、このディレクトリ内のスクリプトを参照する <important if="..."> ブロックを探し、トリガーフレーズを記録します。
4. 現在の意図文字列を（ファイル名のトークン ∪ ヘッダーのキーワード ∪ トリガーフレーズ）とファジーマッチングします。「妥当な一致」とは、共通のキーワードと同じ領域名詞（例：auth、health、webhook）があるものです。
5. 妥当な一致が 1 件以上ある場合は、次の選択肢で AskUserQuestion を使用します：Reuse <name> as-is | Extend <name> | Generate new anyway。

境界線上の一致を黙ってスキップしてはいけません。一致を提示し、ユーザーに判断してもらいます。Extend 分岐では、既存のスクリプトにサブコマンド／フラグを追加します（新しいファイルは作成しません）。新しいフラグをスクリプトのヘッダーコメントと既存の <important if> ブロックに記載します。

Step 3: 意図を収集する

どちらのモードも、同じ内部意図構造に集約されます：{ what, success_signal, failure_signal, inputs, env, side_effects }。

Forward モード — AskUserQuestion を使用します（質問は 5 つではなく、1 つか 2 つ）。

質問	選択肢
「何を検証し、成功の判定基準は何ですか？」	[自由入力 — 1 つの回答で what と success signal を収集]
「注意すべき必須の環境変数、入力、または副作用（例：本番環境への書き込み、費用の発生）はありますか？」	[自由入力 — 任意。forward intent で既に指定されている場合はスキップ]

Retrospective モード — Step 1 の要約を提示し、That's the flow | Close but fix X | Start over を選択肢として AskUserQuestion を使用します。Close but fix X の場合は、その場で修正内容を尋ねます。Start over の場合は、forward モードの Q&A に進みます。

解決した意図は作業メモリに保持します（まだディスクには書き込みません）。

Step 4: 言語を検出する

優先順位 — 最初に一致したものを採用し、上書きパスもあります。

1. TypeScript — package.json と tsconfig.json が存在します。
   • bun.lock または bunfig.toml がある場合は Bun。
   • それ以外で、package.json の devDependencies に tsx がある場合は tsx。
   • それ以外は compiled Node（スクリプトのヘッダーに、tsc によるビルドが必要と記載します）。
2. Python — pyproject.toml、uv.lock、または requirements.txt が存在します。
   • uv.lock が存在する場合、または pyproject.toml に [tool.uv] が設定されている場合は uv（{{UV_METADATA}} を設定します）。
   • それ以外は vanilla python3（{{UV_METADATA}} を空文字列に置き換えます）。
3. TypeScript と Python の両方が検出された場合 — src/／トップレベルのソースファイル数を数え、優勢な方を推奨として AskUserQuestion で決定します。
4. Cargo.toml／go.mod のみの場合 → bash にフォールバックします（注：v1 では TypeScript／Python／Bash のみ）。
5. どれにも一致しない場合 → bash。

タスクに基づく上書き：収集した意図が明らかにシェル向けの場合（「docker コンテナ 3 つの応答を確認する」「このログファイルをエラーが出るまで追跡する」など）は、TypeScript／Python プロジェクトであっても bash を提案します。

検出した言語を最初の選択肢（Recommended）として AskUserQuestion で確認します。Autopilot ではスキップします。

Step 5: スクリプトの下書きを作成する

1. テンプレートを選択します：cc-plugin/base/skills/script-builder/templates/{typescript.ts.tmpl|python.py.tmpl|bash.sh.tmpl}。
2. 収集した意図に基づいて、置換マーカーを解決します：
   • {{SCRIPT_NAME}} ← 提案するファイル名の幹（命名表を参照）。
   • {{WHAT}} / {{WHEN}} / {{ENV}} / {{EXAMPLE}} ← 意図の各フィールド。
   • {{UV_METADATA}} ← Step 4 に従います。
3. 意図から {{TEST_BODY}} を生成します。最小限にとどめます。複数の検査を並べるのではなく、具体的なプローブとアサーションを1つだけにします。契約を確認するため、テンプレートの README（templates/README.md）を読み直してください。本文は PASS／FAIL の仕様に従う必要があります。失敗時には throw／raise／exit 1 を実行し、外側の try／trap に FAIL 行への変換を任せます。
4. 意図の形に合ったファイル名を提案します。下の接頭辞表を参照してください。提案した名前を「推奨」として最初に提示し、「カスタム名」を代替案として提示するために、AskUserQuestion を使用します。

命名規則（参考情報 — スキルが提案し、ユーザーが上書きできます）：

接頭辞	用途	例
e2e-*	複数のコンポーネントをまたぐエンドツーエンドのフロー	e2e-auth-flow.ts
check-*	冪等な単一プローブによる検証	check-db-boundary.sh
smoke-*	デプロイ後の最小限の動作確認	smoke-prod-api.ts
measure-*	パフォーマンス／サイズ／トークンの測定	measure-tool-tokens.ts
seed-* / generate-*	データのシードまたは成果物の生成（検証ではまれ）	seed-api-keys.sh

意図に適合する接頭辞がない場合は、validate-<area>.<ext> のような自由形式の名前を提案します。

5. 解決済みのスクリプトディレクトリにファイルを書き込みます。実行可能にします（chmod +x）。

Step 6: 構文／型チェック

適切なチェッカーを実行します。

言語	チェッカー（優先順位順）
TypeScript	Bun がある場合は bunx tsc --noEmit <file>、ない場合は npx tsc --noEmit <file>
Python	python3 -m py_compile <file>（必ず実行）＋ ruff が PATH 上にある場合は ruff check <file>
Bash	shellcheck <file> が利用できる場合は実行し、そうでなければ bash -n <file>

成功した場合：1行（syntax check OK）を記録し、Step 7 に進みます。

失敗した場合：

1. エラーを出力します（10行以下。出力全体は表示しません）。
2. 1か所を編集する具体的な修正案を提示します（適用する正確な Edit）。
3. Apply fix | Investigate | Stop を選択肢として、AskUserQuestion を使用します。
   • Apply fix → スクリプトを編集し、チェッカーを再実行します（固定の上限を設けず、ループします）。
   • Investigate → ユーザーとの相談に移行し、自動では何も適用しません。
   • Stop → スクリプトを指定のパスに残し、そのパスを出力します。削除はしません。

ステップ 7：スクリプトをドキュメント化する

対象プロジェクトの CLAUDE.md や AGENTS.md を自動編集し、同じ目的が再び発生したときに、後続のエージェントがこのスクリプトを見つけられるようにします。

ブロックのテンプレート（スキルが出力する Markdown のリテラル）：

<important if="[TRIGGER: e.g., you are testing the auth flow]">

## [Area] validation

Run `scripts/<name>` to [one-liner]. Requires [env/deps]. Example: `<cmd>`. Full log at `/tmp/<name>-*.log`.

Generated/maintained via `/script-builder`.

</important>

動作：

1. 対象ファイルの選択：両方が存在する場合は CLAUDE.md と AGENTS.md を編集し、存在するものだけを編集します。どちらのファイルも絶対に新規作成しないでください。どちらも存在しない場合は、1 行のメモ（No CLAUDE.md or AGENTS.md found — script generated but not documented）を出力して、このステップをスキップします。
2. 配置のヒューリスティック：ファイル内で Test|Testing|Validation|Scripts に一致する最初の見出し（大文字小文字を区別しない）を探します。見つかった場合は、そのセクション内またはその後に新しいブロックを追加します。見つからなかった場合は、ファイル末尾近くの、License|Acknowledg|Maintain|Contributors に一致する見出しより前に、新しい ## Scripts for testing & validation セクションを追加します。
3. 冪等性：scripts/<name> を参照するブロックがすでにある場合（つまり、同じスクリプト名で /script-builder を以前に実行した場合）、そのブロックをその場で更新します。重複を追加せず、<important if=...>...</important> ブロック全体を置き換えてください。
4. スクリプトディレクトリのマーカー：ステップ 2 で既存のマーカーではなくユーザーの選択によりスクリプトディレクトリが決まった場合は、CLAUDE.md の上部（タイトルの後）に `` を挿入し、以後の実行で確認が表示されないようにします。マーカーがすでに存在する場合はスキップしてください。
5. 差分を表示する：git diff CLAUDE.md AGENTS.md と同等のコマンドを実行し、変更内容を 5 行で要約して出力します。自動でステージングしないでください。コミットはユーザーが行います。

ステップ 8：エスカレーションを提案する

ドキュメントの編集後、「実行して反復する」段階に進むかどうかを判断します。

自律性	動作
Autopilot	目的に副作用（本番環境への書き込み、実際の金銭の送金、共有リソースの変更）がある場合を除き、ステップ 9 に自動で進みます。副作用がある場合は、Critical の動作に切り替えます。
Critical（デフォルト）	AskUserQuestion を使用します：`Run it now to confirm it works
Verbose	Critical と同じですが、実行前に提案する実行コマンドの確認も求めます。

ユーザーが「I'll run it myself later」または「Just generate, don't run」を選択した場合は、ステップ 10 に直接進みます。

ステップ 9：失敗時に反復する（エスカレーションした場合のみ）

人間が範囲を定めるループです。Autopilot 以外では、修正を自動適用しないでください。

1. 提案した実行例でスクリプトを実行します（--verbose と --json は指定しません）。終了コードと /tmp ログの tail -n 40 を取得します。
2. 終了コードが 0 の場合 → PASS を報告し（スクリプトの PASS 行をそのまま出力）、ステップ 10 に進みます。
3. 終了コードが 0 以外の場合：
   • 失敗の概要を1～3 行で示します。エラーの種類（timeout / 4xx / 5xx / assertion / dependency-missing など）と、ログで既知のパターン（ECONNREFUSED、Traceback、non-zero exit、command not found など）を検索した結果に基づく原因の可能性を記載します。
   • 具体的な差分を提案する — スクリプトに適用する Edit の内容を正確に示します。変更前 → 変更後の形式にします。
   • AskUserQuestion を使用します：Apply fix | Investigate differently | Stop。
     • Apply fix → スクリプトを編集して変更を記録し、(1) に戻ります。
     • Investigate differently → 議論に切り替え、自動適用はしません。
     • Stop → スクリプトはそのまま残し、パスを出力します。元に戻しません。

ハードコードされた再試行上限は設けません。暗黙の上限は人間が決めます。

副作用フラグ：目的に副作用があると宣言されている場合（ステップ 3）に Autopilot が有効なら、最初の実行前に WARNING: this script <does X> against <target> の 1 行を提示し、Autopilot モードでも AskUserQuestion による明示的な確認を必須とします。

ステップ 10：引き継ぎ

スキルの終了方法は、呼び出された方法によって異なります。

サブスキルとして呼び出された場合（planning、qa、verifying から）： 構造化された要約を返して親スキルに制御を戻します：{ script_path, status: "pass"|"fail"|"unrun", log_path?, doc_files_edited: [...] }。

直接呼び出された場合（/script-builder）： AskUserQuestion を使用します：/qa で実行 | /verify-plan を実行 | スクリプトとドキュメントの変更をコミット | 完了。

• /qa で実行 → スクリプトのパスをソースとして desplega:qa を呼び出します。
• /verify-plan を実行 → 現在のコンテキストにプランのパスがある場合は、desplega:verifying を呼び出します。
• コミット → コミットメッセージ（feat(scripts): add scripts/<name> for <area> validation）を提案し、生成されたスクリプトと CLAUDE.md/AGENTS.md の編集のみをステージングします。自動でコミットしないでください。提案する git add コマンドと git commit コマンドを表示し、ユーザーの確認を必須とします。
• 完了 → スクリプトのパスと、エスカレーションを実行した場合はログのパスを表示して終了します。

中止する場合（それ以前のいずれかの確認ポイントで「停止」が選択された場合）：生成されたスクリプトはそのまま残し、ステップ 7 が実行済みなら CLAUDE.md/AGENTS.md の編集もそのまま残し、次の一行を表示します：中止しました。スクリプト：<path>。ドキュメントの編集：<files or "none">。/script-builder を再実行するか、git checkout で破棄してください。 ユーザーに代わって git restore を実行しないでください。

学びの記録

任意のサブスキル： このワークフローで重要な洞察、パターン、注意点、判断が得られた場合は、desplega:learning を使用して /learning capture から記録することを検討してください。今後のセッションでほかの人の役に立つ学びに重点を置いてください。