team-polish

チームによる磨き込み

引数が指定されていない場合は、使用方法の案内を出力し、エージェントを起動せずに終了します。

使用方法：/team-polish [磨き込む機能または領域] [--review full|lean|solo] — 磨き込む機能または領域を指定します（例：combat、main menu、inventory system、level-1）。ここでは AskUserQuestion を使用せず、案内を直接出力してください。

このスキルが引数付きで呼び出された場合は、構造化されたパイプラインを通じて磨き込みチームを統括します。

意思決定ポイント： 各フェーズの移行時に AskUserQuestion を使用して、サブエージェントの提案を選択肢としてユーザーに提示します。エージェントの分析全文を会話に記述し、その後、簡潔なラベルで決定を記録します。 collaborative モードでは、次のフェーズに進む前にユーザーの承認が必要です。 guided モードでは、フェーズが BLOCKED でない限り、パイプラインが自動的に進行します。 autonomous モードでは、各フェーズの結果を log_decision で記録しながら、最初から最後まで実行します。 automation_always_ask カテゴリ（is_always_ask_category ヘルパー）の意思決定では、モードにかかわらず常に確認を求めます。.claude/docs/automation-modes.md を参照してください。

フェーズ 0：設定の解決

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,team.size,workflow

上記で解決済みです。そのまま使用してください。--review は review_mode を上書きします。ブロックがない場合は → .claude/docs/config-resolution.md のデフォルトを使用します。

review_mode はディレクターゲートの深度を設定しますが、このパイプラインにはディレクターゲートはありません。 以下のフェーズでは、どの review_mode でも CD-、TD-、PR-、AD-PHASE-GATE も起動されません。 フェーズゲートはパイプライン独自の意思決定ポイント（以下の team.size の項で定義）であり、そこで作業するエージェントはチームメンバーであって、ディレクターゲートではありません。

automation は上記の意思決定ポイントに関する注記に影響します。各モードがパイプラインの動作をどのように変えるかについては、上記の意思決定ポイントに関する注記と .claude/docs/automation-modes.md を参照してください。

team.size：有効なエージェントを指定します（review_mode のゲート深度やワークフローのドキュメントとは独立しています）。

• individual（デフォルト）：performance-analyst と technical-artist が有効です。他のエージェントにはこの 2 つを通じて相談し、個別には起動しません。プログラマーは有効ではないため、この実行では最適化リストのプログラマー向け項目は実装されません。レポートでは、そのリストを /dev-story に引き継ぐ項目として示します（フェーズ 2）。
• small：sound-designer、qa-tester、engine-programmer が加わります。また、フェーズ 1 のトレースで原因がコンテンツ制作ツールにあると判明した場合は tools-programmer も加わります（ドキュメントに記載されたフルパイプライン）。
• studio：engine-programmer を含む small の構成に加え、敵対的レビューを行います。フェーズ 5 の qa-tester には「この状態が維持されることを確認するのではなく、どうすれば壊れるかを見つけるのがあなたの仕事です」と指示し、レポートにはレビューを実施したことを記載します。このパイプラインには対象範囲を広げるためのエンジンスペシャリストがいないため、エンジンレベルの作業は engine-programmer が担当します。 individual で必要となるコア以外のエージェントは、情報注記を添えて最も近い有効なコアエージェントを通じて対応します。「フェーズゲート」とは、このパイプライン自体が列挙する AskUserQuestion の意思決定ポイントで終了するフェーズを指します。つまり、上記の意思決定ポイントでの遷移、または以下のパイプラインに記載された Gate ステップです。automation モードにかかわらず該当します。 guided と autonomous はゲートの通過方法を変えます（自動で次に進むか、log_decision で記録するか）が、ゲートに該当するかどうかは変わりません。そのため、以下の例外条件（3）はどのモードでも当てはまります。「フェーズゲートのみ」に制限されたエージェントは、それらのポイントでのみ起動し、それ以外では起動しません。この有効エージェントの範囲指定は以下のパイプライン全体に適用されます。有効セット外のエージェントを指定するフェーズでは、起動するのではなく、最も近いコアエージェントを通じて対応します。

フェーズ 1 の前に有効セットを告知してください。縮小を黙って済ませてはいけません。 何も起動する前に、この実行で実際に起動するエージェントと、以下のパイプラインでは名前が挙がっているものの、解決済みの team.size では起動しないエージェントを、1 行で示します。例：

有効セット（team.size: <解決済みの値>）：上記のそのサイズに記載されたエージェント。 今回起動しないエージェント：このパイプラインに記載されたその他すべて — 最も近い有効なコアエージェントを通じて相談します。範囲を広げるには team.size（または modes.rigor）を引き上げてください。

直上の team.size のリストと、このファイルのパイプラインに記載されたエージェントをもとに記入してください。例から判断してはいけません。どちらのセットもオーケストレーターごとに異なります。

以下のパイプラインは複数エージェントへの分担を想定した記述ですが、提供時のデフォルトでは 1〜2 人のエージェントしか動きません。team-release は 10 人を挙げながら 1 人を実行し、team-narrative は 5 つのフェーズで 6 人を挙げながら writer だけを実行します。この縮小は正しい動作です。 team.size は厳密さを優先した設定であり、狭いデフォルト値はトークン消費を抑えるためのものです。 それを明示しないと、読者は意図どおり縮小された実行と、壊れたパイプラインを区別できません。また、「最も近いコアエージェントを通じて情報注記を添えて対応する」というエージェントごとのルールは、ルーティング時に適用されるだけで、実行全体の構成を示すことはありません。

これは、このファイル内の他の箇所にある、スキップしたチェックの報告と同じルールです。適用されていても一度も表に出されない制約は、出力を読む人にとって、適用されなかった制約と見分けがつきません。

チーム構成

• performance-analyst — プロファイリング、メモリ分析、フレーム予算、最適化リストを担当します。ゲームコードは一切書きません。
• engine-programmer — 最適化リストにあるエンジンレベルの項目を実装します。レンダリングパイプライン、メモリ、リソースの読み込み、ホットパスが対象です（performance-analyst が低レベルの根本原因を特定した場合に呼び出します）。
• technical-artist — VFX の仕上げ、シェーダーの最適化、ビジュアル品質を担当します。
• sound-designer — オーディオの仕上げ、ミキシング、環境音レイヤー、フィードバック音を担当します。
• tools-programmer — コンテンツパイプラインツールの検証、エディターツールの安定性、自動化の修正を担当します（Phase 2 で、Phase 1 のトレースからコンテンツ制作ツールが原因と判明した場合）。
• qa-tester — エッジケーステスト、回帰テスト、長時間稼働テストを担当します。

委任方法

Agent ツールを使って、各チームメンバーをサブエージェントとして起動します。

• subagent_type: performance-analyst — プロファイリング、メモリ分析、最適化リスト
• subagent_type: engine-programmer — 最適化リストにあるエンジンレベルの修正：レンダリング、メモリ、リソースの読み込み
• subagent_type: technical-artist — VFX の仕上げ、シェーダーの最適化、ビジュアル品質
• subagent_type: sound-designer — オーディオの仕上げ、ミキシング、環境音レイヤー
• subagent_type: tools-programmer — 最適化リストにあるコンテンツパイプラインとエディターツールの修正
• subagent_type: qa-tester — エッジケーステスト、回帰テスト、長時間稼働テスト

各エージェントには簡潔な指示を出し、コンテキストを丸ごと渡さないでください。 共通の入力は一度だけ読み、要点をまとめたブリーフをインラインで渡します。各エージェントが実際に必要とする行だけを渡し、すでに読んだドキュメントのファイルパスは渡さないでください（パスを渡されたエージェントはファイル全体を読み直します）。まだ読んでいないドキュメントで、そのエージェントだけが必要とするものに限り、パスを渡します。

すべてのエージェントへのプロンプトは、必ず次の成果物提出条件で締めくくってください。 「出力全体を [path] に書き込んでください。この名前付きパスは、以下の限定例外に基づく書き込み許可先です。別途承認を求めずに書き込んでください。返答は、（1）書き込んだパス、（2）決定事項の要約（最大5項目）、（3）BLOCKED/CONCERNS 項目（各1行）のみとしてください。読んだドキュメントの内容を繰り返さないでください。」この条件がないと、エージェントは読んだ内容をすべてこのセッションに返してしまいます。実装ファイルは例外です。 エージェントがコードやアセットを書き込む場合、まず作成・変更するファイルを返答し、あなたが一度その一覧を求め、ユーザーが承認してから、成果物提出条件にそのファイル名を記載します（ファイル書き込みプロトコル）。書き込みを許可するのはその回答であり、限定例外ではありません。

[path] は実際のパスに置き換えてください。このスキルの保存先は production/polish/ です。 エージェントごとに名前を付け、各エージェントにつき1ファイルとします。

エージェント	書き込み先
performance-analyst	production/polish/[area]-report-[date].md
technical-artist	production/polish/[area]-render-notes-[date].md
engine-programmer	production/polish/[area]-engine-fixes-[date].md
tools-programmer	production/polish/[area]-tool-fixes-[date].md
sound-designer	production/polish/[area]-audio-notes-[date].md
qa-tester	production/polish/[area]-verification-[date].md

docs/ ではなく production/ にする理由。 これらは1回の実行に関する、日付入りの測定記録です。production/qa/smoke-[date].md と同様の形式であり、docs/architecture/ にあるような長期保存用の仕様書ではありません。他の時点ごとのプロセス成果物と一緒に保管することで、後から比較できるようになります。

上記の [path] 契約には前提があります。パスはあなたが指定したものなので、具体的な保存先をここに記載する必要があります。そうしないと、実行のたびに保存先を新たに決めることになります。保存先が利用側によって固定されている /team-qa や /team-narrative とは異なり、この場所はリポジトリ内に参照する側がなく、意図的に選ばれています。 現時点では production/polish/ を読み込むものはありません。報告時にその旨を伝え、レポートは後続のゲートへの入力ではなく、記録であることをユーザーに知らせてください。 これがコラボレーションプロトコルに違反しない理由。 CLAUDE.md では、Write/Edit の前にエージェントが「[filepath] に書き込んでもよろしいですか？」と尋ねることが求められています。ここで起動されたサブエージェントは、尋ねずに書き込みます。これは見落としではなく、意図的かつ限定的な例外です。consistency-check が active.md に追記する場合と同じ判断が、すでに行われています。この例外が適用されるのは、次の3つすべてを満たす場合に限られます。（1）パスがプロンプトであなたが指定したものであること。つまり、フェーズを承認した時点で、ユーザーは保存先も承認しています。（2）production/、docs/、tests/ のいずれかの下に作成する新しい成果物であり、既存のソースや設定を編集しないこと。（3）成果物を生成するフェーズからパイプラインを先に進める前に、AskUserQuestion による確認が行われること。この3つ以外の場合、エージェントは尋ねなければなりません。サブエージェントごとに尋ねることで、これを「修正」しないでください。フェーズごとにエージェント1つにつきプロンプトが必要では、オーケストレーターが使い物にならなくなるため、この例外が設けられています。

パイプラインで可能な場合は、独立したエージェントを並行して起動してください（例：フェーズ3と4は同時に実行できます）。

パイプライン

フェーズ1：評価

performance-analyst に委任します：

• /perf-profile を使用して対象の機能／領域をプロファイリングする
• パフォーマンスのボトルネックとフレーム予算の超過を特定する
• メモリ使用量を測定し、リークを確認する
• 目標ハードウェア仕様に照らしてベンチマークを実施する
• 出力：優先順位を付けた最適化リストを含むパフォーマンスレポート。各項目について、変更内容、予算に対して期待される改善量、担当者（レンダリング側の変更は technical-artist、エンジンシステムとホットパスは engine-programmer、コンテンツ作成ツールは tools-programmer、それ以外はそのシステムを担当する programmer）を記載します

フェーズ2：最適化

performance-analyst はゲームコードを書かないため（同エージェントのファイルにある「recommend and assign」を参照）、 フェーズ2では、active set 内の担当者を通じてフェーズ1のリストを実装します：

• engine-programmer — フェーズ1でエンジンレベルの根本原因（レンダリングパイプライン、リソース読み込み、メモリアロケーター、コアループ内のホットパス）が特定された場合にのみ起動します：該当項目を実装し、アロケーションの負荷を軽減し、ゲームプレイの挙動が変わっていないことを確認します。出力：変更前後のメトリクスとプロファイラーによる検証を含む、エンジンレベルの修正
• tools-programmer — フェーズ1で原因がコンテンツ作成ツールにあると特定された場合にのみ起動します：ツールを修正します。出力：変更前後のメトリクスを含むツールの修正
• technical-artist — レンダリング側の項目（ドローコール、オーバードロー、パーティクル、シェーダー、LOD）は、フェーズ3の指示に含めます

フェーズ2～4で実装を行うエージェントは、まず作成または変更するファイルを提示します。その後、ファイルを編集する前に、フェーズ2～4全体のファイルについて一度だけ確認を求めます（ファイル書き込みプロトコル）。

担当者が active set に含まれていない項目は、この実行では実装しません。 team.size: individual の場合、programmer が誰も active でないため、programmer が担当する項目はすべて該当します。どのサイズでも、このパイプラインで指定されていない programmer が担当する項目（例：ゲームプレイスクリプトのホットスポットを担当する gameplay-programmer）も該当します。レポートでは、そうした項目を担当者とともに 「/dev-story に引き継ぐ最適化リスト：production/polish/[area]-report-[date].md」の下に記載します。 対象とするメトリクスが予算を超過したままの場合、その問題はフェーズ6で既知の問題として残ります。

フェーズ3：ビジュアルの仕上げ（フェーズ2と並行）

technical-artist に委任します：

• VFX の品質とアートバイブルとの一貫性を確認する
• パーティクルシステムとシェーダーエフェクトを最適化する
• 適切な場合は、画面揺れ、カメラエフェクト、ビジュアルの演出を追加する
• 低い設定でもエフェクトが適切に劣化することを確認する
• 出力：仕上げ済みのビジュアルエフェクト

フェーズ4：オーディオの仕上げ（フェーズ2と並行）

sound-designer に委任します：

• オーディオイベントに不足がないか確認する（サウンドフィードバックのないアクションはありませんか？）
• オーディオミックスの音量レベルを確認する。ミックス内で大きすぎたり小さすぎたりする音がないようにします
• 雰囲気を作る環境音レイヤーを追加する
• 空間上の位置に応じてオーディオが正しく再生されることを確認する
• 出力：オーディオの仕上げリストとミキシングのメモ

Phase 5: 強化

qa-tester に委任します：

• すべてのエッジケースをテストします：境界条件、すばやい入力、通常とは異なる順序
• 長時間テスト：機能を長時間実行し、劣化がないか確認します
• ストレステスト：エンティティ数が最大の場合、最悪のシナリオ
• リグレッションテスト：調整による変更で既存の機能が壊れていないことを確認します — Phase 2～4の各変更を名前で指定し、エンジンレベルの修正も含めます
• 可能であれば、最小スペックのハードウェアでテストします
• 出力：テスト結果と、残っている問題があればその内容

Phase 6: 承認

• すべてのチームメンバーから結果を収集します
• パフォーマンス指標を予算と比較します
• 報告：リリース準備完了 / 評価未実施 / 追加作業が必要
• 残っている問題をすべて、深刻度（S1～S4）、該当する場合は測定された差分（例：「6 ms の予算に対して 9 ms — 3 ms 超過」）、および推奨事項とともに列挙します。リグレッションの場合は、壊れた動作と、その原因となった調整変更も記載します

評価未実施は、リリース準備完了より上位、追加作業が必要より下位です。 既知の問題 — 予算超過の指標、未解決のリグレッション — がある場合は、ほかに未確認の項目があっても、結果は「追加作業が必要」です。それ以外で、スコープの一部でも確認できなかった場合、結果は「評価未実施」となり、「リリース準備完了」にはなりません。レポートには、それぞれの未確認項目を記載します：

• 確定した予算がない指標。performance.target_framerate、performance.frame_budget_ms、performance.draw_call_limit、performance.memory_ceiling_mb にはデフォルト値がなく、/perf-profile は未設定の値を「評価未実施」として報告します — 比較が行われていないため、予算を達成したとは言えません。
• 実行されなかったフェーズ：BLOCKED、スキップ、または担当エージェントがアクティブセットの対象外。team.size: individual の場合、sound-designer のオーディオ調整と qa-tester の強化は、アクティブなエージェントを通じて参照されるだけで、実行されません。また、Phase 2 のプログラマーの項目は実装されず、/dev-story に引き渡されます。

エラー復旧プロトコル

まず、成果物を確認します。 戻り値の契約でパスが指定されている場合、フェーズが完了したと判断する前に、そのパスが存在することを確認してください — 指定された成果物がディスク上に存在しなければ、応答がどれほど流暢でも、そのフェーズは失敗です。 エージェントがフェーズを丸ごと費やしても何も書き込まず、もっともらしい導入文だけを返すことがあります。これは BLOCKED でもエラーでも「完了できない」でもないため、以下のトリガーは作動しません。未達の契約を明示して再開してください。通常、コンテキストはまだ残っています。

起動したエージェントが BLOCKED を返す、エラーになる、または完了できない場合：ただちに明らかにし、そのエージェントが妨げている依存関係より先に進まず、必ず部分レポートを作成します。 スキップされたエージェントのセクションは、未確認項目として明記したままにしてください — 独自の内容で埋めてはいけません。手順の全文は .claude/docs/error-recovery-protocol.md を参照してください。

よくあるブロッカー：

• 入力ファイルが見つからない（ストーリーが見つからない、GDD がない）→ 作成するスキルに引き継ぎます
• ADR のステータスが Proposed → 実装せず、決定後に /architecture-decision accept ADR-NNNN で承認します
• スコープが大きすぎる → /create-stories で 2 つのストーリーに分割します
• ADR とストーリーの指示が矛盾する → 矛盾を明らかにし、推測で判断しません

ファイル書き込みプロトコル

すべてのファイル書き込み（パフォーマンスレポート、テスト結果、証拠文書）は、Agent 経由で起動したサブエージェントに委任します。これらの書き込みは、「これがコラボレーションプロトコルに違反しない理由」で前述した限定的な例外に従います — パスは事前に指定したものであり、成果物は production/、docs/、または tests/ 配下に新規作成され、フェーズは AskUserQuestion によってゲートされています。サブエージェントは、この範囲内では書き込みごとに確認を求めません。範囲外では確認が必要です。Phase 2～4 の最適化と調整の変更では、既存のコード、シェーダー、オーディオ、またはアセットを編集するため、この範囲外となります。各実装エージェントが作成または変更するファイルを返した後、Phase 2～4 の全ファイルを対象に一度だけ確認します（「[agents] がこれらの [N] 個のファイルを変更してもよいですか？」）。承認後にのみ、各エージェントが編集します — フェーズごとではなく、対象全体について一度確認します。このオーケストレーターは、ファイルを直接書き込みません。

出力

パフォーマンスの改善前後の指標、ビジュアルの仕上げに関する変更、オーディオの仕上げに関する変更、テスト結果、/dev-story に渡した最適化リストの有無、リリース準備状況の評価をまとめたレポートです。

次のステップ

• READY FOR RELEASE の場合：リリース前の最終検証として /release-checklist を実行します。
• NEEDS MORE WORK の場合：残りの課題を /sprint-plan update で計画します（workflow: minimal ではスプリントがないため、ブリーフのビルド順序に追加します）。修正後、/team-polish を再実行します。
• NOT ASSESSED の場合：不足していたものを補います。project.yaml（/settings）で未設定の performance.* 予算をコミットするか、実行されなかったフェーズを実行します（team.size を増やします）。その後、/team-polish を再実行します。この領域をリリース準備完了として扱わないでください。
• レポートから /dev-story に最適化リストが渡された場合：そこで該当項目を実装し、改善効果を測定するために /team-polish を再実行します。
• リリースへ引き継ぐ前に、正式なフェーズゲート判定として /gate-check を実行します。