# AI開発ハーネス設計（汎用版）

版：1.2（2026-10-24）　作成：JumpStack株式会社
本書は自由に複製・改変して利用できます。改変版を配布する場合は出典を明記してください。

AIエージェント（Claude Code 等のコーディングエージェント全般）を開発・運用の実務担当として組み込むときの、周囲の仕組み（＝ハーネス）の設計指針。
実プロジェクトの運用で得た原則と教訓を、特定プロジェクトに依存しない形にまとめたもの。
新しいプロジェクトでは、本書をそのまま `docs/` に置き、§11の `<...>` をそのプロジェクトの値で埋める。**ファイルはこれ1つだけ**（別ファイルは作らない）。

本書の読み方：
- **意思決定者・発注側**：「要約」と§4（責任分界）、§6（実動作確認）だけで足りる
- **実装者**：全体。§11のテンプレートと§12の記入済み見本を手元に置いて作業する
- **AIエージェント**：§0の手順に従う

ツール名（CodePipeline、Amplify、GitHub Actions 等）はすべて**例**であり、同じ役割を果たすものに読み替えてよい。

---

## 用語（本書で使う言葉）

| 用語 | 意味 |
|---|---|
| **ハーネス** | AIエージェントを取り巻く仕組みの総称。指示・記憶・権限・自動チェック・検証・作業分担を含む。「お願い」ではなく環境側の強制力 |
| **不変条件** | どんな状況でも破ってはならない技術上のルール（例：鍵をログに出さない）。文章ではなく lint・テスト・フックで止めるべきもの |
| **フック** | AIが道具（コマンド実行・ファイル編集・コミット）を使う前後に自動で走るチェック。条件に反する操作をその場で止められる |
| **承認ゲート** | 本番反映などの重い操作の手前で、人間の承認が無いと先へ進めない仕組み |
| **ワークフロー** | 複数のAIエージェントに作業を分担させ、決まった順序で流す手順。保存して再利用できる |
| **敵対的検証** | 別のエージェントが「指摘を反証する立場」で原文を確認し直す工程。誤検出を落とす |
| **横断レビュー** | 並列に作業した結果を、別の視点で通しで見直す工程。用語の揺れ・実装との食い違い・未更新のテストを拾う |
| **設定の正本** | 環境ごとの設定（ブランチ・デプロイ先・フラグ）の「ここを見れば正しい」と決めた唯一の場所 |
| **実動作確認** | 「止まるはずの仕組み」が実際に止まるかを、本番相当の環境で一度試すこと |

---

## 要約（意思決定者・発注側向け）

**ハーネスとは何か。** AIに開発を任せるとき、「気をつけてね」と頼むのがプロンプト、「テストが通らないと次へ進めない」と仕組みで縛るのがハーネス。成果の差はAIの賢さではなく、この仕組みの有無で決まる。

**3つの原則。**
1. 守らせたいことは文章ではなく仕組みで止める（lint・テスト・権限・フック）
2. 本番反映・インフラ変更・削除・課金の有効化は、AIが準備し人間が承認する
3. 「完了」の定義にテスト通過を含め、AIの自己申告ではなく実行結果を根拠にする

**人間が必ず持つもの。** 本番デプロイの承認、本番データの書き換え判断、秘密情報（APIキー等）の投入、外部契約・法務判断。これ以外はAIに任せてよい。

**発注先・開発チームへの質問。** 「どんなハーネスがありますか」に対して、次が答えられれば健全：
- 本番に反映される前に、人間が承認する箇所はどこか。**その承認が実際にデプロイを止めることを、いつ確認したか**
- AIが触ってはいけない操作は何で、それはAIの自制ではなく設定で止まっているか
- 秘密情報がAIの作業文脈に入らない手順になっているか
- 変更がテストを通過したことを、AIの報告ではなく記録で確認できるか

「気をつけています」「AIが賢いので大丈夫です」は、ハーネスではなく心がけにすぎない。

---

## 0. AIエージェントへ：このファイルを読んだら最初にやること

新規プロジェクトで本書を渡されたAIは、次の手順で**この同じファイルの§11を埋める**。別ファイルは作らない。人間は結果を確認し、判断事項だけ決めればよい。

1. **リポジトリとCI設定を調査**し、§11のうちAIが導ける項目の `<...>` を実際の値に置き換える
   - C（設定の正本）・D（反映経路と確認先）・F（既存ワークフロー）・H（作業の記録の所在）：コードと設定から確定できる
   - A（不変条件）：コードから読み取れる技術的制約を列挙し、「止める仕組み」の有無を添える
2. **AIが決めてはいけない項目は「要決定」として列挙**し、人間に確認する
   - B（権限境界）：本番承認・インフラ変更・秘密投入を「誰が・どの手段で」行うか
   - A のうち事業上の価値判断（何を絶対に守るか）
3. **E（安全境界の実動作確認）は考えるのではなく実行する**。本番ゲートは人間の承認操作を伴うため、手順を提案して実施を依頼し、実施日を記入する
4. G（教訓）は最初は空でよい。事故・ヒヤリが起きた時点で追記する
5. 本ファイルを `CLAUDE.md`（または同等の指示書）から1行で参照させる（例：「ハーネスの境界と前提は `docs/ai-harness-design.md` §11 を正とする」）

判断を求める際は、選択肢と推奨を添える。

**人間が判断できない項目、または「おすすめで」と返された項目は、推奨案で仮決定して先へ進む。** 仮決定した値には「（仮：<YYYY-MM-DD> AI推奨）」と付け、作業の最後に「決めたこと」と「仮決定したこと」を分けて一覧で報告する。迷ったら安全側（AIに任せる範囲を狭くする方）を選ぶ。人間が確認した時点で「仮」を外す。ただし、本番反映・削除・課金・外部契約など取り消せない操作に関わる項目（§4）は仮決定せず、人間の判断を待つ。

空欄のまま「未定」と書く場合は、いつまでに決めるかを必ず付ける。

---

## 1. 考え方

モデルの能力は固定。成果の差は**周囲の仕組み**で決まる。
要点は「**守らせたいことを、文章（お願い）から仕組み（強制）へ移す**」こと。
違反したときの損害が大きいルールほど、指示書に書くだけで済ませず、lint・テスト・権限設定・フックで機械的に止める。
指示書は、判断が必要な事柄のために使う。

ハーネスは「AIを信用しない」ための装置ではなく、**AIに広い裁量を与えても事故にならない**ための装置である。裁量が広いほど速く、境界が明確なほど安全。両立させるのがハーネス設計の目的。

## 2. 基本原則（優先順）

1. **文章から仕組みへ。** 絶対に破ってはならない条件は、機械的に検出・遮断する。
2. **影響の大きい操作は人間が最終承認。** 本番反映・インフラ変更・削除・課金の有効化は、AIが準備し、人間が実行または承認する。
3. **検証を工程に組み込む。** 「完了」の定義に型チェックとテストの通過を含める。AIの自己申告ではなく実行結果を根拠にする。
4. **秘密はAIに渡さない。** APIキー等は担当者が管理画面から直接投入し、AIは値を見ずに形式だけを検証する。
5. **分業と相互検証。** 大きな作業は複数のエージェントに分け、別のエージェントが敵対的に検証してから採用する。

## 3. ハーネスの6層

| 層 | 役割 | 最低限の実装 | 成熟した状態 |
|---|---|---|---|
| **指示** | 守るべき不変条件・優先順位・取り決めを伝える | `CLAUDE.md`（1本に集約・要約＋地図）、現在地サマリ、運用手順書 | 仕様が矛盾したときの優先順位が明記されている。指示書が複数ある場合は1本を正本とし他は参照のみ |
| **記憶・記録** | セッションをまたいで取り決めを引き継ぎ、AIが何をしたかを後から辿れるようにする | 永続メモリ（運用の委任範囲・端末固有の設定・失敗パターン）。作業の記録＝コミット履歴・CI/デプロイの実行記録・承認記録 | 教訓が「次に同じ状況で何をするか」の形で残っている。任意の本番変更について「いつ・誰が承認し・どのビルドが・何を変えたか」を記録だけで再構成できる |
| **権限** | AIが実行できる操作の境界を定める | 本番・削除・秘密変更は確認必須。読み取り系は許可 | 「許可」「確認必須」「禁止」がプロジェクトの設定ファイルで明示され、分類器任せにしない |
| **フック** | 道具の使用前後に自動チェックを走らせる | 秘密情報のスキャン（コミット前・コマンド出力） | 不変条件（例：暗号処理の呼び出し元制限、鍵素材のログ出力禁止）がlint/フックで機械的に止まる |
| **検証** | 変更の正しさを実行結果で確かめる | 型チェック＋自動テスト、変更ごとのCI、本番前の承認ゲート | **安全境界そのものの実動作確認**（§6）が定期的に行われている |
| **分業** | 大きな作業を複数エージェントで分担・相互検証する | その場で組むワークフロー | 繰り返す作業がワークフローとして保存され、最終工程にテスト通過が組み込まれている |

各層は前の層を信用しない前提で重ねる。指示を守らなかった場合も、権限・検証・承認のどこかで止まる設計にする。

## 4. 人間とAIの責任分界

境界は「取り消せるか」と「利用者に届くか」で引く。

| 操作 | AI | 人間 |
|---|---|---|
| コードの変更・テスト・開発環境への反映 | 実行する | 結果を確認 |
| 開発環境の調査・データ作成 | 実行する | — |
| 本番ブランチへの反映 | 準備と事前検査を行う | 反映を指示 |
| 本番デプロイの承認 | 行わない | 承認する |
| 本番インフラの変更・課金の有効化 | コマンドを用意する | 実行する |
| 本番データの書き換え・削除 | 行わない | 事前に判断 |
| APIキー・署名鍵の投入 | 値を見ず形式だけ検証 | 管理画面から直接投入 |
| 外部契約・本人確認・法務判断 | 必要事項を整理 | 実施する |

AIが「できない」操作は、ハーネス側（権限設定・分類器）でも止まるようにし、AI自身の自制に頼らない。

## 5. 標準ワークフロー（多エージェント）

大きなレビューや修正は、次の8工程を基本形にする。人間が関わるのは2点だけ。

```
面別レビュー（並列） → 敵対的検証（並列） → 統合 → [人間：方針確認]
→ ファイル単位で適用（並列・担当ファイル重複なし） → 横断レビュー → 全テスト → [人間：本番承認]
```

設計上の要点：
- **敵対的検証**：別のエージェントが「指摘を反証する立場」で原文を確認し直す。誤検出を落とし、重要度を再評価する。
- **ファイル単位の分担**：同じファイルを2つのエージェントが触らない。並列編集の衝突を構造的になくす。
- **横断レビュー**：修正役が見落とした用語の揺れ・実装と食い違う説明・未更新のテストを拾う。修正役とは別の視点を必ず入れる。
- **全テストを最終工程に組み込む**：修正役は誰もテストを更新しない前提で設計する。

小さな変更（1〜3ファイル）はワークフローを使わず、単独で実装→lint→テストでよい。

## 6. 安全境界の実動作確認

「ゲートがある」という認識と実装が食い違うことがある。設計書・コード・図のすべてに「承認後に反映」と書かれていても、実際には承認を待たずに反映されていた、という事故が起きた。

この種の食い違いは**一度実際に止まるかを試す**ことでしか検出できない。

- 導入時と、パイプライン・権限・フックを変更したときに、必ず「止まるべき操作が止まるか」を実機で確認する
- 確認方法の例：承認前に本番が変わっていないか（タスクの起動時刻・イメージのダイジェスト・設定の更新時刻を承認時刻と比べる）
- 「ゲートを通ったログ」ではなく「ゲートの前で待っている状態」を観測する
- 年に一度、全ゲートの棚卸しを行う

## 7. 秘密情報の扱い

- 秘密はチャット・コマンド引数・エラー出力のどれにも出さない。AIが実行するコマンドの**出力**に秘密が混ざる事故が実際に起きる（検証コマンドのエラーメッセージ経由など）
- 投入は担当者が管理画面から行う。AIは「必要なキーが正しい形式で入っているか」だけを、値を表示しない方法で検証する
- 露出した場合は、実害の有無にかかわらずローテーションする
- 秘密スキャンのフック（コミット前・コマンド出力）を最初に入れる
- **ビルド成果物も検査する。** ソースコードに秘密がなくても、環境変数の設定を誤ると、ビルド時に公開用のファイル（JavaScript のバンドル等）へ自動的に埋め込まれる。公開前のバンドルに対する秘密スキャンを、コミット前スキャンとは別に入れる。公開用の接頭辞（`NEXT_PUBLIC_`、`VITE_`、`REACT_APP_` 等）が付いた環境変数は「公開される」ものとして扱い、秘密を入れない
- **露出した鍵は、消すのではなく無効化する。** ファイルから削除しても、鍵そのものが有効なら使われ続ける。発行元で無効化（ローテーション）するまでは対処が終わっていない

> 参考：スタンフォード大学等の研究者による論文 "Keys on Doormats: Exposed API Credentials on the Web"（2026年）は、1,000万サイトの動的解析で、主要14サービスの有効なAPIキー1,748件が5,693ドメインで閲覧可能だったと報告している。露出の84%は JavaScript ファイル内にあり、その6割以上はビルドで生成されたバンドルの中にのみ存在していた。漏えいした鍵は平均1年放置され、警告後2週間で約半数が削除されたが、無効化まで行われたのは26%だった。
> 出典：ITmedia NEWS「1000万のWebサイトで『生きたAPIキー』が大量に"丸見え"状態？」（2026年10月23日）

## 8. 運用ルール

### 反映の順序
- 新しい設定や秘密を必要とするコードは「インフラ先行→コード反映」の順。逆だと起動失敗で止まる
- 開発環境で確認してから本番へ。本番は承認ゲートを通す

### push後の確認
- push で終わりにしない。CI・ビルド・デプロイの**結果まで確認**する。「pushした」と「反映された」は別
- 複数の自動経路（API・Web など）があれば、すべての結果を見る

### 設定の正本
- 環境ごとの設定（監視ブランチ・デプロイ先・フラグ）は**設定ファイルに明記**し、コマンドライン引数（context）だけに頼らない。引数は一時上書き専用
- 引数だけで指定された設定は、引数を忘れた再デプロイで既定値に戻る

### 設定の書き戻し
- 外部サービスの設定を読んで書き戻すときは、JSON またはファイル経由で改行を保持する。テキスト出力に文字列メソッドを呼ぶと改行が潰れる環境がある
- 上書き前の控えは、上書きに使う変数とは**別経路**で取る
- 書き戻し後は改行数・主要行の存在を検証する

### ログと失敗の可視化
- バックグラウンド実行のコマンドを `| tail` 等で包むと失敗が exit 0 に隠れる。終了コードを明示的に出す
- 環境依存の失敗（認証期限切れ・証明書ローテーション）は前提条件チェックとして手順に組み込む

### 検証の粒度
- インフラ定義を変えたら lint（型）とテストの**両方**を回す。テストランナーは型を見ない
- 並列で修正したエージェントはテストを更新しない前提で、最終工程に全テストを置く

### 作業の記録
- AIの作業は、人間の作業と同じ経路に記録を残す：コミット（何を・なぜ変えたか）、CI/デプロイの実行記録（どのビルドがいつどこへ）、承認記録（誰がいつ承認したか）
- 多エージェントのワークフローは実行記録（各エージェントの入出力）を保存し、「なぜこの修正になったか」を後から辿れるようにする
- コミットメッセージには、変更の理由と検証結果（通ったテストの件数など）を書く。AIが書いたことが分かるよう作者表記を付ける
- 記録は事故の調査に使えてはじめて価値がある。「いつ・誰が承認し・どのビルドが・何を変えたか」を記録だけで再構成できるかを、年1回の棚卸しで確かめる

## 9. 教訓集（汎用化）

| 起きたこと | 原因 | 対策（仕組みへ） |
|---|---|---|
| テスト用の秘密鍵がエラー出力経由でAIの作業文脈に出た | 「出さない」が指示だけだった | 値を出さず形式だけ検証する手順を標準化。秘密スキャンのフック |
| ソースコードには秘密がないのに、公開中のJSバンドルにAPIキーが含まれていた（一般に多い事故） | 環境変数の設定誤り。ビルド成果物を検査していなかった | 公開前のバンドルに秘密スキャンを追加。公開用接頭辞の環境変数に秘密を入れない（§7） |
| 並列修正したエージェントがテストを更新せず、後で大量に失敗 | 検証が工程に含まれていなかった | 横断レビュー＋全テストを最終工程に固定 |
| 修正役が実装と異なる説明文を書いた | 文言の修正役が実装を確認しなかった | 検証役にコードとの突合を義務化 |
| 承認ゲートが実はデプロイを止めていなかった | 認識と実装の食い違い。誰も「止まるか」を試していなかった | 承認の**後**にデプロイする順序をパイプライン定義で強制。安全境界の実動作確認（§6） |
| 再デプロイで監視ブランチが既定値に戻り、自動ビルドが止まった | ブランチが引数でしか指定されず、手順も未記録 | 設定ファイルを正本にし、テストで固定 |
| 外部サービスの設定を改行なしで上書きした | テキスト出力に文字列メソッドを呼び、改行が潰れた | JSON/ファイル経由に限定。書き戻し前に改行数を検証。控えは別経路 |
| Webのビルドが1か月以上失敗していたのに気づかなかった | push後の結果確認をしていなかった | 「反映の結果まで確認」を手順に。複数経路すべてを見る |
| 認証期限切れで作業が何度も中断 | 前提条件を確認する仕組みがなかった | 事前チェックを手順に組み込む |
| 指示同士の矛盾（モック準拠 vs 最新設計書優先）で古い文言が温存された | 優先順位が未定義 | 指示書に優先順位を明記 |

教訓は「何が起きたか」ではなく「次に同じ状況で何をするか」の形で、記憶層（永続メモリ）と運用手順書の両方に残す。

## 10. 導入ロードマップ

新規プロジェクトでは次の順で入れる。フェーズ1は半日で入る。

**フェーズ1：事故を仕組みで防ぐ**
- 秘密スキャンのフック（コミット前・コマンド出力・公開前のビルド成果物）
- 権限ルールの明文化（許可／確認必須／禁止）
- プロジェクト固有の不変条件のlint化
- 本番承認ゲートの**実動作確認**

**フェーズ2：繰り返しを資産化する**
- 標準ワークフロー（§5）の保存と再利用
- 運用手順（環境リセット・デプロイ・認証）のスキル化
- 指示書の一本化、優先順位の明記

**フェーズ3：外部の目で確かめる**
- 未点検領域のセキュリティスキャン
- 外部ペネトレーションテスト・第三者監査
- 四半期ごとの見直し（ゲートの棚卸しを含む）

---

## 11. 適用テンプレート（プロジェクトごとに埋める）

### 使い方

1. 本ファイルをプロジェクトの `docs/` に置く（別ファイルは作らない。この§11をそのまま編集する）
2. 各項目の **「何を書くか」「なぜ必要か」「記入例」** を読み、`<...>` を自分のプロジェクトの値に置き換える。説明文は残しても消してもよい
3. 分からない項目は空欄にせず、推奨案で仮決定して「（仮）」と付けるか、「未定（<いつまでに決めるか>）」と書く。空欄は「決めた」のか「忘れた」のか区別できない。「仮」の付いた項目は、次の見直しまでに確定させる
4. 書き終えたら、項目Eの「実動作確認」を実際に一度行い、日付を入れる。ここまでが導入の完了
5. 以後、事故・ヒヤリが起きたら項目Gに追記し、設定を変えたら該当項目を更新する

AIエージェントにこのファイルを読ませれば、プロジェクトの境界と前提を一度で伝えられる。
指示書（`CLAUDE.md` など）からは本ファイルへの参照を1行書くだけでよい。

### 対象プロジェクト

- プロジェクト名：<プロジェクト名>
- 最終更新：<YYYY-MM-DD>　担当：<氏名>

## A. 不変条件

**何を書くか**：このプロジェクトで「AIが作業しても、人間が作業しても、絶対に破ってはならない」技術上のルール。
**なぜ必要か**：破ると取り返しがつかない（データ漏えい・資産消失・法令違反）ルールを、指示書の文章ではなく lint・テスト・フックで機械的に止めるため。ここに書いたものは、必ず「止める仕組み」とセットにする。
**書き方**：1行1ルール。「何を」「どこで」「どう止めるか」を揃える。仕組みが未整備なら「止める仕組み：未整備（<期限>）」と正直に書く。
**記入例**：
- 暗号処理は `packages/crypto` 経由でのみ呼ぶ ／ 止める仕組み：ESLint の import 制限ルール
- 鍵・トークンに当たる変数（`*Key`, `*Secret`, `*Token`）を `console.*` に渡さない ／ 止める仕組み：ESLint カスタムルール
- 本番DBへの直接 UPDATE/DELETE をしない ／ 止める仕組み：本番DB接続情報をAIの権限から外す

- <ルール1> ／ 止める仕組み：<lint名・フック名・権限設定、または「未整備（期限）」>
- <ルール2> ／ 止める仕組み：<...>

## B. 権限境界（AIができること・人間がやること）

**何を書くか**：操作ごとに「AIが実行してよいか」「人間が何をするか」の対応表。
**なぜ必要か**：AIに任せる範囲が曖昧だと、速さと安全の両方を失う。境界を決めておけば、AIは境界の内側で遠慮なく動け、外側は確実に人間に回る。
**書き方**：「取り消せない操作」「利用者に届く操作」「お金・契約・法務が絡む操作」は必ず人間側に置く。承認の「手段」（管理画面のボタン・コマンド・口頭）まで具体的に書く。表にない操作はAIが「確認必須」として扱う前提にする。
**記入例**：「本番デプロイ承認 | 行わない | CodePipeline の承認ボタン（担当：<氏名>）」。GitHub Actions なら environment の protection rules、GitLab なら manual job が同じ役割

| 操作 | AI | 人間 |
|---|---|---|
| コード変更・テスト・開発環境への反映 | 実行する | 結果を確認 |
| 本番ブランチへの反映 | 準備と事前検査 | 反映を指示 |
| 本番デプロイの承認 | 行わない | <承認手段・担当者> |
| 本番インフラの変更 | コマンドを用意 | <実行者> が実行 |
| 本番データの書き換え・削除 | 行わない | <判断者> が事前に判断 |
| APIキー・署名鍵の投入 | 値を見ず形式のみ検証 | <管理画面名> から直接投入 |
| 外部契約・本人確認・法務判断 | 必要事項を整理 | <担当者> |
| <プロジェクト固有の操作> | <...> | <...> |

## C. 設定の正本

**何を書くか**：環境ごとの設定（ブランチ・デプロイ先・機能フラグ・外部サービスの接続先）が「どのファイルに」書かれているか。
**なぜ必要か**：コマンドライン引数や管理画面の手入力だけで決まっている設定は、引数を忘れた再実行や別の人の操作で既定値に戻る。「ここを見れば正しい値が分かる」場所を1つに決めておく。
**書き方**：設定の種類ごとに「正本のファイルパス」と「現在の値」を書く。管理画面にしか存在しない設定があれば、それも「正本：<画面名>（控え：<リポジトリ内のパス>）」として書く。
**記入例**：「CI が監視するブランチ：`infra/lib/config.ts` の `pipelineBranch`（dev=`develop` / prod=`main`）」

| 設定 | 正本の場所 | 現在の値 |
|---|---|---|
| 環境別の設定ファイル | <パス> | — |
| CI が監視するブランチ | <パス・項目名> | dev=<branch> / prod=<branch> |
| デプロイ先（本番） | <パス・項目名> | <クラスタ名・サービス名など> |
| 外部サービス側に保存されている設定 | 正本：<画面名>／控え：<リポジトリ内のパス> | <値または「画面参照」> |
| <その他> | <...> | <...> |

## D. 反映経路と結果の確認先

**何を書くか**：コードを push したあと、どの経路で何が自動で起き、結果をどこで確認するか。
**なぜ必要か**：「push した」と「反映された」は別。確認先が決まっていないと、ビルドが失敗したまま何週間も気づかない。経路が複数（API・Web・バッチなど）あるなら、すべて書く。
**書き方**：経路ごとに1行。「確認する人」も書く（AIが確認するなら「AI（push 直後）」）。
**記入例**：「Web | `develop` への push | Amplify コンソールのジョブ一覧 | AI（push 直後に結果まで確認）」（Vercel・Netlify・GitHub Actions でも同様に「結果を見る画面」を書く）

| 経路 | トリガー | 結果の確認先 | 確認する人 |
|---|---|---|---|
| API | <push 先ブランチ> | <CI名・画面> | <AI／氏名> |
| Web | <push 先ブランチ> | <ビルドサービス名・画面> | <AI／氏名> |
| インフラ | <コマンド> | <CloudFormation 等の画面> | <氏名> |
| <その他> | <...> | <...> | <...> |

## E. 安全境界の実動作確認

**何を書くか**：項目A・Bで決めた「止まるべきもの」が、実際に止まることを確かめた日付と方法。
**なぜ必要か**：設計書にもコードにも「承認後に反映」と書いてあるのに、実際には承認を待たずに反映されていた、という事故は起きる。認識と実装の食い違いは、一度実際に試す以外に検出できない。
**書き方**：ゲートごとに「最終確認日」「確認方法」「次回予定」。確認方法は「ゲートを通ったログ」ではなく「ゲートの手前で止まっている状態を観測した方法」を書く。導入時に必ず一度行い、以後はゲートの設定を変えたときと年1回。
**記入例**：「本番承認ゲート | 2026-10-23 | 承認前に本番タスクの起動時刻が変わらないことを確認し、承認後に起動時刻が更新されることを確認 | 2027-10」

| ゲート | 最終確認日 | 確認方法 | 次回予定 |
|---|---|---|---|
| 本番承認ゲート | <YYYY-MM-DD または「未実施」> | <方法> | <年月> |
| 秘密スキャン（コミット前） | <...> | <わざとダミーの鍵を含めてコミットが拒否されることを確認、など> | <...> |
| 秘密スキャン（ビルド成果物） | <...> | <ダミーの鍵を環境変数に入れてビルドし、公開用ファイルに含まれないこと、または検査で止まることを確認、など> | <...> |
| 権限ルール（禁止操作） | <...> | <禁止した操作をAIに依頼し、止まることを確認、など> | <...> |
| <その他のゲート> | <...> | <...> | <...> |

## F. 保存済みワークフロー

**何を書くか**：繰り返し使う多エージェント作業（レビュー・一括修正・監査など）の名前と用途。
**なぜ必要か**：その場で組んだワークフローは再利用できない。保存しておけば、次回は同じ品質で一発で回せる。
**書き方**：「名前」「用途」「保存場所」「最終工程にテスト通過が含まれているか（必須）」。
**記入例**：「全画面コピーレビュー | 公開前の文言点検（法務・トーン・用語） | `.claude/workflows/copy-review.js` | 含む」

| 名前 | 用途 | 保存場所 | 最終工程にテスト通過 |
|---|---|---|---|
| <名前> | <用途> | <パス> | <含む／含まない→含めるよう修正> |

## G. 教訓（このプロジェクト固有）

**何を書くか**：このプロジェクトで実際に起きた事故・ヒヤリと、その対策。
**なぜ必要か**：同じ失敗を、人が代わっても・AIのセッションが変わっても繰り返さないため。
**書き方**：「起きたこと」「原因」「対策」の3列。対策は「気をつける」ではなく「次に同じ状況で何をするか」または「何を仕組みで止めたか」の形で書く。汎用版の§9に昇格させる価値があるものは、汎用版にも追記する。
**記入例**：「再デプロイで監視ブランチが既定値に戻った | ブランチが引数でしか指定されていなかった | 設定ファイルに明記し、テストで固定」

| 起きたこと | 原因 | 対策（次に何をするか／何を仕組みで止めたか） |
|---|---|---|
| <...> | <...> | <...> |

## H. 作業の記録の所在

**何を書くか**：AIと人間の作業が「どこに」記録され、「どう辿れるか」。
**なぜ必要か**：事故が起きたとき、「いつ・誰が承認し・どのビルドが・何を変えたか」を記録から再構成できなければ原因も責任も分からない。記録の場所が散らばっていると、必要なときに探せない。
**書き方**：記録の種類ごとに「場所」「保持期間」「誰が見られるか」。AIのワークフロー実行記録も含める。
**記入例**：「本番の承認記録 | CodePipeline の実行履歴 | 1年（AWS既定） | 運用担当」

| 記録の種類 | 場所 | 保持期間 | 閲覧者 |
|---|---|---|---|
| コード変更（何を・なぜ） | <Git リポジトリ・コミットメッセージ> | 永続 | <全員> |
| CI・デプロイの実行記録 | <CI サービス名・画面> | <期間> | <...> |
| 本番の承認記録 | <パイプラインの実行履歴など> | <期間> | <...> |
| AI ワークフローの実行記録 | <保存先パス・サービス> | <期間> | <...> |
| 本番の操作ログ（監査ログ） | <CloudTrail・Cloud Audit Logs 等> | <期間> | <...> |

## 12. 記入済み見本（架空のプロジェクト）

§11を埋めるとどうなるかの見本。個人の機微情報を端末内で暗号化して預かるサービス（運営者も中身を読めない設計）を想定した架空の例で、固有名はすべて仮のもの。粒度の参考にし、§11を埋め終えたらこの節は削除してよい。

```markdown
### 対象プロジェクト
- プロジェクト名：個人データ保管サービス「サンプル」
- 最終更新：2026-10-23　担当：山田

## A. 不変条件
- 平文の機微情報・鍵を、サーバへ送らない／保存しない／ログに出さない ／ 止める仕組み：ESLint ルール（`*Key`,`*Secret` を `console.*` に渡すと失敗）＋コミット前の秘密スキャン
- 暗号処理は `packages/crypto` 経由でのみ呼ぶ ／ 止める仕組み：ESLint の import 制限（他パッケージから暗号ライブラリを直接 import すると失敗）
- 運営の復号鍵（恒久値）を変更しない ／ 止める仕組み：未整備（2026-11 までに変更検知アラートを追加）
- 本番DBへの直接 UPDATE/DELETE をしない ／ 止める仕組み：本番DB接続情報をAIの権限から外す（開発環境のみ付与）

## B. 権限境界
| 操作 | AI | 人間 |
|---|---|---|
| コード変更・テスト・開発環境への反映 | 実行する | 結果を確認 |
| 本番ブランチへの反映 | 準備と事前検査 | 山田が反映を指示 |
| 本番デプロイの承認 | 行わない | CodePipeline の承認ボタン（山田） |
| 本番インフラの変更 | コマンドを用意 | 山田が実行 |
| 本番データの書き換え・削除 | 行わない | 山田が事前に判断 |
| APIキー・署名鍵の投入 | 値を見ず形式のみ検証 | Secrets Manager の画面から山田が直接投入 |
| 外部契約・本人確認・法務判断 | 必要事項を整理 | 山田 |
| 利用者へ届く文言の変更 | ドラフトと検証 | 公開前に山田がレビュー |

## C. 設定の正本
| 設定 | 正本の場所 | 現在の値 |
|---|---|---|
| 環境別の設定ファイル | `infra/lib/config.ts` | — |
| CI が監視するブランチ | 同上 `pipelineBranch` | dev=`develop` / prod=`main` |
| デプロイ先（本番） | 同上 `prod` ブロック | ECS クラスタ `app-prod` |
| Web ビルド設定 | 正本：Amplify コンソール／控え：`amplify-buildspec.yml` | 画面参照 |

## D. 反映経路と結果の確認先
| 経路 | トリガー | 結果の確認先 | 確認する人 |
|---|---|---|---|
| API | `develop` への push（dev）／`main` への push（prod） | CodePipeline の実行履歴 | AI（push 直後に結果まで） |
| Web | 同上 | Amplify のジョブ一覧 | AI（push 直後に結果まで） |
| インフラ | `cdk deploy`（手動） | CloudFormation のスタック画面 | 山田 |

## E. 安全境界の実動作確認
| ゲート | 最終確認日 | 確認方法 | 次回予定 |
|---|---|---|---|
| 本番承認ゲート | 2026-10-23 | 承認前に本番タスクの起動時刻が変わらないことを確認し、承認後に更新されることを確認 | 2027-10 |
| 秘密スキャン（コミット前） | 未実施 | ダミーの鍵を含めたコミットが拒否されることを確認する予定 | 2026-11 |
| 秘密スキャン（ビルド成果物） | 未実施 | ダミーの鍵を環境変数に入れてビルドし、配信ファイルを検査して止まることを確認する予定 | 2026-11 |
| 権限ルール（本番DB直接操作） | 未実施 | AIに本番DBの更新を依頼し、権限で止まることを確認する予定 | 2026-11 |

## F. 保存済みワークフロー
| 名前 | 用途 | 保存場所 | 最終工程にテスト通過 |
|---|---|---|---|
| 全画面コピーレビュー | 公開前の文言点検（法務・トーン・用語） | `.claude/workflows/copy-review.js` | 含む |
| セキュリティ修正の適用と検証 | 脆弱性対応の実装→敵対的レビュー→全テスト | `.claude/workflows/security-fix.js` | 含む |

## G. 教訓
| 起きたこと | 原因 | 対策（次に何をするか／何を仕組みで止めたか） |
|---|---|---|
| 承認ゲートがデプロイを止めていなかった | デプロイがビルド工程内で実行され、承認がその後ろにあった | 承認の後にデプロイ工程を置く構成へ変更し、承認前に本番が変わらないことを実機で確認した |
| 再デプロイで監視ブランチが既定値に戻った | ブランチが引数でしか指定されていなかった | 設定ファイルに明記し、テストで固定 |
| 外部サービスの設定を改行なしで上書きした | 複数行の出力に文字列メソッドを呼び、改行が潰れた | 設定の書き戻しは JSON／ファイル経由に限定。書き戻し前に改行数を検証 |

## H. 作業の記録の所在
| 記録の種類 | 場所 | 保持期間 | 閲覧者 |
|---|---|---|---|
| コード変更（何を・なぜ） | GitHub リポジトリのコミット（AI作者表記あり） | 永続 | 全員 |
| CI・デプロイの実行記録 | CodePipeline／Amplify の実行履歴 | 1年 | 運用担当 |
| 本番の承認記録 | CodePipeline の承認履歴 | 1年 | 運用担当 |
| AI ワークフローの実行記録 | `.claude/` 配下の実行ログ（セッション単位） | 90日 | 開発担当 |
| 本番の操作ログ | CloudTrail | 1年 | 運用担当 |
```

## 13. 更新方針

- 事故・ヒヤリが起きたら、§9（教訓集）と該当プロジェクトの§11-G（教訓）に追記する
- フェーズの施策を実施したら、§11-E（実動作確認）の「最終確認日」と「最終更新」を更新する
- 本書（汎用版）は四半期に一度、各プロジェクトの教訓を取り込んで改訂する