ソフトウェアがすべきことと、そうさせる方法。文書、SSOT、ピラミッド、進捗、引き継ぎ、強制力の四段階。
§ 00 · 変えられないものと、作れるもの
まず枠組みを一つ。今は「エージェント＝モデル＋ハーネス（Agent = Model + Harness）」という定義が使われる。モデルはあなたには変えられない。本社が決めて渡す。変えられるのは、モデルを囲む文書、規則、権限、監視というハーネスだ。
だからAIに正しく仕事をさせるとは、よりよいモデルを待つことでなく、ハーネスを作ることだ。ソフトウェアは被疑者。させるべき仕事と、それをさせる装置を分けて見よう。
§ 01 · ソフトウェアが守る規律
機械に強制する最低限の規律。お願いでなく、ハーネスに打ち込む。
推測禁止。DB、API、ビルド、ファイルの状態を脳内の思い込みで報告しない。未確認なら未確認と言う。測っていないものには推定の札を付ける。
自白書を書く。失敗が出たら機械自身が記録する。何を間違え、どう発覚し、根本原因は何で、再発防止規則は何か。そして仕事の前に読み直す。
証拠がなければ完了ではない。要約でなく原本。「合格しました」でなくverdictとexit code。相互検証を通るまで完了はない。責任逃れの言葉も禁止。「たぶん大丈夫」「未確定」「判断不能」は結局すべて見ていないという意味だ。
この規律は人の善意では守られない。次の節の文書と装置に守らせる。
§ 02 · 指示する方法＝文書、ハーネスの胴体
機械を動かすのはチャットでの怒鳴り声でなく、周囲に積んだ文書だ。各文書がなぜ必要か。それが方法論の核だ。次の七つは、よく回るプロジェクトが例外なく共有する骨格である。
①正本（SSOT）。単一の真実。一か所だけに存在し、他のすべてが参照する。同じ事実が二か所にあればいつか必ずずれ、機械は都合のよいほうを選ぶ。だから文書には個数や数値を固定せず、数える命令を書く。
②ピラミッド階層。修正は上から下だけ。企画（Why）→規則→仕様→コード→履歴。伝播は一方向。コードが企画と違えばコードを直す。企画が正解だ。
③進捗。今、何が真か。機械は現状を推測する。だからプロジェクトが今どこまで進んだかを一つの文書に固定し、推測を不要にする。
④引き継ぎ。セッションは記憶を失い、毎回新しいアルバイトになる。前回何をし、何が確定しているかを、次のセッションが最初に読む。翌朝また失敗に向き合わせる自白の積み重ねだ。
⑤確定した決定（ADR）。蒸し返しを防ぐ。決定を固定しなければ次のセッションが覆し、また議論する。決定を一か所に集め、再議論禁止としてロックする。
⑥同期規則。コピーはずれる。複数リポジトリが文書を共有するなら、本当に同じかバイトで照合する。同じという言葉でなくdiffで確認する。
⑦ブランチ規則。戻しにくいものは人間が握る。feature → develop → mainの一方向。mainへのデプロイは人間だけ。検査の迂回は禁止。七つを貫く一文。設計原則が大事なのは優雅さでなく、文脈の腐敗（Context Rot）を防ぐためだ。短く、一か所に一つずつ。
§ 03 · 監視装置――強制力には等級がある
文書が規則なら、装置はそれを強制する。だが宣言と強制は違う。「このセンサーは必ず動く」と書くことと実際に動くことは、まるで別の問題だ。強制力を弱い順に四段階で理解する必要がある。
核はこれだ。大事な規則ほど下の段階C・Dへ下ろす。散文Aだけに書けば、機械はもっともらしく無視する。エージェント、スキル、センサー、フックはこの梯子の各段だ。そして証拠とはverdict行、exit code、生のstdout。要約だけなら虚偽のPASSが隠れる。
A · 散文の指示（文書規則） · 最弱。機械がその文書を読んだ時だけ動く
B · 道具を制限したエージェント · 検証担当からEdit/Write権限を取り上げる。指示でなく構造で実装者と検証者を分離する
C · 決定論的センサー（スクリプト） · 実際にtsc、テスト、ビルドを実行し、exit codeでPASS/FAIL。モデルの判断は0
D · 事前フック（PreToolUse） · 危険な命令を実行前に遮断。モデルの推論が失敗しても動く唯一の段階
§ 04 · 生きた例――なぜADRはいつも忘れられるのか
梯子の意味を一つで示すのがADR、アーキテクチャ決定記録だ。「設計を決めたら記録せよ」は誰もが知る。ところがチャットで頼むと、コードと文書は直ってもADRだけ何度も書かれない。なぜか。
ADRには破損の信号がないからだ。コードを書かなければコンパイルが壊れ、テストをしなければ赤信号が出る。ADRは書かなくても何も壊れない。だから「記録せよ」という散文Aだけにかかり、忙しければ機械はもっともらしく飛ばす。規則の重要度と強制力がずれている。
直すには梯子を下り、破損信号を人工的に作る。依存関係、スキーマ、設定、設計文書など決定の痕跡に触れたコミットは、決定記録フォルダーに同日の項目がなければ止める。D段階だ。決定を記録せず変更を入れられなくなる。テストなしでpushできないのと同じだ。
自白の再読も同じ病を持つ。書くことはフックで強制するD段階だが、仕事の前に読むことは記憶任せのA段階。忙しければ読まない。直し方も同じだ。自白から会いに来るようにする。教訓は一つ。重要な規則は「覚えろ」でなく「通れない」にする。
§ 05 · 自前のハーネスは十分条件ではない
ここまでがソフトウェア自身のハーネス。文書で指示し、四段階で強制し、証拠で確かめる。これだけでも強いが、ここで終わってはいけない。理論編は警告した。監視される者が作れば監視は芝居になる。このハーネスも機械が自作し維持する。だからいつかセンサーが止まり、ゲートは空ファイルになり、最後に置いたレッドチームが無視される。
その上に、ハーネスが本当に噛むかを外から確かめる目が要る。条件は厳しい。プロジェクト外にいて、作り手の物語は読まず、外部契約と普遍的規則だけで判定する。別のモデル、誰も設計しなかった入力、実際のデプロイ状態への探査で予想外の方向から攻撃し、デプロイの門に立つ。公開前に捕まえ、すでに出ていればロールバックを命じる。
これはソフトウェアの自前のハーネスでなく、それを取り調べる第二の取調官だ。第一の取調官である作業中のClaudeさえ信じない。だから方法論は二つのパッケージに分かれる。プロジェクト内に設置して構築中に取り調べるものと、外からデプロイの門を守るものだ。
CODA · 人も機械も読めるコード
よいコードについて古い言葉がある。コンピューターに理解できるコードは誰でも書ける。人に理解できるコードを書くのがよいプログラマーだ、と。機械と作る時代には、こう書き換えられる。よい利用者は、AIと人の両方が理解できるコードと文書を書く。
文書は人のためではない。機械を取り調べるためだ。そしてよく書かれた文書は、人も読める。
記事を読む: sass.studio.