— なぜ作り、どこで間違え、どう直したか
作ったもの
カオスエンジニアリングの実験プロセスそのものを体験するための学習アプリを作りました。
Next.js 単体で動き、アプリの中に EC サイト風の小さなシステム(Order API → Payment API)が入っています。Payment API に遅延やエラーを注入し、Order API がそれに耐えられるかを実験します。
大事なのは、これが障害注入ツールではないことです。仮説を立て、実測し、記録し、比較し、改善してもう一度試す — その一連のループを回すための「実験管理アプリ」として作りました。
規模はコード約 4,000 行、テスト約 800 行。開発は Claude Code と一緒に、1か月半ほどのあいだに 4 セッションに分けて進めました。
この記事では、なぜそう作ったのか・途中で何を間違えたのか・AI とどう役割分担したのかを順に書きます。うまくいった話だけでなく、作ったものが根本的に間違っていたと気づいた回のことも含めて書きます。
1. なぜ作ったのか
「壊れたらどうなるか」に答えられなかった
今のシステムは、API・データベース・キャッシュ・外部サービスがネットワーク越しに繋がった集合体です。部品が個々に正常でも全体が壊れることがあり、しかも「壊れるかどうか」ではなく**「いつ壊れるか」**の世界です。
「決済 API が2秒遅くなったら、注文は通りますか」と聞かれて、自信をもって答えられるでしょうか。私は答えられませんでした。
コードを読めば「タイムアウトが1秒だから厳しそうだ」までは言えます。でも、リトライ込みで実際どうなるのか、ユーザーから見た成功率が何 % になるのか、他の機能まで巻き込まれるのかは分かりません。読めば分かるはずなのに、実際どうなるかは言えない。 この状態を埋めるための手法がカオスエンジニアリングです。予測ではなく、実測で答える。
SRE の文脈で広く語られるようになり、AWS FIS のようなマネージドサービスも出てきて、手を出すハードルは下がっています。学んでおいて損はない、というのが出発点でした。
原則を読んでも、手が動かなかった
ところが、原則を読んでも「分かった気」で止まります。Principles of Chaos Engineering の5原則は正しいのですが、正しすぎて手が動きません。
理由ははっきりしていて、この手法で一番難しいのは障害を起こすことではないからです。難しいのはその前後です。
- 「システムが正常」を、どの数値で定義するのか
- 何が起きると予想しているのか、それを実験の前に言えるか
- 結果が出たとき、それは障害のせいなのか、元からそうだったのか
- 反証されたとして、次に何を直せばいいのか
既存の障害注入ツール(Chaos Mesh、AWS FIS、Toxiproxy)はどれも優れていますが、これらは「障害を注入する」ためのもので、この4つを教えてくれるものではありません。 逆に言えば、この4つさえ回れば、注入の手段は後から差し替えられます。
だから、作りながら学ぶことにした
そこで、カオスエンジニアリングのプロセスそのものをアプリとして実装することにしました。読んで学ぶのではなく、作って学ぶ。
遠回りに見えますが、これはかなり効率のいい方法です。理由は単純で、アプリとして実装するには、概念を曖昧なままにしておけないからです。
- 「定常状態」を画面の入力項目にするには、それが何個の数値で表せるのかを決めないといけない
- 「仮説が支持されたか」を判定する関数を書くには、支持の条件を式にしないといけない
- 「改善候補を出す」機能を作るには、どの障害にどの対策が効くのかを自分が理解していないといけない
最後の一つでは、実際に後で痛い目を見ました(5節)。理解が足りないまま実装すると、動くけれど間違っているものができあがります。そしてそれは、動かしてみるまで気づけません。
分かったつもりの部分は、実装しようとすると必ず手が止まる。 これが「作りながら学ぶ」の一番の効用でした。
その結果として、アプリの中心は障害注入ではなく「実験管理」になりました。扱う概念はすべて画面上の入力項目になっています。定常状態、仮説、障害条件、中止条件、レジリエンスポリシー、復旧手順。フォームを埋める行為が、そのまま実験計画を立てる練習になるように作っています。
2. コードを書く前に、規約を書いた
最初にやったのは、実装ではなく CLAUDE.md を書くことでした。287 行あります。
内容は、コーディング原則(YAGNI / KISS / DRY)、関数とモジュールの方針、コメントのルール、エラーハンドリング、命名、ドキュメントの種類と置き場所、TDD のサイクル、ブランチ戦略、コミットメッセージ規約、PR のガイドライン。
あわせて .claude/ 以下も用意しました。
| 種類 | 中身 | 狙い |
|---|---|---|
| agents |
code-reviewer / tdd-coach
|
レビューと TDD を独立した視点でやらせる |
| commands |
/tdd /review /docs /pr
|
繰り返す作業を毎回説明しなくて済むようにする |
| hooks | guard-bash.sh |
git push --force と git commit --no-verify をブロックする |
なぜ実装より先に規約なのか。 AI は指示がなければ「一般的に良さそうなコード」を書きます。それは悪いコードではありませんが、プロジェクト固有の美意識は含まれていません。
特に、明示しないと必ず盛られるものがあります。
-
コメント — 放っておくと「何をするか(WHAT)」の説明が付きます。
CLAUDE.mdには「デフォルトはコメントなし。WHY が自明でない場合のみ」と書きました - エラーハンドリング — 起こりえない分岐にも防御的なコードが足されます。「起こりえないシナリオのエラーハンドリングは追加しない」と明記しました
- 抽象化 — 似たコードが2箇所あると共通化されます。「似たようなコードが3行あっても、それは早期抽象化より良い」と書きました
これらは好みの問題であって、絶対の正解があるわけではありません。だからこそ、自分の好みを先に文章にしておかないと伝わりません。
結果として、この 287 行は何度も効きました。実装のたびに「コメントを減らして」と言う必要がなくなり、レビューの指摘も「規約のここに反している」という具体的な形になりました。
3. 第1セッション — MVP を作る
グリーンフィールドから、実験ループが1周する最小構成を作りました。
設計判断は ADR に残す
このプロジェクトでは、重要な技術的判断を docs/adr/ に記録するルールにしています。MVP の時点で 3 件書きました。
ADR 0001: 単一 Next.js アプリ内でシミュレートする
ターゲットシステムの構成には 3 案ありました。
- A. 単一 Next.js プロセス内に Order/Payment を実装
- B. Payment を別サービスに分離し、実ネットワーク越しに障害注入
- C. 完全インメモリ模擬(HTTP 経路すら持たない)
A を選びました。理由は、npm run dev 一つで動くのでセットアップの摩擦が最小であること。そして C のように数値を捏造しないことです。
これは重要な線引きでした。学習アプリだからといって「成功率 0% ということにする」と表示してしまうと、それは紙芝居です。障害はサーバー側で実際に発生させ、表示されるレイテンシーはすべて実測値にする、と決めました。
ADR 0003: 障害はサーバー側、負荷はクライアント駆動
もう少し細かい判断です。負荷生成を「クライアントから固定数の並列ワーカーで撃ち続ける閉ループ」にしました。
サーバー側で固定 RPS を出す方式(オープンループ)にしなかったのには理由があります。依存が遅くなったとき、閉ループならスループットが自然に落ちます。 オープンループだとキューが無限に積み上がるだけで、現実のユーザー体験とはズレた挙動になります。「遅くなると処理できる注文数が減る」という体感は、閉ループでないと出ません。
詰まったところ
素直には進みませんでした。
-
Prisma 7 が
datasource urlを非対応になっていた(driver adapter +prisma.config.tsが必須)。MVP には過剰なので Prisma 6 に固定し、その判断を ADR 0002 に残した -
Docker が Windows 側から叩けない環境だった。DB を伴う確認は WSL 側でやる方針にして、
docker-compose.ymlと手順だけ用意した -
create-next-appが既存のCLAUDE.mdと競合した。一時退避 → scaffold → 復元で回避
3つ目は些細ですが、1つ目と2つ目は「AI の学習データが古い」「環境が特殊」という、AI と作るときに必ず出る種類の詰まりです。どちらも実際に動かして初めて分かったもので、事前の設計では防げませんでした。
TDD を強制する
純粋ロジックは全部テストファーストで書きました。percentile、computeMetrics、evaluateVerdict、shouldAbort、placeOrder(timeout レース + retry + backoff)、入力バリデーション。
CLAUDE.md に「Red をスキップすると、テストが実際に振る舞いを検証していない可能性がある」と書いてあるので、失敗するところを見せてから実装させる運用にしました。これは地味に効きます。テストが最初から通ってしまう場合、たいていテストが何も検証していません。
この時点で 47 テスト。設計としては、純粋ロジックを src/lib に集め、副作用を src/server の境界に寄せる形にしました。結果として src/lib は 561 行で、ほぼ全部がテスト対象です。
4. セッションをまたぐための記録
AI は前回のセッションの記憶を持ちません。作業を分けて進める以上、毎回コンテキストを渡し直す必要があります。
ここで効いたのが docs/worklog.md です。1エントリ = 1作業セッションで、次の形式で残しています。
## YYYY-MM-DD <タイトル>
### 背景 / ゴール
### やったこと(時系列)
### 詰まった点と対処
### 検証結果
### 次にやること
これは人間のための記録であると同時に、AI のコンテキスト復元装置として書いています。 再開時にこれを読ませるだけで、「何を作りかけているのか」「なぜその選択をしたのか」「次に何をする予定だったのか」が一度に伝わります。
ADR も同じ役割を果たします。「なぜ Prisma 6 なのか」は、書いていなければ次のセッションで確実に 7 に上げようとします。
ただし、記録を過信しないほうがいいとも思いました。あるとき前回のログには「DB を伴う E2E は未実施」と書いてあったのですが、実際に DB を覗いてみると実行結果が 1 件残っていました。ログの記述のほうが間違っていたわけです。記録はコンテキストの入口としては優秀ですが、可能なら実物を確認したほうがいい、という当たり前の教訓でもあります。
5. 山場 — AI が、自分の作ったものの欠陥を見つけた
この回の本題は「アプリ内に学習コンテンツを追加する」でしたが、その前の現状確認で、もっと重大な問題が見つかりました。
シードされている実験はこういう設定です。
- 障害: Payment API に 2000ms の遅延を 100% の確率で
- ポリシー: タイムアウト 1000ms / リトライ 1回 / バックオフなし
- 仮説: 注文成功率 95% 以上を維持できる
当然、仮説は反証されます。2秒待たないと返ってこない相手を1秒で打ち切るので、成功率は 0% になります。ここまでは設計どおりで、「まず失敗を見せる」という意図です。
問題はその次でした。結果画面が出す「改善候補」が、こうなっていたのです。
- 指数バックオフを実装し、リトライの集中を避ける
- サーキットブレーカーを導入し、障害の伝播を止める
どちらも、この障害には効きません。
毎回必ず2秒遅れる相手に対して、リトライの間隔を空けても結果は変わりません。サーキットブレーカーを入れても、成功率が上がるわけではありません。効くのはただ一つ、タイムアウトを遅延より長くすることだけです。
つまり、アプリが出す助言どおりに直しても、仮説が支持されることは永久にありません。学習ループが構造的に閉じていなかった。
このアプリの存在理由は「改善して再検証するループを体験すること」だったので、これは機能の不足ではなく、目的の未達です。
なぜ単体テストでは見つからなかったのか
suggestImprovements にはテストが付いていました。「リトライが0回のとき、リトライ追加を提案すること」のようなテストです。そして全部通っていました。
関数は仕様どおりに動いていて、仕様のほうが間違っていました。
この種の欠陥は、テストでは見つかりません。「この関数は正しいか」ではなく「この関数はアプリの目的を果たしているか」という問いが必要で、それには一段上から全体を眺める視点が要ります。
どう直したか
改善候補の生成に、障害条件そのものを渡すようにしました。
- 遅延がタイムアウト以上なら、タイムアウトの延長を先頭で提案する(「タイムアウトを 2500ms に延ばす」のように具体的な数値を出す)
- 同じ状況で「タイムアウトの短縮」は提案しない(排他にする)
- 常時発生する遅延がタイムアウトを超えるなら、効果のない指数バックオフは提案しない
あわせて explainOutcome という関数を新しく作り、「なぜこうなったか」を障害条件とポリシーの関係から4ステップで説明するようにしました。
1. Payment API へのすべての呼び出しに 2000ms の遅延を注入した
2. Order API は 1000ms で待機を打ち切るため、2000ms 後に返る応答は受け取れない
3. リトライ 1 回も同じ遅延に当たるため、待ち時間が増えるだけで成功しない
4. 結果として注文成功率は 0.0%、P95 レイテンシーは 2050ms になった
数値はすべて実測値と実際の設定から埋めています。「なぜ壊れたか」を自分で推理しなくてよくなり、同時に「だからタイムアウトを延ばすのだ」という次の一手にも繋がります。
6. 「初学者が自力で1周できるか」という問い直し
次のセッションでは、初歩の初歩から学べるようにしたいという観点で全体を見直しました。
ここが、この開発で一番はっきりと役割分担が出たところです。「誰のために作っているのか」を問い直すのは人間の仕事でした。AI は言われたものを作りますが、言われていない観点で作ったものを疑うことはしません(頼めばやりますが、頼むのは人間です)。
観点を与えた上でレビューさせると、4つの穴が出てきました。
穴1: 平常時を測る手段がない
カオスエンジニアリングの第一歩は「壊す前に、正常時の数値を測る」ことです。ところがこのアプリは、実行画面を開いた時点で必ず障害が入る作りでした。定常状態は実験作成時に入力する目標値でしかなく、どこにも実測値がなかったのです。
これだと「成功率が 0% になった」と言われても、それが障害のせいなのか元からなのかを学習者が自分で確かめられません。
そこで実行画面を2ステップに変えました。
- 壊れていない状態を測る(障害なし・20秒)
- 障害を注入して測る
ベースラインは仮説判定の対象外にしました(verdict は null)。判定するものがないからです。測定後は、グラフに平常時の値が基準線として重なり、各数値の下に「平常時 100.0%」が併記されます。
小さな作り込みですが、「壊れた」が初めて体感になるのはここです。
穴2: 障害の種類が1つしかない
シードされていたのは遅延実験だけでした。これでは「リトライが効く / 効かない」という、この分野で最初に気づくべきことに到達できません。
シナリオを3本に増やし、それぞれ到達点が違うように設計しました。
| シナリオ | 障害 / 初期ポリシー | 学べること |
|---|---|---|
| 遅延 | 2000ms を 100% / タイムアウト 1000ms | タイムアウト延長しか効かない |
| 全面エラー | HTTP 500 を 100% / リトライ 1 | リトライが効かない障害がある |
| 間欠エラー | HTTP 500 を 30% / リトライ 0 | リトライが効く障害もある |
3本目がポイントです。リトライ0回だと成功率は約 70%(30% が失敗するので)。リトライを2回に増やすと、3回とも失敗する確率は 0.3³ = 2.7% なので、成功率は約 97% まで戻り、判定が反証から支持に変わります。
数字の上でそうなるだけでなく、実際に実験を回すとその通りになります。「同じエラーでも発生率で効く対策が変わる」を実測で確かめられるのが狙いです。
穴3: 改善のたびにフォームを再入力していた
結果画面の「改善する」リンクは、空の新規作成フォームに飛んでいました。10項目を再入力しろということです。初学者はここで確実に脱落します。
/experiments/[id]/improve という専用画面を作りました。ここでは障害条件・仮説・定常状態は読み取り専用で表示され、編集できるのはタイムアウト・リトライ・バックオフの3つだけです。
これは手間を省くためだけの機能ではありません。「1回の実験で変えるのは1つだけ」という作法を、UI として強制しています。
科学の実験と同じで、比較できるのは他の条件が揃っているときだけです。障害条件を変えながらポリシーも変えたら、成功率が戻った理由を説明できません。文章で「1つだけ変えましょう」と書くより、変えられないようにするほうが確実です。
穴4: before / after を並べて見られない
改善が「別の実験を新規作成する」形になっていたため、改善前後の結果が別々の実験にぶら下がり、並べようがありませんでした。
Experiment.parentId(自己参照)を足して、改善案が元の実験に紐づくようにしました。その上で比較ビューを作り、系譜(元の実験+そこから派生した改善案)の全実行を時系列で1つの表にしました。
ベースライン タイムアウト1000ms 100.0% 20ms —
障害注入 タイムアウト1000ms 0.0% -100.0pt 2050ms 反証
障害注入 タイムアウト2500ms 99.2% +99.2pt 2010ms 支持
「平常時 → 壊れたとき → 直したあと」が縦に読めます。差分は1つ上の行との比較です。
データモデルの判断も ADR に
このとき ExperimentRun.phase(baseline / chaos)と Experiment.parentId を追加したので、ADR 0004 を書きました。
書き残したのは主に「なぜそうしなかったか」です。
-
なぜ
phaseを既存のstatusに相乗りさせなかったか —statusは「どう終わったか」(completed / aborted)で、「何を測ったか」とは直交します。混ぜると「中止されたベースライン」が表現できなくなります - なぜ改善をポリシーの上書きにしなかったか — 実験は記録です。あとから条件を書き換えたら、過去の結果の解釈が壊れます
- なぜベースラインを別の実験にしなかったか — ベースラインは「この実験の基準値」であって、独立した実験ではないからです
この「検討したが選ばなかった案」は、書いておかないと次のセッションで必ず蒸し返されます。
7. アプリの中に教科書を入れた
最後のセッションで、学習ガイドを1ページから全9章に拡張しました。
| 章 | 内容 |
|---|---|
| 1. なぜ壊すのか | カスケード障害、テストとの対比 |
| 2. 5つの原則 | Principles of Chaos Engineering |
| 3. 実験の進め方 | 7ステップと、各ステップで踏む地雷 |
| 4. 何を壊すのか | 障害パターンの地図、注入点の選び方 |
| 5. 守る側の道具 | タイムアウト / リトライ / バックオフ + ジッター / サーキットブレーカー / バルクヘッド / フォールバック / 冪等性 |
| 6. 安全に壊す作法 | ブラストラジウス、中止条件、可観測性、ゲームデイ |
| 7. このアプリで試す | 構造、シナリオ、再現していないこと |
| 8. 現場へ持ち出す | 最初の一歩、SLO との関係、実ツール |
| 9. 用語集 | 実験の文脈つきで引ける用語集 |
なぜ外部記事へのリンク集にしなかったのか。 学習の途中でタブを移動すると、戻ってこないからです。「タイムアウトって何だっけ」と思った瞬間にその場で読めて、読んだらすぐ実験に戻れる、という距離感を作りたかった。
意識したことが3つあります。
実測と結びつける。 5章の「どの障害に何が効くか」対応表は、アプリの3シナリオと1対1で対応させました。読んで終わりではなく、実験して反証され、表のとおりの道具で支持に変わる、という確認ができます。
できないことを正直に書く。 本番環境での実験(原則3)、ジッター、サーキットブレーカー、ネットワーク障害は「このアプリでは扱わない」と各章に明記しました。7章には「このアプリが再現していないこと」という節を丸ごと置いています。
ここは少し迷ったところです。作ったものの限界をわざわざ書くと見栄えは悪くなります。でも、**学習アプリで一番まずいのは「これで全部できたつもりになること」**です。再現していないものを把握しておけば、現場に持ち出すときに何を足すべきかが分かります。
各画面から該当章へ飛べる。 実験詳細の4つのカードには「解説を読む」を付け、それぞれ該当する章へリンクしています。
実装上の工夫
章のメタデータ(slug / タイトル / 要約 / 読了目安)は src/lib/curriculum.ts に集約し、章番号と前後ナビは共通レイアウトが自動生成します。本文側で章番号を手書きしないので、章を足しても順序がずれません。
テストでは、slug の一意性と前後ナビの境界に加えて、全章に対応する page.tsx が実在することを fs で確認しています。slug とディレクトリ名のずれは型では防げないので、リンク切れの回帰テストとして入れました。
8. AI と作って分かったこと
効いたこと
1. 規約を先に書く
CLAUDE.md の 287 行は、書いた時間の何倍も回収しました。特にコメント・エラーハンドリング・抽象化の方針は、書いておかないと毎回口頭で修正することになります。
2. 作業ログを、AI のコンテキストとして書く
docs/worklog.md は人間のための記録でもありますが、実質的にはセッション間の記憶装置です。セッションが変わっても、これを読ませるだけで前提が復元されます。
3. 「なぜそうしなかったか」を残させる
ADR で一番価値があるのは「検討したが選ばなかった案」の部分でした。これがないと、次のセッションで同じ議論を最初からやり直すことになります。
4. TDD を強制し、Red を見せてもらう
テストが最初から通ってしまう場合、たいていテストが何も検証していません。「失敗を確認してから実装」を規約に書いておくと、これが防げます。
5. AI に、自分の作ったものを疑わせる
これが一番大きかった発見です。「改善候補が構造的に間違っている」という欠陥は、作った直後ではなく、時間を置いて全体を見直したときに見つかりました。
実装中の AI は「言われた機能を作る」モードにいるので、目的そのものは疑いません。セッションを分けて「現状を確認して」「初学者の視点で見て」と観点を与えると、別の視点が入ります。
人間がやる必要があったこと
誰のために作っているのかの問い直し。 「初歩の初歩から学べるようにしたい」という要求を出したのは人間側です。この一言がなければ、ベースライン計測もシナリオの複数化も入りませんでした。AI は言われたものを作りますが、言われていない観点から作ったものを疑うことはしません。
完成の判断。 どこまでやったら十分かは、目的を持っている側にしか決められません。
実測していないことの管理。 このアプリはまだ、改善後に判定が supported に変わるところを実機で確認できていません(DB が止まっている環境で作業していたため)。AI は「テストは全部通りました」と正直に報告しますが、テストが通ることと、目的が達成されていることは別です。その差分を追い続けるのは人間の仕事でした。
9. 現状と、次にやること
現在の状態です。
- コード約 4,000 行 / テスト 85 件(12 ファイル)
- 画面 9 ルート + 学習ガイド 9 章 + API 5 エンドポイント
- ADR 4 件 / 作業ログ 4 エントリ
残っているのは、
-
改善後に判定が
supportedに変わることの実機確認(間欠エラー 30% でリトライ 0 → 2)。これでループが初めて1周します - サーキットブレーカーの実装。今は改善候補として名前が出るだけで、実測できません
- 実インフラ(AWS FIS)への拡張
おわりに
AI と一緒に作ってみて一番印象に残ったのは、AI がコードを書く速度より、「作ったものが目的を果たしていない」と気づくきっかけをくれたことでした。
改善候補が構造的に間違っていた件は、テストは全部通っていて、機能としては動いていて、それでもアプリの存在理由を満たしていませんでした。こういう欠陥は、書いた本人が書いた直後に見つけるのが一番難しい種類のものです。
そのために効いたのは、派手な仕組みではありませんでした。規約を文章にしておくこと、作業ログを残すこと、判断の理由を書き残すこと、時間を置いて別の観点で見直すこと。人間のチーム開発で昔から言われていることが、そのまま効いたという感想です。
違うのは、そのドキュメントの読者に AI が加わったこと。そして、読者が増えたぶん、書く価値も上がったことでした。