レビュー・テスト・再リサーチループ 詳細記入例・解説ガイド
Author: Manus AI
Version: 1.0
対象: 非エンジニアの希望を、世界最高基準の要件定義、仕様、技術要件、ハーネス設計、テスト、レビュー、再リサーチ、再提案へ変換する実務担当者
前提ファイル: review_test_reresearch_loop_templates_complete.md
0. 本ガイドの目的
このガイドは、前回作成した「レビュー・テスト・再リサーチループ完全テンプレート集」を、実際のプロジェクトで迷わず埋められるようにするための詳細な記入例・解説版です。単に欄を埋めるのではなく、各項目で何を判断し、何を書いてはいけないか、どの状態ならGreen、Yellow、Redにするべきかを明確にします。
重要な考え方は、素人に専門判断をさせないことです。素人は「何をしたいか」「何が怖いか」「どのリスクなら許容できるか」を伝えます。一方で、技術的破綻、規約違反、テスト不能、運用不能、本番破壊リスクは、テンプレート、レビュー、テスト、再リサーチループが検出します。
| 判定 | 意味 | 実務上の扱い |
|---|---|---|
| Green | 根拠、要件、受入基準、テスト、リスク対策が接続されている | 次工程へ進める |
| Yellow | 調査不足、設計不足、テスト不足、運用不安がある | 本番禁止。PoC、Sandbox、追加調査のみ許可 |
| Red | 規約違反、破壊的操作の安全策なし、重大セキュリティ懸念がある | 停止、要件変更、代替案検討 |
1. Intent Intake Sheet の記入例と解説
1.1 目的
Intent Intake Sheetは、ユーザーの自然言語の希望を、いきなり仕様に変換せず、目的、成功状態、制約、避けたい失敗に分解するためのテンプレートです。ここで重要なのは、「実装方法」を決めることではなく、何を達成したいのか、何を壊してはいけないのかを明らかにすることです。
1.2 詳細記入例
| 項目 | 悪い記入例 | 良い記入例 | 解説 |
|---|---|---|---|
| プロジェクト名 | 自動化ツール | Googleカレンダー予定通知自動化 | 何を自動化するのか分かる名前にします。 |
| やりたいことを一文で | 予定管理を便利にしたい | Googleカレンダーの予定開始30分前にSlackへ通知したい | 「便利にしたい」は曖昧です。対象、動作、出力先を入れます。 |
| なぜやりたいのか | 楽にしたい | 会議の見落としを減らし、手動確認の時間を削減したい | 背景目的があると、代替案を評価できます。 |
| 誰のためのものか | 自分たち | 営業チーム5名。技術者ではない | 利用者のスキルが設計に影響します。 |
| 成功した状態 | ちゃんと動く | 予定の30分前に1回だけ通知され、重複通知がない | 検証可能な状態にします。 |
| 絶対に避けたい失敗 | バグ | 誤通知、重複通知、個人情報のSlack誤送信 | 破壊リスクや信用損失を具体化します。 |
| 自動化レベル | 自動 | 通知文の生成は自動、外部送信は承認なしで実行。ただし初期2週間はdry-run | 完全自動か承認付きかを明確にします。 |
| 本番で触る対象 | カレンダー | Google Calendar API、Slack API、通知ログDB | 破壊・漏洩・外部依存の範囲を見える化します。 |
| 個人情報・機密情報の有無 | たぶんない | 予定タイトルに顧客名が含まれる可能性あり | 「たぶんない」は危険です。可能性があるならYellowです。 |
| 初期判定 | Green | Yellow | 外部APIと個人情報の可能性があるため、初期はYellowが妥当です。 |
1.3 記入時の注意点
このテンプレートで最も多い失敗は、ユーザーの言葉をそのまま仕様にしてしまうことです。たとえば「自動投稿したい」は、完全自動投稿、承認後投稿、下書き生成、通知のみの4種類に分かれます。どれを選ぶかで、規約リスク、誤投稿リスク、ハーネス設計、テスト計画が大きく変わります。
| 危険な表現 | 追加で確認すべきこと |
|---|---|
| 自動化したい | どの操作を、どこまで自動化するのか |
| 安全にしたい | 何を失敗とみなすのか |
| 使いやすくしたい | 誰が、どの場面で、何秒以内に使えればよいのか |
| AIでやりたい | AIが判断する範囲、承認者、誤判定時の停止条件 |
| 連携したい | 認証、権限、Rate Limit、データ保存先 |
2. Assumption & Unknowns Log の記入例と解説
2.1 目的
Assumption & Unknowns Logは、プロジェクト開始時点での「分かっているつもり」を可視化するための台帳です。ここを省略すると、後で「APIでできると思っていた」「規約上問題ないと思っていた」「運用者が対応できると思っていた」という破綻が起きます。
2.2 詳細記入例
| ID | 種別 | 内容 | 悪い記入例 | 良い記入例 | 判定 |
|---|---|---|---|---|---|
| A-001 | 前提 | Slack通知が可能 | Slackに送れるはず | Slack Bot Tokenで指定チャンネルへ投稿可能か公式Docsで確認する | Yellow |
| U-001 | 不明点 | Google Calendar API制限 | 制限は大丈夫そう | 1ユーザーあたりのRate Limit、再試行推奨、失敗時レスポンスを確認する | Yellow |
| U-002 | 不明点 | 個人情報の扱い | 個人情報はない | 予定タイトル、参加者メール、説明欄に個人情報が含まれる可能性を確認する | Yellow |
| A-002 | 前提 | 運用者がログを確認できる | 管理者が見る | 非エンジニアが確認できるログ画面または通知レポートが必要 | Yellow |
2.3 解説
前提は「正しいなら設計に使える仮定」、不明点は「確認しないと設計に使ってはいけない情報」です。どちらも未確認のままMust要件や技術要件にしてはいけません。
| 状態 | 扱い |
|---|---|
| 未確認 | Yellow。要件確定不可 |
| 確認済 | 根拠IDを付けて要件へ接続可能 |
| 破棄 | 間違った前提として記録し、設計から除外 |
3. Research Brief の記入例と解説
3.1 目的
Research Briefは、調査を検索作業で終わらせず、意思決定に使える根拠へ変換するための指示書です。調査対象、判断したいこと、一次情報、完了条件を明確にします。
3.2 詳細記入例
| 項目 | 悪い記入例 | 良い記入例 | 解説 |
|---|---|---|---|
| 調査テーマ | Googleカレンダーについて調べる | Google Calendar APIで予定開始30分前通知を実装する際の認証、Rate Limit、イベント更新検知、再試行設計を調べる | 調査範囲を実装判断に直結させます。 |
| 調査の目的 | 使えるか確認 | 本番自動通知に進めてよいか、PoCに留めるべきか判断する | 判定目的を明確にします。 |
| 必ず確認する一次情報 | Docs | Google Calendar API Docs、OAuth Scope、Usage Limits、Google API Services User Data Policy | 公式情報を優先します。 |
| 確認する二次情報 | ブログ | GitHub Issues、Stack Overflow、技術ブログ、障害・Rate Limit事例 | 二次情報は失敗例の発見に使います。 |
| 調査完了条件 | だいたい分かったら | 認証方式、必要Scope、Rate Limit、失敗時挙動、禁止事項、代替案をEvidence Matrixへ登録済み | 完了条件を成果物ベースにします。 |
3.3 良いResearch Briefの例
| 項目 | 記入例 |
|---|---|
| 調査ID | RS-001 |
| 調査テーマ | Google Calendar APIとSlack APIを用いた予定通知自動化の安全な実装条件 |
| 調査の目的 | 非エンジニア運用で本番自動通知してよいか判断する |
| 判断したいこと | Greenで本番へ進めるか、YellowでPoCに留めるか |
| 必ず確認する一次情報 | Google Calendar API Docs、OAuth Scope、Slack API Docs、各利用規約、Rate Limit、Security Policy |
| 確認する二次情報 | GitHub Issues、Stack Overflow、運用失敗事例、類似OSSの設計 |
| 成果物 | Evidence Matrix、Risk Register、Harness Design更新案 |
| 調査完了条件 | High根拠が3件以上、主要リスクと代替案が記録済み |
| 調査後の判定方法 | RYG GateでGreen / Yellow / Red判定 |
4. Evidence Matrix の記入例と解説
4.1 目的
Evidence Matrixは、調査結果を「信じてよい根拠」と「参考に留める情報」に分けるための表です。ここで根拠強度を誤ると、弱い情報をもとにMust要件を作ってしまいます。
4.2 詳細記入例
| Evidence ID | 情報源 | 種別 | 要約 | 根拠強度 | 採用判断 | 解説 |
|---|---|---|---|---|---|---|
| EV-001 | Google Calendar API公式Docs | 公式Docs | イベント取得・更新検知・認証方式を確認 | High | 採用 | Must要件や技術要件の根拠にできます。 |
| EV-002 | Slack API公式Docs | 公式Docs | Bot Tokenでチャンネル投稿可能 | High | 採用 | 通知方式の根拠にできます。 |
| EV-003 | 個人ブログ | Blog | 似た通知Bot実装例 | Medium | 参考 | 実装参考には使えますが、Must要件の根拠には弱いです。 |
| EV-004 | SNS投稿 | SNS | Rate Limitに引っかかったという投稿 | Low | 仮説 | 再調査のきっかけには使えます。 |
4.3 悪い記入と良い記入
| 観点 | 悪い例 | 良い例 |
|---|---|---|
| URL | Googleで見た | 公式DocsのURLを記録 |
| 要約 | できそう | どのAPIで、どの条件なら可能かを書く |
| 根拠強度 | 全部High | 公式、標準、論文、ブログ、SNSを分ける |
| 採用判断 | 採用 | 採用、参考、仮説、不採用を分ける |
4.4 判定ポイント
| 条件 | 判定 |
|---|---|
| Must要件にHigh根拠が接続されている | Green候補 |
| 重要要件がMedium根拠だけ | Yellow |
| 重要要件がLow根拠だけ | Redまたは保留 |
| 規約・禁止事項が未確認 | YellowまたはRed |
5. Requirement ID Ledger の記入例と解説
5.1 目的
Requirement ID Ledgerは、要件、根拠、受入基準、テスト、リスクを接続する中核台帳です。この台帳があることで、レビュー指摘やテスト失敗がどの要件に影響するか追跡できます。
5.2 詳細記入例
| 要件ID | 種別 | 要件 | 優先度 | 根拠ID | 受入基準ID | テストID | リスクID | 判定 |
|---|---|---|---|---|---|---|---|---|
| FR-001 | Functional | 予定開始30分前にSlackへ通知する | Must | EV-001, EV-002 | AC-001 | T-001, T-004 | R-001 | Green候補 |
| FR-002 | Functional | 通知文をAIで自動要約する | Should | EV-005 | AC-002 | T-005 | R-004 | Yellow |
| NFR-001 | Non-Functional | API失敗時は3回まで指数バックオフで再試行し、失敗をログへ記録する | Must | EV-006 | AC-003 | T-006 | R-002 | Green候補 |
| SEC-001 | Security | OAuth Scopeは必要最小限に限定する | Must | EV-007 | AC-004 | T-007 | R-003 | Green候補 |
5.3 悪い要件と良い要件
| 悪い要件 | 問題 | 良い要件 |
|---|---|---|
| 通知をいい感じにする | 測定不能 | 予定開始30分前に、指定Slackチャンネルへ1回だけ通知する |
| エラーに強くする | 何をどうするか不明 | API失敗時は最大3回再試行し、失敗時は管理者へ通知する |
| 安全にする | 範囲不明 | OAuth Scopeを読み取り専用に限定し、Tokenを環境変数で管理する |
5.4 判定ポイント
要件は、根拠ID、受入基準ID、テストID、リスクIDが揃って初めてGreen候補になります。1つでも欠ける場合はYellowです。破壊的操作や規約懸念があるのにハーネスがない場合はRedです。
6. Acceptance Criteria Sheet の記入例と解説
6.1 目的
Acceptance Criteriaは、「完成した」と判断する条件を明確にするものです。Given / When / Then形式で書くと、状況、操作、期待結果が分かれ、テストへ接続しやすくなります。
6.2 詳細記入例
| 受入基準ID | 関連要件ID | Given | When | Then | 測定方法 | 合格条件 | 不合格条件 |
|---|---|---|---|---|---|---|---|
| AC-001 | FR-001 | カレンダーに予定が登録されている | 予定開始30分前になったとき | Slackに通知が1回だけ送信される | 通知ログ、Slack投稿履歴 | 1予定につき1通知 | 未通知、重複通知、誤チャンネル通知 |
| AC-003 | NFR-001 | Google APIが一時的に失敗する | APIリクエストが失敗したとき | 最大3回再試行し、失敗ログを残す | mock API、ログ確認 | 再試行回数とログが仕様通り | 無限リトライ、ログなし、通知漏れ |
| AC-004 | SEC-001 | OAuth設定を行う | Tokenを発行するとき | 必要最小限のScopeだけが付与される | OAuth設定画面、設定ファイル確認 | 不要Scopeなし | 過大権限あり |
6.3 解説
受入基準は、開発者の主観ではなく、ユーザー、レビュー担当、テスト担当が同じ結果を確認できる形で書きます。「速い」「安全」「分かりやすい」は、そのままでは受入基準になりません。
| 曖昧な基準 | 検証可能な基準 |
|---|---|
| 速い | 95%の通知処理が5秒以内に完了する |
| 安全 | Tokenがログ、画面、リポジトリに出力されない |
| 分かりやすい | 非エンジニアが手順書を見て10分以内にdry-runを実行できる |
7. Technical Requirement Sheet の記入例と解説
7.1 目的
Technical Requirement Sheetは、技術選定、外部依存、認証、データ、ログ、エラー処理、運用方針を明文化します。技術的に作れるかだけではなく、非専門家が安全に運用できるかを確認します。
7.2 詳細記入例
| 項目 | 悪い記入例 | 良い記入例 | 解説 |
|---|---|---|---|
| 採用技術 | Pythonで作る | Python + Google Calendar API + Slack Web API + SQLite通知ログ | 構成要素を具体化します。 |
| 採用理由 | 使いやすい | API SDKがあり、ログ処理と定期実行が実装しやすい | 理由は保守性・安全性と接続します。 |
| 外部依存 | GoogleとSlack | Google Calendar API、Slack API、OAuth、Bot Token | 依存先を網羅します。 |
| 認証・権限 | OAuth | Google OAuthは読み取りScope限定、Slackは投稿先チャンネル限定Bot Token | 最小権限を書きます。 |
| 秘密情報の扱い | 環境変数 | Tokenは環境変数またはSecret Managerで管理し、ログ出力禁止 | 漏洩防止を明確にします。 |
| エラー処理方針 | エラーなら止める | 一時エラーは3回再試行、認証エラーは即停止、管理者通知 | エラー種別ごとに扱いを分けます。 |
| ログ方針 | ログを残す | 通知対象ID、実行時刻、結果、エラー種別を記録。予定本文やTokenは記録しない | 個人情報をログに残さない設計が重要です。 |
7.3 判定ポイント
| 条件 | 判定 |
|---|---|
| 認証、権限、データ保存、ログ、エラー処理が明確 | Green候補 |
| 外部API制限や料金が未確認 | Yellow |
| Tokenをコードやログに出す設計 | Red |
| 過大権限を前提とする設計 | Red |
8. Harness Design Sheet の記入例と解説
8.1 目的
Harness Design Sheetは、本番を壊さずに検証するための安全装置を設計するテンプレートです。メール送信、SNS投稿、DB更新、ファイル削除、決済、外部API更新などは、ハーネスなしで本番実行してはいけません。
8.2 詳細記入例
| ハーネスID | 関連要件ID | 対象操作 | 破壊リスク | 安全装置 | 検証方法 | ロールバック | 停止条件 | 判定 |
|---|---|---|---|---|---|---|---|---|
| H-001 | FR-001 | Slack通知送信 | 中 | dry-run、sandboxチャンネル、audit log | dry-runで送信予定内容をログに出す | 投稿削除は原則不可。誤通知時は訂正通知 | 5分以内に3件以上失敗で停止 | Green候補 |
| H-002 | NFR-001 | API再試行 | 中 | mock API、fixture、timeout | 429、500、timeoutをmockで再現 | 状態変更なし | 連続失敗時にkill switch | Green候補 |
| H-003 | DATA-001 | 通知ログ保存 | 低 | test DB、migration rollback | テストDBで保存確認 | DBバックアップから復元 | migration失敗で停止 | Yellow |
8.3 ハーネス部品の書き方
| 部品 | 良い記入例 | 不十分な記入例 |
|---|---|---|
| dry-run | send=falseで外部投稿せず、投稿予定内容だけログへ出す |
テストする |
| mock | 429、500、timeout、認証失敗を再現するmock APIを用意 | APIが落ちたら確認する |
| sandbox | 本番Slackではなく検証用チャンネルへ送る | 少人数で試す |
| kill switch | 環境変数 AUTOMATION_ENABLED=false で即時停止 |
必要なら止める |
| rollback | DB migration失敗時は前バージョンへ戻す手順を記載 | バックアップする |
| audit log | 実行ID、対象ID、結果、時刻、操作者を記録 | ログを残す |
8.4 判定ポイント
破壊的操作にdry-runがない場合はRedです。外部APIや自動実行があるのにkill switchがない場合はYellowまたはRedです。個人情報を含む処理でaudit logやマスキングがない場合もRed候補です。
9. Test Plan Matrix の記入例と解説
9.1 目的
Test Plan Matrixは、要件ごとの検証方法を明確にする表です。テストは「動いたか確認」ではなく、要件、受入基準、リスクを検証するために設計します。
9.2 詳細記入例
| テストID | 関連要件ID | テスト種別 | テスト内容 | 前提データ | 期待結果 | 自動化 | 実行タイミング | 合否 |
|---|---|---|---|---|---|---|---|---|
| T-001 | FR-001 | Integration | 予定開始30分前通知をsandbox Slackへ送る | fixture予定1件 | 1回だけ通知 | Yes | PR / Release | Pending |
| T-002 | FR-001 | Regression | 同一予定で重複通知されないか確認 | 同一予定IDの再実行 | 2回目は送信しない | Yes | PR | Pending |
| T-003 | NFR-001 | Integration | API 429時に再試行する | mock 429応答 | 指数バックオフ後に再試行 | Yes | PR | Pending |
| T-004 | SEC-001 | Security | Tokenがログに出ないか確認 | 疑似Token | ログにToken文字列なし | Yes | PR | Pending |
| T-005 | OPS-001 | Acceptance | 非エンジニアがdry-run結果を確認できる | 手順書 | 10分以内に確認完了 | No | Release前 | Pending |
9.3 解説
重要なのは、Must要件にテストIDが接続されていることです。手動テストでも構いませんが、実行者、タイミング、合格条件が必要です。
| 悪いテスト | 問題 | 良いテスト |
|---|---|---|
| 通知を確認する | 条件が不明 | fixture予定1件に対して30分前通知が1回だけ送信されることを確認する |
| エラー処理を確認する | エラー種別が不明 | 429、500、timeout、認証失敗ごとに期待動作を確認する |
| セキュリティ確認 | 何を見るか不明 | Tokenがログ、画面、リポジトリに出ないことを確認する |
10. CI Quality Gate Sheet の記入例と解説
10.1 目的
CI Quality Gateは、実装をマージまたはリリースしてよい条件を明文化します。すべてを自動化できなくても、重大な失敗を止める条件を先に決めることが重要です。
10.2 詳細記入例
| Gate ID | 対象 | 条件 | 閾値 | 失敗時アクション | 例外承認者 | 状態 |
|---|---|---|---|---|---|---|
| QG-001 | Unit Test | 主要ロジックの単体テストが通る | 100% Pass | Stop | Tech Lead | Active |
| QG-002 | Secret Scan | Token、API Key、個人情報らしき文字列が混入しない | 重大検出0件 | Stop | Security Owner | Active |
| QG-003 | Integration Test | mock APIで通知・再試行が成功 | 主要ケースPass | Yellow | Tech Lead | Active |
| QG-004 | Manual Acceptance | 非エンジニアがdry-run結果を確認 | 承認済み | Stop | Product Owner | Draft |
10.3 判定ポイント
秘密情報混入、重大脆弱性、破壊的操作のテスト失敗はRedです。IntegrationやE2Eの不安定さはYellowですが、本番リリース前には解消が必要です。
11. Risk Register の記入例と解説
11.1 目的
Risk Registerは、起こり得る失敗を台帳化し、対策、残リスク、監視方法まで明確にするものです。リスクは「怖いことリスト」ではなく、意思決定の材料です。
11.2 詳細記入例
| リスクID | 関連要件ID | リスク内容 | 発生確率 | 影響度 | リスクレベル | 対策 | 残リスク | 監視方法 | 判定 |
|---|---|---|---|---|---|---|---|---|---|
| R-001 | FR-001 | 重複通知で利用者に混乱が生じる | 中 | 中 | Medium | 予定IDと通知済み時刻を記録し冪等化 | DB障害時の重複可能性 | 通知ログ監視 | Yellow |
| R-002 | NFR-001 | API Rate Limitで通知漏れが起きる | 中 | 高 | High | バックオフ、キュー、失敗通知 | 大量予定時の遅延 | API失敗率監視 | Yellow |
| R-003 | SEC-001 | Token漏洩 | 低 | 高 | High | Secret管理、ログマスク、権限最小化 | 管理端末侵害 | Secret Scan、監査ログ | Green候補 |
| R-004 | COM-001 | 規約上の自動化制限に抵触 | 不明 | 高 | High | 公式規約を再調査 | 未確認中 | Evidence更新 | Red/Yellow |
11.3 解説
対策を書いても、残リスクがゼロになるとは限りません。重要なのは、残るリスクを説明し、監視または停止条件を用意することです。
| 悪い書き方 | 良い書き方 |
|---|---|
| セキュリティリスクがある | Tokenがログに出力されると第三者がSlack投稿できる可能性がある |
| 対策する | ログ出力前にToken形式をマスクし、Secret ScanをCIで実行する |
| 大丈夫 | 残リスクは管理端末侵害。監査ログと権限分離で監視する |
12. Codex Review Request の記入例と解説
12.1 目的
Codexレビューは、実装、テスト、CI、依存関係、例外処理、セキュリティ、破壊的操作の観点で破綻を検出するレビューです。要件の採否判断ではなく、作りとして壊れていないかを確認します。
12.2 良い依頼文の例
あなたは実装・テスト・CI破綻を検出するレビュー担当です。
以下の対象について、要件の採否ではなく、実装品質、テスト妥当性、CI、依存関係、例外処理、セキュリティ、破壊的操作の観点からGreen / Yellow / Redで判定してください。
対象:
- 要件ID: FR-001, NFR-001, SEC-001
- 関連仕様: Google Calendar予定を30分前にSlack通知する
- 関連コード: notification_service.py, calendar_client.py, slack_client.py
- テスト: T-001, T-002, T-003, T-004
- ハーネス: H-001, H-002
重点レビュー観点:
1. 重複通知を防ぐ冪等性があるか
2. API 429、500、timeout、認証失敗に対応しているか
3. dry-runが本当に外部送信を止めているか
4. Tokenがログや例外に出ないか
5. CIで検出できる問題と手動確認が必要な問題を分けているか
出力形式:
- 総合判定
- Critical / Major / Minor指摘
- 修正案
- 再リサーチすべき論点
- 更新すべきテンプレート
12.3 悪い依頼文
このコードをレビューしてください。問題があれば直してください。
この依頼では、レビュー観点、対象要件、テスト、ハーネス、判定形式が不明です。結果として、表面的なコード修正だけで終わり、要件やリスクへ戻りません。
13. Opus Review Request の記入例と解説
13.1 目的
Opusレビューは、要件、採否、運用、規約、保守、非専門家利用の観点で評価します。Codexレビューが「壊れずに作れているか」を見るのに対し、Opusレビューは作るべきか、運用できるか、目的に合っているかを見ます。
13.2 良い依頼文の例
あなたは要件・採否・運用リスクを再分析するレビュー担当です。
以下のプロジェクトについて、技術的に作れるかではなく、作るべきか、非エンジニアが安全に運用できるか、規約・セキュリティ・費用・保守の面で破綻しないかを判定してください。
対象資料:
- Intent Intake Sheet
- Evidence Matrix
- Requirement ID Ledger
- Technical Requirement Sheet
- Harness Design Sheet
- Test Plan Matrix
- Risk Register
重点レビュー観点:
1. ユーザーの目的と要件が一致しているか
2. 根拠が弱いMust要件はないか
3. 規約上の自動化制限やデータ利用制限はないか
4. 非エンジニアが誤操作せず運用できるか
5. YellowをGreen扱いしていないか
6. より安全な代替案、縮小案、承認付き案はあるか
出力形式:
- 総合判定: Green / Yellow / Red
- 採用してよい要件
- 保留すべき要件
- 停止すべき要件
- 追加調査テーマ
- 代替案
- 更新すべきテンプレート
13.3 判定の例
| 指摘 | Opus判定 | 理由 |
|---|---|---|
| 公式APIで許可され、dry-runとログがある | Green | 採用可能 |
| 規約確認前だが技術的には可能 | Yellow | 本番禁止。規約調査が必要 |
| スクレイピング禁止の可能性がある | Red | 代替APIまたは手動運用へ変更 |
| 非エンジニアが復旧できない | Yellow | 運用手順、アラート、停止手段が必要 |
14. Review Finding Log の記入例と解説
14.1 目的
Review Finding Logは、レビューで見つかった指摘を、単なる修正タスクではなく、再リサーチ、要件更新、テスト更新へ接続するための台帳です。
14.2 詳細記入例
| Finding ID | 発見元 | 関連ID | 指摘内容 | 重大度 | 原因仮説 | 影響範囲 | 必要対応 | 再リサーチID | 状態 |
|---|---|---|---|---|---|---|---|---|---|
| F-001 | Codex | T-003 | 429時の再試行が固定間隔で、Rate Limit悪化の可能性 | Major | API制限設計不足 | NFR-001, H-002 | 再調査、実装修正、テスト追加 | RRS-001 | Open |
| F-002 | Opus | COM-001 | 自動通知内容に個人情報が含まれる可能性 | Critical | データ分類不足 | SEC-001, OPS-001 | 要件見直し、マスキング検討 | RRS-002 | Open |
| F-003 | Test | FR-001 | 同一予定で重複通知が発生 | Critical | 冪等性不足 | FR-001, R-001 | 実装修正、回帰テスト追加 | RRS-003 | Open |
14.3 注意点
指摘を「対応済み」にする前に、Requirement ID Ledger、Test Plan Matrix、Harness Design Sheet、Risk Registerのどれを更新したか確認します。コードだけ直して閉じると、次回同じ破綻が再発します。
15. RYG Gate Decision Log の記入例と解説
15.1 目的
RYG Gateは、専門的なレビュー結果を、非専門家でも判断できるGreen、Yellow、Redに変換するための意思決定ログです。
15.2 詳細記入例
| Gate ID | 対象 | 判定 | 判定理由 | 次の行動 | 禁止事項 | 承認者 | 状態 |
|---|---|---|---|---|---|---|---|
| G-001 | FR-001 通知機能 | Yellow | dry-runはあるが、重複通知対策のテストが未完了 | sandboxで追加テスト | 本番通知禁止 | Product Owner | Open |
| G-002 | SEC-001 Token管理 | Green | Secret管理、ログマスク、Secret Scanが確認済み | 次工程へ進む | なし | Security Owner | Closed |
| G-003 | COM-001 規約確認 | Red | 自動取得・自動送信の許可範囲が未確認 | 公式規約再調査 | 実装、本番運用禁止 | Product Owner | Open |
15.3 判定の注意点
Yellowは「少し不安だが進める」ではありません。Yellowは本番禁止です。Redは失敗ではなく、本番で壊れる前に止められた成功として扱います。
16. Re-Research Brief の記入例と解説
16.1 目的
Re-Research Briefは、レビューやテストで見つかった問題を、局所修正ではなく、根拠調査へ戻すためのテンプレートです。
16.2 詳細記入例
| 再リサーチID | 起点Finding ID | 調査テーマ | なぜ再調査が必要か | 確認すべき情報源 | 期待する判断 | 状態 |
|---|---|---|---|---|---|---|
| RRS-001 | F-001 | Google API Rate Limit時の推奨リトライ設計 | 固定間隔再試行が制限悪化を招く可能性 | 公式Docs、API Error Handling、事例 | 再試行方式をGreenにできるか | Open |
| RRS-002 | F-002 | 通知文に含まれる個人情報の扱い | 予定タイトルに顧客名が含まれる可能性 | 利用規約、社内ポリシー、個人情報保護方針 | マスキング要否を判断 | Open |
| RRS-003 | F-003 | 冪等性設計と重複通知防止 | 重複通知が発生したため根本原因が必要 | 類似実装、DB制約、キュー設計 | 要件とテストを更新 | Open |
16.3 悪い対応と良い対応
| 発見事項 | 悪い対応 | 良い対応 |
|---|---|---|
| 429で失敗 | リトライ回数を増やす | 公式推奨リトライ、バックオフ、キュー設計を再調査 |
| E2Eが不安定 | 待機時間を増やす | 非同期処理、fixture、環境差分を再調査 |
| 規約が不安 | とりあえず作る | 公式規約、禁止事項、代替APIを再調査 |
| 誤操作リスク | UI説明を増やす | 権限、承認、undo、kill switchを再設計 |
17. Re-Proposal Sheet の記入例と解説
17.1 目的
Re-Proposal Sheetは、再リサーチの結果をもとに、元の案を継続するのか、縮小するのか、代替案へ変えるのか、停止するのかを提案するためのテンプレートです。
17.2 詳細記入例
| 再提案ID | 起点再リサーチID | 提案種別 | 提案内容 | メリット | デメリット | 影響範囲 | 推奨判定 | 採否 |
|---|---|---|---|---|---|---|---|---|
| RP-001 | RRS-001 | 代替 | 固定間隔再試行を指数バックオフ＋キューに変更 | Rate Limit悪化を防ぎやすい | 実装が少し複雑 | NFR-001, T-003, H-002 | Green候補 | 採用 |
| RP-002 | RRS-002 | 縮小 | 通知文から予定タイトルを除外し、リンクのみ通知 | 個人情報漏洩リスク低下 | 利便性が下がる | FR-001, SEC-001, UX-001 | Yellow/Green候補 | 保留 |
| RP-003 | RRS-003 | 継続改善 | 通知済み予定IDをDBで一意制約化 | 重複通知を防げる | DB設計変更が必要 | DATA-001, T-002 | Green候補 | 採用 |
17.3 比較例
| 案 | 内容 | 安全性 | 実装容易性 | 運用容易性 | 推奨度 |
|---|---|---|---|---|---|
| A案 | 完全自動通知 | 中 | 高 | 高 | 中 |
| B案 | 初期2週間はdry-run、その後自動通知 | 高 | 中 | 中 | 高 |
| C案 | 毎回承認して通知 | 高 | 低 | 低 | 中 |
17.4 解説
再提案は「元の案をどう直すか」だけではありません。目的に立ち戻り、より安全な達成方法を提示します。非専門家向けには、推奨案だけでなく、採用しなかった案の理由も書くと判断しやすくなります。
18. Change Impact Matrix の記入例と解説
18.1 目的
Change Impact Matrixは、要件や実装の変更がどこに影響するかを確認する表です。コードだけ変更し、仕様やテストが古いままになることを防ぎます。
18.2 詳細記入例
| 変更ID | 変更内容 | 影響要件ID | 影響テストID | 影響リスクID | 影響ドキュメント | 必要レビュー | 判定 |
|---|---|---|---|---|---|---|---|
| CH-001 | 再試行方式を指数バックオフへ変更 | NFR-001 | T-003 | R-002 | Technical Requirement, Test Plan | Codex | Green候補 |
| CH-002 | 通知文から予定タイトルを除外 | FR-001, UX-001, SEC-001 | T-001, T-005 | R-003 | PRD, Acceptance Criteria | Opus, User | Yellow |
| CH-003 | 通知済みIDに一意制約を追加 | DATA-001, FR-001 | T-002 | R-001 | DB設計, Test Plan | Codex | Green候補 |
18.3 注意点
変更影響を見ないまま修正すると、仕様、実装、テスト、リスクの整合性が崩れます。特に、セキュリティ、データ構造、外部API、運用手順に関わる変更は、必ずOpusレビューまたはユーザー承認が必要です。
19. Loop Completion Checklist の記入例と解説
19.1 目的
Loop Completion Checklistは、レビュー・テスト・再リサーチループを止めてよいか、次工程へ進めてよいかを判断する最終チェックです。
19.2 詳細記入例
| チェック項目 | 条件 | 状態 | 良い記入例 |
|---|---|---|---|
| Intentが明確 | 目的、成功状態、避けたい失敗が記載済み | 済 | 会議通知漏れ削減、重複通知防止、個人情報漏洩回避が明記済み |
| 根拠が接続済み | Must要件にEvidence IDがある | 済 | FR-001にEV-001, EV-002接続済み |
| 受入基準が接続済み | Must要件にAC IDがある | 済 | AC-001でGiven/When/Then記載済み |
| テストが接続済み | Must要件にTest IDがある | 済 | T-001, T-002, T-003接続済み |
| ハーネスが設計済み | 破壊的操作にdry-run等がある | 済 | dry-run、sandbox、mock、kill switchあり |
| リスク対策が記載済み | リスク、対策、残リスクがある | 未 | R-002の残リスク監視が未記入 |
| Codexレビュー済み | 実装・CI・テスト観点の判定あり | 済 | CR-001 Yellow、修正後Green予定 |
| Opusレビュー済み | 要件・運用・採否観点の判定あり | 未 | 規約確認後に実施予定 |
| 再リサーチ完了 | 指摘が再調査されている | 未 | RRS-002がOpen |
19.3 判定
| 状態 | 結論 |
|---|---|
| 全項目が済、重大リスクなし | Green。次工程へ進める |
| 未完了項目があるがPoCで検証可能 | Yellow。Sandbox限定 |
| 規約、セキュリティ、破壊的操作に未確認がある | RedまたはYellow。本番禁止 |
20. Project Learning Log の記入例と解説
20.1 目的
Project Learning Logは、今回のプロジェクトで得た知見を、次回以降のテンプレートやチェックリストへ反映するためのものです。
20.2 詳細記入例
| Learning ID | 発見内容 | 発生箇所 | 原因 | 今後の予防策 | 更新すべきテンプレート | 状態 |
|---|---|---|---|---|---|---|
| L-001 | Rate Limit調査を要件定義前に行う必要がある | Research / Technical | 外部API制限を後回しにした | Research BriefにRate Limit確認を必須項目として追加 | Research Brief, Evidence Matrix | Open |
| L-002 | 非エンジニアはログだけでは異常判断できない | Operations | ログの意味が専門的すぎた | RYG表示と管理者通知を追加 | Technical Requirement, OPS要件 | Open |
| L-003 | dry-run結果をユーザーが確認する画面が必要 | Harness | ログ確認が難しい | dry-run summaryを出力する | Harness Design, Acceptance Criteria | Closed |
20.3 解説
学習ログは反省文ではありません。次回以降、同じ失敗をテンプレートで予防するための改善指示です。
21. 1機能を最後まで埋めたミニサンプル
ここでは、「Googleカレンダーの予定をSlackに通知したい」という1機能を例に、主要テンプレートを短縮形で接続します。
| テンプレート | 記入例 |
|---|---|
| Intent | 会議開始30分前にSlack通知し、通知漏れと重複通知を防ぎたい |
| Unknown | API Rate Limit、個人情報、Slack投稿権限が未確認 |
| Research | Google Calendar API、Slack API、OAuth Scope、Rate Limit、規約を確認 |
| Evidence | EV-001 Google Calendar公式Docs、EV-002 Slack API公式Docs |
| Requirement | FR-001 予定開始30分前に1回だけSlack通知する |
| Acceptance | Given予定登録済み、When開始30分前、Then Slackに1回だけ通知 |
| Technical | OAuth Scope最小化、Bot Token、通知ログDB、再試行設計 |
| Harness | dry-run、sandboxチャンネル、mock API、kill switch |
| Test | T-001通常通知、T-002重複防止、T-003 API失敗、T-004 Token漏洩なし |
| Risk | R-001重複通知、R-002Rate Limit、R-003個人情報漏洩 |
| Codex Review | 実装、冪等性、CI、Tokenログ、API失敗処理を確認 |
| Opus Review | 目的整合、運用可能性、規約、非エンジニア利用を確認 |
| RYG Gate | 個人情報確認が未完了ならYellow。本番は禁止 |
| Re-Research | 通知文に予定タイトルを含めてよいか再調査 |
| Re-Proposal | 初期案は予定タイトルあり。代替案はリンクのみ通知 |
このように、各テンプレートは単独で使うのではなく、IDで接続して使います。ID接続があることで、レビュー指摘が発生したときに、どの要件、どのテスト、どのリスク、どの再リサーチへ戻すべきかが明確になります。
22. 各テンプレートを埋める際の共通チェックリスト
| チェック | OKの状態 | NGの状態 |
|---|---|---|
| 主語が明確 | 誰が、何を、いつ、どこへ行うか分かる | 「自動でやる」「便利にする」だけ |
| 測定可能 | 合格条件、失敗条件がある | 「いい感じ」「高速」「安全」だけ |
| 根拠がある | Evidence IDがある | 誰かが言っていた、たぶん可能 |
| テストできる | Test IDと期待結果がある | 動けばOK |
| 壊さず試せる | dry-run、mock、sandboxがある | 本番で試す |
| 止められる | kill switch、rollbackがある | 問題が起きたら考える |
| 非専門家が判断できる | Green / Yellow / Redがある | 技術者しか分からない説明 |
| 学習へ戻る | FindingからRe-Researchへ接続 | 修正して終わり |
23. よくある失敗と修正例
| よくある失敗 | なぜ危険か | 修正方法 |
|---|---|---|
| Must要件に根拠IDがない | 思い込みで実装される | Research Briefを作り、Evidence Matrixへ登録する |
| テストIDがない | 完了判定できない | Acceptance CriteriaからTest Planへ接続する |
| Yellowを本番投入する | 未確認リスクが本番で顕在化する | YellowはPoCまたはSandbox限定にする |
| レビュー指摘を修正だけで閉じる | 同じ問題が再発する | FindingをRe-Researchへ変換する |
| ログに個人情報やTokenを出す | 情報漏洩につながる | ログ方針、マスキング、Secret Scanを追加する |
| 本番環境で試す | 誤送信、誤削除、誤課金が起きる | dry-run、sandbox、mockを先に作る |
24. 実務での完成基準
この詳細記入例に沿ってテンプレートを埋めた場合、完成状態は次のように確認します。
| 観点 | 完成基準 |
|---|---|
| ユーザー意図 | 成功状態と避けたい失敗が具体化されている |
| 根拠 | Must要件がHighまたは十分なMedium根拠に接続されている |
| 要件 | 要件ID、根拠ID、受入基準ID、テストID、リスクIDが接続されている |
| 技術 | 外部依存、認証、権限、データ、ログ、エラー処理が明記されている |
| ハーネス | dry-run、mock、sandbox、kill switch、rollbackの要否が判断済み |
| テスト | Must要件の検証方法が明確で、合格・不合格条件がある |
| レビュー | CodexとOpusの役割が分離され、両方の判定がある |
| 再リサーチ | Yellow / Red / 重大Findingが再調査へ戻っている |
| 再提案 | 継続、縮小、代替、停止の選択肢が提示されている |
| 非専門家判断 | Green / Yellow / Redで次の行動が明確 |
25. まとめ
各テンプレートの記入で最も重要なのは、欄を埋めることではなく、思い込みを検出し、壊れる前に止めることです。Intentで目的を整理し、Evidenceで根拠を確認し、RequirementでID接続し、HarnessとTestで壊さず検証し、CodexとOpusで異なる観点からレビューし、FindingをRe-Researchへ戻すことで、プロジェクトは単発開発ではなく継続的に安全性を高めるループになります。
このガイドを使うと、非エンジニアは専門判断を背負わずに、「目的」「許容リスク」「赤黄緑の判断」に集中できます。一方で、システム側は、技術的破綻、規約リスク、セキュリティ問題、テスト不足、運用不能性をテンプレートとレビューで検出できます。これが、レビュー・テスト・再リサーチループを実プロジェクトに適用する際の中核です。