Urazuke — 参照文書：方法の背後にある事例

著者：Pablo Kuschniroff、Claude Codeの支援による。第4版、2026年10月18日。

この文書は一つのことのために存在する。方法の手順とマニュアルをきれいに保つためだ。主文書で、段の契約で、またはコースのレッスンで、私が「これは痛手を重ねて学んだ」「これはモデルがうまく適用しなかったから課した」のようなことを主張するとき、説明を日付、コミット識別子、保留項目の番号で汚したくない。短い印 [Ref. N] を置き、事例を調べたい人はここに来て、日付、証拠、そして何が起きたかについての私の読みとともにそれを見つける。調べたくない人は、つまずかずに読み続ける。

始める前に二つの注意。第一：これらの事例が出てくる三つのシステムは実在し、今日本番稼働しており、本物の人々が使っている。顧客は匿名化されており、「共済組合」（その「認可者」とともに）と「協会」と呼び、そのシステムを「Autorizaciones」と「Kikan」と呼ぶ。三つ目のリポジトリは方法が生まれたツール、yujin-forgeで、私のものであり、その名前を持つ。数字、日付、コミット識別子は実在のものだ。いつか顧客の許可を得られたら、名前を載せる。

第二の注意はより重要で、誤解されたくないので主文書でも繰り返している：方法は失敗の事例だけから生まれたのではない。二つのものが組み合わさって生まれた。一方では、これらのモデルが存在するずっと前から私が適用してきたシステム工学についての私自身の知識。段で私が求めることの大半は、よく運営されたプロジェクトで常に求めてきたことだ。他方では、この五か月のインシデントが、次々と、モデルがそれらの原則を脆く適用する場所を私に見せたこと：テストしたと言ってテストしていない場所、自信ありげな顔で推定する場所、事業ルールの穴を思いつきで埋める場所、過剰に報告する場所。だから続く事例は、締めるべき場所の証明であって、方法全体の起源ではない。そのレンズで読んでほしい。

引用の仕方

方法のどの文書でも、[Ref. 26] はこのファイルの「Ref. 26」の項目にリンクする。項目は起源システムごとにまとめられ、各グループ内では時系列順。最後に三つの完全な年表があり、誰かが全体の順序を見たいときのためのもの、そして各失敗をそれを覆う段に対応付ける表がある。

A. yujin-forge：方法が形成された場所（2026年5月から10月）

Ref. 1 — 品質基準の誕生（5月25日）

最初の品質基準の文書 SQ.md を5月25日に書いた（コミット 2219f7a）。人間とエージェントの最初の「共働の約束」であり、書いたのは、二週間にわたって毎セッション同じことをモデルに繰り返していたからだ：私の時間は神聖で、自分で解決できることには使わない。技術的負債は残さず、壊れたものは根本から直す。文書は最新に保つ。範囲は正確に、頼まれた以上でも以下でもなく。システム工学ではどれも新しくない。新しかったのは、毎朝昨日の記憶なしにやってくる協力者のためにそれを書かねばならなかったことだ。第1段の起源。

Ref. 2 — 最初のアンチパターンの記録（5月27日）

5月27日（コミット 73f4029）に GOTCHAS.md を開いた：繰り返した各誤りが固定形式で書き留められるファイル。どう匂うか、根本原因は何か、どう直したか、次回痛む前にどう検知するか。開いたのは、モデルが以前に犯した記憶をまったく持たずに、別のセッションで同じ誤りを犯していたからだ。第11段の「アンチパターン」の半分。

Ref. 3 — ワークフローのゲート、該当するときだけ注入（6月2日）

6月2日（コミット 5b47475）にワークフローの明示的なゲートをG1からG9まで番号付きで定義し、文書化のゲートG-DOCを定義した。G-DOCは文書が変更と同じコミットで更新されることを要求する。そして重要と判明した決定を取った：各ゲートの教義はそれが適用される瞬間だけエージェントのプロンプトに入り、常にではない。文脈は有限であり、余計に注入されるものは注意力で支払われるからだ。ゲートを通過するときに注入される「段の契約」という考えの直接の前身。

Ref. 4 — テスト方針の再定式化（6月4日）

6月4日まで私はすべてに「テストが先、コードが後」を強いていた。その日（コミット a9f59c7、文書 testing-policy.md）、普遍的には役立たないことを受け入れた：既定ではテストは実装の後、テスト先行は小さく明確な範囲の選択肢として残り、骨組みはゲートとして緑でなければならず、ループ対策を加えた。エージェントが進まず空回りするときすべてを止めるモーダルだ。これを語るのは、私のルールが硬直しすぎと判明したとき、方法が自分自身を修正することも示すからだ。

Ref. 5 — 決定は構築前に凍結される（6月4日）

大きなスプリントの前に、6月4日の決定文書に三つの構造的決定（D1、D2、D3）を書いて番号を付けた。古典的プロジェクトで常にしてきたことを初めて形式化した：決定は構築前に、日付付きで書く。後で誰も記憶で議論しないように。第6段の前身。

Ref. 6 — 数字を手にマルチエージェントチームを廃止（6月5日）

互いに仕事を渡し合う五つのエージェント（ディレクター、アナリスト、プログラマ、テスター、骨組み構築者）のチームがあった。計測された実験をした：そのチームは60ドルと73分を費やして半端なものを納めた。単一エージェントの単一セッションは90分かかり、公開可能なものを納めた。 6月5日（コミット 7584f8b、内部論文で文書化）にチームまるごとを廃止した。「数字を手にした振り返り、そして再設計」の最初の事例であり、第23段が印象ではなく数字を要求する理由だ。

Ref. 7 — 計画が保留項目のリストになる（6月6日）

6月6日（コミット 4fc82c6、保留項目記録の計画）に作業計画が保留項目のキューそのものになった：正規の、番号付きの、管理コマンド付きの、毎セッション更新されるリスト。「計画」が一方に「タスク」が他方にあるのではなくなった。第5段の起源。

Ref. 8 — 検証の誠実さとワークフローの種類（6月10日）

6月10日（コミット 7ab9d8a と 2c552c0、文書 verification-honesty.md と workflow-kinds.md）に教義をすべてのプロンプトで必須にし、「検証の誠実さ」のルールを書いた：ネットが必要なときに本当に赤になることを検証し、盲点を宣言し、検証したことに釣り合った主張をする。さらに三種類のワークフローを分けた：新規プロジェクト、修正、進化。第12段と第8段の「赤」の半分の起源。

Ref. 9 — 地図を読まなかったための捨てられた仕事（6月12日）

6月12日、あるセッションがプロジェクトの知識グラフを読まずに構築を始め、午後一つ分の仕事が捨てるものになった。既に書かれていた決定に矛盾していたからだ。そこから第2段の必読のルール：地図は存在するが、読むよう義務付けなければ、作用しない。

Ref. 10 — 24時間と48時間の自動操縦（6月14日から21日）

6月14日から21日の間、エージェントを一日、そして二日、単独で働かせた。書面の委任付きで：ピースごとにコミットとプッシュ、質問なし、私は要約を受け取る。これを語るのは、共働の約束と保留項目の記録がよくできていれば方法が長い自律に耐えることを証明するからであり、そこで要約を疑いながら読むことを学んだからだ。それが第12段だ。

Ref. 11 — 他者のシステムに対する診断モード（7月）

7月（文書 diagnostic-mode.md）、エージェントが顧客の本番システムに診断モードで入り始めた：読み取り専用、限定、何も触らない。第23段の常駐エージェントの範囲の最初のレベル。

Ref. 12 — 共済組合の本番から取った性能のパターン（7月22日）

7月22日（コミット 873339c）、共済組合のシステムから抽出したスケールのパターンをツールに組み込んだ：二つのトランザクションのパターン、そして何より「触る前に計測」。初めて方法が既に本番にあるシステムから養分を得た。第7段の前身。

Ref. 13 — エージェントが共済組合の本番に常駐する（8月14日）

8月14日、エージェントが顧客のシステムの中に常駐アシスタントとして設置された。三つのルール付き：操作前に必須のシステム地図、何かが失敗したとき「まず運用上の解決」、そしてチケットを開く能力。第23段の前半の起源。

Ref. 14 — ゲートとしてのサイジング（10月10日と11日）

10月10日と11日（コミット c602725 と 0bd1b05、文書 sizing.md）、構築前のサイジングを固定の選択肢から選ぶ形で形式化し、もう一つのゲート（G9）として記録した。遅く形式化した。参照15で語るKikanの痛手の後に。それがまさに第3段の教訓だ。

Ref. 15 — 一行目から非同期の永続化インターフェース（10月13日）

10月13日（コミット 7391cc5、文書 persistence-interface.md）、データベースとのインターフェースは最初のエンジンが同期でも最初の行から非同期である、というルールを書いた。「非対称な」決定だ：間違えても安く、取らなければ非常に高くつく。知っているのは、Kikanで間に合うように取らず、後から変えるのに再設計の一段階まるごと、E6、三つのテスト群の非同期化を要したからだ。第3段の事例。

Ref. 16 — 1時間43分の孤児ターン（10月14日）

10月14日、エージェントが私に見えないまま1時間43分働き、その間に六つのコミットをした。方法の失敗であり、ひどかった。バージョン1.18.0（コミット b80a659）で根本から直した：生きている兆候を出さなくなったターンを殺す沈黙の番犬、子が親とともに死ぬためのプロセス間のリード、そして28のテスト。第12段（報告は見えなければならない）と第14段（疑わしきはシステムは進まない）に落ちる。

B. Autorizaciones：実負荷の下の方法（2026年6月から10月）

Ref. 17 — リポジトリが追い越した初期設計（6月11日）

Autorizacionesは設計文書（「選択肢C」）で始まった。リポジトリは非常に速くそれを追い越した：構築されたものは紙に書かれたものよりはるかに多かった。私に残った教訓、第5段にあるものは、仕様は出発点として有効で、生きた計画は保留項目だということだ。

Ref. 18 — インデックスなしクエリの最初の監査（6月23日）

6月23日、稼働中のシステムで最初の「フルスキャン」（インデックスがないためテーブル全体を読むクエリ）の監査を行った。発見は保管される報告ではなく、保留項目に変換された。第13段の起源。

Ref. 19 — Googleクラウドの教訓（6月24日）

Googleクラウドでの最初の数週間のインフラの誤りは、繰り返さないための教訓として書き残された。後に第20段のインフラマニュアルとなるものの最初の版。

Ref. 20 — ユーザーマニュアルはシステムとともに生まれる（6月26日）

6月26日には既にユーザーマニュアルがあった。システムは構築途中で。意図的にそうした：古典的プロジェクトではマニュアルは最後に、誰も何も覚えていないときに書かれた。無料で再生成するモデルがあれば、システムとともに生まれない言い訳はない。第20段。

Ref. 21 — 第二層のバックアップ（7月13日）

実データでシステムを信用する前に、二層のバックアップを設置した：ローカルとGoogleストレージ。第15段と第20段の復旧マニュアル。

Ref. 22 — PND-300：根本原因まで四往復（7月14日）

あるバグが、7月14日に本当の原因が見つかるまで三度戻ってきた。それまでの各「修正」は症状に対するものだった。ここで、既に共働の約束にあった「修正は根本からか、修正ではないか」が言葉であることをやめて実践になった：触る前に仮説を計測しなければならない。第1段と第7段。

算数を声に出して言う。二つの数字は同じ事例を二つの側から数えたものだからだ。 修正の 四ラウンドと、バグの三回の再発があった：ラウンド1が「直して」再発し（再発1）、2が「直して」再発し（再発2）、3が「直して」再発し（再発3）、4が根本原因を見つけた。だからこの参照の題は四ラウンドと言い、この段落は三回戻ったと言い、段ごとの不具合の表は根本ではなかった三つの修正を数えている：矛盾ではなく、nラウンドとn−1回の再発だ。この行がなければ三つの言及が同じ事実の三つの違う数字として読まれるので、ここに書いておく。実際、この事例を再現した最初の外部の読者は「四回戻った」と書いた。注意深く読んだ人が別の数字を持ち帰れる参照なら、欠陥は参照の側にある。

Ref. 23 — セキュリティ監査（7月16日）

7月16日、最初の正式なセキュリティ監査を行い、発見は保留項目に変換された。セキュリティを最初に一度チェックするリストではなく定期的な監査として扱うことを私に確信させたものだ。第13段。

Ref. 24 — 内部マニュアルと災害復旧マニュアル（7月26日と29日）

7月26日と29日（コミット 6444ce6、保留項目442、と a30cee3、保留項目459）、運用のすべて、デプロイ、復旧、保守を「AIなしで手で再現可能」な形で文書化した。私が使い、第20段にある基準は、明日エージェントがいなくても、プログラミングをしない信頼できる人がマニュアルを追えることだ。

Ref. 25 — 反射としてのフェイルクローズド（7月27日）

7月27日（コミット e18406d、保留項目452）：テーブルが存在しないか検索が失敗したら、行はただそのボタンなしで残る。決してリスト全体は壊れない。疑わしきは行動せず、壊さず。そしてその修正のテストは「try/exceptなし」で赤で証明された。つまり保護なしではリストが壊れることが示された。第8段と第14段。

Ref. 26 — 一致しなかったカウンタ：1,355対1,234（8月6日と7日）

私にとって「計器で検証する」の最も完全な例。画面のカウンタは1,355の承認を示し、データベースへのクエリは1,234を示した。8月6日と7日（コミット ab3e529、保留項目517、と 1f5feb9、保留項目514）、本番で直接、読み取り専用で根本原因を検証し、差を数字ごとに分解し（145多く、24少なく。145引く24は121）、古い基準に対して赤で証明されたテストを書き、診断スクリプトは次回のためにリポジトリに残った。第8段、第11段、第7段。

Ref. 27 — 生産者と消費者の対称性（8月6日）

8月6日（コミット 50fe968、保留項目510、と 7251129、保留項目509）、ユーザーが見る「待機理由」がロボットが決定するのと同じゲートで計算されること、そしてグリッドの列のリストをサーバーが定義しフロントエンドが消費することを課した。こうして乖離しえない。第11段の「すべてのリストには一人の所有者しかいない」のルール。

Ref. 28 — 錠付きの緊急ボタン、承認者のドライランモード、ガード付きの番人（8月7日）

8月7日（コミット 0954740、保留項目524）、システムの錠が揃った：二重の安全装置付き緊急ボタン、まずドライランモードで走る自動承認者（承認以外のすべてをし、承認したはずのものを記録する）、そして二度押さないためのガード付きで詰まったものを押す番人。第14段。

Ref. 29 — コミットに書かれたドメインルール（8月10日）

8月10日（コミット 0ae3ae6、保留項目550）、コミットメッセージは原文でこう言う：「Pabloのルール：承認済み + 残高 = 戻る」「Pablo決定 2026-08-10」。事業の決定が日付とオーナー付きで、それを実装するコードに貼り付いて残った。第6段。

C. Kikan：成熟した方法（2026年8月から10月）

Ref. 30 — 既に書かれた方法で開始、そして監査シリーズAUD-*（8月21日から29日）

Kikanは、前述のすべてが初日から既に書かれた状態で始まった最初のプロジェクトだった：運用可能なプロジェクトファイルと、最初のコミット（8月21日）からの計画としての保留項目。8月28日と29日に早期の監査シリーズ（AUD-1、AUD-2…）を行い、それは直接19の保留項目文書に変換された。第2段、第5段、第13段。

Ref. 31 — 最初の週からの継続的インテグレーション。パッケージとしてのデプロイ（8月28日、9月23日と24日）

テストは最初の週からGitHubで走った（ci.yml、8月28日）。デプロイは9月23日に来た（deploy.yml、コミット bb801ed）：パッケージ、設定はリポジトリではなくサーバーに住み、ランタイムのバージョンは釘付け。デプロイが立ち上げの一か月後に来たことが、第4段を動機づける誤りだ。

Ref. 32 — 保留項目を重ねて強化されたデプロイ（9月30日から10月4日）

9月30日から10月4日の間、デプロイがうまく動くためだけに五つの連続した保留項目があった：両環境での公開URL（f85c3c9）、再起動の前と戻す前のサービスのリロード（513c8d0、保留項目 108）、複製する代わりに照合するフィクスチャ（076df76、保留項目134）、ミラーされるツリーの外の顧客の素材（9d76af8、保留項目130）、そしてデプロイで運ばれる設定をもう汚さないテスト群（0bd20a8、保留項目107、10月3日）。骨組みが最初の週に空でデプロイされていれば、その五つの痛手は機能ゼロの状態で受けていた。第4段と第15段。

Ref. 33 — UATから本番への昇格（10月4日と8日）

10月4日と8日（コミット 4eb5ad7、保留項目027、と 7658e2e）、設定とキャンペーンをテスト環境から本番環境へ渡す明示的な回路ができた。第15段。

Ref. 34 — コードから導出されたスキーマ、錠付き（10月11日）

永続化の再設計の段階1（コミット 6113319 と 68819ce）で、テーブルとフィールドの目録がコード自体から導出され、守るテスト付きで、私がレビューできるよう共有の掲示板に開かれた。一人の所有者、コード、を持つリストだ。第11段。

Ref. 35 — 静的ラチェット、そして見ていなかった計器（10月11日から13日）

再設計の段階6（コミット 06b2734、f6e5221、2fc6239、1d55a93）で「ラチェット」を設置した：await なし、つまり結果を待たないデータベース呼び出しのカウンタで、下がることしかできず決して上がらない。そして語る価値のあることが起きた：計器がコードの一部を見ていないことが二度発覚した。最初は70回、次に84回の呼び出し、カウンタはゼロのまま。計器が検証されなければ、数字は安心させて嘘をつく。第7段。

Ref. 36 — 嘘をついた計器と11.b節の五つのルール（10月13日と14日）

10月13日のコミット（880ac0f、f955620）の原文：「E7.5の計器はALTER適用済みのベースで嘘をついていた」「27ではなく44」。そして数日前、ある計画がある種のループが121あると主張し、実行者が計測したら79だった。これらすべてから再設計文書の11.b節を書いた。今日第7段である五つのルール付きで：ガード付きの計器。計器がなければ作る。双方向で監査する。近似は印す。そして実行者は計画者の数字を検証する。それを要約する文とともに：「四つの主張のうち三つが間違っていた。計器があったところでは正確だった」。

Ref. 37 — クエリ予算と計測値に締められた天井（10月14日）

段階8（コミット 5926b3f、10ada00）で、アプリケーションの各経路に計測されテストで守られたデータベースクエリの予算がつき、データベースエンジンの変更は環境ごとのスイッチになった。段階9（0730082、7f5f1af）で天井は計測値プラス小さな余裕に締められた：60に対して63。予算は作られた数字ではない。第7段。

Ref. 38 — テーブルごとの保持、そして別のセッションによる整合性報告（10月14日）

段階10と12（コミット f72b15a、b266f11）で、実際のパッケージが移行スクリプトを運ぶようになり、データの保持はテーブルごとに宣言されて本番で制限され、システムを構築していないClaude Codeの別のセッションによる整合性報告が保留項目として吸収された。第13段の構築者とは別の監査者だ。

Ref. 39 — デプロイはパッケージするだけ、そして燃え尽きたクォータ（10月14日）

テストはコミットごとに三度走り、それぞれ16から27分かかった。16日間でGitHub Actionsのクォータ2,000分が消費され、23回プッシュした一日がそれを燃やし尽くした。10月14日（コミット 39497b0）に回路を分割した：テストは継続的インテグレーションで一度だけ走る。デプロイはその結果を待ってパッケージするだけ。コミットあたり16から27分から、11分へ。第15段。

Ref. 40 — 二十四時間で二つの管理者の扉（10月15日）

10月15日、一日で二つの管理者の扉が作られた（保留項目223と257）。外部レビューがそれを検知した。一つを撤回し（コミット 69bdab2、20fdbe7、1558ee4）、単一の道が残った。これを語るのは、方法がドラマなしに「素早く取り消す」に耐えることの証拠として、そして監査は構築していない誰かがしなければならない理由として。第13段と第14段。

Ref. 41 — 品質監査：一つの脆弱性、巨大なコンポーネント、9,661行のプロジェクトファイル（10月15日）

10月15日の品質監査は、依存関係の既知の脆弱性、2,679行の画面コンポーネント、ウェブ版とモバイル版で重複した八つのモジュール、そして9,661行789キロバイトまで育った CLAUDE.md、その時点では誰も、モデルすら読まないファイルを見つけた。そこから第2段のルール：プロジェクトファイルは綱領であって履歴ではなく、事例集は別に置く。第2段、第11段、第13段。

Ref. 42 — チャットに貼られた秘密（10月14日と16日）

10月14日、データベースの鍵がトランスクリプトに印字され、16日にはAPIキーがチャットに貼られた。どちらも「誰にも見られ」なかったが、どちらも同じくローテーションしなければならない。チャット、ログ、コミットにあった秘密はもう秘密ではないからだ。第15段。

Ref. 43 — 言っていることと違った三つの報告（10月14日から16日）

第12段の、小さく非常に示唆的な三つの事例。10月14日、認証エラーがツールによって「success」という表示で報告された。16日、サーバーのCORSが最初のドメイン名からのみ導出され、テスト環境の設定アシスタントは報告が言及しないエラー500を出していた。そしてモバイルアプリは、報告が検証済みと宣言した条件でタブを失っていた。三つとも同じルールで直る：検証したことと信じていることを分け、盲点を宣言する。

Ref. 44 — メモリで死んで失敗したテストに見えたテスト群

テスト群まるごとがメモリ不足で「死に」（コミット 1d7a20b）、報告はそれを失敗するテストと読んだ。完全な出力を見るまで、どのテストも失敗していなかったことがわからなかった：プロセスが落ちていたのだ。第8段が判定だけでなく赤と緑の数字を求める理由。

D. セッション中に私が課したこと、そして断ったこと

Ref. 45 — セッション中に私がした四つの訂正、後にルールになったもの（10月）

コミットからではなく、セッションの最中にエージェントにした訂正から生まれ、後に形式化した方法のルールがある。引用するのは、方法の起源の第二の要因、モデルの脆い適用に対する私自身の工学の判断を示すからだ。「ガード付きの計器、grepではなく」：決定に入力される数字はテキスト検索ではなくテスト付きのプログラムで計測する。「症状だけでなく仮説を計測しろ」：私が印象の形で原因を持ち込むとき、構築前に計測しなければならない。私はたいてい症状については正しく、原因はたいていその隣にあるからだ。「限界は散文ではなくログで検証しろ」：モデルの拒否は限界が適用されていることを証明しない。呼び出しを強制して記録を読まなければならない。そして「まず公開されているバージョンを比べろ」：「まだ壊れている」に対して、診断し直す前に私が問題を見ている場所でどのバージョンが動いているか見る。第7段と第12段。

Ref. 46 — 私が断ったプロジェクト、そして排除基準の出所（10月17日）

第0段の二つの排除基準は、私が受け入れたプロジェクトからではなく、断ったプロジェクトから来ている。アクセス可能なリポジトリのない、または標準に従わないリポジトリを持つレガシー技術を断った。リポジトリなしには証拠を残す場所がないからだ。そしてエンドツーエンドでテストできない技術、画面を実行しインターフェースの各要素にその各種の操作でアクセスして変更がバックエンドに届いたことを検証できない技術を断った。そのとき明確にし、今も維持していることは、NAC3は必須ではない、ということだ。必須なのは画面の実行からテストすることだ。

E. 完全な年表

誰かが個別の事例ではなく全体の順序を見たい場合のために置く。各行はリポジトリにあるままの証拠を持つ。

E.1 yujin-forge

E.2 Autorizaciones

E.3 Kikan

F. 各失敗と、それを覆う段

この表はある意味ではしごの証明だ：各痛手はどこかの段に落ちなければならない。どの段にも落ちないものが現れたら、段が欠けている。