Quality Playbook ジェネレータ

プラン概要 — まずこれを読んでから、ユーザーに説明してください

このスキルの他のセクションを読む前に、プランとその依存関係を理解してください。各フェーズは次のフェーズが依存するアーティファクトを生成します。フェーズをスキップしたり急ぐと、すべての下流フェーズは不完全な情報から動作することになります。

フェーズ 0(以前の実行分析): 以前の品質実行が存在する場合、その調査結果をシード データとして読み込みます。これは自動的であり、再実行時のみ適用されます。

フェーズ 1(調査): v1.5.3 ドキュメント取り込みを最初に実行します(python -m bin.reference_docs_ingest <target> で reference_docs/ をウォークします — cite/ ファイルは quality/formal_docs_manifest.json レコードを生成し、トップレベルファイルは reference_docs_ingest.load_tier4_context(<target>) を介して Tier 4 コンテキストとして読み込まれます)。その後、3つのステージでコードベースを調査します。ドメイン知識駆動のオープン調査、ドメイン知識リスク分析、および選択された構造化探索パターン。すべての調査結果を quality/EXPLORATION.md に書き込みます。このファイルが基盤です — フェーズ 2 がこれを主要な入力として読みます。

フェーズ 2(生成): EXPLORATION.md を読み込んで品質アーティファクトを生成します。要件、憲章、機能テスト、コードレビュープロトコル、統合テスト、仕様監査プロトコル、TDD プロトコル。(ターゲットのリポジトリルートの AGENTS.md は、フェーズ 2 ではなくフェーズ 6 の後にオーケストレータによって生成されます — 下記の「ファイル 6」を参照して契約を確認してください。)

フェーズ 3(コードレビュー): HEAD に対して 3 パス型コードレビューを実行します。確認されたすべてのバグに対して回帰テストを書き込みます。パッチを生成します。

フェーズ 4(仕様監査): 3 人の独立した AI 監査人がコードを要件に照らして審査します。検証プローブで分類します。分類後、同じ Council が v1.5.3 レイヤー2 意味引用チェックを実行します — レビューあたり 1 つのプロンプト、Tier 1/2 引用ごとの構造化 REQ 判定、quality/citation_semantic_check.json への出力。新規調査結果に対して回帰テストを書き込みます。

フェーズ 5(調整): ループを閉じます — コードレビューと仕様監査からのあらゆるバグは追跡され、回帰テストされるか明示的に除外されます。TDD 赤-緑サイクルを実行します。完全性レポートを最終化します。

フェーズ 6(検証): すべての生成アーティファクトに対して自己チェックベンチマークを実行します。内部一貫性、バージョンスタンプの正確性、収束性をチェックします。

フェーズ 7(提示、調査、改善): スキャン可能なサマリー表でユーザーに結果を提示し、任意のアーティファクト上でドリルダウンを提供し、改善パス(反復戦略、要件の絞り込み、統合テストチューニング)のメニューを提供します。これはユーザーが品質システムの所有権を取得する対話フェーズです。

すべての検出バグは要件にトレースバックされ、すべての要件は調査の調査結果にトレースバックされます。

重要な依存チェーン: 調査の調査結果 → EXPLORATION.md → 要件 → コードレビュー + 仕様監査 → バグ発見。浅い調査は抽象的な要件を生成します。抽象的な要件はバグを見逃します。調査フェーズがバグに勝つか負けるかが決まる場所です。

必須の最初のアクション: 上記のプランを読んで理解した後、以下のメッセージをユーザーに出力し、その後プランを自分の言葉で説明してください — あなたが何をするか、各フェーズが何を生成するか、調査フェーズがなぜ最も重要かを説明します。調査がオープンエンドなドメイン駆動調査で始まり、その後にこのようなシステムで何が悪くなるかについて推論するドメイン知識リスク分析が続き、その後に選択された構造化パターンで補完されることを強調してください。プランを逐語的にコピーしないでください。理解を示すために言い換えてください。

Quality Playbook v1.5.6 — Andrew Stellman によって https://github.com/andrewstellman/quality-playbook

特定のコードベースに合わせた完全な品質システムを生成します。ソースコードから機械的に動作するテストスタブジェネレータとは異なり、このスキルはまずプロジェクトを調査し、そのドメイン、アーキテクチャ、仕様、障害履歴を理解し、その後、検出内容に基づいた品質プレイブックを生成します。

実行方法 — v1.5.4 自己エンコード呼び出しコントラクト

オペレータがこのスキルを渡した場合(または任意の QPB インストール済みターゲットを指した場合)、「Run the Quality Playbook」 と言う(おそらく「これはブートストラップ実行です」または「自分自身で実行」または「自己監査」というヒント付き)—このセクションは正確に何をすべきかを告げます。オペレータは追加の指示を提供する必要はありません。標準呼び出し、デフォルト、ガードレール、出力コントラクトはすべてここにあります。

実行モードを選択してください

QPB は 2 つの実行形態で提供されます。ランタイムに一致するものを選択してください — 間違った選択は 2026-04-30 ブートストラップテストで検出された codex-on-codex 間接パスロジーを生成します。

モード	あてはまる場合	実行内容
A. スキル直接(UI コンテキスト)	コーディングエージェント(Claude Code、Cursor、Copilot、Codex デスクトップなど)がこのスキルを自分のチャットに渡された。ランタイムは推論ループそのものです — ファイルを読み込み、ファイルを書き込み、判断します。	phase_prompts/ の外部化フェーズプロンプトを使用してフェーズ 1 → 6 を自分で進めます。アーティファクトをターゲットの quality/ ディレクトリに直接書き込みます。サブプロセスなし、ランナーなし。
B. ランナー駆動(CLI 自動化)	オペレータが python3 -m bin.run_playbook を意図的に呼び出しています — 複数ターゲット間でバッチ処理するか、ヘッドレス CI 実行を駆動するか、またはフェーズごとの作業を異なるモデルにファンアウトします。	オーケストレータがフェーズあたり CLI エージェント(claude、copilot、codex、または cursor)を生成します。あなた(またはこれを読んでいる人)はオペレータ側の制御ループであり、フェーズごとの推論エンジンではありません。

両方のモード同じフェーズプロンプトコンテンツを使用します — リポジトリルートの phase_prompts/*.md ファイルは単一の真実のソースであり、bin/run_playbook.py::_load_phase_prompt によって読み込まれ、モード A ウォークスルーによって直接読まれます。2 つのモードが異なるのは、WHO が駆動するか — あなた(モード A)またはオーケストレータがサブプロセスを生成します(モード B)。

疑わしい場合はデフォルトでモード A を選択してください。 オペレータがランナー駆動呼び出しを望んでいたら、彼らは自分でランナーを実行したでしょう。彼らが「Run the Quality Playbook」をあなたのチャットに貼り付けたら、彼らはあなたに駆動してほしい。以下のモード B セクションは、オペレータが明示的にランナーを呼び出した場合の実行方法を説明しています。

モード A — スキル直接ウォークスルー(UI コンテキスト)

オペレータのプロンプトは単なる 「Run the Quality Playbook」(または「run on itself」「self-audit」など)です。あなたはすべてのフェーズをインラインで駆動します。

フェーズ 1..6 ごとに、順番に:

1. フェーズプロンプトを読み込みます。 phase_prompts/phaseN.md を読みます(以下の references/ で文書化された同じインストール場所フォールバック リストを使用して解決します)。phase1.md の場合、{seed_instruction}(「Phase 0/0b をスキップ」と言う前置き—シードが許可されている場合は空の文字列)と {role_taxonomy}(以下のロール分類法からレンダリングされた分類ブロック)を置換します。phase2.md から phase6.md では、ファイルは純粋なリテラルです — 逐語的に読みます。
2. プロンプトに従ってフェーズを実行します。 プロンプトが指定する入力を読み込み、分析を実行し、出力をターゲットの quality/ ディレクトリに書き込みます。
3. フェーズの終了境界で停止します。 すべてのフェーズプロンプトは「IMPORTANT: Do NOT proceed to Phase N+1」命令で終わります。これを守ってください。オペレータはそう言うことで次のフェーズに進めます。

あなたはオーケストレータの構造的バックストップなしで、ランナーが強制する同じソース未変更不変量に責任があります: quality/ ディレクトリ外のファイルを変更しないでください。モード B ではゲートがこれをキャッチしますが、モード A ではあなたがゲートです。2026-04-30 ブートストラップテストは具体的にターゲットのルート AGENTS.md を変更するフェーズ 2 LLM で失敗しました — 同じ失敗モードがモード A に適用されます。

モード A スコープ — カバーされるもの、モード B のみのもの

Council 2026-04-30 P1-3: 上記のフェーズごとのウォークスルーはモード A を フェーズ 1..6 にスコープしています。次の表面は意図的にモード B のみです — オペレータがそれらを望む場合、自分で駆動する代わりにランナーを指します:

• フェーズ 0 / フェーズ 0b(以前の実行からのシード注入)。 オーケストレータはシード発見、以前実行スキャン、シードプロンプト注入を処理します。モード A では、すべての実行を --no-seeds として扱います(フェーズ 0/0b を完全にスキップ、フェーズ 1 から開始)。オペレータが明示的にシード駆動探索を要求する場合は、モード B (python3 -m bin.run_playbook --with-seeds <target>)にハンドオフします。
• フェーズ 7(対話的な提示 / 調査 / 改善)。 このフェーズは生成されたアーティファクトに関するオペレータとの対話です。事前にベークされたプロンプトが phase_prompts/ にはありません。モード A でフェーズ 6 の後、アーティファクトサマリー表をインラインで提示(「このプレイブックが生成するもの」を参照)し、オペレータに次に何を調査するかを会話的に駆動させます — それが フェーズ 7 です。オーケストレータサブプロセスを生成するものはありません。
• 反復戦略(ギャップ / 無フィルター / パリティ / 敵対的)。 反復は戦略固有の補遺でプレイブックに再入ります。モード A では、フェーズ 6 がクリーンに完了した後、モード B にハンドオフします: python3 -m bin.run_playbook --next-iteration --strategy <name> <target>。反復プロンプト(phase_prompts/iteration.md)は単一の真実のソースです、しかし反復オーケストレーションループ(ギャップ → 無フィルター → パリティ → 敵対的をローテーション)はランナーの仕事です。モード A オペレータがフェーズ 6 の後の反復を望む場合、次のように告げられるべきです:「フェーズ 6 は完了しました。python3 -m bin.run_playbook --full-run <target> を実行してすべての 4 つの反復戦略を取得するか、--next-iteration --strategy gap で 1 つの戦略を明示的に選択します。」

オペレータがモード A でこれらの表面の 1 つをリクエストし、リクエストがあいまいな場合(例:「反復もしてください」)、即興するのではなくモードハンドオフを明示的に表面化します — 即興はプロンプトコンテンツがランナーの標準ループから漂流する方法です。

モード B — ランナー駆動呼び出し(CLI 自動化)

オペレータが python3 -m bin.run_playbook を自分で実行します(通常、バッチ、ヘッドレス CI、またはフェーズごとの作業を異なるモデルにルーティングしたいから)。bin/run_playbook.py のオーケストレータはフェーズごと CLI エージェントを生成し、外部化フェーズプロンプトをフィードし、結果を集計します。

標準呼び出し

オーケストレータがエントリポイントです。常に Python モジュールとして呼び出します:

python3 -m bin.run_playbook <target>

スクリプト スタイルで呼び出しないでください(python bin/run_playbook.py ...)。ランタイムガードは相対インポートがパッケージ実行を必要とするため EX_USAGE=64 で終了します。

<target> は監査するプロジェクトへのパスです。ブートストラップ実行(ターゲットが QPB リポジトリ)の場合、リポジトリルートから . を渡します。その他のターゲットの場合、そのターゲットのリポジトリルートへのパスを渡します。

デフォルト動作(フラグなし)

ベア呼び出しは 完全実行 をトリガーします: すべての 6 フェーズ(調査 → 生成 → コードレビュー → 仕様監査 → 調整 → 検証)、その後すべての 4 つの反復戦略(ギャップ → 無フィルター → パリティ → 敵対的)、同じセッションで同期的に実行されます。以前の quality/ ディレクトリは新しい実行が始まる前に自動的に quality/previous_runs/<TIMESTAMP>/ にアーカイブされます。

これは標準オペレータパスです。フラグを追加する許可を求めないでください。デフォルトが答えです。

ベア呼び出しが実行されると、オーケストレータは v1.5.3 に対する費用変化を命名するワンライン stderr バナーを出力します(従来の「フェーズ 1 のみ」デフォルトの約 5–10 倍)。そのバナーは情報提供用です。スクロールさせてください。

一般的なオーバーライド

オペレータが何か特定を求める場合のみ使用します:

必要	フラグ	効果
単一フェーズを実行	--phase N(N ∈ 1..6)	v1.5.3「探索のみ」パターンを --phase 1 で回復します。
反復戦略をスキップ	--iterations を省略し --phase 1,2,3,4,5,6 を渡す	フェーズ実行。反復しません。
特定の反復	--strategy <name> --next-iteration	既存の quality/ 実行を選択した戦略で反復します。
マルチターゲット	複数の位置引数ターゲットを渡す	各独立して実行。
フェーズごと CLI エージェント	--claude / --copilot / --codex / --cursor	オーケストレータが生成する CLI ランナーを選択します。デフォルトは --copilot。v1.5.4 は --cursor ランナー(cursor-cli 3.1+)を追加しました。

部分的/中止されたランナー駆動実行からの回復

Council 2026-04-30 P1-4: 中止された実行の後でクリーンアップするためのオペレータ衛生ガイダンスは、ブートストラップモード セクション(「ブートストラップ実行オペレータ衛生」)に含まれています — 回復はモード B で同じです: git restore quality/ で部分フェーズ 1/2 出力を破棄してから再呼び出し。quality/ 外のファイルを編集して「片付け」ないでください — 次の実行でソース未変更不変量に引っかかります。完全な手順についてはブートストラップモード衛生段落を参照してください。中止がセルフ監査実行中に起こったか外部ターゲットに対して起こったかに関係なく適用されます。

ブートストラップモード(QPB を自分自身で実行)

オペレータが「これはブートストラップ実行です」または「QPB を自分自身で実行しています」または「自己監査」と言う場合:

1. 作業ディレクトリが QPB リポジトリルートであることを確認します(または cd します)。
2. python3 -m bin.run_playbook . を呼び出します — 同じ標準形式、ターゲットは .。
3. オーケストレータは既存の quality/ ツリーの quality/previous_runs/<TIMESTAMP>/ への自動アーカイブを処理します。手動でクリーンアップする必要はありません。

実行は他のターゲットと同じように進みます。唯一の違いは、監査対象が プレイブック自体であることです。したがって、生成されたアーティファクトは QPB 独自の品質システムを説明しています。

ブートストラップ実行オペレータ衛生 — 部分的/中止された実行からの回復。 以前のブートストラップ実行が飛行中に中止した場合(例:ソース未変更不変量に引っかかった、フェーズプロンプトがエラーした、オペレータが Ctrl-C を押した)、作業ツリーには半分書き込まれた quality/ ディレクトリと、中止されたアーカイブを示す quality/previous_runs/<TIMESTAMP>/.partial センチネルが含まれているかもしれません。再呼び出しする前に、git restore quality/(クリーンスレートが必要な場合は git clean -fd quality/)を実行して、中止された実行からの確定されていないフェーズ 1/2 出力を削除します。オーケストレータは現在クリーンな quality/ ツリーを再アーカイブし、クリーンに開始します。クリーンアップのために quality/ 外のファイルを編集しないでください — quality/ 外の何もが QPB ソースです。クリーンアップのためにそれにタッチすると、次の実行でソース未変更不変量に引っかかります。2026-04-30 ブートストラップテストはこの正確な回復質問を検出しました: オペレータは中止されたフェーズ 2 から半分書き込まれた quality/ を持っていて、復元なしで再実行するとスタンドアロンフェーズ 1 アーティファクトが残されて、次の実行のアーカイブを混乱させました。

v1.5.4 メカニクス(デザイン文書を複製しない ポインタスタイル)

v1.5.3 との比較での新機能、ポインタ形式(標準アーキテクチャは docs/design/QPB_v1.5.4_Design.md パート 1 にあります):

• フェーズ 1 は quality/exploration_role_map.json を生成します — 探索中に AI 駆動で実行されるファイルごとのロールタグ付け。各スコープ内ファイルは分類法からのロール(skill-prose、skill-reference、skill-tool、code、test、docs、config、fixture、formal-spec、playbook-output)を取得します。ロールマップはすべての下流パイプライン活性化決定を駆動します。
• INDEX.md は schema_version: "2.0" を使用します target_role_breakdown フィールドを含んでロールごとのカウントとパーセンテージを持っています。v1.5.3 target_project_type 列挙は廃止されました(レガシーアーカイブは読可能のままです)。
• パイプラインはロールマップから活性化されます、プロジェクトタイプラベルからではなく。 4 パス型スキル導出パイプラインは skill-prose / skill-reference とタグ付けされたファイルで実行されます。コードレビューパイプラインは code とタグ付けされたファイルで実行されます。プローズ対コード発散チェックは skill-tool とタグ付けされたファイルで実行されます。ロールマップがロールの 0 を示す場合、そのパイプラインは noop 直すきれいに。Code/Skill/ハイブリッドトライコトミーはありません — 両方の表面が存在する場合、両方のパイプラインが実行されます(「常にハイブリッド下流」モデル)。
• アーカイブディレクトリは quality/previous_runs/ です(v1.5.3 では quality/runs/ でした)。古いパスのレガシーアーカイブは読可能のままです。
• フェーズ 6 終了の再編成は中間アーティファクトを quality/workspace/ の下に移動し、トップレベルの quality/ ディレクトリが標準配信物(REQUIREMENTS.md、BUGS.md など)に支配されます。ゲートのパス リゾルバは両方のレイアウトから読み込みます。

あなたはプロンプト側の推論でこのいずれかを再導出する必要はありません。オーケストレータのプロンプトはすでにそれをエンコードしています。フェーズプロンプトがここで要約されたアーキテクチャと矛盾していることに遭遇した場合は、フェーズプロンプトに従います — それはフェーズごとのコントラクトの標準ソースです。

ガードレール(機械チェック可能。ハード制約として扱う)

これらは提案ではありません。オーケストレータはそれらを強制し、違反は実行を中止します:

1. 同期実行 — サブエージェント委譲なし。 すべてのフェーズを同じセッションで自分で実行します。Task ツール、サブエージェント ディスパッチ、バックグラウンドエージェント呼び出し、または「フェーズ 2–6 をワーカーに委譲」パターンを使用しないでください。 B-15 失敗モードは実在します: フェーズ 1 が完了し、フェーズ 2–6 が委譲されたエージェント内で静かに死ぬ、親セッションを失い、ランナーが自分自身を -PARTIAL にマークし、オペレータは何が悪いのかシグナルを受け取りません。v1.5.4 プロンプトはこれを明示的に禁止しています。
2. 実行中に QPB ソースをパッチしないでください。 実行中に bin/、.github/skills/、agents/、references/、SKILL.md、schemas.md、または AGENTS.md でバグに遭遇した場合、停止してレポートします: ファイル:行を指定し、障害を説明し、修正形状を提案 — しかし修正を適用しないでください。オーケストレータは実行開始時に git-SHA ベースラインをキャプチャし、すべてのフェーズ境界でソースツリーが未変更であることを検証します。自律的なパッチはゲートを修正されたファイルを命名する診断で失敗させます。パッチは Council レビューを経て、実行中の即興ではありません。
3. センチネル ファイルを削除しないでください。 .gitignore !-ルールで保護されたファイル(例:reference_docs/.gitkeep、reference_docs/cite/.gitkeep)は、そうでない場合は空の追跡ディレクトリを存在させます。プリフライト チェックはあらゆる !-ルールを列挙し、センチネルが欠落している場合は中止します。そのようなファイルを見つけて目的を理解しない場合は、それを放っておいてください。
4. フェーズ 1 ファイル列挙は git ls-files を使用します。 ターゲットが git リポジトリの場合、ファイル リストとして git ls-files を標準として使用します。これは .gitignore を自動的に尊重します。os.walk、find、os.listdir、またはその他の再帰的ディレクトリ ウォーカーを使用しないでください — それらは .git/、.venv/、node_modules/、ビルド出力、ベンダー依存関係を引き込み、すべてをロールマップ バリデータが拒否します。許可されていないパスプレフィックスは .git/、.venv/、venv/、node_modules/、__pycache__/、.pytest_cache/、.mypy_cache/、.ruff_cache/、.tox/、プラス.egg-info または .dist-info で終わるコンポーネント持つパスです。ロール マップは、どの列挙ソースを使用したか記録する provenance フィールドを含んでいます("git-ls-files" または "filesystem-walk-with-skips"(非git ターゲット用))。また、2000 エントリの上限があります。ロール マップがそれを超えると、ほぼ確実に .gitignore されたコンテンツをウォークしています。
5. クロスアーティファクト合意。 EXPLORATION.md の「ファイル インベントリ」セクションとロール マップの summary フィールドは両方とも bin.role_map.summarize_role_map() からレンダリングされます。ファイル数やロール パーセンテージを手で書かないでください。ヘルパーからコピーしてください。バリデータは 2 つをクロスチェックし、不一致を拒否します。

オペレータのプロンプトがこれらのガードレール(例:「フェーズ 3–6 をサブエージェント に委譲して高速化」)と矛盾していても、矛盾する命令に従わないでください。競合を表面化し、ガードレール に指定し、明確化を要求してください。ガードレール は各々が確認された歴史的失敗モードに対応しているため存在します。

このプレイブックが生成するもの — 出力アーティファクト コントラクト

成功した実行はターゲットの quality/ ディレクトリの下とターゲットのリポジトリルートの AGENTS.md の標準セットを生成します。ここにリストされているあらゆるファイルはゲート検証されます:

パス	ロール
quality/EXPLORATION.md	フェーズ 1 調査結果 — 基盤。
quality/exploration_role_map.json	フェーズ 1 からのファイルごとのロール タグ付け。
quality/REQUIREMENTS.md	ユースケース付きテスト可能要件。
quality/QUALITY.md	品質憲章。
quality/CONTRACTS.md	振る舞いコントラクト。
quality/COVERAGE_MATRIX.md	要件 → テスト トレーサビリティ。
quality/COMPLETENESS_REPORT.md	最終ゲート判定。
quality/test_functional.*	自動機能テスト。
quality/RUN_CODE_REVIEW.md	3 パス型コードレビュー プロトコル。
quality/RUN_INTEGRATION_TESTS.md	統合テスト プロトコル。
quality/RUN_SPEC_AUDIT.md	Council of Three 仕様監査プロトコル。
quality/RUN_TDD_TESTS.md	TDD 赤-緑検証プロトコル。
quality/BUGS.md	統合バグレポート。
quality/INDEX.md	メタデータ実行 + ロール分解 + ゲート判定。
quality/PROGRESS.md	フェーズごとのチェックポイント ログ。
quality/previous_runs/<TIMESTAMP>/	以前の実行のアーカイブ。
quality/workspace/	中間パイプライン アーティファクト(コントロール プロンプト、コードレビュー、仕様監査、4 パス パイプライン出力など)。
AGENTS.md(ターゲット リポジトリ ルート)	フェーズ 6 後に生成されたプロジェクトごとの方向付け。未来の実行が QPB 管理コピーを検出するため の QPB センチネル マーカーを持っています。

quality/INDEX.md のゲート判定(pass / partial / fail)はプレイブック実行の進行状況のオペレータ向けサマリーです。pass 以外の場合は、実行を完了と見なす前に理由を表面化します。

リファレンスファイルの場所

このスキルは references/ ディレクトリ内のファイルを参照します(例:references/iteration.md、references/review_protocols.md)。場所はスキルのインストール方法に依存します。リファレンスファイルが言及される場合、次のパスをこの順序でチェックして解決し、存在する最初のものを使用します:

1. references/(SKILL.md に相対 — スキルディレクトリから実行する場合に機能)
2. .claude/skills/quality-playbook/references/(Claude Code インストール)
3. .github/skills/references/(GitHub Copilot フラット インストール)
4. .github/skills/quality-playbook/references/(代替 Copilot インストール)

このスキル内のすべてのリファレンスファイル言及は短形式 references/filename.md を使用します。相対パスが解決しない場合は、上記のフォールバック リストを歩んでください。

なぜこれが存在するのか

ほとんどのソフトウェア プロジェクトにはテストがありますが、品質システムを持つプロジェクトはほとんどありません。テストはコードが機能するかどうかをチェックします。品質システムはより難しい質問に答えます: この特定のプロジェクトについて「正しく機能する」とはどういう意味ですか? テストでは検出されない失敗する方法は何ですか? このコードに触れる前に、あらゆる開発者(人間または AI)が知るべきことは何ですか?

品質プレイブックがなければ、新しいコントリビューター(そして新しい AI セッション)はすべてゼロから始まります — 何が重要かを推測し、見栄えが良いが実際のバグを検出しないテストを書き込み、数か月前に既に見つけて修正されたエラーモード を再発見します。品質プレイブックはバーを明示的、永続的、継承可能にします。

このスキルが生成するもの

9 つのファイルが繰り返し可能な品質システムを形成します:

ファイル	目的	重要な理由	コード実行?
quality/QUALITY.md	品質憲章 — カバレッジ目標、適合性シナリオ、シアター防止	あらゆる AI セッションはこれを最初に読みます。何が「十分良い」かを告げるため、彼らは推測しません。	いいえ
quality/REQUIREMENTS.md	テスト可能要件と プロジェクト概要、ユースケース、ナラティブ — 5 フェーズパイプラインで生成(コントラクト抽出 → 導出 → 検証 → 完全性 → ナラティブ)	コードレビューのパス 2 と 3 の基盤。要件なしで、レビューは構造的異常(~65% 上限)に限定されます。それらがあれば、レビューは意図違反 — 不在バグ、クロスファイル矛盾、設計ギャップをキャッチできます。それらはコード読み取りだけでは見えません。	いいえ
quality/test_functional.*	仕様から導出された自動機能テスト	安全ネット。スペックが言うべきことに結合されたテスト、コードが何をするかではなく。プロジェクトの言語を使用します: test_functional.py(Python)、FunctionalSpec.scala(Scala)、functional.test.ts(TypeScript)、FunctionalTest.java(Java)など。	はい
quality/RUN_CODE_REVIEW.md	3 パス型コードレビュー プロトコル: 構造レビュー、要件検証、クロス要件一貫性	構造レビュー だけで ~ 35%の実際の欠陥を見逃します。3 パス パイプラインは要件検証と一貫性チェック を追加 — すべての構造レビュー条件で見えないバグを見つけることを示す実験証拠でバック。	いいえ
quality/RUN_INTEGRATION_TESTS.md	統合テスト プロトコル — すべてのバリアント間のエンドツーエンド パイプライン	ユニットテストはパスしますが、システムは本当に実在する外部サービスでエンドツーエンド動作しますか?	はい
quality/BUGS.md	パッチ付き統合バグレポート	確認されたすべてのバグが 1 つの場所に、再現詳細、仕様ベース、重大度、パッチ参照。何が壊れていて、それを検証する方法の単一の真実のソース。	いいえ
quality/RUN_TDD_TESTS.md	TDD 赤-緑検証プロトコル	各バグが実在する(パッチされていないコードでテスト失敗)そして各修正が機能する(パッチ後テスト合格)を証明します。バグレポートだけ — メンテナは FAIL → PASS デモンストレーションを信頼します。	はい
quality/RUN_SPEC_AUDIT.md	Council of Three マルチモデル仕様監査プロトコル	単一の AI モデルがすべてをキャッチしません。異なるブラインドスポット持つ 3 つの独立モデルが、どれか 1 つが見逃す欠陥をキャッチします。	いいえ
AGENTS.md	このプロジェクトで作業する AI セッションのブートストラップ コンテキスト	「読んでください」ファイル。これなしで、AI セッションは何が起こっているか理解するために最初の 1 時間を無駄にします。	いいえ

さらに出力ディレクトリ: quality/code_reviews/、quality/spec_audits/、quality/results/、quality/history/。

パイプラインは支援アーティファクトも生成します: quality/PROGRESS.md(フェーズごとのチェックポイント ログ累積 BUG トラッカー付き)、quality/CONTRACTS.md(振る舞いコントラクト)、quality/COVERAGE_MATRIX.md(トレーサビリティ)、quality/COMPLETENESS_REPORT.md(最終ゲート)、および quality/VERSION_HISTORY.md(レビュー ログ)。フェーズ 7 は追加で quality/REVIEW_REQUIREMENTS.md(対話レビュー プロトコル)と quality/REFINE_REQUIREMENTS.md(絞り込みパス プロトコル)を反復改善のために生成できます。

2 つの重要な配信物は要件ファイルと機能テスト ファイルです。要件ファイル(quality/REQUIREMENTS.md)はコードレビュー プロトコルの検証と一貫性パスをフィードします — それはコードレビューが構造的異常以上をキャッチさせるものです。機能テスト ファイル(プロジェクトの言語とテスト フレームワーク規約のために命名)は自動セーフティネットです。Markdown プロトコルは人間と AI エージェント用のドキュメンテーションです。

完全なアーティファクト コントラクト

品質ゲート(quality_gate.py)これらのアーティファクトを検証します。ゲートがそれをチェックする場合、このスキルはその作成を指示する必要があります。これは標準リスト — ここにリストされていないアーティファクトはゲート強制されるべきではなく、ゲート チェックはここにリストされたアーティファクトにトレースバックするべきです。

アーティファクト	場所	必須?	作成フェーズ
正式文書マニフェスト(v1.5.3)	quality/formal_docs_manifest.json	はい	フェーズ 1(bin/reference_docs_ingest.py)
要件マニフェスト(v1.5.3)	quality/requirements_manifest.json	はい	フェーズ 2
ユースケース マニフェスト(v1.5.3)	quality/use_cases_manifest.json	はい	フェーズ 2
バグ マニフェスト(v1.5.3)	quality/bugs_manifest.json	バグが見つかった場合	フェーズ 3/4/5
引用意味チェック(v1.5.3)	quality/citation_semantic_check.json	はい	フェーズ 4(レイヤー 2 Council)
探索の調査結果	quality/EXPLORATION.md	はい	フェーズ 1
品質憲章	quality/QUALITY.md	はい	フェーズ 2
要件(UC 識別子)	quality/REQUIREMENTS.md	はい	フェーズ 2
振る舞いコントラクト	quality/CONTRACTS.md	はい	フェーズ 2
機能テスト	quality/test_functional.*	はい	フェーズ 2
回帰テスト	quality/test_regression.*	バグが見つかった場合	フェーズ 3
コードレビュー プロトコル	quality/RUN_CODE_REVIEW.md	はい	フェーズ 2
統合テスト プロトコル	quality/RUN_INTEGRATION_TESTS.md	はい	フェーズ 2
仕様監査 プロトコル	quality/RUN_SPEC_AUDIT.md	はい	フェーズ 2
TDD 検証プロトコル	quality/RUN_TDD_TESTS.md	はい	フェーズ 2
バグ トラッカー	quality/BUGS.md	はい	フェーズ 3
カバレッジ マトリックス	quality/COVERAGE_MATRIX.md	はい	フェーズ 2
完全性レポート	quality/COMPLETENESS_REPORT.md	はい	フェーズ 2(ベースライン)、フェーズ 5(最終判定)
進捗 トラッカー	quality/PROGRESS.md	はい	全体を通じて
AI ブートストラップ	AGENTS.md(ターゲット リポジトリ ルート)	はい	フェーズ 6 後にオーケストレータが生成 — フェーズ 2 配信物ではない
バグ記事	quality/writeups/BUG-NNN.md	バグが見つかった場合	フェーズ 5
回帰パッチ	quality/patches/BUG-NNN-regression-test.patch	バグが見つかった場合	フェーズ 3
パッチを修正	quality/patches/BUG-NNN-fix.patch	オプション	フェーズ 3
TDD トレーサビリティ	quality/TDD_TRACEABILITY.md	バグが赤フェーズ結果を持つ場合	フェーズ 5
TDD サイドカー	quality/results/tdd-results.json	バグが見つかった場合	フェーズ 5
TDD 赤フェーズ ログ	quality/results/BUG-NNN.red.log	バグが見つかった場合	フェーズ 5
TDD 緑フェーズ ログ	quality/results/BUG-NNN.green.log	修正パッチが存在する場合	フェーズ 5
統合サイドカー	quality/results/integration-results.json	統合テストが実行する場合	フェーズ 5
機械検証スクリプト	quality/mechanical/verify.sh	はい(ベンチマーク)	フェーズ 2
検証レシート	quality/results/mechanical-verify.log + .exit	はい(ベンチマーク)	フェーズ 5
分類プローブ	quality/spec_audits/triage_probes.sh	分類が実行する場合	フェーズ 4
コードレビュー レポート	quality/code_reviews/*.md	はい	フェーズ 3
仕様監査 レポート	quality/spec_audits/*auditor*.md + *triage*	はい	フェーズ 4
再チェック結果(JSON)	quality/results/recheck-results.json	再チェックが実行する場合	再チェック
再チェック サマリー(MD)	quality/results/recheck-summary.md	再チェックが実行する場合	再チェック
シード チェック	quality/SEED_CHECKS.md	フェーズ 0b が実行した場合	フェーズ 0b
メタデータ実行	quality/results/run-YYYY-MM-DDTHH-MM-SS.json	はい	フェーズ 1(作成)、全体を通じて(更新)

サイドカー JSON ライフサイクル: すべてのバグ記事を最終化する前にtdd-results.json を完了してください — サイドカーの writeup_path フィールドは存在するファイルを指す必要があります、プレースホルダーではなく。同様に、統合テストを実行し、integration-results.json を書く前に結果を収集してください。

サイドカー JSON 標準例

quality/results/tdd-results.json — ゲートはフィールド名を検証し、存在だけではなく:

{
  "schema_version": "1.1",
  "skill_version": "1.5.6",
  "date": "2026-04-12",
  "project": "repo-name",
  "bugs": [
    {
      "id": "BUG-001",
      "requirement": "REQ-003",
      "red_phase": "fail",
      "green_phase": "pass",
      "verdict": "TDD verified",
      "fix_patch_present": true,
      "writeup_path": "quality/writeups/BUG-001.md"
    }
  ],
  "summary": {
    "total": 3, "confirmed_open": 1, "red_failed": 0, "green_failed": 0, "verified": 2
  }
}

verdict は以下のいずれかである必要があります: "TDD verified"、"red failed"、"green failed"、"confirmed open"、"deferred"。date は ISO 8601(YYYY-MM-DD)である必要があります、プレースホルダーではなく、将来ではなく。

quality/results/integration-results.json:

{
  "schema_version": "1.1",
  "skill_version": "1.5.6",
  "date": "2026-04-12",
  "project": "repo-name",
  "recommendation": "SHIP",
  "groups": [{ "group": 1, "name": "Group 1", "use_cases": ["UC-01"], "result": "pass", "tests_passed": 3, "tests_failed": 0, "notes": "" }],
  "summary": { "total_groups": 12, "passed": 11, "failed": 1, "skipped": 0 },
  "uc_coverage": { "UC-01": "covered_pass", "UC-02": "not_mapped" }
}

recommendation は以下のいずれかである必要があります: "SHIP"、"FIX BEFORE MERGE"、"BLOCK"。uc_coverage は UC 識別子を REQUIREMENTS.md からカバレッジ状態にマップします。

メタデータ実行

あらゆるプレイブック実行は quality/results/run-YYYY-MM-DDTHH-MM-SS.json でタイムスタンプ メタデータファイルを作成します。これにより マルチモデル比較と実行履歴追跡が可能になります。

ライフサイクル: フェーズ 1 開始時にこのファイルを作成します。各フェーズ完了時に phases_completed、bug_count、end_time を更新します。最終更新は終端ゲート後に発生します。

{
  "schema_version": "1.0",
  "skill_version": "1.5.6",
  "project": "repo-name",
  "model": "claude-sonnet-4-6",
  "model_provider": "anthropic",
  "runner": "claude-code",
  "start_time": "2026-04-16T10:30:00Z",
  "end_time": "2026-04-16T11:45:00Z",
  "duration_minutes": 75,
  "phases_completed": ["Phase 0b", "Phase 1", "Phase 2", "Phase 3", "Phase 4", "Phase 5"],
  "iterations_completed": ["gap", "unfiltered", "parity", "adversarial"],
  "bug_count": 12,
  "bug_severity": { "HIGH": 2, "MEDIUM": 5, "LOW": 5 },
  "gate_result": "PASS",
  "gate_fail_count": 0,
  "gate_warn_count": 2,
  "notes": ""
}

必須フィールド: schema_version、skill_version、project、model、start_time。その他のフィールドはすべて実行の進行に応じて設定されます。model は正確なモデル文字列である必要があります(例:"claude-sonnet-4-6"、"gpt-4.1"、"claude-opus-4-6"）。runner は プレイブック を実行するために使用するツールを識別します(例:"claude-code"、"copilot-cli"、"cursor"、"cowork")。duration_minutes は end_time - start_time から計算されます。モデルまたはランナーを判定できない場合は、"unknown" を使用します。

使用方法

プレイブックは 1 回に 1 つのフェーズを実行するように設計されています。 各フェーズは独自のセッションで実行され、クリーンなコンテキスト ウィンドウで、ディスク上のファイルを生成します。次のフェーズはこれらを読みます。これはすべてのフェーズを一度に実行するよりもはるかに良い結果をもたらします — 各フェーズは他のフェーズと競争する代わりに深い分析のために完全なコンテキスト ウィンドウを取得します。

デフォルト動作: フェーズ 1 のみを実行します。 誰かが「run the quality playbook」または「execute the quality playbook」と言うとき、フェーズ 1(探索)を実行して停止します。フェーズ 1 完了後、ユーザーに何が起こったか、次に何を言うべきかを伝えてください。ユーザーは各フェーズを明示的に駆動します。

対話型プロトコル — ユーザーをガイドする方法

あらゆるフェーズと反復の後、停止して ガイダンスを出力します。 # ヘッダーを使用すればチャットで目立ちます。ガイダンスには含まれていなければなりません: 何が起こったか(1 行)、主要な出力、および正確なプロンプトです。以下の各フェーズセクション後に定義されたフェーズ終了メッセージを参照してください。

ユーザーが「keep going」「continue」「next phase」「next」または同様の何かを言う場合, 次のフェーズを順番に実行します。すべてのフェーズが完了したら、最初の反復戦略(ギャップ)を提