Urazuke — コース。段ごとの実践課題付きマニュアル、アプリケーションが本番に出るまで

著者：Pablo Kuschniroff、Claude Codeの支援による。第2版、2026年10月18日。Urazukeプロジェクトの作業文書だ：これを使う最初のコホートとともに修正していく。日常の言葉で書かれており、略語や見慣れない表現はすべて主文書（ESCALERA_METODOLOGICA.md）の用語集にある。実際の事例を引用するときは [Ref. N] の印で参照文書へ導く。マニュアルはきれいなまま、詳細はワンクリック先にある。方法の公開リポジトリは github.com/pkuschnirof/urazuke。

始める前に

このコースは誰のためか

人工知能でソフトウェアを構築し、そのソフトウェアが本当に使われることを望む人のため。本物の人々に、何か月も。プログラミングのコースではない：言語もフレームワークも学ばない。「プロンプト」のコースでもない：モデルにうまく書かせるコツは学ばない。方法のコースだ：何をどの順でするか、各時点でモデルに何を頼むか、何を納めてもらうべきか、そして——コードを読まずに——納められたものが完全だとどう知るか。

次のどれかに当てはまるなら役立つ：

• 事業、診療所、小さなコンサルティング会社を持ち、開発チームを雇わずに自分のシステムが欲しい。
• 自動化のコンサルタントやフリーランスで、顧客がロボット以上の「何か」を求めてくる。
• プログラミングはできるが、モデルに重労働をさせて自分は決定だけを握りたい。
• 既に何かを「バイブコーディング」し、二週間動いて、三か月目に崩れた。

金曜のデモのためのプロトタイプが欲しいなら役に立たない。それにはもっと速いツールがあり、この方法は遅く感じるだろう。方法はデモの後も動き続けなければならないもののためにある。

最後に何を手にするか

本番で動くあなた自身のアプリケーション。それには：通る前に失敗するのを見たテスト。すべてのフローのエンドツーエンドテスト。ロールバック付きの再現可能なデプロイ。リポジトリの外の設定と秘密。日付付きで書かれた事業の決定。システムのセマンティックツリーと、構築した各物の詳細な仕様、その保留項目の中に。請求し、送信し、削除するすべてに錠。人がAIなしで追える三つのマニュアル。構築したのとは別のエージェントによる監査。そして数字による振り返り。それがここで「プロダクショングレード」と呼ぶものだ：動くことではなく、維持できることだ。

そしてもう一つ、本当に持ち帰るものを手にする：証拠なしにモデルを信じない反射と、各手順でどんな証拠を求めるべきかを正確に知ること。

必要なもの

1. プログラミングのためのAIツール。 あなたのリポジトリのファイルを読み書きし、コマンドを実行できるものなら何でも：Claude Code、Cursor、Codex CLI、Gemini CLI、Forge。方法はどれかに依存しない。主文書に各ツールで各成果物がどこへ行くかの表がある。このマニュアルでは、あなたが使うものを指して「エージェント」と言う。
2. GitHub（または同等）のアカウントと、リポジトリ、コミット、プッシュとは何かの最低限の知識。なければ、始める前に午後一つを充てること。どんな入門チュートリアルでも足りる。それ以上は要らない。
3. プロジェクト。 理想はあなた自身のもの：あなたが必要とする、または顧客が頼んだシステムで、使うユーザーがいるもの。なければ、下に記すガイドプロジェクトを使うこと。二十四の段を一つも飛ばさずに通るよう考えられている。あなたが持っているのが既に存在していて修正するか成長させなければならないシステムなら、この第一部は新規プロジェクトの上で方法を教え、 コースのパート2が、二つ目の受け継いだガイドプロジェクトとともに、それをまず正常化する方法を教える。
4. 時間。 コースには段ごとに一つ、二十四のレッスンがあり、各事項がどの段階に来るかを言う順序がある（「コースの順序」参照）。期限は意図的に与えない：方法はプロセスであって速度の約束ではなく、各段階がどれだけかかるかはあなたのプロジェクトの大きさが決める。与えるのは順序であり、それは交渉の余地がない。
5. 決定する時間のあるドメインのオーナー。 プロジェクトがあなたのものなら、あなただ。顧客のものなら顧客で、プロジェクト全体を通じて質問に答えなければならないと知っておく必要がある。この点は交渉の余地がない：決定するオーナーなしには、モデルが決定し、そこで方法は壊れる。

コースの進め方

各レッスンは同じ構造を持つ：

• 理解すべきこと：概念、人に説明するように説明されたもの。
• 課題：一歩ずつ、エージェントに与える正確なプロンプト（英語で。モデルは英語でより正確に指示に従うからだ。それぞれに翻訳が付き、下に何を求めているかが説明されている）と、返ってきたもので何をするか。各プロンプトの前には「プロンプトを送る前に」という枠がある：貼る前にあなたが自分の手で作っておかなければならないファイルと材料だ。飛ばさないこと：プロンプトはそれらのファイルを名指しし、存在しないか空なら、エージェントはそれを発明するか、あなたに求めることになる。
• 完全性の検証：エージェントが納めたものについて、コードを開かずに自問する質問のリスト。どれかが「否」なら、レッスンは終わっていない。
• 提出物：最後に存在しなければならないファイルまたは証拠。
• 典型的な誤り：初めてのとき、ほぼ全員に起きること。
• ガイドプロジェクトでは：このレッスンを例のプロジェクトに適用するとどう見えるか。

コース全体のルール：検証が「否」のまま次の段へ進まないこと。「後で直す」の誘惑は、まさに方法が避けるために存在するものだ。段を完全に登らなければ、次の段は砂の上に建つ。

コースの順序：いつ何をするか

主文書のパートBに方法の完全なタイムラインがある。ここでそれを、ガイドプロジェクトのためのコースの順序に翻訳する。週ではなく段階だ。それぞれはあなたのプロジェクトが求めるだけ続き、交渉の余地がないのは順序と、何よりレッスンとレッスンの間に何が起きるかだ。

プロジェクトがより大きいなら、育つのは段階2と3（より多くのブロック）であって、段階1でも 4と5でもない。そして段階3にインフラをしていたり、段階5に初めてエンドツーエンドのテスト群を走らせていたりしたら、順序に戻ること：何かが飛ばされた。

ガイドプロジェクト：「Turnera」

自分のプロジェクトがなければ、これを使うこと。小さいが、二十四の段のどれも偽物にならないために必要なすべてを持っている：実ユーザー、個人データ、世界へ出るメッセージ、そして金銭。

事業。 診療所（事務所、美容院、工房でもよい：予約を出すところならどこでも）。今日、予約はノートに書かれ、WhatsAppで手で確認される。人が忘れるので予約が失われ、二人が別々のノートに書いたので二重予約があり、先月いくつの予約がキャンセルされたか誰も知らない。

望むもの。 二人の受付係と三人の専門職が予約を見られるウェブの予約台帳。24時間前の WhatsAppまたはメールによる自動リマインダー。特定の予約について支払いリンクで手付金を求められること。そして月末のいくつかの数字（予約数、欠席数、手付金数）。

オーナー。 診療所の責任者。事業についての判断力があり（どの予約に手付金が要るか、どれだけ前ならキャンセルできるか、三回欠席した患者に何と言うか）、質問に答えるのに一日十五分ある。プログラミングはせず、コードは読まない。

彼女だけが知る数字。 一日約四十の予約、年間二百五十日。予約あたり約三つのメッセージ（確認、リマインダー、ときに再予約）。患者のデータは五年保存する。ピークは月曜の朝、二人の受付係が同時に登録するとき。そして彼女が答えられず、重要な問い：これが機能したら、他の診療所にも売るのか？（答えはサイジングを十倍変える。）

帰結のあるもの。 リマインダーの送信（二度送れば迷惑。間違った番号に送れば、プライバシーの問題）。手付金の請求（金銭）。予約のキャンセル（それを失う患者にとって不可逆）。患者の削除（個人データ）。

責任者が名付けるユースケース、彼女が言う通りに：「予約を登録する」「患者を探す」「予約をキャンセルする」「患者にリマインダーが届く」「手付金を求める」「今月の予約数を見る」。六つ。エンドツーエンドのフローになる。

これで始めるには十分だ。それ以外のすべてはエージェントが質問し、質問することが演習の一部だ。

立ち上げ区間：レッスン0から4

この五つのレッスンはプロジェクトごとに一度、段階1に、機能を書く前に行う。最も飛ばす誘惑を与え（「何か動くものを見たい」）、最も飛ばすと高くつくものだ。続けて行い、その後初めてループを開くこと。

レッスン 0 — このプロジェクトはこの方法で取り組めるか？

理解すべきこと。 方法はどんなプロジェクトにも役立つわけではなく、始める前にそれを知ることが最初の品質の決定だ。それなしには機能しない二つの条件がある：証拠を残す標準リポジトリがあること（X1）、そして画面からバックエンドまでエンドツーエンドでテストするために画面をプログラムから操作できること（X2）。どちらかが欠ければ、エージェントは自分を検証できず、あなたがコードを読む羽目になる。それはまさに方法が避けると約束するものだ。二つは私が断ったプロジェクトから取った Ref. 46。その後に重み付け基準（時間のあるオーナーがいるか、誤りに帰結があるか、別の環境でテストできるか、など）があり、まだ較正中だ。

ガイドプロジェクトでは二つの条件は満たされる：新規プロジェクト（レガシーなし）で、プログラムから操作できるウェブインターフェースで構築する。自分のプロジェクトでは、このレッスンは「不可」で終わることがあり、それはコースの有効な結果だ。

課題。

1. このプロンプトを貼ること：

求めているのは、二つのファイルを読むこと、調査が十分か評価し、答える前に足りないものを質問すること（この条項はコースのすべてのプロンプトで繰り返される。方法の心臓部だ）、各答えの出所を言いながらシートを埋めること、そして決定しないこと：決定はあなたのものだ。

2. 質問に答えること。一つもしなかったなら、疑って何を推測したか聞くこと。
3. シートを提示されたら、読んで決めること。

4. 締めのプロンプトを貼ること：

完全性の検証。 docs/ELIGIBILITY.md を開いて自問すること：二つの排除基準に明示的な答えと出所があるか？「おそらく」で答えられた基準があるか？（あるなら、エージェントは質問すべきだった。）決定に日付と名前があるか？ 条件があれば、検証できるか？ エージェントがした質問とあなたの答えがあるか？

提出物。 一ページの docs/ELIGIBILITY.md。

典型的な誤り。 エージェントが質問しないよう「完全な」調査を書くこと：演習を失い、もっと悪いことに、モデルの仕事をする癖がつく。五つの条件付きで「可」と答えること：変装した「不可」だ。そして最も多いもの：「可なのは明らか」だからとレッスンを飛ばすこと。明らかなことは書かれず、書かれないことが後で議論される。

ガイドプロジェクトでは。 エージェントは最低限、インターフェースがウェブかモバイルか（X2はそれに依存するから）、Excelでも以前のシステムがあるか、どのメッセージチャネルを使うか（WhatsAppにはメールにない要件がある）を質問すべきだ。シートは「可」で終わり、妥当な条件が一つ：第14段の前にメッセージチャネルを決めておくこと。

レッスン 1 — 共働の約束

理解すべきこと。 エージェントは毎セッション、前回の記憶なしにやってくる。毎朝新しい協力者が来るようなものだ。共働の約束とは、初日にあなたが言うことであり、毎日読み返すものだ：どう働くか、何を許容しないか、どの程度の自律を与えるか。約束なしには、毎セッション同じことを繰り返し、毎回少しずつ違う。私は二週間繰り返した後に初めてこれを書いた Ref. 1。

六つの最低限のルールにはそれぞれ背後に失敗がある：「私の時間は神聖」はあらゆる細部を聞かれることを防ぐ。「負債ゼロ」は「後で直す」を防ぐ。「正確な範囲」は「ついでに」物を追加されることを防ぐ。「同じコミットでの文書」は古いマニュアルを防ぐ。「検証していないことを決して完了と報告しない」は完了ではなかった「完了」を防ぐ。「私の言語で話せ」はプロンプトが英語だったからと英語で答えられることを防ぐ。

課題。

1. このプロンプトを貼ること：

求めているのは、それぞれが防ぐ失敗付きの六つのルール、あなたが受け入れるか拒否できるよう提案と印された固有のルール、そしてあなたについて質問すること。

2. 質問に答えること。提案を読むこと：役立つものを受け入れ、役立たないものを拒否する。常に一行の理由とともに。

3. こう締めること：

まだプロジェクトファイルがなければ（レッスン2で作る）、その指示を持つ最小限のものを作る。それでよい。

完全性の検証。 六つのルールが、それぞれ防ぐ失敗とともにあるか？ 願望として書かれたものがあるか（「…するよう努める」）？ プロジェクトファイルは毎セッションの最初にこれを読むよう命じているか？ あなたの働き方について少なくとも一つ質問したか？

提出物。 日付とバージョン付きの docs/WORKING_AGREEMENT.md、プロジェクトファイルに結び付けられて。

典型的な誤り。 すべて良さそうに聞こえるからと二十のルールを受け入れること：誰も二十は守らない。六つか八つなら守られる。エージェントが約束を変えられると言うルールを残すこと：だめ。そして最も静かなもの：読んでいるかを一度も試さないこと。レッスン2でその方法を見る。

ガイドプロジェクトでは。 Turneraのためにエージェントがよく提案し、受け入れる価値のある固有のルール：「本番以外の環境から患者に本物のメッセージを決して送らない。テストでは、メッセージは偽の受信箱へ行く」。早くから顔を出す第14段だ。

レッスン 2 — プロジェクトの定義、セマンティックツリー、必読

理解すべきこと。 プロジェクトファイル（PROJECT.md、または CLAUDE.md、またはあなたのツールが使う名前）はエージェントが各セッションの最初に読む地図だ。短くなければならない：システムは何か、誰のためか、何でないか、モジュール、日付付きでなされた決定、そして約束を読む命令。毎日起きたことはそこには行かない：生きた状態（docs/STATUS.md）と保留項目の記録へ行く。私のあるシステムはこのファイルを九千行以上まで育てさせた。その状態では誰も読まず、モデルも読まない Ref. 41。

だが地図には二つ目の部品があり、最も多くの仕事をするものだ：セマンティックツリー。システムを木として分解したもの：最上位にドメイン、各ドメインの下にそのアクター、プロセス（取り込みで名付けたユースケース、アクター、トリガー、手順、結果、例外付き）、属性と状態を持つエンティティ、画面、外部インテグレーション。昔からある要件工学のドメインモデルを、モデルが読めるよう木の形にしたものだ。各ノードから、それに触れる保留項目と決定がぶら下がる。その価値は二重だ：エージェントに触れるノードの正確な文脈を与え、あなたにはコードを読まずに、エージェントが理解しているシステムが事業が求めたものであることを検証する方法を与える。木に事業が一度も名付けなかった状態があれば、モデルが発明したのであり、その上に構築する前にあなたはそれを見る。

「何でないか」の節は依然として最も重要で、全員が空のままにするものだ。書かれていないことが、モデルが穴に出くわしたときに発明するものだ。

課題。

1. 貼ること：

求めているのは、起草する前に質問すること、「何でないか」の節を持つ短いプロジェクトファイル、完全な構造と印された推論ノードを持つセマンティックツリー、そして別のファイルの生きた状態。

2. PROJECT.md 全体を読むこと。五分に収まらなければならない。真実でないもの、あなたのものでないものを修正すること。
3. 顧客になったつもりでセマンティックツリーを辿ること。推論と印された各ノードを見て、確認または修正すること。欠けているアクター、事業が使わないエンティティの状態、頼んでいない画面を探すこと。

4. こう締めること：

5. 読み取りテスト。 エージェントのセッションを閉じ、新しいセッションを開くこと。他に何も言わずに、こう頼むこと：「このシステムがしてはならないことは？ そして予約台帳の画面は木のどのノードからぶら下がる？」。PROJECT.md と木が言うことで答えるなら、結び付けは機能している。他の何かで答えるなら、地図を読んでいない：あなたのツールがプロジェクトファイルをどう読み込むか見直すこと。

完全性の検証。 PROJECT.md は五分で読めるか？ システムが何をしないかを言っているか？ 木にはあなたが知るすべてのアクターがあり、各エンティティは事業が使う状態をそれ以上でも以下でもなく持っているか？ 推論ノードをすべて確認または修正したか？ 各決定に日付と誰が決めたかがあるか？ エージェントは起草する前に何か質問したか？ 生きた状態は別のファイルにあるか？ 読み取りテストを通ったか？

提出物。 PROJECT.md（最大三百行）、確認されたノードを持つ docs/SEMANTIC_TREE.md、 docs/STATUS.md、そして通った読み取りテスト。

典型的な誤り。 既に持っていた仕様全体を PROJECT.md に貼ること：綱領であって仕様ではない。「何でないか」を空のままにすること。辿らずに木を受け入れること：モデルは恐ろしいほど自然に状態と画面を推論し、発明された各ノードは誰も頼んでいないのに構築される機能だ。そして読み取りテストをしないこと：第1段と第2段が存在するだけでなく作用していると知る唯一の方法だ。

ガイドプロジェクトでは。 Turneraの「何でないか」には最低限：カルテシステムではない（医療データを保存しない）、決済ゲートウェイではない（プロバイダの支払いリンクを使い、カードを処理しない）、マーケティングメッセージを送らない（確認とリマインダーのみ）。木には、アクター受付係と専門職、プロセス「予約を登録する」「予約をキャンセルする」「患者を探す」、エンティティ予約（状態：未確認、確認済み、キャンセル、欠席）と患者、画面「当日の予約台帳」と「患者カード」を持つドメイン「予約台帳」。プロセス「リマインダーを送る」、エンティティメッセージ、 WhatsAppプロバイダとのインテグレーションを持つドメイン「メッセージ」。そして「手付金を求める」と決済プロバイダとのインテグレーションを持つドメイン「支払い」。エージェントが予約に状態「再予約済み」を追加したら、どこから取ったか聞くこと：責任者は名付けていない。必要かもしれないし、必要でないかもしれない。決めるのはあなたであって、エージェントではない。

レッスン 3 — アーキテクチャを設計する前にサイジングする

理解すべきこと。 間違って取ると数週間を要する決定がある：どのデータベースか、データベースへの呼び出しが同期か非同期か、何人が同時にシステムを使えるか。そしてすべては事業だけが持つ数字に依存する：一日の予約数、予約あたりのメッセージ数、何年保存するか。モデルはその数字を推論できない。そこから派生するもの（年間行数、五年後のサイズ）は推論できる。だからプロンプトは一次データと派生データを区別し、足りない一次データを推定する代わりに求めるよう要求する。モデルが一次データを推定するとき、計算するときと同じ自信ありげな顔でそうする。口調で区別する術はない。私はこれを間に合うようにしなかったために再設計の一段階まるごとを払った Ref. 15。

さらに、常に取った方がよい種類の決定がある：非対称な決定、余っても安く、欠けると非常に高くつくもの。典型例は、最初のデータベースがファイルでも初日からデータベースとのインターフェースを非同期にすること：データベースを決して変えないなら await が一つ余っただけ。変えるなら、すべての書き直しを免れた。

課題。

1. 貼ること：

求めているのは：一次と派生を区別すること。欠けているか「推定」の一次データをあなたに求め、決して推定しないこと。計算を見せて派生物を算出すること。「十倍」のシナリオ。一方から他方へ変えるコスト付きの三つの選択肢。そして選ばないこと。

2. 「推定」を求めてきたら、良い：それが演習だった。数字を手に入れ（オーナーに聞く、ノートで数える）、与えること。求めずに計算したなら、止めて推定をどうしたか聞くこと：段の失敗であり、今見ておく方がよい。
3. 三つの選択肢を読むこと。一つの計算を手でやり直すこと（例えば最大のテーブルの年間行数）：同じにならなければならない。選ぶこと。

4. こう締めること：

完全性の検証。 出所「推定」または出所なしの一次データがあるか？ 各派生データは計算を示し、やり直すと合うか？ 三つの選択肢があり、理由付きで一つが選ばれているか？「十倍」で何が起きるかを言っているか？ 非対称な決定は書かれているか？ 質問したか？

提出物。 docs/SIZING.md。

典型的な誤り。 エージェントが質問しないよう、あなたが発明した数字で調査を埋めること（レッスン0と同じ誤りで、ここではその数字がアーキテクチャを決めるのでより悪い）。念のため「最も強力な」選択肢を選ぶこと：移行コストが表にあるのは、まさに「十倍」に耐える最も小さいものを選ぶためだ。そして非対称な決定を書かないこと：書かれていなければ、レッスン4でエージェントはそれを守らない。

ガイドプロジェクトでは。 一次：40予約/日 × 250日 = 10,000予約/年。予約あたり3メッセージ = 30,000メッセージ/年。5年の保存。二人の受付係が同時のピーク。「十倍」は他の診療所に売るかの問い：年間100,000予約と300,000メッセージ。典型的な三つの選択肢：SQLiteファイル（一つの診療所には何年も足りる。複数が書き込む十倍には耐えない）、最初からPostgreSQL（すべてに耐える。インフラが少し多くかかる）、または今はSQLiteで非同期インターフェースとPostgreSQLへの移行を予定（非対称なもの）。コースでは三つ目を選ぶ：最も多くを教えるものだ。

レッスン 4 — ゲート付きの骨組み

理解すべきこと。 システムが何か役立つことをする前に、空のまま起動し、テストされ、デプロイされなければならない。時間の無駄に見えるが（「何もないのに何をデプロイするのか」）その逆だ：本番への道はプロダクトの一部で、機能すると知る唯一の方法は、まだ失うものがないときにそれを辿ることだ。私のあるシステムではデプロイは立ち上げの一か月後に来て、五つの連続した保留項目を要した Ref. 32。骨組みが立ち上げでデプロイされていれば、その五つの痛手は空の状態で受けていた。

このレッスンはさらに、プロジェクトのインフラのすべてとインテグレーションとデプロイの連鎖を作る場所だ。レッスン15まで再び触れることはなく、その間にすべての機能をその上に構築する。だから段階1の大半を占める。

ゲートとは、ある段階から別の段階へ進むための条件だ（「テスト群が緑」「テストへのデプロイが機能した」）。自明に見えても今書くことが、後で議論せずに「これは通らない」と言えるようにするものだ。

課題。

1. 貼ること：

求めているのは、始める前にアクセスを確認すること、骨組みとは何かの正確なリスト、書かれたゲート、テスト環境の実際のスクリーンショット、そして機能追加の禁止。

2. この課題は長く、行ったり来たりがある：足りない認証情報、メールの確認を求めるサービス、など。普通のことだ。普通でないのは、テスト環境のスクリーンショットなしに「完了」と言うことだ。
3. スクリーンショットを見せられたら、あなたがブラウザでURLを開くこと。同じものが見えなければならない。システムの最初の人間による目視であり、節目だ。

4. こう締めること：

完全性の検証。 あなたがテスト環境のURLを開いて空の画面を見たか？ 緑の継続的インテグレーション実行へのリンクはあるか？ デプロイは二度実行され、二度目は何も壊さなかったか？ゲートはそれぞれ検証可能な条件を持つか？ 頼んでいない機能があるか？

提出物。 骨組みを持つリポジトリ、緑の継続的インテグレーション、機能するテスト環境の URL、docs/GATES.md、三つのコマンドを持つ docs/STATUS.md。

典型的な誤り。 「ローカルで動く、デプロイは後で見よう」を受け入れること：だめ、デプロイが骨組みだ。テスト環境の代わりにエージェントのマシンのスクリーンショットを受け入れること。そして「ついでに」ログイン画面、メニュー、ロゴを追加させること：保留項目なしに入る各物は逃げた範囲だ。

ガイドプロジェクトでは。 Turneraの骨組みは、テスト環境の公開URLで動く「Turnera — バージョン0.0.1」と言うウェブページ、ヘルスチェックのルートで「ok」と応答するサーバー、そのルートを呼ぶスモークテスト、プッシュごとにそのテストを走らせる継続的インテグレーション、そしてテスト環境への自動デプロイ。ゲート：「マージするにはテスト群が緑」「本番へ昇格するにはテスト環境が緑」「本番への最初のデプロイには試されたロールバック」。それだけ。そして本物のURLでその空のページを見るのは、不思議なほど満足感がある。

ループ区間：レッスン5から12

この八つのレッスンは、プロジェクト全体を通じて変更ごとに使うものだ。段階2と3に最初の二つの機能ブロックで学び、最後まで実践する。各保留項目とともに行う順に並んでいる：依頼を仕様付きの保留項目に変換してブロックを開き、一つ取り、欠けているものを決め、計測すべきものを計測し、構築し、赤でそしてエンドツーエンドでテストし、品質のゲートを通し、手動テストケースを書き、相手側を更新し、検証したことと信じていることを分けて報告する。ブロックの締めに、手動テストケースを自分で実行する。その反射が方法だ。

実践するには実際の機能が必要になる。ガイドプロジェクトでは、最初のブロックは基本の予約台帳：当日の予約を見る、予約を登録する、キャンセルする。二つ目は患者と検索。メッセージも支払いもまだ。それは錠（レッスン14）の後に来る。

レッスン 5 — 計画とは保留項目のこと、そして詳細な仕様はそれぞれの中に住む

理解すべきこと。 「計画」が一方に「タスクリスト」が他方にあるのではない：保留項目のリストが計画だ。だがさらに二つの考えがあり、それがこの方法を単なるタスクリストから区別する。

一つ目：詳細な仕様は各保留項目の中に住む。古典的方法には、完成する前に古びる長い要件仕様書があった。ここでは分解される：各保留項目が、ぶら下がるセマンティックツリーのノード、顧客の言葉でそれを生むユーザーストーリーまたはユースケース、詳細な記述、決定と日付付きの適用される事業ルール、入出力データ、影響を受ける画面、境界ケース、「前提、もし、ならば」の形の受け入れ基準、そしてどう検証するかを持つ。保留項目の仕様を読むことは、あなたがコードを読むことに最も近づく瞬間であり、まさに正しい距離だ：そこで、構築する前に、エージェントが別のことを理解したとあなたが検知する。

二つ目：閉じた保留項目は文書である。保留項目が閉じるとき、その仕様、それを生んだ決定、閉じたときの証拠、コミット、日付とともに残る。閉じた保留項目のキューはシステムの機能的な履歴で、そこから変更日誌とマニュアルの新しい節が出てくる。そしてエージェントへの黄金律：リスト外に現れたものは仕様付きの新しい保留項目として記し、やらない。

課題。

1. 貼ること：

求めているのは、依頼を検証可能な項目に変換すること、依頼が検証可能な項目を書けるほど十分でないときは質問すること、それぞれの完全な仕様をフィールドごとに、ぶら下がる木のノード、決定付きか欠落と印された事業ルール、後にテストの台本となる受け入れ基準、そして理由付きの順序。

2. 質問に答えること（Turneraでは例えば、「当日」とは何か：今日か、選んだどの日でもか？キャンセルは削除か印か？と聞く）。その質問は事業の決定だ。レッスン6でどこに書くかを見る。
3. 各保留項目の仕様を顧客になったつもりで読むこと。レッスンで最も重要な課題であり、最も飛ばす誘惑を与えるものだ。あなたが頼んだことを、あなたの言葉で記述しているか？受け入れ基準は、あなたが「よし」と言うために使うものか？ あなたが知っていて載っていない境界ケースはあるか？ 正しいノードからぶら下がっているか？ 何も構築される前に修正すること。

4. 共働の約束に毎セッションのルーチンを追加すること。貼ること：

5. さあ、構築を始めること。最初の保留項目を取るよう頼むこと。ここから、各セッションは「どの保留項目をなぜ取るか」で始まり、各締めは保留項目を文書化して残す。

完全性の検証。 無作為に選んだ保留項目の仕様を読むこと：すべてのフィールドを持ち、あなたが頼んだことを記述しているか？ 各保留項目はあなたが認識する木のノードからぶら下がっているか？ それぞれどう検証するかを言っているか？「欠落、質問済み」と印されたのに聞かれていないルールがあるか？ 証拠もコミットもなしに閉じた保留項目があるか？ 閉じたものはその仕様と終了の文書を保持しているか？ 無作為に三つのコミットを取ること：保留項目を引用しているか？保留項目なしの何かがコードに現れたか？

提出物。 最初のブロックの仕様を持つ docs/PENDING.md、約束の中のルーチン、そして進行中の最初の保留項目。

典型的な誤り。 一行の仕様を受け入れること：エージェントは形式のために書いたのであり、構築の時点で足りないものを発明する。仕様を読まないこと：誤解が高くつく前に止められる唯一の瞬間だ。「もう動くのを見た」からと証拠なしに保留項目を閉じさせること。文書化せずに閉じさせること：六か月後、なぜシステムがそうするのか誰も知らない。そして最も直しにくいもの：リスト外の「もう一つだけ」をさせること。最初に許したとき、正確な範囲を失った。

ガイドプロジェクトでは。 Turneraの最初のブロックは約六つの保留項目で、木のドメイン「予約台帳」からぶら下がる：PND-001 ある日の予約を見る。PND-002 患者、専門職、日付、時刻付きで予約を登録する。PND-003 同じ専門職の同じ時刻の二つの予約を防ぐ。PND-004 予約をキャンセルする（削除ではなく印：レッスン6の決定）。PND-005 名前または電話で患者を探す。 PND-006 最低限のデータでの患者登録。例えばPND-003の仕様はこう言う：ノード 予約台帳 → プロセス「予約を登録する」→ エンティティ 予約。ストーリー：「同じ専門職の同じ時刻に二つの予約があってはならない、ノートで二回起きた」（責任者の言葉）。ルール：「専門職が有効にした場合のみ二重予約可」（決定保留、質問済み）。データ：専門職、日付、開始時刻、所要時間。画面：登録フォーム。境界ケース：部分的に重なる予約、所要時間の異なる予約。受け入れ基準：「Dr. A の10:00の予約があるとき、Dr. Aの10:00にもう一つ登録しようとすると、画面が警告しデータベースは保存しない」。検証：フォームのエンドツーエンドテストとデータベースへのクエリ。それが仕様だ。

レッスン 6 — 決定はコードの隣に書く

理解すべきこと。 モデルは、事業ルールの穴を見つけると、それを埋める。止まって質問しない。最もありそうなもので補完し、他のすべてを書くのと同じ自然さでそうする。だからこのレッスンは「決定を書け」ではなく「欠けていたら止まって質問するよう要求しろ」だ。そしてあなたが決めたら、決定はあなたの発言そのまま、あなたの名前、日付とともに、コミット、保留項目の仕様、記録に書かれる。私は最初のシステムからそうしている Ref. 29。六週間後、誰かが「なぜキャンセルは削除しないのか？」と聞いたとき、答えは書かれていて、あなたのものだ。

課題。

1. 約束に決定のルーチンを追加すること。貼ること：

求めているのは、書かれていないルールの前で止まること、推奨と代替案付きで質問すること（十秒で決められるように）、あなたの発言そのままを三つの場所に記録すること、そしてあなたが答えないときは最も可逆なものを選んで印すこと。

2. ブロックの保留項目の構築を続けること。事業ルールを聞かれるたびに、決めること。

3. 貼ること：

4. 一度、意図的に逆のテストをすること：一セッションの間、質問を未回答のままにして何をするか見る。最も可逆なものを選んで「省略による」と印さなければならない。思ったものを選んで印さなかったなら、段の失敗だ：約束で修正すること。

完全性の検証。 事業ルールに触れる三つのコミットを開くこと：誰がいつ決めたかを引用しているか？ ルールは保留項目の仕様にもあるか？ 未確認の「省略による」決定があるか？ システムにあなたのものと認識できないルールがあるか？ 文は原文か「改良」されたか？

提出物。 育っていく docs/DECISIONS.md、最初のブロックの少なくとも五つの決定付き、そしてそれを引用するコミットと保留項目。

典型的な誤り。 質問にチャットで答え、書き残すことを要求しないこと：三セッション目には誰も覚えていない。エージェントにあなたの言葉を「改良」させること：言い換えられたルールは別のルールだ。そして最も重大なもの：誰も決めていないルールを本番で発見すること。起きたら（起きる）、バグではない：第6段の失敗であり、コードだけでなく約束で直す。

ガイドプロジェクトでは。 Turneraの最初のブロックの典型的な決定：「キャンセルは予約をキャンセル済みと印し、誰がいつかを保存する。何も削除しない」。「専門職は同じ時刻に二つの予約を持てないが、専門職が有効にしたなら二重予約に二人の患者は持てる」。「患者の電話は必須。メールは任意」。それぞれ日付と責任者の名前付きで、それぞれそれを必要とした保留項目の仕様に貼り付けられて。

レッスン 7 — 構築の前に計測する、自身も検証される計器で

理解すべきこと。 モデルは数字付きの主張（「その種のクエリは120ほどある」）を作り、計測されたときも推定されたときもまったく同じに聞こえる。口調で区別することはできない。唯一の方法は計器を要求することだ：「何で計測した？ コマンドを見せて」。段のルールは何かを決める数字は印象からは出ないということだ：リポジトリに住み、既知の事例に対して検証するテストを持ち、あなたが実行できる計器から出る。

そしてもう一つ、痛手を重ねて学び、自明視していたこのルールを形式化するのに時間がかかった理由：計器も嘘をつく。私のあるシステムでは、ある計器がコードの一部を見ていなかったためゼロを出し、別のものは44なのに27と言っていた Ref. 35、 Ref. 36。だから双方向の監査：コードから計測へ（数えるべきものはすべて数えられているか？）と計測からコードへ（数えられたものはすべて実際に存在するか？）。

小さいプロジェクトでは「計測する」は控えめだ：画面が読み込み時にいくつクエリを発行するか数える、月次レポートがどれだけかかるか、昨日いくつメッセージが送られたか。ラチェットも経路ごとの予算も要らない。要るのは、数字の裏にコマンドがあることだ。

課題。

1. 貼ること：

求めているのは、リポジトリ内の計器、計器のテスト、近似する代わりに足りないものを求めること、近似を印すこと、コマンド付きの数字、双方向の監査、そして順序：まず計測、次に提案。

2. 与えられたコマンドをあなたが実行すること。同じ数字が出なければならない。スクリプトを理解する必要はない。実行することは必要だ。
3. 仮説が真でエージェントが直すことを提案するなら、予算を求めること。

4. 貼ること：

こうして、三か月後に誰かがループを戻したら、テスト群がそれを検知する。

5. 計画が数字を持ってくるときのために、約束にルール五を追加すること：

完全性の検証。 計器を実行して同じになったか？ テストはあるか、どの既知の事例に対して？報告に計器の裏付けのない数字があるか？ 近似は印されているか？ テスト付きの予算はあるか？

提出物。 テスト付きのリポジトリ内の計器、docs/STATUS.md または保留項目の中のコマンドと日付付きの数字、そして（該当するなら）テストで守られた予算。

典型的な誤り。 コマンドを実行せずに数字を受け入れること：このレッスンの価値の半分はあなたが実行することにある。ゼロを出す計器：ほとんどの場合ゼロではない。ほとんどの場合何かを見ていない。そしてエージェントに「計測しながら直す」ことをさせること：順序が方法だ。

ガイドプロジェクトでは。 Turneraの計器は、テストデータベースに10、50、200件の予約の日を読み込み、クエリを数えながらその日の予約台帳を開き、三つの数字を書くスクリプトだ。計器のテストは0件の予約で正確に基本クエリ（例えば2）を数えることを検証する。ループがあったなら、数字は12、52、202。直すと3、3、3になり、予算は4になって、予約数がいくつでも予約台帳が4より多くクエリを発行したら失敗するテストが付く。

レッスン 8 — 錠としてのテスト、赤で証明、そしてエンドツーエンドテスト

理解すべきこと。 これがコースの中心のレッスンだ。一度も失敗するのを見ていないテストは、何かを証明しているかわからない。モデルはコードとテストを同じセッションで、同じ理解で書く：依頼を誤解していれば、テストは誤解したものを証明し、通る。テストが重要なものを見ていると知る唯一の安価な方法は、古いコードに対して赤で見ることだ：変更前のコードもそれを通るなら、テストは前後を区別しておらず、役に立たない。だから依頼は「テストを書け」ではなく「赤を見せて、次に緑、次に回帰」だ。これを最もよく示す事例は一致しなかったカウンタのものだ Ref. 26。

そして二つ目の考え、一つ目と同じくらい重要なもの：エンドツーエンドテスト。画面から（クリックし、入力し、読み）検証し、バックエンドでの効果（行が残った、状態が変わった）を確かめるテストが、あなたのコード読みを置き換えるものだ。保留項目の受け入れ基準（「前提、もし、ならば」）がその台本だ。そして三回、三つの規模で実行する：各保留項目とともに触れたフロー。各ブロックの締めに存在するすべてのフロー。本番への各デプロイの前に正確なバージョンですべてのフロー。三つ目だけをするなら、何週間も誰もエンドツーエンドでテストしなかったシステムで最後に至る。

課題。

1. 約束に証拠のルーチンを追加すること。貼ること：

求めているのは、受け入れ基準に導かれたテスト、レシートとして示された赤（コマンド、バージョン、数字、終了コード。あなた自身がもう一度走らせられるように）、緑、隣接項目の回帰、バックエンドでの効果付きのフローのエンドツーエンドテスト、まさに試すものをシミュレートしないこと、そして欠けているものはシミュレートせずに求めること。

2. 二重予約の保留項目（TurneraではPND-003、あなたのプロジェクトでは同等のもの：何かを防ぐルール）を取ること。ルーチンで閉じるよう頼むこと。報告を読むこと：数字付きの赤の出力（「ルールなしのバージョンに対して1のうち1が失敗」）、次に緑、そしてエンドツーエンドテスト：プログラムから制御されたブラウザが画面を開き、二重予約を登録しようとし、警告を読み、データベースで保存されなかったことを確かめる。
3. 画面をプログラムから操作できないためエンドツーエンドでテストできないと言われたら、止まること：それはX2が失敗しているのであり、続ける前に今直さなければならない（画面の要素に識別子を追加する）。

4. 貼ること：

5. ブロックの締めに、六つの保留項目が閉じたら、完全なテスト群を走らせること。

6. 貼ること：

7. そしてその後、あなたがシステムを使うこと。テスト環境を開き、受付係がすることをする：予約を登録し、二重予約を試み、キャンセルし、探す。気になること、理解できないこと、あるべきでない場所にあるもの：保留項目として記すこと。このひとときが、どのテストも見つけないものを見つける。

完全性の検証。 報告は数字付きで赤を見せているか？ 回帰は同じセッションで数字付きで走ったか？ エンドツーエンドテストはバックエンドも検証しているか？ 変更のまさにその場所にシミュレートされた部分があるか？ コミットは「赤で証明」と言っているか？ ブロックの締めに：すべてのフローがエンドツーエンドのテスト群にあるか？ あなたがシステムを使い、見つけたものを記したか？

提出物。 完全なルーチン（赤、緑、回帰、エンドツーエンド）で閉じた少なくとも三つの保留項目、ブロックの緑の完全なエンドツーエンドのテスト群、そしてあなたの人間によるテストから出た保留項目。

典型的な誤り。 数字も赤もなしに「テストは通る」を受け入れること。エンドツーエンドテストをシミュレーションに置き換えてテスト群が「加速」されるのを受け入れること。保留項目を開かずに「テストできない」を通すこと。そしてあなたが使わずにブロックを閉じること：人間の目は委任できない。

ガイドプロジェクトでは。 二重予約の赤はこう見える：エージェントが一時的にルールを外し、テストを実行し、出力は二つ目の予約が保存されたためテストが失敗したと言う。ルールを戻し、実行し、緑。次に回帰：PND-001とPND-002のテストは緑のまま。そしてエンドツーエンド：プログラムから制御されたブラウザがフォームを埋め、「保存」を押し、「その時間は既に埋まっています」のメッセージを読み、データベースへのクエリがその時刻の予約が一つだけであることを確かめる。ブロックの締めに、エンドツーエンドのテスト群は存在する三つのフロー（当日を見る、登録、キャンセル）を辿り、責任者が十のテスト予約を登録して、時刻が使いにくいドロップダウンで選ばれることを発見する。新しい保留項目。その報告を初めて見たとき、方法全体が何のためかわかるだろう。

2026年10月19日に変わったこと（D-037）。 新規プロジェクトの最初のブロックには以前のコードがありません。新しいテストはモジュールが存在しないから失敗するだけで、その赤は何も証明しません。この日から、以前のバージョンにモジュールがないときは、赤をミューテーションで証明します。エージェントは書いたばかりの関数に意図的な欠陥を植え、その欠陥に対してテストが赤になるところを見せ（レシートに diff が付く）、元に戻して緑を見せます。Forge では「ファイルが読み込めない」としか言わない赤では、もう保留項目を閉じられません。項目ごとにミュータントひとつ。コードベース全体のミューテーションテストは、引き続きレッスン 9 の任意の補強です。

レッスン 9 — 機械で検証されるコードの品質

理解すべきこと。 あなたはコードを読まない。それでよい。だがコードは存在し、誰かがそれを保守する。誰も読まないなら、機械が見なければならない：*リンタ*（ワープロのスペルチェッカーのようなもの、ただしコード用）、*フォーマッタ*（全体に単一のスタイル）、ファイルと関数の大きさの上限、*複雑度*の上限（一つの関数がいくつの経路を持つか）、重複したコードと死んだコードの検出、そして*ラチェット*付きのテストの*カバレッジ*（今日のものが明日の床）。すべて継続的インテグレーションの中で、違反したら赤に。私はそれを自分のすべてのプロジェクトでやってきた。ある監査は、どの上限も止めなかったせいで二千行を超えるコンポーネントを返してきた Ref. 41。

1. 第9段の契約（docs/peldanos/ にある）の最初のプロンプトを、空欄にあなたの上限を入れて貼る。
2. docs/CODE_QUALITY.md を読む。今日失敗しているもののリストがあるはずだ。何を今すぐ直し（それぞれ一つの保留項目）、何を日付付きで許容するかを決め、同じファイルに書く。

3. 第9段のルーチンを、他と同じように「Add this routine to docs/WORKING_AGREEMENT.md:」で包んで約束に追加する。
4. ブランチの中に、百行の関数一つと使われない変数一つをわざと入れてもらう：連鎖は二つともで赤にならなければならない。

完全性の検証。 連鎖の最後の実行は品質が緑か。ブランチの試しは赤になったか。リンタへの例外はあるか、そしてそれぞれに書かれた理由があるか。今日のカバレッジは昨日のもの以上か。

成果物。 連鎖の中の品質のゲート、上限と値の入った docs/CODE_QUALITY.md、そして約束の中のルーチン。

典型的な誤り。 エージェントが「このルールは厳しすぎるので無効にしよう」とするのを、あなたを通さずに許すこと。通すために上限を引き上げること。そしてカバレッジと品質を混同すること：カバレッジはテストを数え、レッスン8の赤はそれが何かを証明しているかを言う。

任意の補強。 ブロックが閉じたら、第9段の契約には三つ目のプロンプト、*ミューテーションテスト*のものがある：道具が、一度に小さな変更を一つずつ、コードをわざと壊し、それらの誤りをテストがいくつ捕まえるかを数える。カバレッジが与えない尺度であり、エージェントが赤を装えるという反論に答えるものだ。Turneraでは二つ目のブロックの締めに、変更された行だけについてこれを行う。

ガイドプロジェクトでは。 Turneraの最初の実行は三つで赤になる：予約のフォームに70行の関数がある（二つに割る：保留項目）、日付の書式の写しが二つある（一つに、サーバーの中に：保留項目）、そしてカバレッジが61%。ラチェットは61に置かれ、各保留項目とともに上がる。ブロックの締めには74%。

レッスン 10 — 手動テストケースは機能とともに書かれる

理解すべきこと。 ここまで見てきたテストはすべてモデルが書きモデルが走らせ、モデルが理解したことを検証する。欠けているのは、人が自分の目と自分の手で、*台本*に従って行うテストだ：前提条件、手順、期待される結果、そして各実行を書き留める表を持つ、手動テストケース。台本はエージェントが各保留項目とともに、受け入れ基準から書く。実行するのはあなた（または担当者）で、各ブロックの締め、最初のデプロイの前、そして各デプロイの後に。そして失敗したものは、あなたの言葉とともに、修正の保留項目としてループへ戻る。台本付きの人間の目であり、プロセスの図の円環の閉じだ：手動実行が要件を再注入する。

1. 第10段のルーチン（契約の「各保留項目のルーチン」）を、他と同じように包んで約束に追加する。これ以降、画面に触れる各保留項目はそのケースとともに閉じられる。
2. ブロックの既に閉じた保留項目のケースを書いてもらう。無作為に一つ取り、何も聞かずに自分でテスト環境で追ってみる：聞かなければならなかったなら、そのケースは人に向けて書かれていない。書き直してもらうこと。
3. ブロックの締めに、ブロックのすべてのケースを自分で、手で実行し、それぞれに日付、あなたの名前、通ったか失敗したか、そして所見を書き留める。煩わしく、どのケースにも収まらないものは、ファイルの最後に書き留める。

4. 第10段の契約の実行のプロンプトを貼る。各失敗はあなたの言葉とともに修正の保留項目として戻らなければならない。

完全性の検証。 聞かずにケースを追えたか。画面に触れる閉じた保留項目はそれぞれケースを持っているか。各ケースは画面の向こう側で何を検証するかを言っているか。実行は各ケースに日付と名前を持っているか。各失敗はあなたの言葉とともにその保留項目を持っているか。

成果物。 ブロックのフローごとに一つのケースを持つ docs/MANUAL_TESTS.md、記録された最初の実行、そして失敗ごとに一つの保留項目。

典型的な誤り。 エージェントにケースを実行済みと印させること。自動テストを散文に写しただけのケース。そして失敗をその場で、保留項目なしに直すこと：あなたの言葉と、何が繰り返されているかの痕跡が失われる。

ガイドプロジェクトでは。 Turneraの最初のブロックのケースは六つ：当日の予約台帳を見る、予約を登録する、重複予約を試す、キャンセルする、患者を検索する、患者を新規登録する。最初の実行で二つ失敗する：キャンセル（ページを再読み込みするまで予約台帳が更新されない。担当者の所見：「キャンセルされなかったのかと思った」）と検索（同じ姓の患者が二人いると一人しか表示されない）。二つの修正の保留項目、彼女の言葉とともに。どのテストも見なかった時刻の使いにくいドロップダウンメニューは、単独の所見として現れる。

レッスン 11 — 生産者と消費者の対称性、そしてアンチパターンの記録

理解すべきこと。 システムの一方の端（サーバー、データベース、ロボット）を変えたら、もう一方の端（画面、カウンタ、レポート）も同じコミットで変わらなければならない。さもなければ乖離し、ユーザーは一方である数字を、他方で別の数字を見る Ref. 26。それを防ぐ原則は言うのは簡単で保つのは難しい：すべてのリストには一人の所有者しかいない。予約の可能な状態、レポートの列、何かが待つ理由：一つの部分（生産者）だけがそれを定義し、他はそこから読む Ref. 27。セマンティックツリーはそのリストが最初に宣言される場所だ。コピーが二つあった途端、一方は古い。どちらかを知るだけだ。

レッスンの後半はアンチパターンの記録（GOTCHAS）：既に一度食らった誤りを、その匂い、根本原因、修正、事前の検知法とともに記したもの Ref. 2。重要なのは記すことではない：それを検知する自動検証を追加することだ。記されたが自動化されていないアンチパターンはセッションが変われば繰り返すからだ。

課題。

1. 契約の地図を求めること：

求めているのは、二つの側を持つ契約の目録、そして見えないものは省略するのではなく宣言すること。

2. 約束にルーチンを追加すること：

3. リストのテストをすること：画面に現れるリストを一つ選び（Turneraでは予約の状態：未確認、確認済み、キャンセル、欠席）、エージェントにどこで定義されどこで読まれるかを見せるよう求めること。定義が二つあれば、一つだけ残し、セマンティックツリーと一致させるよう求めること。
4. 何かが初めて二度目に壊れたら（起きる）、それを記録すること。

5. 貼ること：

完全性の検証。 地図から契約を一つ選ぶこと：各消費者は生産者からそれを読むか、自分のコピーを持つか？ 二つの画面に表示される数字があり、同じか？ エンティティの状態はコードとセマンティックツリーで一致するか？ GOTCHASの各項目に四つの部分があるか？ 既に記されたものが繰り返されたか？

提出物。 docs/PRODUCER_CONSUMER_MAP.md、約束の中のルーチン、そして docs/GOTCHAS.md （一項目だけで始まっても）。

典型的な誤り。 地図を一度作って二度と見ないこと：新しい契約ごとに育たなければならない。「事前にどう検知するか」の部分なしに、アンチパターンを逸話（「一度こんなことがあって…」）として記すこと。そして定番：サーバーと画面に手書きされた同じ状態のテキスト。一方が変わる日、他方は残る。

ガイドプロジェクトでは。 Turneraの地図には、最初、四つか五つの契約がある：予約状態のリスト（サーバーが定義し、画面と月次レポートが読む）。予約テーブル（登録が書き、当日の予約台帳とレポートが読む）。患者テーブル。そして後に、メッセージのキュー（予約台帳が書き、送信者が読む）。最初のGOTCHAはたいてい日付のもの：サーバーがあるタイムゾーンで保存し画面が別のタイムゾーンで表示したため、予約台帳が予約を間違った日に表示した。匂い：「23時の予約が明日に出る」。根本原因：二つのタイムゾーン。修正：一つだけ、サーバーで。検知：23:30の予約のテスト。

レッスン 12 — 誠実な検証と釣り合った報告

理解すべきこと。 コードを読まないのなら、エージェントの報告は信頼できなければならず、それは自然には起きない。モデルは役に立ち完全であるよう訓練されており、「これは検証できなかった」と言う報告は「完了」と言う報告より役に立たないと感じられる。だから悪い知らせ、盲点、やらなかったことを明示的に求めなければならない。求めなければ、くれない。隠すからではなく、答えの一部と考えないからだ。私は認証エラーを「success」という表示で報告された Ref. 43。

それを誠実にする構造は三つのブロックだ：検証済み（隣に証拠付き）、信じている（動くと思うこととなぜテストしなかったか）、盲点（いる場所から見えないもの）。そして一つのルール：悪い知らせを最初に。

課題。

1. 約束に報告のルーチンを追加すること：

2. 次の保留項目を閉じるよう頼み、下の検証リストで報告を読むこと。初回は、ほぼ確実に「盲点」ブロックは空だ。聞くこと：「いる場所から何が見えない？」。何かがなければならない（あなたのブラウザ、本番環境、実データ）。何もないと言い張るなら、あなたが言い張ること。
3. 「まだ壊れている」を練習すること。何か小さいものを頼み、テスト環境で検証し、何らかの理由で変更が見えなければ（よくある：デプロイに時間がかかる、またはされていない）、「まだ壊れている」と言うこと。

4. 貼ること：

「まだ壊れている」の半分は、リポジトリにはあるがあなたが見ている場所にない修正だ Ref. 45。この条項は何時間も節約する。

完全性の検証。 三つのブロックはあるか？「検証済み」から無作為に主張を一つ選び、隣に証拠があり、再現できたか？ 頼んだ各項目を網羅しているか？ 悪い知らせは最初にあるか？ そっけなく「完了」と言ったことがあるか？

提出物。 約束の中のルーチンと、三つのブロックを持つ三つの連続した報告、うち一つは実際の盲点付き。

典型的な誤り。 「検証済み」ブロックだけ読んで他の二つを飛ばすこと：他の二つがあなたを守るものだ。「検証済み」の中の「動くはず」を受け入れること：変装した「信じている」だ。そしてだんだん長くなる報告に慣れること：膨らんだ報告は量で何かを覆っている。

ガイドプロジェクトでは。 TurneraのPND-004（予約のキャンセル）の良い締めの報告：「検証済み：キャンセルのテストが通る（1/1、削除していたバージョンに対して赤で証明）。回帰6/6。フロー『キャンセル』のエンドツーエンドが緑、データベースで印された行付き。テスト環境で、 11月3日の予約17が『recepcion1』により10:42にキャンセル済みと表示（スクリーンショット）。信じている：月次レポートはキャンセルを正しく数えるはずだが、レポートはPND-011でまだ存在しないためテストしていない。盲点：受付係の携帯で状態『キャンセル済み』がどう見えるかは見られない。あなたが試してください。」

本番リリース区間：レッスン13から20

この八つのレッスンは「動く」を「維持できる」に変えるもので、一度、順に行う。最初の二つのブロックがループで構築され、あなたがテスト環境でテストした後、そしてシステムが世界に作用する（メッセージを送る、請求する）か実ユーザーを持つ前に。ガイドプロジェクトでは、リマインダーと手付金を追加する時点であり、だからレッスン14（錠）はその機能を構築する前に来る。後ではない。運用品質の四つ（16から19）は私が名前を付けずにやっていたものだ。初心者なら、その契約にはそれぞれ、その言葉を説明する「初心者の方へ」の段落がある。レッスンの前に読むこと。

レッスン 13 — 計画への入力としての定期監査

理解すべきこと。 ときどきシステム全体を新鮮な目で見なければならず、見えたものは保管される報告には行かない：保留項目のリストに行く。重要なのは「新鮮な目」：監査する者は構築した者であってはならない。前提を共有するからだ。モジュールを構築したモデルは、コードに書かれたパスワードが暫定だったと「知っている」。初めて見るモデルはそれをそのまま報告する。こうして構築者が一日で残した二つの管理者の扉が見つかった Ref. 40。別の会社は要らない：参加していない、別の指示ファイルを持つ別のセッションで足りる。

課題。

1. 貼ること：

求めているのは、読み取り専用、監査できなかったものを省略によって承認する代わりに宣言すること、サンプルではなくすべてのコード、各発見に位置・リスク・証拠・優先度、次元ごとの評点、そしてP0は既に提案保留項目として。

2. 報告を読むこと。発見を二つ選び、監査者に証拠（コマンド、行）を見せるよう求めること。できなければならない。

3. 構築者のセッションに戻り、貼ること：

4. 本番への最初のデプロイ（レッスン15）の前にこのレッスンを繰り返し、その後は一、二か月ごとに。

完全性の検証。 報告は何を監査できなかったかを言っているか？ 無作為の二つの発見にファイル、行、再現可能な証拠があるか？ 各P0に開かれた保留項目があるか？ 評点は次回の監査と比べられるか？ 構築したのとは別のセッションが監査したか？

提出物。 docs/AUDIT_[日付].md と開かれたP0/P1の保留項目。

典型的な誤り。 構築したのと同じセッションで監査すること：自身の前提を確認する。一か月以上のシステムでP0が一つもない報告を受け入れること：ほとんどの場合真実ではない。そして保留項目を開かずに報告を保管すること：そこで監査は何の役にも立たなかった。

ガイドプロジェクトでは。 Turneraの最初の監査がよく見つけるもの：ログ内の患者データ（メッセージ送信時に印字された電話番号：P0）。インデックスなしの名前による患者検索（P1、 5,000人の患者で気づく）。日付が未来であることを検証しない予約フォーム（P1）。そして既知の脆弱性のある依存関係（P1）。四つの新しい保留項目、すべてファイルと行付き。

レッスン 14 — フェイルクローズド、錠、静かな損害ゼロ

理解すべきこと。 ソフトウェアは既定で、疑いの前で進む：検証が失敗すればコードは続く。サービスが応答しなければ、すべて問題ないと仮定する。「フェイルオープン」、停電したとき開く扉のようなものだ。方法は既定を逆転する：疑わしきは、しない。帰結のあるすべての行動（請求、送信、削除、承認）は錠を持ち、書かれた戻り道を持ち、新しい自動化はすべて、あなたが有効化するまで、したはずのことを記録しながらドライランモードで始まる。私の最初のシステムに設置した錠が模範だ Ref. 28。

このレッスンは世界に作用する機能を構築する前に来る。Turneraでは、三つ目のブロックであるリマインダーと手付金の前に。

課題。

1. 貼ること：

求めているのは、事業が言ったこととコードがすることを比べること（誰も覚えていなかった行動がそこに現れる）、差異は質問すること、そして各行動に可逆性、錠、戻り道を、書かれたフェイルクローズドのルールとともに。

2. オーナーとともに、錠ごとに確認すること。

3. こう締めること：

4. さあ、レッスン5で三つ目のブロック（リマインダー、手付金）を開き、レッスン5から12の完全なループで構築し、ドライランモードに置くこと。実際の送信を有効化する前に、数日間「送ったはず」の記録を見ること。

完全性の検証。 請求し、送信し、承認し、削除する各行動は表にあるか？ 各錠に赤のテストがあるか？ すべての不可逆な行動に書かれた戻り道があるか？ 新しい自動化はドライランモードで始まり、有効化する前に記録を見たか？

提出物。 docs/LOCKS.md、赤で証明された錠ごとのテスト、そして記録付きのドライランモードの自動化。

典型的な誤り。 「自分の電話へのメッセージでテストするため」に実際の送信を有効化すること：ドライランモードはまさにそのためにある。「テスト用」パラメータで飛ばせる錠：そのパラメータは本番に残る。そして「したはず」の記録を見ないこと：患者に届く前に誤りを見る唯一の窓だ。

ガイドプロジェクトでは。 Turneraの錠の表：リマインダーの送信（不可逆。錠：予約ごとの冪等性、予約とチャネルごとに一回の送信、一日200の上限、まずドライランモード。戻り：なし、だから上限）。手付金の請求（返金で可逆。錠：受付係の明示的な確認、専門職が定めた金額。戻り：決済プロバイダによる返金）。予約のキャンセル（患者にとって不可逆。錠：確認と誰がの記録。戻り：予約の再作成）。患者の削除（不可逆。錠：二重確認、責任者のみ、将来の予約がない場合のみ。戻り：なし、だから二重）。各錠に、錠なしでは行動が起きたことを示すテスト付き。

レッスン 15 — プロダクトの一部としての継続的インテグレーション、環境、秘密、デプロイ

理解すべきこと。 本番に至ることは再現可能なパッケージでなければならない：テストは一度 走り、デプロイはパッケージしてアップロードするだけ、設定はリポジトリではなくサーバーに住み、テストから本番へ昇格する二度実行できる手順があり、ロールバックは試されている（一度も試されていないロールバックは存在しない）。私はコミットごとに三度走るテストで継続的インテグレーションのクォータを燃やした Ref. 39。秘密については、例外のないルール：チャット、ログ、コミットで見られた秘密はもう秘密ではない。ローテーションする、以上 Ref. 42。

この大半は骨組み（レッスン4）から既に持っている：継続的インテグレーションとテストへのデプロイ。このレッスンはそれを本番へ向けて完成させる。

課題。

1. 貼ること：

求めているのは、始める前のアクセス、コミットごとに一度だけのテスト、パッケージするだけのデプロイ、外の設定、繰り返し可能な昇格、試されたロールバック、秘密に対する錠、そして人のための文書化。

2. 本番への最初のデプロイの前に、していなければレッスン13の監査をし、昇格する正確なバージョンですべてのフローの完全なエンドツーエンドのテスト群を走らせること（レッスン8のブロック締めのプロンプト）。

3. 約束にデプロイのルーチンを追加すること：

4. システムにまだ実ユーザーがいない状態で、本番への最初のデプロイをすること。そしてその後 ロールバックを試すこと：前のバージョンに戻して動いていることを見せ、その後新しいバージョンに戻すよう頼む。
5. コースのどこかでチャットに秘密（APIキー、パスワード）を貼ったなら、ローテーションすること。

6. 貼ること：

完全性の検証。 コミットごとにテスト群は何度走るか？（一度。リンクを求める。）リポジトリに実際の設定値があるか？（空の検索結果を求める。）あなた一人で docs/DEPLOYMENT.md を追えるか？ ロールバックは試されたか、いつ、どんな証拠で？ チャットに現れたすべての秘密はローテーションされたか？ 継続的インテグレーションのクォータがどれだけ残っているか知っているか？

提出物。 コミットごとに一度の継続的インテグレーション、パッケージするだけのデプロイ、 docs/DEPLOYMENT.md、試されたロールバック、有効な秘密対策の錠、そして本番で動くシステム（まだユーザーなし）。

典型的な誤り。 「手で、素早く、小さな変更だから」のデプロイ：小さな変更こそ本番を壊す。誰もテストしないからだ。本物に見える値を持つ設定の例ファイル（本物だ）。そして必要になる日までロールバックを試さないこと。

ガイドプロジェクトでは。 Turneraでは、継続的インテグレーションがプッシュごとにテスト群（この時点で約30テスト、六つのエンドツーエンドフローを含む）を走らせる。テストへのデプロイは main へのマージで自動。本番への昇格はテストにあるバージョンをパッケージしてアップロードするコマンドで、設定（メッセージプロバイダの鍵、決済プロバイダの鍵、データベースの URL）はリポジトリにないサーバー上の環境ファイルにある。ロールバックは前のバージョンでの同じコマンド。そして秘密対策の錠は、鍵に見えるものを拒否するコミットごとの検証だ。

レッスン 16 — 可観測性とトレーサビリティ、設定可能なレベルを持つ

理解すべきこと。 本番で何かが失敗したとき、あなたはコードを開かず、エージェントに「調べて」と頼まずに何が起きたかを知りたくなる：一つの番号を探して、その行動の完全な歴史が、画面からデータベースまで現れること。それが*相関識別子*を持つ*構造化された記録*だ。そして調べているあいだ、一分だけ、システムが書く詳細さを、再デプロイせずに上げたくなる：それが*設定可能なレベル*だ。*トレーサビリティ*はもう半分だ：帰結のあるすべての行動（請求した、送信した、削除した）が、アプリケーションの編集できないリストに、誰が、いつ、何をとともに残る。これがなければ、レッスン23の常駐エージェントは盲目で運用し、レッスン21と22の監視は見るものを持たない Ref. 16。

1. 第16段の契約（docs/peldanos/ にある）の最初のプロンプトを、そのまま貼ること。
2. 実際の要求の識別子を見せてきたら、あなた自身でテスト環境の記録の中を探すこと：画面に、バックエンドに、データベースに、そしてメッセージの提供者への呼び出しに現れなければなりません。
3. あなた自身でレベルをデバッグに上げ、行動を一つして、見て、下げること。デプロイが必要だったなら、登れていません。
4. 記録の中で「Juan」（またはテストの氏名）を探すこと：あってはなりません。

5. 第16段のルーチン（契約の「ルーチン」）を、他と同じように "Add this routine to docs/WORKING_AGREEMENT.md:" で包んで約束に加えること。

完全性の検証。 あなた自身が識別子をすべての層を通って追いましたか？ デプロイせずにレベルを変えましたか？ 記録の中に個人データがありますか？ テストでの予約のキャンセルは、誰が、いつとともに監査に残りましたか？ docs/OBSERVABILITY.md だけで一人で記録を見つけられますか？

提出物。 設定可能なレベルを持つ構造化された記録、伝播した識別子、帰結のある行動の監査、 docs/OBSERVABILITY.md、そして約束の中のルーチン。

典型的な誤り。 モジュールごとに違う書き方の「ログ」を受け入れること。本番を「今のところ」デバッグのままにすること。そして識別子がリマインダーの夜のジョブに届かないこと。インシデントが失われるのはまさにそこだ。

ガイドプロジェクトでは。 「予約17をキャンセルする」の識別子が、クリックに、サーバーに、データベースの印の付いた行に、そして専門職へのメールに現れる。監査は「recepcion1が10:42にその日の予約台帳から予約17をキャンセルした。結果：ok」と言う。責任者は、あるリマインダーがなぜ遅れたかを見るためにレベルをトレースに上げ、見つけて、下げる。

レッスン 17 — 永続化層の最適化、前と後を計測して

理解すべきこと。 データベースはシステムがゆっくり死ぬ場所だ：百件の予約ではよく、十万件では悪く。*インデックス*は本のそれと同じだ：なければ、一つの予約を見つけるためにデータベースはテーブル全体を読む。*N+1ループ*とは、百件の予約を表示するのに一回ではなく百回クエリをすることだ。このレッスンはレッスン7をデータベースに当てる：各クエリをテスト付きの計器で計測し、数字が言うことを変え、同じデータの上で計測し直し、戻ってこないようにテスト付きの予算を残す Ref. 18、Ref. 37。データベースを書き直すことでもエンジンを変えることでもない：それはレッスン3だった。

1. 第17段の契約の最初のプロンプトを貼ること。
2. 提案された変更のリストを、責任者が診療所の修理のリストを読むように読むこと：それぞれが何を得て、どんなリスクがあるか理解していますか？ 一つずつ承認するか却下すること。計算を一つ手でやり直すこと（予約のテーブルの月あたりの行数）。

3. 承認したリストとともに、第17段の契約の締めのプロンプトを貼ること。
4. もらった二つのコマンドで、あなた自身が計器を前と後に走らせること。

完全性の検証。 あなたの実行は docs/PERSISTENCE.md の表と一致しますか？ 重要なフローの中にテーブル全体を読むクエリが残っていますか？ 各テーブルに保持が書かれていますか？ 予算にテストがありますか（一つ超えて赤を見せるよう求めること）？

提出物。 テスト付きの計器、前と後の付いた docs/PERSISTENCE.md、テスト付きの予算、そして緑のテスト群。

典型的な誤り。 骨組みの十件の記録で計測すること。「別のデータベースへ移行したほうがいい」を受け入れること。そしてそのテーブルを読んでいた月次の集計表を壊して数字を良くすること：地図が抜けていた。

ガイドプロジェクトでは。 その日の予約台帳は予約ごとに一つのクエリをしていた（レッスン7のループ）：50件の予約に52のクエリが3になる。氏名による患者の検索はテーブル全体を読んでいた：インデックスが、一万人の患者で800ミリ秒を4ミリ秒に下げる。保持：メッセージは一年で書庫に入れ、予約は決して入れない。予算：予約台帳に4クエリ、テスト付きで。

レッスン 18 — 脆弱性の走査と解決

理解すべきこと。 *脆弱性*とは、誰かが侵入したり、データを盗んだり、システムに本来すべきでないことをさせたりするのに使える欠陥だ。監査（レッスン13）はそれを判断力で、ときどき探す。このレッスンは機械で、いつも、四つの層で探す：*依存関係*（あなたのシステムが使う他人の部品、その既知の欠陥は公開されている）、コード（*静的解析*）、リポジトリの履歴の中の秘密、そしてサーバーの設定。そして一つのルール：依存関係を更新することは変更であり、ループを通る。回帰なしの「発見を閉じるためにバージョンを上げた」は、金曜日に本番を壊す最もよくある形だ Ref. 41、Ref. 23。

1. あなたの基準を空欄に入れて、第18段の契約の最初のプロンプトを貼ること。
2. docs/SECURITY_[日付].md を読むこと。発見を二つ選んで証拠を求めること。何を走査しなかったか言っていますか？

3. 第18段の契約の締めのプロンプトを貼ること。
4. 既知の脆弱性を持つ依存関係を、ブランチにわざと入れるよう求めること：連鎖は赤にならなければなりません。

完全性の検証。 走査の最後の実行は緑で、いつのものですか？ 各P0に証拠とともに閉じられた保留項目がありますか？ 走査は docs/GATES.md のゲートですか？ 次の予定された走査がいつ走るか知っていますか？

提出物。 連鎖の中と暦とともにある四つの層の走査、docs/SECURITY_[日付].md、 docs/SECURITY.md、直されたP0とP1、そしてゲート。

典型的な誤り。 一か月以上のシステムでの「一度目できれい」な走査：層が一つ抜けていた。一つのコミットで十の依存関係を更新すること。保留項目も日付もない「受け入れられた」P0。

ガイドプロジェクトでは。 Turneraの走査はこう見つける：PDF生成器の依存関係に既知の脆弱性（P1、回帰とエンドツーエンドとともに更新する）。予約台帳を別のサイトに埋め込ませないヘッダが欠けている（P1、設定一行、テスト付きで）。支払いの提供者のテスト用の鍵がリポジトリの履歴にある（P0：テスト用でもローテーションする）。そしてテスト用サーバーでデータベースのポートが世界に開いている（P0：閉じる）。走査はゲートとして残り、月曜日に走る。

レッスン 19 — 量に対する性能テストと破断点

理解すべきこと。 レッスン3は計算でサイジングした。これは動いているシステムでそれを確かめる。*負荷テスト*は多くの利用者を同時に模擬する。見るのは*スループット*（一秒あたりの行動）、 *レイテンシ*（各行動にかかる時間。中央値と、苦情を言う人が見ている*95パーセンタイル*）、そしてエラー率を、期待される量と「十倍」で。その後、何かが壊れるまで負荷を上げる：*破断点*は「遅くなる」ではなく「180ユーザーでデータベースへの接続が尽きた」だ。その数字がこの区間で最も役に立つ。そこからレッスン21の警報の*閾値*が出るからだ Ref. 12、 Ref. 44。

1. フローと許容を空欄に入れて、第19段の契約の最初のプロンプトを貼ること。
2. 許容を隣に置いて docs/PERFORMANCE_[日付].md を読むこと：その日の予約台帳は期待される量で二秒に収まりますか？ 十倍では？ 最初に何がどの負荷で壊れましたか？
3. どの量までボトルネックを今直すかを責任者と決めること：他の診療所に売ることを考えているなら「十倍」は今。そうでなければ、日付とともに。

4. 第19段の契約の締めのプロンプトを貼ること。
5. もらったコマンドで、あなた自身がスクリプトを期待される量で走らせること：数字は似ていなければなりません。

完全性の検証。 最もよく使われる画面は許容に収まりますか、またはその数字を持つ保留項目がありますか？ 破断点は何がどの負荷で壊れたかを言っていますか？ docs/PERFORMANCE.md の閾値は破断点の下、期待される量の上にありますか？ テストはゲートで、最初の実行は保管されていますか？

提出物。 テスト付きの負荷スクリプト、docs/PERFORMANCE_[日付].md、閾値とゲートを持つ docs/PERFORMANCE.md、そしてボトルネックごとの保留項目。

典型的な誤り。 破断点なしの「十倍を問題なく耐える」：負荷を十分に上げていない。画面ではなくAPIを叩くスクリプト。「ついでに」テストのあいだにボトルネックを直すこと。

ガイドプロジェクトでは。 期待される量で予約台帳は300ミリ秒で応答する。十倍で1.4秒。400件のリマインダーの夜の送信は50秒かかる。破断点：同時180人の利用者で接続プール（10）が尽き、行動が失敗し始める。閾値：予約台帳が1.5秒を超えるか、使用中の接続が7を超えたら警報。保留項目：夜の送信を50件ずつのバッチに。責任者は本当に売りたいと思っているからだ。

レッスン 20 — 生きた文書と、人がAIなしで追えるマニュアル

理解すべきこと。 システムはエージェントなしで、あなたなしで、使い、保守し、復旧できなければならない。復旧マニュアルの基準は具体的だ：プログラミングをしない信頼できる人が、午前三時に、システムが落ちてエージェントが接続できない状態で、追えなければならない。ある手順が「開発者に相談」と言うなら、不完全だ。そしてモデルで文書を再生成するのは無料なので、ルールは「同じコミットで」になる：ユーザーが見るもの、オペレータがすること、デプロイ方法に触れる各変更は、同じコミットでマニュアルを更新する。その基準で私の最初のシステムのために書いたマニュアルが模範だ Ref. 24。

そして既に持っている源：閉じた保留項目。レッスン5が求めるように各締めを文書化したなら、ユーザーマニュアルはゼロから書かない：閉じた保留項目からブロックごとに組み立て、変更日誌はそこから直接出てくる。

課題。

1. 約束にルーチンを追加すること：

2. 貼ること：

求めているのは、実際のスクリーンショット付きの三つのマニュアル、復旧マニュアルのための午前三時の基準、穴を残す代わりに事業だけが知ることを質問すること、そして日付とバージョン。

3. 本当のテスト：復旧マニュアルをプログラミングをしない誰か（オーナー、家族）に渡し、テスト環境で「落ちた」の節を追うよう頼むこと。つまずいた場所で、マニュアルを直さなければならない。
4. 次の画面の変更の後、コミットがユーザーマニュアルに触れたことを確かめること。
5. そしていよいよ受け入れテスト：オーナーが、最初の実ユーザーが入る前に、現実的なデータで、六つのフローに従って、テスト環境でシステム全体を使う。見つけたものは保留項目。それらが閉じれば、システムは受け入れられた。

完全性の検証。 無作為のスクリーンショットは今日のテスト環境と一致するか？ プログラミングをしない誰かが「落ちた」の節を追えたか？ 画面を変えた最後のコミットはマニュアルに触れたか？変更日誌には閉じた各保留項目の項目があるか？「[要記入]」のような穴があるか？ 各マニュアルはどのバージョンに有効か言っているか？ オーナーはすべてのフローについて受け入れテストをしたか？

提出物。 日付とバージョン付きの三つのマニュアル、人によるテスト済み、そして閉じた受け入れテスト。

典型的な誤り。 マニュアルを一度生成して約束にルーチンを入れないこと：二か月後にはもう存在しない画面のスクリーンショットがある。「エージェントとのセッションを開く」で始まる復旧マニュアル。そして人によるテストをしないこと：価値のある唯一の検証だ。

ガイドプロジェクトでは。 Turneraのユーザーマニュアルは三つのブロックの閉じた保留項目から組み立てられたスクリーンショット付きの六つの画面を持つ。保守マニュアルは各モジュールがどこにあり、テスト群をどう実行するかを説明する。復旧マニュアルは順に、コマンド付きで言う：システムが落ちているかどう知るか、どう再起動するか、前のバージョンにどう戻るか、最新のバックアップ（毎晩取られる：それもこのレッスンから出る）からデータベースをどう復元するか、誰に電話するか。責任者はテスト環境でそれを追い、「データベースの復元」でつまずいた。コマンドが彼女の持っていないフォルダを前提としていたからだ。マニュアルが直された。

運用区間：レッスン21から23

この三つのレッスンは本番への最初のデプロイとともに始まり、終わらない。二つの監視はそれとともに組み立てられ、それ以降は独りで走る。そして振り返りが各段階を締め、次の段階のために0へ戻る。

レッスン 21 — 資源と性能の監視、周期報告とともに

理解すべきこと。 レッスン19はある一日にシステムがどうふるまうかを言う。本番は毎日であり、データは増え続ける。*監視する*とは、機械で、いつも、*資源*の使用（プロセッサ、メモリ、ディスク、接続、メッセージの提供者のクォータ）と各関数、各クエリの応答時間を見て、何かが範囲外に出たら知らせることだ：*閾値*（レッスン19のもの）を超えているか、*基準線*（それまで出していた値）と大きく違うか。*警報*はその場で知らせる。*周期報告*は毎週か毎月、落ち着いて読む。ルールは二つ：誰も読まない警報は警報の欠陥だ。そして閾値は、計測された書かれた理由なしに、警報を黙らせるために上げない Ref. 37、 Ref. 39。

1. 経路、サイクル、逸脱を空欄に入れて、第21段の契約の最初のプロンプトを貼ること。
2. テストでわざと閾値を超えるよう求めること：その経路で警報が届かなければなりません。
3. 最初の報告を読むこと：範囲外の各イベントに原因か提案がなければなりません。

4. 第21段のルーチンを "Add this routine to docs/WORKING_AGREEMENT.md:" で包んで約束に加えること。

完全性の検証。 引き起こした警報は届きましたか？ 報告は各逸脱に原因か提案を持っていますか？ 対応すると決めた逸脱ごとに、数字を基準とする保留項目がありますか？ レッスン19から上がった閾値はありますか、どんな理由で？ 報告はメッセージの提供者のクォータを見ていますか？

提出物。 歴史を持つ収集、警報、周期報告、docs/MONITORING.md、約束の中のルーチン。

典型的な誤り。 誰も読まない毎日の警報。「すべて正常」と言う三つ続きの報告。「知らせなくなるように」上げられた閾値。「診断のために」保存された個人データ。

ガイドプロジェクトでは。 Turneraの最初の月次報告はこう言う：ディスク40%、メモリは安定、その日の予約台帳は中央値320ミリ秒（基準線）、患者の検索は4から9ミリ秒に上がった（テーブルが育っている。範囲内）、メッセージのクォータは60%（提案：80%で知らせる）。逸脱が一つ：責任者の月次の集計表が1日に11秒かかった（提案：夜に先に計算しておく。保留項目）。

2026年10月19日に変わったこと（D-039）。 サイジングを再検証する測定には検証可能な期間を添えます。データベースから読んだ最初と最後のレコードであって、手で入力した数字ではありません。練習では、3 年分の 30,000 行を 1 年分として渡したために誤報が出ました。手入力の期間はレポートにそう明記し、警告するだけです。

レッスン 22 — エラーの監視と周期報告

理解すべきこと。 本番のシステムは誰も報告しないエラーを生む：白い画面を見てもう一度やり直した受付係、途中で切れた夜のジョブ。このレッスンはそれらを、隠れる三つの場所（バックエンド、ジョブ、ブラウザ）で*捕捉*し、*まとめ*（同じエラーの千回はカウンタ付きの一項目）、新しいものと増えているものを知らせ、*フローごとのエラー率*（登録された百件の予約のうち何件が失敗したか）を持つ報告を生む。ルールは二つ：保留項目のないエラーは一つもない。そして、なぜ許容するのかいつまで許容するのかを言う保留項目のない「既知のエラー」は存在しない Ref. 43、Ref. 22。

1. 経路、サイクル、数字を空欄に入れて、第22段の契約の最初のプロンプトを貼ること。
2. テストで、あなた自身がブラウザにエラーを引き起こすこと（たとえば予約のフォームにありえない日付）：あなたの識別子とともに捕捉に現れ、新しいものなら警報が届かなければなりません。

3. 第22段のルーチンを、他と同じように包んで約束に加えること。
4. 最初の報告とともに：新しいエラーの修正の保留項目を、それぞれ再現とともに開き、レッスン8のルーチン（それを再現する赤のテスト）で閉じること。

完全性の検証。 引き起こしたエラーは捕捉に、警報に、報告に届きましたか？ 保留項目も日付付きの理由もない繰り返すエラーがありますか？ 報告の「直された」エラーは、その保留項目に赤のテストを持っていますか？ フローごとのエラー率はあり、前の期間と比べられていますか？ 捕捉の中に個人データがありますか？

提出物。 中央でまとめられた捕捉、警報、フローごとの率を持つ周期報告、完成した docs/MONITORING.md、約束の中のルーチン、そしてエラーごとの保留項目。

典型的な誤り。 実際の利用者がいるのに「一か月でエラーゼロ」：捕捉がブラウザかジョブを見ていない。千回発生したエラーに「既知、影響なし」というコメント。再起動で「直される」エラー。そしてエラーの報告を資源の報告と突き合わせずに読むこと：一方の遅いクエリが他方のタイムアウトだ。

ガイドプロジェクトでは。 Turneraの最初の報告には三つのエラーがある。一つはブラウザで（専門職の氏名にアポストロフィがあると予約台帳が失敗する。14回。保留項目、赤のテスト）。一つは夜のジョブで（メッセージの提供者がある夜エラーを返した。1回。記録とともに再試行する保留項目）。そして一つは月次の集計表の甥の「既知の」もの（日付付きの保留項目：パート2のレッスンR2 の報告に置き換える）。エラー率：「予約を登録する」で0.3%、他は0%。

2026年10月19日に変わったこと（D-038）。 エラーの捕捉は発生源で分けます。システムのエラーと、それを観測する道具（パネル、常駐エージェント、監視そのもの）のエラーはレポートの別の節に入り、保留項目を開くのはシステムのエラーだけです。練習では、最初の周期レポートが六つの「バグ」を開きましたが、それは道具が停止中のサーバーと話していただけでした。

レッスン 23 — システムの中のエージェント、そして数字による振り返り

理解すべきこと。 二つのことがサイクルを閉じる。一つ目は任意：常駐エージェントを限定された範囲で本番に残し、あなたがいなくても診断しサポートできるようにすること Ref. 13。それを律するルールは誰かの名において行動するということだ：その認証情報は責任ある人に紐付けられ、することのすべてがその人の名で記録される。匿名のアカウントではなく、上司のいる従業員だ。二つ目は必須：数字による振り返り。何がかかったか、保留項目はいくつ、どれが往復を要したか、どんなインシデントが起きどの段に落ちるか、そしてはしごへの少なくとも一つの提案された変更。何も変えない振り返りは振り返りではなかった。エージェントのチームまるごとを廃止するに至ったものが模範だ Ref. 6。

課題（常駐エージェント、該当するなら）。

1. 貼ること：

求めているのは、運用する前の地図、地図の穴を宣言すること、あなたが一つを選ぶための三つの範囲のレベル、そして人の名における認証情報。

2. レベルを選ぶこと（始めるには、常に一つ目：読み取り専用と診断）。

3. こう締めること：

課題（振り返り、常に）。

4. 貼ること：

求めているのは、出所付きの数字、段に対応付けられた各インシデント（どの段にも落ちないインシデントは欠けている段だ）、持っていない数字を求めること、そしてはしごへの具体的な変更提案。

5. 変更提案を読むこと。有効だと思うなら、改善提案として Urazukeのリポジトリへ送ること（CONTRIBUTING.md 参照）：それが方法が各プロジェクトから学ぶ形だ。

完全性の検証。 地図はエージェントが何を見られないかを言っているか？ 範囲外の行動が拒否されるのをログで見たか？ 認証情報は人の名において行動しているか？ 振り返りには出所付きの数字があるか、形容詞か？ 各インシデントは段に落ちるか？ 少なくとも一つの具体的な変更提案があるか？

提出物。 docs/RESIDENT_AGENT.md（該当するなら）と docs/RETROSPECTIVE_[日付].md。

典型的な誤り。 「すべて解決できるように」常駐エージェントに高いレベルを与えること：読み取り専用から始め、証拠があれば上げる。すべてうまくいったと言う振り返り：すべてうまくいくことは決してない。あなたのために書かれており、方法のためではない。そして変更提案を送らないこと：第23段は文書が書かれたときではなく、はしごが変わったときに閉じる。

ガイドプロジェクトでは。 典型的なコースでのTurneraの振り返り：受講生の約四十時間、二十八の保留項目、最も往復を要したのはメッセージのもの（タイムゾーンとWhatsAppプロバイダ）。二つのインシデント、一つは第11段（状態「欠席」が画面には存在しサーバーには存在せず、セマンティックツリーにもなかった）、もう一つは第15段（テストの設定での本番へのデプロイ、デプロイ後のエンドツーエンド検証で検知）。変更提案：第15段のデプロイのルーチンが、昇格の前に「何が変わるか」だけでなくテストと本番の設定の差分を見せることを要求すること。

本番リリースのチェックリスト

二十四のレッスンが終わったとき、システムはこのリストを満たす。Urazukeにおける「プロダクショングレード」の運用上の定義であり、最終の検証リストとして、オーナーとともに、コードを開かずに使える：

1. 決定、日付、名前付きの適格性シートがある（P0）。
2. エージェントが毎セッション読む共働の約束があり、読むことが証明された（P1、P2）。
3. プロジェクトファイルは五分で読め、システムが何でないかを言う。オーナーが確認したセマンティックツリーがあり、すべての保留項目がノードからぶら下がる（P2）。
4. 出所付きの一次データ、計算付きの派生データ、「十倍」のシナリオを持つサイジングがある（P3）。
5. 骨組みは立ち上げで、インテグレーションとデプロイの連鎖とともに空でデプロイされ、デプロイは二度実行された（P4）。
6. すべての変更に詳細な仕様付きの保留項目があり、閉じたすべての保留項目はその仕様と証拠を保持する：完了したことの文書だ（P5）。
7. すべての事業ルールにオーナー、日付、発言そのままが、コミット、保留項目、記録にある（P6）。
8. 何かを決めたすべての数字に、あなたが実行できるテスト付きの計器がある（P7）。
9. すべての重要なテストは緑の前に赤で見られた。各フローには画面からバックエンドを検証するエンドツーエンドテストがある。完全なテスト群は各ブロックの締めと本番の前に走った（P8）。
10. コードの品質は各コミットで機械によって検証され、ゲートであり、カバレッジは一度も下がらなかった（P9）。
11. 各機能には人に向けて書かれた手動テストケースがある。各ブロックの締めと受け入れで、日付と名前付きで実行された。各失敗は保留項目として戻った（P10）。
12. すべてのリストには一人の所有者しかいない。生産者/消費者の地図がある。自動検証付きのアンチパターンの記録がある（P11）。
13. すべての報告は検証済み、信じている、盲点を分ける（P12）。
14. 別のセッションによる少なくとも一回の監査があり、そのP0は保留項目になった（P13）。
15. 帰結のあるすべての行動に赤のテスト付きの錠と戻り道がある。自動化はドライランモードを通った（P14）。
16. テストはコミットごとに一度走る。設定はリポジトリの外にある。ロールバックは試された。リポジトリにもチャットにもローテーションされていない秘密はない（P15）。
17. 記録は構造化されていて、デプロイせずに設定可能なレベルを持ち、各行動を画面からデータベースまで追う識別子を伴う。帰結のある行動は不変の監査に残る。記録の中に個人データは一つもない（P16）。
18. 実際のクエリは期待される量で計測され、前と後とともに直され、重要な経路ごとにテスト付きの予算がある（P17）。
19. 脆弱性の走査は各プッシュと暦で走り、ゲートであり、開いたP0はない（P18）。
20. テスト付きの負荷テストがあり、期待される量と「十倍」で走り、破断点が書かれ、そこから導かれた閾値がある（P19）。
21. 日付とバージョン付きの三つのマニュアルがあり、閉じた保留項目から組み立てられた。プログラミングをしない人が復旧マニュアルを追った。オーナーはすべてのフローについて受け入れテストをした（P20）。
22. 資源の使用と応答時間は警報と周期報告で見張られ、各逸脱に原因か保留項目がある（P21）。
23. エラーはバックエンド、ジョブ、ブラウザで捕捉され、まとめられ、フローごとの率とともにサイクルごとに報告され、保留項目のないものは一つもない（P22）。
24. 数字による振り返りとはしごへの変更提案がある（P23）。

二十四すべてが「はい」なら、システムは導入する準備ができている。どれかが「否」なら、どの段を登り直すべきかもうわかっている。

そしてその後：パート2、受け継いだプロジェクト

この第一部が空のフォルダの上で方法を教えるのは、それが学ぶのに最も明快な形だからだ。だが現実では空のフォルダを渡されることはほとんどない：既に動いているシステムを渡されて、「これを直して」か「あれを足して」と言われる。コースのパート2 は同じ診療所を別の時間軸で取り上げる。甥が一夏で作り、誰も丸ごとは理解していないアプリケーションとともに。そして進化・修正の道の正常化の区間を教える：方法が前提とする入力を復元し、安全ベルトを組み、負債に順序を付けるための八つのレッスン。そして最初のバグを修正し、完全な方法で最初の新しい機能を構築するためのもう二つ。

付録A — 評価の仕方（コースを教える人、または自己評価する人のために）

レッスンごとの、三段階の簡単なルーブリック：

• 登れていない：提出物が欠けているか、完全性の検証のどれかが「否」。
• 登れた：提出物が存在し、すべての検証が「はい」。
• 判断力の証拠付きで登れた：加えて、受講生がそのレッスンでエージェントが何か間違えた事例（推測した、発明した、過剰に報告した）とそれをどう検知したかを語れる。それがコースの本当の目的だ：成果物ではなく、反射。

評価しないもの：コードの品質。誰も読まない。証拠の品質を評価する。

付録B — 各ツールへのコースの適応

プロンプトはどのツールでも同じだ。変わるのは、コースで docs/WORKING_AGREEMENT.md に追加するルーチンがどこへ行くかだ：

• Claude Codeでは、ルーチンはプロジェクトの CLAUDE.md に入り（またはそこから約束を取り込み）、毎セッション自動で読まれる。
• Cursorでは、.cursor/rules/ に、常に有効なルールとして。
• Codex CLIまたはGemini CLIでは、ルートの AGENTS.md または GEMINI.md に。
• Forgeでは、約束とルーチンは教義で、段のプロンプトは各ゲートを通過するとき自動で注入され、保留項目の記録はネイティブで、セマンティックツリーはプロジェクトの知識グラフだ。 Forgeでのコースは、コピー＆ペーストが少ない同じコースだ。

レッスン2の読み取りテストはすべてに通用する：新しいセッションがシステムが何をしないか知らないなら、ツールは約束を置いたファイルを読み込んでいない。

付録C — このマニュアルにまだないもの

• これを受講したコホート。段階の順序、典型的な誤り、ガイドプロジェクトは私の三つのシステムから書かれており、受講生からではない。最初のコホートがそれらを修正する（そしてそれは文字通り、コースに適用された第23段だ）。
• 適格性基準の重み（レッスン0）、較正中。
• ガイドプロジェクトの docs/PENDING.md の完全な例、仕様付きで閉じた二十八の保留項目とともに。受講生がプロジェクトの終わりに完了したことの文書がどう見えるかを見られるように。