code-production-process

コード作成プロセス

概要

このスキルは、重要度の低くないコード実装タスクが完了と宣言される前に通過しなければならない、6 段階の品質ゲートパイプラインを実装します。このパイプラインがあるのは、リポジトリのオーナーがコード品質を目視で評価できないためです。そのため、品質保証はすべて、事後の人間によるレビューではなく、エージェントのパイプライン内にある自動ゲートによって確実に実施する必要があります。各段階では具体的な成果物を作成し、次の段階に進む前に定義済みのゲートを通過しなければなりません。標準パスでは、どの段階も省略できません。批評エージェントはコンテキストを完全に分離して動作し、実装担当者自身の説明によるアンカリングバイアスを防ぎます。意図的に敵対的なレビューを行うことで、協調的に通過するだけでは見落とされる問題を検出します。

トリガー条件

以下の条件のいずれかに該当する場合、このスキルが読み込まれます。

明示的なトリガー（ディスパッチ前）：

• PM が、ソースコードを 50 行超作成するタスクのためにエンジニアエージェントをディスパッチしようとしている
• PM が、ソースファイルを 1 つ超変更するタスクのためにエンジニアエージェントをディスパッチしようとしている
• タスクの説明に実装を示す動詞が含まれている："implement"、"write"、"build"、"create"、"refactor"、"add feature"、"fix bug in [module]"

ディスパッチ後の検出：

• エンジニアエージェントからの応答後、git diff --stat にソースファイル（ロジックを含む .py、.ts、.js、.go、.rs、.java、.rb、.sh）の変更が表示される（申告されたタスクの範囲を問いません）
• エンジニアエージェントが src/、lib/、app/、services/、api/ ディレクトリに新しいファイルを作成する

明示的な除外 — 以下の場合、このパイプラインを起動しないでください：

• ドキュメントの編集（コンテンツのみの .md、.rst、.txt、.html）
• コミットメッセージ、PR の説明、変更履歴
• 設定のみの変更（コードロジックを含まない *.yaml、*.toml、*.json、*.env）
• 範囲が 5 行未満であることを確認済みの 1 行修正
• コード変更を伴わない依存関係のバージョン更新

迷った場合： パイプラインを起動する方向に判断してください。誤検知のコストは、批評エージェントのディスパッチ 1 回です。誤検出がなければ、壊れたコードや安全でないコードをリリースすることになります。

6 段階のパイプライン

各段階には、担当エージェント、必須の出力成果物、ゲート条件が定義されています。次に進む前に、ゲート条件を満たす必要があります。ゲートに失敗した場合、要件の根本的な誤解が示されていない限り、ステージ 1 ではなく現在の段階に戻ります。

ステージ 1：調査

エージェント： research

ツール： mcp__vector-indexer-mcp__search_hybrid、mcp__knowledge__kb_search、mcp__knowledge__search_local

エージェントの作業内容：

• 再利用または拡張できる類似の実装がないか、既存のコードベースを検索します
• 実装で従う必要がある既存の抽象化、パターン、規約を特定します
• アーキテクチャ上の決定、データモデル、API コントラクトを扱う関連 KB エントリーを検索します
• 外部依存関係と、コードベース内で確立されているその使用パターンを列挙します

必須の出力成果物： 以下を含む仕様書（Markdown）：

• すでに存在するもの（ファイルパスと関数名を記載）
• 新たに構築する必要があるもの
• 実装が従う必要のある既存のパターン
• 新しいコードが満たす必要のある入力／出力コントラクト
• 既存の使用状況から判明しているエッジケース

ゲート： 仕様書が存在し、少なくとも 1 つの既存コードベース内の参照先が記載されていること。調査エージェントは実装コードを生成してはなりません。関連する既存コードがない場合は、出力に「既存の実装は見つからなかった」と明記します。これは有効な調査結果であり、失敗ではありません。

参照： プロンプトテンプレートと検索戦略については、references/stage-research.md を参照してください。

---

Stage 2: アーキテクト

エージェント: python-engineer（設計モード — 実装コードは作成しません）

読み込むスキル: software-patterns

エージェントの作業内容:

• Stage 1 の仕様書を読みます
• 公開インターフェースを設計します：クラスのシグネチャ、関数のシグネチャ、データモデル、型注釈
• 多態性が必要な箇所では、抽象基底クラス（ABC）または Protocol クラスを指定します
• 各公開メソッドの不変条件と事前条件を記録します
• 使用する外部依存関係とその使用方法を記載します

必須の成果物: 以下を含むインターフェース仕様書：

• 完全な型注釈を含む、すべての公開クラス／関数のシグネチャ
• ABC または Protocol の定義（メソッド本体は含めず、... または pass のみ）
• データモデルのスキーマ（Pydantic モデル、dataclass、TypedDict — ロジックなし）
• 発生するエラーの種類とその階層
• 実装で行わないことを述べた 1 段落

ゲート: インターフェース文書が存在すること。実装コードが一切ないこと（ロジックを含む関数本体、アルゴリズムの手順、I/O 呼び出しを含まない）。アーキテクトが契約を作成し、エンジニアがそれを実装します。

重要: 実装開始前に API の一貫性を確認するため、必要に応じて code-critic エージェントをここでディスパッチできます。これは Phase 2 の設計批評パスです。ディスパッチする場合、批評担当への入力はインターフェース文書のみです。コードはまだありません。

参照: インターフェース仕様書のテンプレートについては、references/stage-architect.md を参照してください。

---

Stage 3: 実装

エージェント: python-engineer

読み込むスキル: software-patterns、asyncio（非同期コードが必要な場合）、pytest

エージェントの作業内容:

• Stage 2 で定義されたインターフェースを厳密に実装します（スコープを勝手に広げないでください — インターフェースの修正が必要な場合は PM に報告します）
• pytest で単体テストを作成し、以下を網羅します：
  • 各公開関数の正常系
  • 文書化された各エラー条件
  • 関数ごとに少なくとも 1 つのエッジケース
• 新しいコードに対して mypy --strict を実行し、完了を宣言する前にすべての型エラーを解決します
• ローカルで pytest を実行し、返す前にすべてのテストが成功することを確認します

必須の成果物:

• Stage 2 のインターフェースを実装したソースファイル
• pytest テストを含むテストファイル
• エラーがゼロであることを示す mypy --strict の出力
• すべてのテストが成功したことを示す pytest の出力

ゲート: PM に戻る前に、エンジニアはエラー／失敗がゼロであることを示す mypy と pytest の出力を提示する必要があります。この出力を提示できない場合、エンジニアの作業は未完了です。Stage 3.5 に進まず、PM は再ディスパッチする必要があります。

参照: 実装標準とセルフチェックリストについては、references/stage-implement.md を参照してください。

---

Stage 3.5: テスト合格ゲート

エージェント: PM（エージェントのディスパッチではなく、PM が Stage 3 の出力を直接評価します）

PM の作業内容:

• Stage 3 の pytest 出力成果物を確認します
• pytest で失敗が 1 件でもある場合：ただちに Stage 3 のエンジニアに差し戻します。code-critic をディスパッチしてはいけません。パイプラインを先に進めようとしてはいけません。テスト失敗は実装が未完了であることを意味します。
• pytest がすべて成功した場合（失敗ゼロ）：Stage 4 に進みます

このゲートは交渉の余地がありません。 テスト失敗があるコードに対して code-critic をディスパッチすると、壊れた状態に起因する可能性のある指摘にトークンを浪費します。批評担当がレビューするのは動作するコードであり、修正中のコードではありません。

エンジニアへの差し戻しメッセージ（テンプレート）：

Tests failed. Return to Stage 3. Fix the following failures before requesting critic review:

[paste pytest output here]

When tests pass green, provide updated implementation + passing pytest output.

参照: テスト品質要件とカバレッジ基準については、references/stage-tests.md を参照してください。

---

ステージ 4：批評レビュー

エージェント： code-critic

読み込まれるスキル： code-review-standards、code-production-process

コンテキストの分離は必須です。 要件の詳細については、以下の「批評者の分離ルール」セクションを参照してください。批評者のコンテキストを分離できない場合、プロセス違反となります。

批評エージェントの役割：

• Stage 2 のインターフェース仕様に照らして実装をレビューします
• code-review-standards の重大度タグ付きチェックリスト（CRITICAL/HIGH/MEDIUM/LOW）を適用します
• 各指摘について、ファイル名と行番号を引用した構造化された指摘表を作成します
• 最上位の判定として、APPROVE、WARN、BLOCK のいずれかを返します

必須の出力成果物：

• 応答の冒頭に判定（APPROVE / WARN / BLOCK）を記載します
• 指摘表（APPROVE の場合は空でも可）。列は Severity | File | Line | Issue | Fix とします
• 判定の理由を説明する要約段落

ゲート： 批評者が判定を返します。PM は以下の判定プロトコルに従って対応します。

参照： ディスパッチ用テンプレートと分離チェックリストについては、references/stage-critic.md を参照してください。

---

ステージ 5：セキュリティ

エージェント： security

対象範囲： OWASP Top 10、シークレット／認証情報の露出、インジェクションの脆弱性（SQL、シェル、テンプレート）、認証および認可のバイパス、任意コード実行の経路、安全でないデシリアライゼーション、暗号技術の弱点。

エージェントの役割：

• 上記の対象範囲について、Stage 3 の実装にセキュリティ脆弱性がないかレビューします
• コードスタイルや構造上の問題については再レビューしません（これは批評者の担当範囲です）
• 重大度（CRITICAL / HIGH / MEDIUM / LOW）と修正方法を含む指摘リストを作成します

ゲート： CRITICAL または HIGH の重大度に該当するセキュリティ指摘がゼロであること。MEDIUM の指摘は文書化して記録します。LOW の指摘は記載します。CRITICAL または HIGH のセキュリティ指摘がある場合、PM は処理を中断してユーザーに報告します。批評者が BLOCK を返した場合と同じプロトコルです。

参照： セキュリティレビューの対象範囲と OWASP との対応については、references/stage-security.md を参照してください。

---

批評者の分離ルール

批評エージェントの判定がどれだけ独立しているかは、受け取るコンテキストによって決まります。アンカリングバイアス、つまりレビュー担当者がコードの動作に関する作者の説明を無意識に受け入れてしまうことは、マルチエージェントシステムにおけるコードレビューの主な失敗要因です。

PM は、以下のみを含むように批評者へのディスパッチプロンプトを作成しなければなりません。

1. Stage 1 の仕様書（依頼内容）
2. Stage 2 のインターフェース仕様（設計内容）
3. Stage 3 の実装ファイル（構築内容）
4. Stage 3 の pytest 出力（テスト結果）

PM は、以下を批評者へのディスパッチプロンプトに含めてはなりません。

• エンジニアのコミットメッセージ
• 実装の回答に含まれる、エンジニアが述べた根拠や設計メモ
• エンジニアが行ったことについて PM が書いた要約
• 「エンジニアの説明によると……」や「実装担当者によると……」といった表現

エンジニアの実装回答に、コードと混在した説明文が含まれている場合、PM は批評者へのディスパッチに向けてコードとテスト出力のみを抽出し、実装担当者の説明を取り除かなければなりません。

このルールが設けられているのは、エンジニアが「別の方法ではパフォーマンスの問題が生じるため、この方法を選びました」と書くと、批評者がパフォーマンス上の懸念を指摘するのを無意識に妨げるおそれがあるためです。批評者は、予断を持たずにコードを確認しなければなりません。

参照： プロンプトの作成テンプレートについては、references/critic-isolation.md を参照してください。

判定プロトコル

PM の動作は、クリティックによるトップレベルの判定によって完全に決まります。PM は判断を用いて判定プロトコルを覆したり、緩和したりしてはなりません。

APPROVE（CRITICAL の指摘が 0 件、HIGH の指摘が 0 件）：

• Stage 5（セキュリティ）に進みます
• エンジニアによる追加対応は不要です
• 指摘テーブル（空でない場合は、MEDIUM／LOW のみを含む）は、「今後の参考用のメモ」としてドキュメントエージェントへの引き継ぎに渡します

WARN（CRITICAL の指摘が 0 件、HIGH の指摘が 1 件以上）：

• Stage 5（セキュリティ）に進みます。パイプラインを停止してはなりません
• PM はクリティックの指摘テーブル全体を、ドキュメントエージェントに送る引き継ぎメッセージに追加しなければなりません
• PM は追跡できるよう、メモ（KB エントリまたは TODO コメント）に指摘を記録しなければなりません
• PM は HIGH の指摘を黙って破棄してはなりません。必ずどこかで明示しなければなりません

BLOCK（CRITICAL の指摘が 1 件以上）：

• PM は直ちにパイプラインを停止します
• PM はクリティックの指摘テーブルをそのままユーザーに提示します
• PM は次のように伝えます。「クリティックにより、この実装はブロックされています。パイプラインを続行する前に、以下の CRITICAL な問題を解決する必要があります。どのように進めるかご指示ください。」
• PM はユーザーからの明示的な指示（修正して再試行、根拠を示してオーバーライド、または中止）を待ちます
• PM はユーザーの入力なしに、エンジニアへ自動で再委任してはなりません
• ユーザーが修正して再試行するよう指示した場合：クリティックの指摘テーブルを追加の入力として、Stage 3（実装）に戻ります。Stage 2 のアーキテクトインターフェースは引き続き正式なものとして扱います。ただし、CRITICAL の指摘によってインターフェース設計に根本的な欠陥が明らかになった場合は、PM は Stage 2 に戻ります。

スキップルール（ホットフィックスパス）

以下のルールでは、ステージをスキップできる条件を定めています。パスにかかわらず、Stage 3 から Stage 5 は決してスキップできません。

標準パス： 全 6 ステージ。すべての新機能、100 行を超えるリファクタリング、認証／認可コードへのあらゆる変更、データモデルへのあらゆる変更で必須です。

ホットフィックスパス： 以下のすべてに該当する場合、Stage 1 と 2 をスキップできます：

• 修正対象のバグが本番環境で確認されている（仮説上の障害やローカル環境のみの障害ではない）
• 修正範囲が、最大 2 ファイルにわたる新規コードの純増 20 行以下であると検証されている
• 修正が認証、認可、暗号処理、またはデータのシリアライズに触れない
• PM がセッションログに「ホットフィックスパス」と明記している

ホットフィックスパスであっても、Stage 3（実装 + テスト）、Stage 3.5（テスト必須ゲート）、Stage 4（クリティック）、Stage 5（セキュリティ）は必須であり、スキップできません。

ドキュメントのみのパス： すべての変更がドキュメント、設定値、または依存関係のバージョン更新のみであり、ロジックの変更がないと確認された場合は、全 6 ステージをスキップします。PM は git diff --stat でソースファイルが変更されていないことを確認してください。

参照： スキップルールの判断ツリーと例については、references/skip-rules.md を参照してください。

失敗時のループプロトコル

ステージゲートが失敗した場合、指摘は構造化された形式で担当エージェントに戻されます。PM は指摘を解釈したり、修正したりせず、そのまま渡します。

BLOCK 後にエンジニアへ返す形式：

PIPELINE GATE FAILURE — Return to Stage [N]

Critic verdict: BLOCK
Findings (CRITICAL):

| Severity | File | Line | Issue | Required Fix |
|----------|------|------|-------|--------------|
[paste finding table verbatim]

Instructions:
- Fix ALL CRITICAL items above
- Re-run pytest (must pass green)
- Re-run mypy --strict (must pass)
- Return updated implementation with fresh test output

Do NOT return until all CRITICAL findings are resolved and tests pass.

WARN 後にエンジニアへ返す形式（ユーザーが修正を求めた場合）：

PIPELINE GATE — WARN findings for review

Critic verdict: WARN
Pipeline proceeded, but the following HIGH findings were logged:

| Severity | File | Line | Issue | Recommended Fix |
|----------|------|------|-------|-----------------|
[paste finding table]

These were noted in the documentation handoff. If you choose to address them in this session,
re-run tests and confirm they still pass. No re-critic required for WARN resolutions.

トークン効率に関する注記

Stage 1 と 2 は、意図的に軽量に設計されています。リサーチエージェントとアーキテクトエージェントは、大規模なコードベースではなく、主にテキスト文書（仕様書、KB エントリ、インターフェースファイル）を扱います。トークン消費の大半は Stage 3～5 で発生します。この段階では、実装、テスト、クリティックレビュー、セキュリティレビューのすべてで、コードベース全体のコンテキストを扱うためです。リサーチエージェントとアーキテクトエージェントを先に実行すると、Stage 3（実装）に明確な仕様が渡され、反復的な確認が不要になります。その結果、構造化されていない実装ワークフローにおけるトークン浪費の主な原因である、エンジニアへの再ディスパッチ回数を減らせます。