自己レビューフローを追加する

[mapserver2007]

④′ 自己レビュー
├─ 実装/テスト指摘 → ③ and/or ④ → ④′ を繰り返す
└─ タスクレポート（契約・設計）に関わる指摘 → ワークフロー停止 + 問題報告
（再開は PO/人間が ② 改訂を明示指示したときだけ）

[mapserver2007]

PR前自己レビュー導入仕様書（検討版）

1. 文書の位置づけ

本書は、実装・テスト完了後からPR作成前に実施する「PR前自己レビュー（Pre-PR Self Review）」について、これまでの議論を整理した検討仕様書である。

本書は .cursor/plans/ 配下に置く一時成果物であり、現時点では本リポジトリの正本仕様書ではない。実際にワークフローへ導入する場合は、関連する設計判断・ADR・ワークフロー文書への反映要否を別途判定する。

2. 背景

本リポジトリ（agentic-workflow-foundation-kit）は、以下を前提とする仕様駆動設計（SDD）・Agentic Workflowプロジェクトである。

• AGENTS.md が運用・境界・参照順序の基準を定義する
• 自己完結 SoT（manifest.yaml + templates）から基盤ファイル群を決定論的に生成・監査・メンテナンスする
• docs/spec.md / docs/spec/*.md が Domain 層業務仕様の Source of Truth（SoT）である（seed 生成物は PO が充実させる）
• docs/architecture.md / docs/coding-standards.md / docs/tech-stack.md が実装・設計・技術制約を定義する
• Meta / Domain の semantic 2層モデル（大文字 Meta / 小文字 Domain）がドキュメント命名の基準である
• docs/agent-tasks/reports/{ticket}-*.md が進行中タスクのSoTである
• bin/quality-gate / bin/foundation-gate と workflow-gate.sh が機械的な品質・フェーズゲートを担う（本 kit の profile は foundation）

現在の標準ワークフローは、実装・テスト後に Step⑤ で PR を作成し、PR作成後に agent-code-review で外部レビューコメントを検証する構成である。

一方、PRを作成する前に、実装者自身の視点とは独立したレビューを行い、仕様漏れ・設計逸脱・kit 固有制約違反を早期に検出する余地がある。

3. 目的

PR作成前に、実装とテストの成果物を以下の観点から独立検証する。

1. 実装が要求・仕様を満たしているか
2. 既存のコーディング規約・アーキテクチャに従っているか
3. agentic-workflow-foundation-kit 固有のドメイン制約に違反していないか
4. テストが実際の回帰を検出できる内容になっているか
5. PRレビューに進む前に、根拠付きの指摘・未解決事項を整理できているか

4. 非目的

本機能は以下を目的としない。

• PRの作成
• GitHubへのレビュー投稿・コメント返信
• 自動的なコード修正
• commit / push
• 既存のPR後レビュー（Step⑤ の agent-code-review）の置き換え
• bin/quality-gate / bin/foundation-gate の代替
• 仕様が存在しない場合の要求の推測

5. 用語

5.1 PR前自己レビュー

実装・テスト後、PR作成前に現在のworking treeを対象として実施するread-onlyレビュー。

5.2 ReviewContext

レビュー実行に必要な差分基準、SoT、規約、ドメイン制約、出力条件をまとめたレビュー入力情報。

5.3 Standards review

実装がリポジトリ固有の規約、アーキテクチャ、既存パターンに従っているかを確認するレビュー。

5.4 Spec review

実装がタスクレポート・仕様書・受入条件に記載された要求を満たしているかを確認するレビュー。

5.5 Domain review

manifest→生成物チェーン、Boundaries、品質ゲート契約、Session Protocol、Meta/Domain 命名など、本 kit 固有の業務・運用制約を確認するレビュー。

6. 推奨する公開スキル

6.1 採用候補

第一候補は Matt Pocock の code-review skill とする。

• GitHub: https://github.com/mattpocock/skills/tree/main/skills/engineering/code-review
• skills.sh: https://skills.sh/mattpocock/skills/code-review
• インストール例:

npx skills add https://github.com/mattpocock/skills --skill code-review

6.2 採用理由

このskillは、レビューを以下の2軸に分離する。

• Standards: リポジトリの規約に従っているか
• Spec: 元のIssue・PRD・仕様を満たしているか

また、両軸を独立したsubagentで並列レビューし、結果を分離して集約する。

本リポジトリの「仕様と実装規約を分離して確認する」「main agentの自己判断だけに依存しない」という要件と親和性が高い。

6.3 スキル実行モデル

mattpocock/skills@code-review は、独立した実行バイナリやAPIではなく、SKILL.md に記載された手順である。

推奨される実行構造は以下とする。

workflow-orchestrator（main agent）
    └─ code-review skillをロードして実行
         ├─ Standards subagent
         └─ Spec subagent

workflow-orchestratorから単一のreview workerを起動し、そのworkerにさらにcode-reviewを起動させるnested構造は、subagentの起動可否とコンテキスト継承が不安定になるため採用しない。

Domain review は本 kit 固有制約のため、Standards / Spec と同列の第三軸として ReviewContext に明示し、集約時に独立セクションとして扱う（実装形態は §15 未決事項を参照）。

7. ワークフロー上の配置

7.1 推奨配置

現在のStep⑤は PR作成と PR作成後のレビューコメント検証（agent-code-review）を担っているため、PR前自己レビューはStep⑤に直接混在させない。

Step④と既存Step⑤の間に、論理的な Step 4.5: Pre-PR Self Review を設ける。

Step④ テスト・コードゲート
    ↓
Step 4.5 PR前自己レビュー
    ├─ Standards review
    ├─ Spec review
    └─ Domain review
    ↓
ユーザーによるレビュー結果確認
    ↓
Step⑤ PR作成 + PRレビュー検証（agent-code-review）
    ↓
Step⑥ 完了報告

7.2 Step 4.5の入口条件

• Step③の実装が完了している
• Step④のテストが完了している
• workflow-gate.sh step4 がexit 0である（本 kit では profile=foundation のため bin/foundation-gate self を含む）
• base_commit_sha が確定している
• 対象タスクレポートが特定できる
• レビュー対象の仕様・規約の参照先が解決できる

7.3 Step 4.5の退出条件

• Standards reviewが完了している
• Spec reviewが完了している
• Domain reviewが完了している
• すべての指摘に判定が付いている
• 未解決の修正必須指摘が明示されている
• read-onlyレビューであることが確認できる
• レビューレポートが保存されている
• PR作成前にユーザーへ結果を提示している

8. ReviewContext仕様

workflow-orchestratorはcode-review skillを起動する前にReviewContextを構成する。

8.1 差分情報

• base_commit_sha: 実装開始時点のcommit SHA
• review_scope: base commitから現在のworking treeまで
• changed_files: staged / unstaged変更ファイル
• untracked_files: 未追跡ファイル
• commit_list: base commit以降のcommit一覧（存在する場合）

8.2 仕様SoT

タスクに応じて、以下を明示的に渡す。

• 対象タスクレポート docs/agent-tasks/reports/{ticket}-*.md
• docs/spec.md
• 対象機能の docs/spec/*.md
• docs/workflows.md
• 関連する受入条件
• 必要に応じて関連リポジトリの仕様・実装参照先（cross-repository-knowledge-link 経由・読み取り専用）

8.3 規約・設計SoT

• AGENTS.md
• .cursor/rules/00-init.mdc
• .cursor/rules/01-critical-constraints.mdc
• .cursor/rules/02-agent-conduct.mdc
• docs/architecture.md
• docs/coding-standards.md
• docs/tech-stack.md
• docs/QUALITY_GATE.md
• docs/DECISIONS.md
• docs/GOTCHAS.md
• manifest.yaml（生成物変更時は SoT として必須）

8.4 実行制約

• read-onlyで実行する
• --fixを使用しない
• ファイルを変更しない
• commitしない
• pushしない
• PRを作成しない
• GitHubへコメント・レビューを投稿しない
• 不明な仕様を推測しない
• token / secret / credential の値を表示・出力しない

9. 未コミット差分の取り扱い

Matt Pocock版の標準的な差分取得は、固定点と HEAD の比較を前提とする場合がある。

PR前の実装では変更が未コミットの場合があるため、以下を明示的に処理する。

1. git diff <base_commit_sha> でstaged / unstaged変更を取得する
2. git status --short でuntracked fileを列挙する
3. untracked fileの内容をレビュー入力に含める
4. base_commit_shaから現在のworking treeまでをレビュー範囲として固定する

レビューのためだけにsynthetic commitを作成してはならない。commitが必要なレビュー実装を採用する場合は、別途ユーザー承認と運用設計が必要である。

10. レビュー観点

10.1 Standards review

• docs/coding-standards.md / docs/tech-stack.md の制約に従っているか
• TypeScript strict / 既存のテストパターン（Vitest 等）を踏襲しているか
• 既存のスキル・Hook・ゲート・スクリプトの実装パターンを踏襲しているか
• Progressive Disclosure（SKILL.md → references/）の分割規約を壊していないか
• 生成物コメント（「直接編集せず manifest.yaml を更新して再生成する」等）の扱いを誤っていないか
• 変更前に関連ファイルを全体読み込みする原則に反する部分変更になっていないか
• 自動生成・render 対象ファイルを SoT 迂回で手編集していないか
• テストが実際の回帰を検出できる内容か（skip / 抑制 / アサーション削除で回避していないか）

10.2 Spec review

• タスクレポートの要件をすべて実装しているか
• 受入条件を満たしているか
• 仕様にない振る舞いを追加していないか
• 仕様上の異常系・境界値を扱っているか
• 状態遷移・フェーズ境界が仕様で許可された範囲に限定されているか
• 運用制約（Session Protocol / ゲート契約）を破っていないか
• 仕様書と実装の乖離がある場合に明示しているか

10.3 agentic-workflow-foundation-kit Domain review

• 出力ファイル（生成物）を直接編集せず、manifest.yaml / templates 経由の再生成になっているか
• Meta 層（UPPER_SNAKE_CASE.md）と Domain 層（kebab-case.md）の命名規約を守っているか
• AGENTS.md Boundaries（Always / Ask First / Never）に抵触していないか
• GitHub API / git clone・fetch・pull・push が bin/*-safe wrapper 経由か
• project.quality_gate.profile（本 kit は foundation）に従った検証入口を壊していないか
• G-* / foundation-gate の backend contract や exit code セマンティクスを変質させていないか
• D-* 設計次元の変更がある場合、ADR worker → 草案ゲート → 承認 → docs/DECISIONS.md 確定追記のフローを想定しているか（レビュー時点で未承認の直接追記がないか）
• 追跡ドキュメント（.cursor/.tracking/）・step envelope（.cursor/.artifacts/）・handoff（.cursor/.session/）のパス規約を守っているか
• Context Budget 規約（.cursor/ 直下への独自ファイル作成禁止、リンク衛生）を破っていないか
• secret / credential / 認証ファイルへ触れていないか、値を出力していないか
• 独立メンテナンスパイプライン（maintenance-docs-workflow / maintenance-gotchas-workflow）と標準ワークフローの責務境界を混同していないか

11. サブエージェントへの情報伝達

main agentが読んだファイルや会話上の判断は、subagentへ自動的に継承されるとは限らない。

したがって、code-review skillを起動する際は、少なくとも以下をプロンプトまたはReviewContextとして渡す。

• 固定点と差分取得方法
• 仕様ファイルのパス
• 規約ファイルのパス
• ドメイン制約（§10.3）
• 変更対象ファイル一覧
• untracked fileの一覧
• 期待する出力形式
• read-only制約

仕様が不足している場合、Spec subagentは要求を推測せず、spec unavailableまたはinsufficient evidenceとして報告する。

12. 出力仕様

12.1 出力先

PR後レビュー用のレポートと区別するため、PR前レビューは以下のような別名を推奨する。

docs/agent-tasks/reviews/{task-report-stem}-pre-review.md

既存の docs/agent-tasks/reviews/{task-report-stem}-review.md はPR後レビュー（agent-code-review）用として維持する。

12.2 必須内容

• レビュー対象のbase commit
• レビュー対象ファイル
• 参照したSoT一覧
• Standards findings
• Spec findings
• Domain findings
• 指摘ごとのファイルパス・行番号
• 指摘ごとの影響
• 指摘ごとのSoT根拠
• 判定（修正必須 / 修正推奨 / 修正不要）
• 仕様不明・証跡不足の項目
• 実行したコードゲートの結果（本 kit では bin/foundation-gate self 等）
• レビューがread-onlyで実行されたこと

12.3 指摘の判定

指摘には以下のいずれかを付与する。

• 修正必須: 仕様違反、SoT迂回、Boundaries違反、セキュリティ問題、重大な回帰
• 修正推奨: 保守性・可読性・設計整合性上の改善
• 修正不要: SoT上の根拠がなく、既存制約にも違反しないもの

根拠のないスタイル嗜好だけで修正必須と判定してはならない。判定 3 段階は agent-code-review の判定語彙と揃える（責務境界は §13）。

13. 既存Step⑤との責務境界

Step 4.5 PR前自己レビュー

• 対象: 現在のworking tree
• PR: 未作成
• 目的: 仕様・設計・kit 固有制約の事前検証
• GitHub操作: なし
• 出力: pre-review report

Step⑤ PR作成 + PRレビュー検証

• 対象: 作成済みPR
• PR: 必須（本ステップ内で作成）
• 目的: CodeRabbit・人間レビュアー等の指摘取得、妥当性検証、返信・修正承認
• GitHub操作: agent-github-pr / agent-code-review の承認ループ・wrapper 経由のみ
• 出力: PR review report（{task-report-stem}-review.md）

両者は同じ「レビュー」という名前を持つが、入口条件・対象・操作権限・成果物が異なるため、同一Stepに統合しない。

14. 受入条件

• PR前自己レビューがPR作成なしで実行できる
• 実装開始時点のbase commitがレビュー範囲に使われる
• staged / unstaged / untracked変更がレビュー対象になる
• タスクレポートと該当仕様書がレビュー入力に含まれる
• StandardsとSpecが独立して評価される
• kit 固有の Domain reviewが実行される
• 仕様不明時に推測せず停止または明示報告する
• 修正・commit・push・PR投稿が発生しない
• 指摘にファイル・行・SoT根拠が含まれる
• PR後のagent-code-reviewと責務が混ざらない
• レビューレポートをPR後レビューと区別して保存できる

15. 未決事項

実装前に以下を決定する必要がある。

1. Step 4.5を正式なワークフローステップとして追加するか
2. pre-review reportを追跡対象にするか、一時成果物にするか
3. workflow-gate.shにStep 4.5用ゲートを追加するか
4. 修正必須指摘がある場合の戻り先をStep③またはStep④のどちらにするか
5. code-review skillのインストール先とバージョン固定方法
6. Standards / Spec / Domain reviewを同じskillに拡張するか、Domain reviewを別skillとして追加するか
7. D-*設計判断が発生した場合のADR worker連携
8. 未コミット差分を扱うReviewContextの実装方法

16. 参照文書

• AGENTS.md
• .cursor/skills/workflow-orchestrator/SKILL.md
• .cursor/skills/agent-code-review/SKILL.md
• .cursor/skills/agent-github-pr/SKILL.md
• docs/agent-tasks/agent-workflow.md
• docs/agent-tasks/agent-workflow/04-testing.md
• docs/agent-tasks/agent-workflow/05-pr-review.md
• docs/architecture.md
• docs/coding-standards.md
• docs/tech-stack.md
• docs/QUALITY_GATE.md
• docs/DECISIONS.md
• docs/GOTCHAS.md
• docs/CONTEXT_BUDGET.md
• docs/spec.md
• docs/spec/*.md
• manifest.yaml
• Matt Pocock code-review: https://github.com/mattpocock/skills/tree/main/skills/engineering/code-review