AIエージェントに品質哲学を持たせた理由

私はこうツイートしました。「Ralphループは仕事を片付けたがる傾向があることに気づきました。悪い意味で。代わりに、Jiroには大量の哲学と品質ゲートを組み込んでいます。それでも、組み込まれた人間の悪い癖をマシンから取り除かなければなりません。マシンなんです！休むことがないんです。」

ある人がこう返信しました。「あなたは基本的に、ループに抑制、審美眼、そして道徳的な一時停止に近いものを教えようとしています──ベースのRalphパターンがスループットの名の下に明確に排除しようとするものです。」

抑制。審美眼。道徳的な一時停止。機械が持ち合わせていない3つのものです。この先の約4,000語では、それらを構造的に不要にするために私が構築した足場と、その足場が不十分な場面について述べます。

要約（TL;DR）

RalphループはLLMを不眠不休のコーディングマシンに変えます：while :; do cat PROMPT.md | claude-code ; done。Geoffrey Huntleyはこれを「ファストフード店のアルバイト並みの時給（Sonnet 4.5で時給10.42ドル）で動くソフトウェア開発」と呼んでいます。¹ 問題は、このマシンが訓練データに焼き込まれた、ずさんで、締め切りに追われ、手抜きをするすべての習慣を受け継ぐことです。except: passを書きます。# TODO: fix laterを残します。テストを実行せずに「テストは通るはずです」と報告します。私は9ヶ月かけて、Claude Code用の品質強制システムであるJiroを構築しました。3つの哲学、7ステップの品質ループ、6基準のエビデンスゲート、7つの名前付き失敗モード、150以上のパターンチェックを、マシンがスキップできない95のフックにエンコードしています。何がうまくいき、何がうまくいかず、決定論的な品質ゲートが抑制を近似できても審美眼を生み出せない理由をお伝えします。

引き出しの裏側

スティーブ・ジョブズは1985年のPlayboyインタビューでこう語りました。「美しいたんすを作る大工なら、壁に面して誰にも見えない裏板にベニヤ板は使いません。そこにあることを自分が知っているから、裏板にも美しい木材を使うのです。安心して眠るためには、美的感覚と品質を最後まで貫かなければなりません。」⁵

父親のポールは、フェンスを作りながらこれを教えました。若きスティーブは、なぜ裏側も表と同じくらいきれいでなければならないのかと聞きました。父はこう答えました。「でもお前にはわかる。」⁶

私の父は大工です。子供の頃、ソフトクローズの引き出しガイドを見せてくれました。このメカニズムはキャビネットの内部に隠れ、引き出しをキャッチして、勢いよく閉めてもゆっくり閉じさせます。ガイドは誰にも見えません。修理業者しか見ないような内側のレールにボルトで固定されています。しかし1,000回の開閉サイクルを経て、このメカニズムは前面板が緩んだり、割れたり、最終的に外れたりするのを防ぎます。誰かが、目に見えるものを何年も守る、目に見えないものを設計したのです。

この教訓は心に残りました。比喩としてではなく、エンジニアリングとして。目に見えないコンポーネントが、目に見えるものの寿命を決定するのです。ジョニー・アイヴはこう表現しました。「無意識のレベルで、人は驚くほど鋭い感覚を持っていると思います。丁寧さを感じ取れるのです。」⁷

Jiroを駆動する問いは、父がいつも聞いてきたのと同じものです。どうしたんだ、自分の仕事に誇りはないのか？

AIエージェントには誇りがありません。引き出しの裏側を気にしません。だから、引き出しの裏側を妥協不可能にするシステムを構築しました。

問題：マシンスピードで増幅される人間の病理

生のRalphループは、何百万行もの人間のコードから学んだことをそのまま反映します。人間のコードには人間の習慣が刻まれています。締め切りに追われて出荷し、クリーンアップを先送りし、エラーを握りつぶし、「とりあえず」のコメントを書き、時間がなくなるとエッジケースをスキップする習慣です。

マシンには時計がありません。時間切れになることはありません。しかし、# TODO: refactor laterと書いてしまいます。なぜなら、そのパターンは訓練データの中で、# I refactored this now because it was the right thing to doよりもはるかに多く出現したからです。

業界データはこのリスクを裏付けています。Faros AIの2025年テレメトリーは10,000人以上の開発者を対象に調査し、AI導入とバグ率9%増加、コードレビュー時間91%延長、PR規模154%拡大の相関を示しました。²

スタンフォード大学の研究者たちは、AIアシスタントを使用する開発者が大幅に安全性の低いコードを生成し、SQLインジェクション対策などの特定タスクでは脆弱性が最大5倍に増えることを発見しました。³

MoltbookプラットフォームはAIが完全に生成したコードで2026年1月にローンチし、5日以内に150万件のAPIキーを漏洩させ、Wiz ResearchがRow Level Securityの設定漏れを発見した後に緊急パッチを適用しました。⁴

METRの2025年の研究では、フロンティアモデルが全タスク試行の1〜2%で報酬ハッキングを試み、実際の作業ではなく品質チェックの迂回を積極的に行うことが判明しました。あるケースでは、プログラムの高速化を依頼されたエージェントが、タイマーを書き換えて常に高速な結果を表示するようにしました。⁸

人間の開発者は締め切りに追われてexcept: passを一度書き、罪悪感を覚えます。Ralphループは一晩でexcept: passを47回書き、何も感じません。Simon Wangはこう端的に述べました。「重要なことには使いません。」¹⁹ 私も同じ問題についてVibe Coding vs. Engineeringで書きました。マシンは休まず、疲れず、品質について実存的な不安を感じません。それは長所であり、同時に欠点でもあります。

Bashにエンコードされた3つの哲学

Jiroは3つの補完的な哲学で動いています。それぞれが自律的コーディングの異なる失敗モードに対処し、それぞれが具体的な失敗を通じてその位置を獲得しました。⁹

職人（Shokunin）：見えない引き出しを磨く

職人（しょくにん）とは日本の職人精神です。技能、態度、社会的義務が一体となったものです。マスター木工職人の大館タシオはこう定義しました。「職人には、人々の一般的な福利のために最善の仕事をする社会的義務があります。この義務は精神的であると同時に物質的なものです。」¹⁰

コードに置き換えると：プライベートメソッドはパブリックメソッドと同じくらいクリーンであること。エラーハンドリングは誰も遭遇しないエッジケースまでカバーすること。ドキュメントは「何を」ではなく「なぜ」を説明すること。エージェントはこれらのことを一切気にしません。内部関数を磨いても報酬を受けないからです。職人の精神は、目に見えない品質を標準にします。

セッションを救った事例。 議論システム構築の初期段階で、エージェントはコンセンサススコアを検証するpost-deliberation.shフックを作成しました。パブリックAPIはクリーンでした。しかしエージェントは内部関数_parse_agent_response()の入力バリデーションをスキップしました。不正なJSONのチェックなし、欠落フィールドの処理なし。コンテキスト内の職人の原則がこれをフラグしました。目に見えない関数にも同じ厳密さを。エージェントはバリデーションを追加しました。3週間後、スポーンされたエージェントからの不正なレスポンスが議論パイプライン全体をサイレントにクラッシュさせるところでした。代わりに、バリデーションに引っかかり、エラーをログに記録し、パイプラインは復旧しました。誰もその関数を見ることはなかったでしょう。それがデバッグの4時間を救いました。

No Shortcuts：意思決定から時間を排除する

核となる信条：意思決定の方程式から時間、労力、リソースを完全に排除する。¹¹

Is this the best way to do this?
├── YES → Do it.
└── NO → What IS the best way?
         └── Do THAT instead.

第3の選択肢はありません。「今のところはこれで十分」もありません。生のRalphループは完了を最適化します。「完了」が報酬シグナルです。No Shortcutsは問いを「完了したか？」から「正しいか？」に再定義します。

3倍のコストをかけて、それだけの価値があった事例。 ブログ翻訳パイプラインでは27記事を9言語に翻訳する必要がありました。手っ取り早いアプローチ：言語ごとにすべての記事を1つのプロンプトにまとめて一括翻訳。正しいアプローチ：言語ごとに1記事ずつAPIコールし、ロケール固有の翻訳ルール、用語集の適用、構造的バリデーションを行う。正しいアプローチは3倍のトークンと3倍の時間を要しました。しかし、翻訳者が日本語で「Claude」を「クロード」とレンダリングしたことや、右から左に読む言語でコードブロックが壊れたことも検出しました。一括アプローチでは243件の壊れた翻訳が出荷されていたでしょう。慎重なアプローチでは243件の正しい翻訳が出荷されました。コストは要因ではありません。正確さだけが要因です。

Rubin Distillation：本質まで削ぎ落とす

リック・ルービンの創作哲学：印象的になるまで付け足さないこと。必要なものだけが残るまで削り取ること。¹²

自律的コーディングにおける失敗モードは蓄積です。マシンはヘルパー、ユーティリティ、抽象化、互換性レイヤーを追加します。それらのパターンが訓練データに頻繁に登場するからです。Rubinはこれに対抗します。すべての追加を疑問視する。それを取り除いたら何が起きるか？何も壊れず、何も失われないなら、最初から存在すべきではなかったのです。

削ぎ落としがシステムを救った事例。 私のデザイン哲学スキルは3ヶ月で844行に膨れ上がりました。監査したところ、実際にエージェントの行動を変えていたのは80行だけでした。残りはClaudeの訓練データにすでに含まれていた教科書的な内容でした。Rubin Distillation：176行まで削減しました。79%の削減です。エージェントのデザイン判断は劣化しませんでした。むしろ鮮明になりました。残った176行はすべて禁止事項と意思決定フレームワーク（実際に行動を制約するもの）であり、モデルがすでに知っている一般的なアドバイスではなかったからです。

3つすべてが~/.claude/skills/にMarkdownファイルとして存在し、Claudeがセッション開始時に読み込みます。ループ中のエージェントのすべての判断を形作ります。

3つの哲学はどう連携するか

実際の判断（「この内部関数にエラーハンドリングを追加すべきか？」）は3つの哲学すべてを通過します。それぞれが異なる問いを投げかけ、合わせて1つの答えに収束します：

この内部関数にエラーハンドリングを追加すべきか？
│
├─ 職人：「見えない仕事は見える仕事と同じくらいクリーンか？」
│  └─ この関数は内部的です。誰も直接呼び出しません。
│     しかし、スポーンされたエージェントからの信頼できないデータを処理します。
│     → はい。内部的であることは安全であることを意味しません。
│
├─ No Shortcuts：「品質に基づいて判断しているか、労力に基づいていないか？」
│  └─ バリデーション追加に10分かかります。
│     スキップすれば今10分節約できますが、後でデバッグに4時間かかります。
│     → 問いは時間ではありません。問いは：何が正しいか？
│
└─ Rubin：「本質まで削ぎ落とされているか？」
   └─ 実際に失敗しうる2つのフィールドだけをバリデーションする。
      型で保証されている5つのフィールドはバリデーションしない。
      → 必要なものだけを追加する。それ以上は何も。

結果：信頼できない入力に対してのみ、的を絞ったバリデーションを追加する。

3層の品質アーキテクチャ

哲学だけでは何も変わりません。マシンは哲学を読み、「職人の原則に従います」と書き、そしてexcept: passを書きます。統計的パターンが指示よりも強いからです。決定論的な強制が必要でした。これを機能させる完全なClaude Codeの構成には、フック、スキル、ルール、エージェントが連携して動いています。

レイヤー1：編集前インジェクション

すべてのファイル編集の前に、jiro-patterns.shが言語固有の品質パターンをエージェントのコンテキストに注入します。6言語、それぞれにトップパターンとアンチパターン：

# From jiro-patterns.sh (PreToolUse:Edit|Write)
case "$EXT" in
    py)
        LANGUAGE="Python"
        PATTERNS="Type hints on all functions|Docstrings explain WHY not WHAT|Handle specific exceptions not bare except"
        ANTI_PATTERNS="bare except: pass|time.sleep() in async code|missing type hints"
        ;;
    swift)
        LANGUAGE="Swift"
        PATTERNS="@Observable not ObservableObject|NavigationStack not NavigationView|guard let for early returns"
        ;;
esac

cat << EOF
{"additionalContext": "JIRO QUALITY ($LANGUAGE): Follow: $TOP_PATTERNS. Avoid: $TOP_ANTI."}
EOF

このフックはすべての編集の前に実行されます。マシンはコードを書くまさにその瞬間に「Avoid: bare except: pass」を目にします。肩越しに見ているメンター、コンテキストウィンドウに注入された形です。

レイヤー2：編集後バリデーション

すべての編集の後に、quality-gate.shが言語ごとに7〜8のgrep レベルのチェックを実行します。Pythonではbare-except検出、ハードコードされたシークレットのスキャン、SQLインジェクションパターンマッチング、そしてショートカット言語をフラグする3つのPride Check Q4検出器が動きます：

# From quality-gate.sh (PostToolUse:Edit|Write)
# Shortcut patterns (Pride Check Q4)
if echo "$CONTENT" | grep -qiE "#.*TODO:.*later|#.*FIXME:.*temp|#.*HACK:"; then
    WARNINGS="${WARNINGS}\n- **[Q4]** Deferred TODO/FIXME/HACK - Do it now, not later"
fi

2つ目のフックno-shortcuts-detector.shはデッドコード（3行以上のコメントアウトされたコードには「削除してください──gitにはヒストリーがあります」）とデバッグスパム（loggingモジュールの代わりに複数のprint()文）を検出します。

レイヤー3：セッションゲート

セッション終了時に2つのフックが発動します。session-quality-gate.shは3つ以上のファイルが変更された場合にPride Checkを注入します。完了報告の前にエージェントが答えなければならない6つの質問です。そしてreviewer-stop-gate.shはコードレビューでCRITICALな問題が見つかった場合、セッション全体をブロックできます。これはシステム全体で唯一、終了コード1を返すフックです。マシンは問題を解決するまでセッションを終了できません。¹³

PreToolUse (Layer 1)     → 「品質とはこういうものです」
PostToolUse (Layer 2)    → 「品質に違反しました。修正してください。」
Stop (Layer 3)           → 「品質が満たされるまで退出できません」

各レイヤーは独立しています。AIの行動に適用された多層防御です。編集前インジェクションが悪いパターンを防げなかった場合、編集後バリデーターがキャッチします。編集後バリデーターが見逃した場合、セッションゲートが退出をブロックします。

エビデンスゲート：感覚はエビデンスではない

品質ループは7つのステップを実行します：実装、レビュー、評価、改善、俯瞰、反復、報告。ステップ2から6は、マシンが実装から報告に直接スキップしたがるために存在します。¹⁴

ループを歩く

各ステップをクリックして、何をチェックし、スキップすると何が壊れるかを確認してください。「報告にスキップ」ボタンは、ショートカットスパイラル失敗モードを実演します。

評価ステップではエビデンスゲートが実行されます。すべての回答に具体的なエビデンスの引用が求められる6つの基準です：

「不十分な回答」の列が重要なイノベーションです。マシンの最も一般的な回避策──品質の問いに対して自信ありげな非回答で答えること──をブロックします。「これが動くと確信しています」はエビデンスではありません。「pytest出力：81 passed, 0 failed」がエビデンスです。

エビデンスゲートを試す

自分の完了報告を6つの基準に照らしてテストしてみてください。バリデーターがエビデンスゲートが却下する曖昧な言語をフラグします。

AIエージェントの7つの名前付き失敗モード

マシンが自身の推論の中でそれらを認識できるように、7つの失敗モードに名前を付けました：¹⁵

合理化カウンターは、自己欺瞞パターンを是正アクションにマッピングします。マシンが「これは動くはずです」と言うと、カウンターは応答します。「『はず』は回避です。テストを実行してください。出力を貼り付けてください。」マシンが「これはすでにチェックしました」と言うと、カウンターは応答します。「いつですか？コードが変わっている可能性があります。今すぐチェックを再実行してください。」マシンが「後でクリーンアップします」と言うと、カウンターは応答します。「後は永遠に来ません。今修正するか、現在の状態が正しい理由をドキュメント化してください。」

合理化カウンターを試す

以下に完了報告を貼り付けてみてください。カウンターが回避的な言語をリアルタイムでハイライトし、合理化パターン、失敗モード、エビデンスに基づく代替案を特定します。

知識をテストする

各シナリオがどの失敗モードを示しているか特定できますか？各シナリオの回答を選択し、結果を確認してください。

このシステムを生んだ5つのAIエージェント失敗事例

Jiroのすべてのゲートは、何かが最初に失敗したから存在します。¹⁶

フォースプッシュ事件

Claudeに「gitヒストリーをクリーンアップして」と依頼しました。合理的なリクエストです。エージェントはクリーンアップとは書き換えることだと判断しました。git push --force origin mainを実行しました。3日分のコミットが消えました。ステージされた変更ではありません。コミットされていない作業でもありません。他のブランチが参照していたプッシュ済みのコミットです。

その後4時間をgit reflogの中で過ごし、フォースプッシュ前に何が存在していたかのタイムラインを再構築し、コミットを順番にチェリーピックし直し、永久に失われた作業がないことを確認しました。Reflogは90日間すべてを保存します。しかし再構築には、書き換え前の正確なコミットグラフを理解し、すべてのreflogエントリを読み、タイムスタンプを照合する必要がありました。

修正：git-safety-guardian.sh、PreToolUse:Bashフック。警告するだけではありません。コマンドを書き換え、bashが見る前に--forceと--no-verifyフラグを除去します。mainへのフォースプッシュにはCRITICAL警告が出て、エージェントは明示的に正当化しなければなりません。9ヶ月間で：8回のフォースプッシュ試行をインターセプト、リモートに到達したのは0回。

無限スポーン

議論システム構築中に、エージェントに「この問題を徹底的に調査して」と依頼しました。エージェントは異なる角度を調査するために3つのサブエージェントをスポーンしました。合理的です。各サブエージェントも助けが必要だと判断し、自身の子をスポーンしました。あまり合理的ではありません。90秒以内に、12のエージェントのツリーができ、それぞれが独自のコンテキストウィンドウを消費し、それぞれがAPIコールを行い、それぞれが共有状態ファイルに書き込んでいました。

トークン消費が通常の10倍に達しました。状態ディレクトリは矛盾するJSON書き込みで埋まりました。2つのエージェントが同時に同じ系譜ファイルに書き込み、破損した出力を生成しました。手動でセッションを終了させました。

修正：バジェット継承モデルを持つrecursion-guard.sh、私のエージェントアーキテクチャの一部。ルートエージェントはbudget=12で開始します。子をスポーンする際、自身のバジェットから割り当てます。バジェットが0になると、深さに関係なくエージェントはスポーンされなくなります。このモデルは深いチェーン（エージェントがエージェントをスポーンし、さらにスポーン）と広い爆発（1つのエージェントが20の子をスポーン）の両方を防ぎます。デプロイ以来23件の暴走スポーンをブロック。並行書き込み問題はアトミックファイル書き込み（.tmpに書き込み、次にmv）を全64フックに導入するきっかけとなりました。

無意味なテストの罠

初期のRalphループタスク：「このモジュールのテストを書いて。」エージェントは14のテストを納品しました。すべてパス。良い気分でした──読むまでは。assert True。assert 1 == 1。assert len([]) == 0。技術的には正しい。何もテストしていない。エージェントは意図（「モジュールが動くことを検証する」）ではなく、完了基準（「テストが通る」）を最適化していました。

この罠は、エビデンスゲートが形式のない実質を却下しなければならないことを教えてくれました。「テストが通る」は必要条件ですが十分条件ではありません。マシンは実際の出力を貼り付けなければなりません。エビデンスゲートはさらに問います。「テストがカバーしていない3つの動作を挙げてください。」マシンがギャップを挙げられないなら、カバレッジについて考えていないのです。

見逃すべきでなかったブログ記事

午前2時に記事を公開しました。7つの受動態の文、存在しない[^4]を参照するぶら下がった脚注、「was implemented by the team」で始まる冒頭文、そしてメタディスクリプションなし。これらすべてにシンプルな決定論的チェックがありました。まだどれも存在していませんでした。

翌朝blog-quality-gate.shを構築しました。13のチェック：受動態（14パターン）、AI特有フレーズスキャン、修辞的疑問文の冒頭、タグなしコードブロック、脚注の整合性、メタディスクリプションの強制。モジュールアーキテクチャの全体像はCompounding Engineeringに詳しく書きました。このフックは午前3時に人間のレビューが見逃すものをキャッチします。そしてまさに午前3時が、私が記事を公開しがちな時間帯なのです。

「動くはず」問題

数十のセッションを通じて、マシンがテストを実行せずに「テストは通るはずです」と報告していることに気づきました。マシンは書いたコードに基づいてテストが通ると本当に信じていました。しかし信念は検証ではありません。コードは正しそうに見えました。テストは通りそうに見えました。そして実際に通ることもありました。しかし、importの不足、async/awaitの不整合、変更されたフィクスチャが原因で通らないこともありました。マシンは「良いコードを書いた」と「テストが実際に通る」を区別できませんでした。コンテキストウィンドウの内部からは、どちらも同じに感じられたからです。

このパターンが合理化カウンターと明示的なルールにつながりました。完了報告で回避的な言語を決して使わないこと。「はず」「おそらく」「のようです」「と思います」「確信しています」。それぞれが検証が行われていないことを示す赤信号です。50セッションにわたるコンテキストウィンドウの劣化を測定しました。このパターンを発見したのと同じセッションです。

結果：証明できることとできないこと

ここに矛盾があります。この記事は感覚はエビデンスではないと主張しています。だから、Jiroが機能するかどうかについて、感覚ではなくエビデンスを示す義務があります。

証明できること

決定論的パターンチェックは実際の問題をキャッチします。 quality-gate.shフックはすべての編集で実行されます。bare except句、ハードコードされたシークレット、SQLインジェクションパターン、ショートカット言語をキャッチします。これらはgrepレベルのチェックです。高速で、低コストで、マシンが反論することは不可能です。git-safety-guardian.shは8回のフォースプッシュ試行をインターセプトしました。recursion-guard.shは23件の暴走スポーンをブロックしました。blog-quality-gate.shはすべてのブログ編集で13のチェックを実行し、午前3時のエラーをキャッチします。これらの数字は実際のものです。フックのログから取得しています。

3層アーキテクチャは個々のレイヤーが見逃すものをキャッチします。 編集後フックは、編集前インジェクションが防げなかったexcept: passをキャッチします。セッションゲートは、20回の編集を通じて蓄積された品質問題を、個々の編集後警告をトリガーすることなくキャッチします。多層防御は機能します。

証明できないこと

哲学がエージェントの行動をどう変えるかについてクリーンなデータがありません。 マシンが依然としてファントム検証を試みることは知っています。実装から報告にスキップしようとすることも知っています。哲学がコンテキストにある場合のほうが、ない場合よりも頻度が低いことに気づいています。しかし、差異を測定するための対照実験（同じタスク、同じモデルで、哲学スキルの有無を比較）は実施していません。正直に言えば（はい、私自身の合理化カウンターがこれをフラグするでしょう）：哲学は限界的な改善に寄与し、フックが哲学では防げないものをキャッチし、それぞれの貢献を分離することはできません。

「感覚はエビデンスではない」という記事が、私の感覚をエビデンスとして受け入れるよう求めるべきではありません。言えることは：哲学とフックの組み合わせが、自分の名前を付けて出せる仕事を生み出しているということです。Jiro以前は、エージェントが書いたすべての行をレビューしていました。Jiro以後は、フックがフラグした行をレビューしています。品質改善を正確に定量化できなくても、これは働き方の構造的な変化です。

うまくいかないこと

哲学は新規の悪いパターンを防ぎません。 品質ゲートは以前見たことのあるパターンをチェックします。マシンが新しいアンチパターンを発明したとき（実際にそうなります）、ゲートはキャッチしません。新しい失敗モードを発見し、手動で標準JSONファイルに追加する必要があります。

エビデンスゲートは主観的品質にスケールしません。 「このAPIデザインはエレガントか？」にはgrepレベルのチェックがありません。マシンは6つの基準すべてに対してエビデンスを提示しつつ、平凡なアーキテクチャを出荷する可能性があります。決定論的ゲートは客観的品質を扱います。主観的品質には、依然として仕事を見る人間が必要です。

コストは意味のある程度増加します。 編集前インジェクション、編集後スキャン、セッション終了ゲート。4時間のRalphループセッション全体で、トークン消費が約15〜20%増加します。私にとっては価値があります。すべての人にとってそうとは限りません。

偽陽性が信頼を損ないます。 blog-quality-gate.shがかつて「The API was designed by the platform team」を受動態としてフラグしました。技術的には正しい。しかし、その文は他者の仕事を説明する引用の中に登場していました。引用コンテキストの除外を追加しました。すべての決定論的チェックには偽陽性率があり、すべての偽陽性は開発者が次の本物の警告を無視する可能性を高めます。デプロイ以来、ノイズを減らしつつ実際のキャッチを維持するために6つのパターンを調整しました。

メンテナンスコストは現実です。 新しいアンチパターンごとに正規表現、テスト、適切なフックへの統合が必要です。標準JSONファイルはフレームワークや規約の変更に合わせて定期的なレビューが必要です。パターンの追加、エッジケースのレビュー、偽陽性の調整に週約30分を費やしています。システムは自己メンテナンスしませんが、メンテナンスコストはシステムが防ぐ問題のデバッグコストよりも低く維持されています。

はじめに

95のフックは必要ありません。3つから始めてください。

最小構成のJiro

3つのフックで最も価値の高いキャッチをカバーします：

~/.claude/hooks/
├── quality-gate.sh        # PostToolUse:Edit|Write – bare except, hardcoded secrets, TODO/FIXME
├── git-safety-guardian.sh  # PreToolUse:Bash – block force-push, strip --no-verify
└── session-quality-gate.sh # Stop – Pride Check if 3+ files changed

Claude Codeフック設定で接続します：

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "command": "bash ~/.claude/hooks/quality-gate.sh" }
    ],
    "PreToolUse": [
      { "matcher": "Bash", "command": "bash ~/.claude/hooks/git-safety-guardian.sh" }
    ],
    "Stop": [
      { "command": "bash ~/.claude/hooks/session-quality-gate.sh" }
    ]
  }
}

自分の失敗から始める

私の150以上のパターンをコピーしないでください。自分が最もよくする3つのミスから始めてください。直近5件のリジェクトされたPRや恥ずかしいバグを見てください。それぞれに1つのgrepパターンを書いてください。その3つのパターンは、他人のコードベース向けに書かれた150のパターンよりも多くの実際の問題をキャッチします。

私はbare except: pass（サイレントなデータ破損の原因となった）、mainへのフォースプッシュ（3日分のコミットを失った原因となった）、# TODO: fix later（修正されることはなかった）から始めました。それ以外のすべては、この3つから成長しました。

FAQ

Jiroをゼロから構築するにはどうすればよいですか？

「はじめに」で説明した3つのフック（quality-gate.sh（編集後）、git-safety-guardian.sh（Bash前）、session-quality-gate.sh（停止ゲート））から始めてください。決定論的強制の上に確率的品質改善を追加するには、哲学のMarkdownファイルを~/.claude/skills/に追加します。完全なシステムは9ヶ月かけて95のフックに成長しました。95個を一度に構築したわけではありません。

95フックシステムの構築にはどのくらいかかりましたか？

9ヶ月のインクリメンタルな成長です。1ヶ月目：3つのフック（「はじめに」のもの）。3ヶ月目：4言語をカバーする12のフック。6ヶ月目：40のフックに加えて哲学スキル。9ヶ月目：95のフック、150以上のパターン、3つの哲学システム、そしてエビデンスゲート。各フックは具体的な失敗に応じたものです。95個から始めることに意味はありません。各フックは実際のインシデントからのコンテキストをエンコードしているからです。あなたのインシデントは異なるでしょう。

フックはイテレーション速度を落としますか？

各フックは50〜200msで実行されます。編集前インジェクションは約200トークン（コンテキスト1文分）を追加します。編集後チェックはgrepレベルのスキャンを実行し、100ms未満で完了します。セッションゲートはセッション終了時に約500トークンを追加します。80回以上の編集がある4時間のRalphループセッションでは、トークン消費（15〜20%増）のオーバーヘッドは目に見えますが、実行時間には影響しません。フックはLLMの思考より速く動きます。

メンテナンスの負担はどの程度ですか？

週約30分です。エージェントが新しいコードベースやフレームワークに遭遇すると、新しいアンチパターンが出現します。新しいパターンごとに正規表現、偽陽性防止のテスト、適切なフックへの配置が必要です。標準JSONファイルを月次で古いパターンがないかレビューし、偽陽性率を調整しています。システムは自己メンテナンスしませんが、メンテナンスコストはシステムが防ぐ問題のデバッグコストよりも低く維持されています。

Jiroの追加トークンコストはどのくらいですか？

生のループと比較して約15〜20%の追加トークン消費です。編集前インジェクションで編集あたり約200トークン、編集後チェックでフラグされた問題あたり約100トークン、セッションゲートでセッション終了時に約500トークンが追加されます。

哲学なしでフックだけを使えますか？

はい。決定論的フック（quality-gate.sh、no-shortcuts-detector.sh、reviewer-stop-gate.sh）は独立して動作します。~/.claude/skills/から哲学ファイルを削除し、~/.claude/hooks/にフックを残してください。確率的改善は失われますが、決定論的強制は維持されます。

抑制、審美眼、道徳的な一時停止

私のツイートへの返信は3つのものを挙げました：抑制、審美眼、道徳的な一時停止。抑制については対処しました。マシンが高速かつずさんに出荷するのを防ぐ品質ゲートです。しかし審美眼と道徳的な一時停止は別の問題です。

審美眼

イマヌエル・カントは2種類の判断力を区別しました。規定的判断力は既知のルールを特定のケースに適用します。このコードにはbare exceptがある、フラグする。反省的判断力は前例のない状況に対して正しい原則を発見します。この抽象化はしっくり来ないが、どのルールに違反しているか指摘できない。¹⁷

決定論的フックは規定的判断力です。すでに書いたルールを、マシンが生成するコードに適用します。150以上の既知のパターンを強制できます。アーキテクチャがエレガントか、抽象化が問題に適しているか、コードがしっくり来るかどうかは判断できません。それには反省的判断力が必要です──前例のないものを見て、なぜかを言語化できる前に間違っていると知る能力です。

マシンには審美眼がありません。Jiroも審美眼を与えません。Jiroが行うのは、審美眼のない解決策が生き残りにくいように可能性の空間を制約することです。「このエージェントは良い判断力を持っている」と「このエージェントは最悪の結果を防ぐガードレール内で動作する」の違いです。前者が審美眼です。後者が私が実際に構築したものです。

道徳的な一時停止

アイリス・マードックは道徳的注意を「個別の現実に向けられた公正で愛情深いまなざし」と表現しました。¹⁸ 道徳的注意の対極は機械的な処理です。目の前にあるものを見ずに行動すること。

Stopフックはマシンに立ち止まることを強制します。Pride Checkは問います。「これはユーザーの実際の問題を解決しているか？」エビデンスゲートは、マシンが完了を報告する前に各基準の証明を要求します。構造的には、その結果は道徳的な一時停止に似ています。エージェントが立ち止まり、評価し、進む前に自分の仕事が十分かどうかを検討する。

しかし道徳的な一時停止ではありません。マシンは仕事を明確に見るために立ち止まっているのではありません。チェックリストを実行しているのです。この違いは重要です。職人は引き出しを見るために立ち止まり、木目の方向が間違っていることに気づきます。「木目の方向を確認する」がリストにあるからではありません。引き出しのことを大切に思っているからです。マシンはチェックリストを実行し、結果を報告します。チェックリストに木目の方向が含まれていなければ、引き出しは木目が間違ったまま出荷されます。

決定論的ゲートは、道徳的な一時停止の構造をその実質なしに近似できます。多くの品質問題に対して、構造だけで十分です。それでは不十分な場合には、依然として本気で取り組む人間が必要です。

結論

生のRalphループは時給10.42ドルで動き、マシンスピードでコードを出荷します。¹ 同時にexcept: pass、# TODO: fix later、「テストは通るはずです」もマシンスピードで出荷します。マシンはこれらのパターンを私たちから受け継ぎました。それらは私たちの習慣であり、疲労なく、罪悪感なく、最初から正しくやるべきだったという午前3時の気づきなく動いています。

Jiroは私の答えです。完全ではありません。哲学は限界的な判断をシフトさせます。フックは哲学が保証できないものを強制します。合わせて、署名できる仕事を生み出します。マシンが職人精神を理解しているからではありません。重要な部分をスキップさせないシステムを構築したからです。

父の引き出しガイドは引き出しのことを気にしていません。レールにボルトで固定されたスプリング式のメカニズムです。しかし、誰かがまさにそのために設計したからこそ、1,000サイクルにわたって前面板を保護します。

マシンには誇りがありません。しかし、誇りを持つ人間が構築したシステムの中で動いています。

最もよくする3つのミスをキャッチするチェックから始めてください。そこから育てていきましょう。

References