ハーネス教本 — 02 手で作る方法

憲法文書、エージェントファイル、スキルファイル、配線表、そして検問所。五つのテキストファイルで最小のハーネスを構築する実際の順番。九つの作業場に共通して検証された骨格だけを残した。

§ 00 · 最初のファイル — 六十行の憲法

リポジトリのルートにCLAUDE.mdというファイルを作る。この名前のファイルはセッション開始時に自動で読み込まれる。ハーネスの礎となる慣例だ。最初に書くことは三つだけ。このプロジェクトが何かを五行。絶対にしてはいけないことを数項目。たとえば「未確認のことを完了と報告するな」「本線のmainブランチへ直接プッシュするな」。そして検証コマンド。何でテストを回し、何でビルドを確認するかを書く。

長さは六十行前後から始め、その付近を保つ。理由は単純だ。規則書が長いほど、各規則に向けられる注意は薄くなる。公開された測定は冷ややかだ。十個なら大半を守るが、五十個なら半分を無視し、百個なら重要なものを判断できない。三百行を超えると機械は規則を選んで無視し始める。実測もこれを示す。ある作業場は憲法が五百行を超えて規則無視が増えたため、百五十行に削り、残りを別の知識フォルダへ移した。最大の作業場は七十三行を維持し、上限を超えるとコミット直前のセンサーが警告する装置まで付けていた。憲法には地図だけを残し、詳細はリンクの先へ置く。

最初から避けるべき罠が一つある。文書に個数を書くな。「センサー七個」「テスト二十四個」のような数字は、書いた瞬間から腐り始める。ファイルは増えても文書は直らないからだ。実測で得た処方は二つ。数字の代わりに数えるコマンドを書いて「個数はlsで実測せよ」とするか、コミット直前に実測値で文書を自動更新するスクリプトを付ける。原則は同じだ。文書に現実を主張させず、現実を指させる。

§ 01 · 二つ目のファイル — エージェント

.claude/agents/を作り、作業員一人につきMarkdownファイルを一つ置く。最上部の三本のダッシュ（---）で囲むfrontmatterに四行を書く。nameは作業員名、たとえばverifier。descriptionはいつ呼ぶか。例は「完了宣言を検証するとき。コードは変更せず判定のみ」。toolsは渡す道具、たとえばRead、Bash、Grep。修正道具は意図的に外す。modelは使うモデルで、05編で扱う。

本文の骨格は九つの作業場でほぼ同じだ。最上部に絶対制約ブロック。必須・推奨・任意の三段階ラベルを付けた禁止・義務の一覧を置く。続けて役割の説明と「作業前に必ず読む正本文書」の一覧。最下部でもう一度、提出直前の自己検問。「実測なしで完了と書いていないか」「出力原文を付けたか」。上下に同じ制約を打つ二重アンカーだ。長い文書で機械が最もよく守る位置は最初と最後だという、複数の作業場で確認された経験則から来ている。

最初の作業員は何にするか。実測の答えは明確だ。検証者から作れ。実装がうまい作業員より、実装が本当にできたかを代わりに測る作業員が先だ。修正道具を持たない検査専任の作業員が一人できた瞬間、「全部できました」は「検査官を通過しました」に変わる。その差がハーネスの始まりだ。

§ 02 · 三つ目のファイル — スキル

.claude/skills/の下にフォルダを一つ作り、その中にSKILL.mdを置く。frontmatterはnameとdescriptionの二行で始められる。descriptionには具体的な発動条件を書く。トリガーキーワード配列を加える作業場もある。「完了しました」「すべて通過」「問題ありません」など二十ほどの表現を並べ、その言葉が出ようとする瞬間にスキルを割り込ませる。

最初のスキルはほぼ決まっている。完了宣言ゲートだ。本文にこう書く。完了を宣言する前に①型検査②テスト③ビルドを実際に実行する。各コマンドの出力原文を報告に付ける。そして三つの禁止。実測のない完了主張は禁止。一部だけ検証して全体が合格したと言うのは禁止。前のセッションの結果を今の証拠に化けさせるのは禁止。この三行は複数の作業場で実際の事故後に固定された文で、効果も数値で測られる。先に挙げたベンチマーク逆転で最大の寄与要因だったのは、この「提出前の自己検問」という一つのパターンだった。

最後に報告テンプレートをスキル内に置く。判定、実行コマンド、出力原文、残る問題。この四項目でよい。報告形式が固定されれば、ごまかしにくくなる。空欄は埋まるか、空欄であることが見えるかのどちらかだからだ。

§ 03 · 四つ目と五つ目 — 配線表と検問所

四つ目は配線表の.claude/settings.jsonだ。「どの瞬間にどのスクリプトを回すか」をつなぐ。実測で最も多い最小配線は三本。セッション開始時には記憶の鮮度を調べる。ファイル修正直後には型検査を静かに回す。セッション終了時には、その日のコミットがあるのに記録がなければ警告する。スクリプト本体は.claude/scripts/に置く。03編の方法で機械に書かせればよい。

配線の規律を一つ。フックはできるだけ遮断しない。調べたフックスクリプトの大半は「何があっても通過（exit 0）」で終わる。フック自身の欠陥が作業全体を止めてはいけないからだ。ただし本当の価値は別にある。チャットで「するな」と頼むのは機械が無視できる最も弱い制約だが、フックは機械の意図に関係なく動く。だから最も信頼性が高い制約になる。普段のフックはささやき、噛み付く役目は五つ目のファイルが担う。

五つ目が本当の検問所だ。.githooks/にpre-pushというシェルスクリプトを作る。リモートリポジトリへプッシュする直前に自動実行されるGitの慣例だ。内容は型検査・テスト・ビルドの三段センサーを順に回し、一つでも失敗すれば終了コード1でプッシュ自体を拒否する。有効化はターミナルの一行、git config core.hooksPath .githooks。これだけは利用者が一度直接実行する。この瞬間から「テストが壊れたままデプロイされる」事故は構造上不可能になる。機械の怠慢の問題ではなく、扉が施錠されているからだ。

記事を読む: sass.studio.