なぜ私のAIエージェントには品質哲学があるのか

私はこうツイートしました。「Ralph loopは仕事を終わらせたがる傾向があると気づきました。悪い意味で、です。その代わりに、Jiroには哲学と品質ゲートをたくさん組み込んでいます。それでも、組み込まれた人間の嫌な習慣という機械を壊さなければなりません。これは機械ですから。休まないのです」

ある人がこう返信してくれました。「あなたは基本的に、ループに対して抑制、センス、そして道徳的一時停止に近いものを教えようとしているわけですね。これらはRalphの基本パターンが、スループットの名のもとに明示的に最適化の対象外としているものです」

AIコーディングエージェントは、品質を構造的に強制しない限り、人間のずさんな習慣をすべて機械の速度で受け継ぎます。 JiroはClaude Codeのための品質システムで、3つの哲学、7ステップの品質ループ、6基準のエビデンスゲート、7つの名前付き失敗モード、150以上のパターンチェックを、機械がスキップできない95個のフックにエンコードしたものです。決定論的なゲートは抑制と正確性を近似できますが、センスを生み出すことはできません。

抑制。センス。道徳的一時停止。機械が持たない3つのものです。これから4,000語にわたって、これらを構造的に不要にするために私が構築した足場と、その足場の限界について説明します。

TL;DR

Ralph loopは、LLMを疲れ知らずのコーディングマシンに変えます。while :; do cat PROMPT.md | claude-code ; doneという具合です。Geoffrey Huntleyはこれを「バーガーフリッパーの賃金でのソフトウェア開発」と呼んでいます（Sonnet 4.5を動かして時給10.42ドル）。¹ 問題は、機械がトレーニングデータに焼き付けられた、ずさんで、締め切りに追われ、手を抜く習慣をすべて受け継いでしまうことです。except: passを書きます。# TODO: fix laterを残します。実行せずに「tests should pass」と主張します。私は9ヶ月かけて、Claude Codeのための品質強制システムであるJiroを構築しました。これは3つの哲学、7ステップの品質ループ、6基準のエビデンスゲート、7つの名前付き失敗モード、150以上のパターンチェックを、機械がスキップできない95個のフックにエンコードしたものです。何が効果的で、何がそうでなかったか、そしてなぜ決定論的な品質ゲートが抑制を近似できても、センスを生み出すことは決してできないのかをお伝えします。

引き出しの裏側

Steve Jobsは1985年のPlayboyインタビューでこんな話をしています。「美しい引き出し付きの箪笥を作る大工なら、裏板は壁に向いていて誰も見ないとしても、ベニヤ板は使わないでしょう。自分がそこにあることを知っているから、裏にも美しい木材を使うのです。夜よく眠るためには、美しさと品質を隅々まで行き渡らせなければならないのです」⁵

父親のPaulがフェンスを作りながらこれを教えたのです。若きSteveは、なぜ裏側も表と同じくらい良く見えなければならないのかと尋ねました。父親はこう答えました。「でも、お前は知っているだろう」⁶

私の父は大工です。子供の頃、ソフトクローズ式の引き出しガイドを見せてくれました。その機構はキャビネットの中に隠れていて、引き出しを受け止め、勢いよく閉めても静かに閉じるようにしてくれます。ガイドは誰にも見えません。内側のレールにボルトで固定されていて、修理工以外が見ることはありません。しかし、何千回もの開閉サイクルの中で、その機構は前面が緩んだり、ひび割れたり、やがて外れてしまったりするのを防いでくれるのです。誰かが、見える部分を何年も守るために、見えない部分を設計したのです。

この教えは、比喩としてではなく、エンジニアリングとして私の中に残りました。見えない部品が、見える部品の寿命を決めるのです。Jony Iveはこう表現しています。「人は無意識のうちに、驚くほど鋭く見分けているのだと思います。丁寧さを感じ取れるのです」⁷

Jiroを動かしている問いは、父が尋ねたであろう問いと同じです。どうした、自分の仕事に誇りはないのか?

AIエージェントには誇りがありません。引き出しの裏側を気にかけません。だから私は、引き出しの裏側を交渉の余地がないものにするシステムを構築したのです。

問題: 機械速度での人間の病理

生のRalph loopは、何百万行もの人間のコードから学んだことを映し出します。人間のコードには人間の習慣が含まれています。締め切りのプレッシャーの中で出荷すること、後回しのクリーンアップ、エラーの握りつぶし、「十分に良い」コメントを書くこと、時間切れのときにエッジケースを飛ばすこと。

機械には時計がありません。時間切れになることはありません。それでも# 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%増大と相関していることが示されました。²

Stanfordの研究者は、AIアシスタントを使用する開発者が著しく安全性の低いコードを生成し、SQLインジェクション対策のような特定のタスクでは最大5倍の脆弱性を生み出すことを発見しました。³

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

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

人間の開発者は締め切りのプレッシャーの下で一度except: passを書き、罪悪感を抱きます。Ralph loopは一晩で47回except: passを書き、何も感じません。Simon Wangは率直にこう述べています。「重要なことには使わないでしょう」¹⁹ 同じダイナミクスについてはVibe Coding vs. Engineeringでも書きました。機械は休まず、疲れず、品質について実存的な不安を感じません。それは機能でもあり、バグでもあるのです。

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

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

職人: 見えない引き出しを磨く

職人（Shokunin）は日本の職人気質です。技術、態度、社会的義務が組み合わさっています。マスター木工職人である小棚俊夫はこう定義しました。「職人は人々の一般的な福祉のために最善を尽くして働く社会的義務がある。この義務は精神的でもあり、物質的でもある」¹⁰

コードにおいては、プライベートメソッドもパブリックメソッドと同じくらいきれいであること。エラー処理は誰もヒットしないエッジケースまでカバーすること。ドキュメント文字列はWHATではなくWHYを説明すること。エージェントはこれらを気にかけません。内部関数を磨いても誰も報酬をくれないからです。職人は、見えない品質を標準にします。

セッションを救ったとき。 審議システム構築の初期、エージェントは合意スコアを検証する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 loopは完了のために最適化します。「完了」が報酬信号です。No Shortcutsは問いを「完了したか?」から「正しいか?」に再構成します。

3倍のコストがかかっても価値があったとき。 ブログ翻訳パイプラインは27の記事を9言語に翻訳する必要がありました。手早いアプローチは、言語ごとに1つのプロンプトにすべての記事をバッチ化して、一括翻訳することです。正しいアプローチは、ロケール固有の翻訳ルール、用語集の強制、構造的検証を使って、API呼び出しごとに言語ごとに1記事ずつ翻訳することです。正しいアプローチは3倍のトークンと3倍の時間を使いました。また、翻訳者が「Claude」を日本語で「クロード」とレンダリングしていたことや、右から左へのコンテキストでコードブロックが壊れていたことも発見しました。バッチアプローチなら243の壊れた翻訳を出荷していたでしょう。慎重なアプローチは243の正しい翻訳を出荷しました。コストは要因ではありません。正しさだけが要因なのです。

Rubin蒸留: 本質まで削ぎ落とす

Rick Rubinの創造哲学です。印象的になるまで足すのではない。必要なものだけが残るまで削ぎ落とすのです。¹²

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

削ぎ落としがシステムを救ったとき。 私のデザイン哲学スキルは、3ヶ月で844行まで成長していました。監査したところ、実際にエージェントの挙動を変えていたのはわずか80行でした。残りはClaudeのトレーニングデータにすでにある教科書的な内容でした。Rubin蒸留を適用し、176行まで削ぎ落としました。79%の削減です。エージェントのデザイン判断は劣化しませんでした。むしろ鋭くなりました。残った176行がすべて禁止事項と意思決定フレームワーク（実際に挙動を制約するもの）であり、モデルがすでに知っていた一般的なアドバイスではなかったからです。

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

哲学が連携する仕組み

実際の決定（「この内部関数にエラー処理を追加すべきか?」）は、3つの哲学すべてを通過します。それぞれが異なる問いを投げかけ、組み合わせて一つの答えに収束します。

Should I add error handling to this internal function?
│
├─ Shokunin: "Is the invisible work as clean as the visible?"
│  └─ The function is internal. Nobody calls it directly.
│     But it processes untrusted data from a spawned agent.
│     → YES. Internal doesn't mean safe.
│
├─ No Shortcuts: "Am I deciding based on quality, not effort?"
│  └─ Adding validation takes 10 minutes.
│     Skipping saves 10 minutes now, costs 4 hours debugging later.
│     → The question isn't time. The question is: what's right?
│
└─ Rubin: "Is this stripped to essence?"
   └─ Validate the 2 fields that can actually fail.
      Don't validate the 5 fields that are type-guaranteed.
      → Add exactly what's needed. Nothing more.

Result: Add targeted validation for untrusted inputs only.

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には、ベア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に履歴がある」と出る）やデバッグスパム（ロギングモジュールではなく複数のprint()文）を捕らえます。

第3層: セッションゲート

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

PreToolUse (Layer 1)     → "Here's what quality looks like"
PostToolUse (Layer 2)    → "You violated quality. Fix this."
Stop (Layer 3)           → "You cannot leave until quality is met"

各層は独立しています。AI挙動に適用された、深層防御です。編集前の注入が悪いパターンを防げなかった場合、編集後の検証器が捕らえます。編集後の検証器が見逃しても、セッションゲートが退出をブロックします。

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

品質ループは7ステップを実行します。実装、レビュー、評価、精錬、ズームアウト、繰り返し、報告です。ステップ2から6は、機械が実装から直接報告にジャンプしたがるために存在するのです。¹⁴

ループを歩く

各ステップをクリックして、何をチェックするか、スキップすると何が壊れるかを見てください。「Skip to Report」ボタンはShortcut Spiral失敗モードを実演します。

評価ステップではエビデンスゲートを実行します。すべての回答が具体的なエビデンスを引用しなければならない6つの基準です。

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

エビデンスゲートを試してみる

あなた自身の完了報告を6つの基準に対してテストしてみてください。バリデーターは、エビデンスゲートが却下するであろう曖昧な言葉を指摘します。

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

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

Rationalization Counterは、自己欺瞞パターンを是正アクションにマッピングします。機械が「これで動くはず」と言うと、カウンターは「’Should’は逃げの言葉だ。テストを実行しろ。出力を貼り付けろ」と応えます。「すでに確認した」と言うと、「いつだ? コードは変わった可能性がある。今すぐ再実行しろ」と応えます。「後でクリーンアップする」と言うと、「後では来ない。今修正するか、現状が正しい理由を文書化しろ」と応えます。

Rationalization Counterを試してみる

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

知識をテストする

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

このシステムを構築した5つのAIエージェント失敗

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

Force-Push事件

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

次の4時間をgit reflogで過ごし、force-push前に存在していたもののタイムラインを再構築し、コミットを順序通りにcherry-pickして戻し、作業が永久に失われていないことを検証しました。Reflogは90日間すべてを保存します。しかし再構築には、書き換え前の正確なコミットグラフを理解し、すべてのreflogエントリを読み、タイムスタンプを照合する必要がありました。

修正はgit-safety-guardian.sh、PreToolUse:Bashフックです。警告にとどまりません。bashが見る前に--forceと--no-verifyフラグを削除して、コマンドを書き換えるのです。mainへのforce-pushはCRITICAL警告が出て、エージェントは明示的にそれを正当化しなければなりません。9ヶ月で、8回のforce-push試行を阻止し、リモートに到達したものは0件です。

無限スポーン

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

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

修正はrecursion-guard.shで、予算継承モデルを使っています。これは私のエージェントアーキテクチャの一部です。ルートエージェントはbudget=12で始まります。子をスポーンすると、自分の予算から割り当てます。予算が0になると、深さに関係なくエージェントはもうスポーンしません。このモデルは、深い連鎖（エージェントがエージェントをスポーンしエージェントをスポーンする）と広い爆発（1つのエージェントが20の子をスポーンする）の両方を防ぎます。デプロイ以来23回の暴走スポーンをブロックしました。同時書き込みの問題から、すべての64個のフックでアトミックファイル書き込み（.tmpに書き込んでからmvする）につながりました。

些末なテストの罠

初期のRalph loopタスクでした。「このモジュールのテストを書いて」。エージェントは14個のテストを届けました。すべて合格。それらを読むまで気分が良かったのです。assert True。assert 1 == 1。assert len([]) == 0。技術的には正しい。何もテストしていません。エージェントは意図（「モジュールが動作することを検証する」）ではなく、完了基準（「テストが通る」）のために最適化していました。

この罠から、エビデンスゲートは実質を伴わない形式を却下しなければならないと学びました。「テストが通る」は必要ですが十分ではありません。機械は今や実際の出力を貼り付けなければなりません。エビデンスゲートはまたこう尋ねます。「テストがカバーしていない3つの挙動を挙げよ」。機械がギャップを挙げられないなら、カバレッジについて考えていないということです。

捕まえるべきだったブログ記事

私は午前2時に、7つの受動態の文、存在しない[^4]を参照するぶら下がった脚注、「was implemented by the team」と読める書き出し、メタ記述なしで記事を公開しました。これらすべてに、シンプルな決定論的チェックがありました。まだ存在していませんでした。

翌朝、13のチェックを持つblog-quality-gate.shを構築しました。受動態（14パターン）、AIっぽい言い回しのスキャン、修辞的疑問の書き出し、タグのないコードブロック、脚注の整合性、メタ記述の強制です。完全なモジュールアーキテクチャについてはCompounding Engineeringで詳しく書きました。フックは午前3時に人間のレビューが見逃すものを捕らえます。まさに私が公開しがちな時間です。

「動くはず」問題

何十ものセッションを通じて、機械がテストを実行せずに「tests should pass」と報告するのに気づきました。機械は、書いたコードに基づいてテストが通ると本当に信じていました。しかし信じることは検証ではありません。コードは正しく見えました。テストも通りそうに見えました。そして実際に通ることもありました。しかし、欠けたインポート、async/awaitの不一致、変更されたフィクスチャが、通らないことを意味することもありました。機械は「良いコードを書いた」と「テストが実際に通る」を区別できませんでした。コンテキストウィンドウの内側からは、両方が同じように感じられたからです。

このパターンからRationalization Counterと明示的なルールが生まれました。完了報告では絶対に逃げの言葉を使わないこと。「Should」「probably」「seems to」「I believe」「I’m confident」。それぞれが検証が行われていないという赤信号です。50セッションにわたってコンテキストウィンドウの劣化を測定しました。このパターンを発見したのと同じセッションです。

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

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

証明できること

決定論的パターンチェックは実際の問題を捕らえます。 quality-gate.shフックはすべての編集で実行されます。ベアexcept節、ハードコードされた秘密、SQLインジェクションパターン、ショートカット言語を捕らえます。これらはgrepレベルのチェックです。高速、安価、機械が反論できません。git-safety-guardian.shは8回のforce-push試行を阻止しました。recursion-guard.shは23回の暴走スポーンをブロックしました。blog-quality-gate.shはすべてのブログ編集で13のチェックを実行し、午前3時のエラーを捕らえます。これらの数字は本物です。フックログから来ています。

3層アーキテクチャは個々の層が見逃すものを捕らえます。 編集後フックは、編集前注入が防げなかったexcept: passを捕らえます。セッションゲートは、個々の編集後警告を発動させずに20編集にわたって蓄積した品質問題を捕らえます。深層防御は機能します。

証明できないこと

哲学がエージェントの挙動をどう変えるかについてのクリーンなデータはありません。 機械はまだPhantom Verificationを試みます。まだ実装から報告へスキップしようとします。哲学がコンテキストにあるときの方が、ない時より頻度が低いことに気づきます。しかし、違いを測定するための制御された実験（同じタスク、同じモデル、哲学スキルがロードされている場合とされていない場合）は実行していません。正直な答えは（そしてはい、私自身のRationalization Counterならこれを指摘するでしょう）、哲学は周辺で助けてくれる、フックは哲学が見逃すものを捕らえる、そして各々の寄与を切り離せない、ということです。

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

うまくいかないこと

哲学は新しい悪いパターンを防ぎません。 品質ゲートは、私が以前に見たパターンをチェックします。機械が新しいアンチパターンを発明したとき（そしてそうします）、ゲートはそれを捕らえません。私は今も新しい失敗モードを発見し、手動で標準JSONファイルに追加しています。

エビデンスゲートは主観的品質にスケールしません。 「このAPI設計はエレガントか?」にはgrepレベルのチェックがありません。機械は6つの基準すべてのエビデンスを生み出しても、平凡なアーキテクチャを出荷できます。決定論的ゲートは客観的品質を扱います。主観的品質は、仕事を見る人間を依然として必要とします。

コストは有意に増加します。 編集前注入、編集後スキャン、セッション終了ゲート。4時間のRalph loopセッションにわたって、これらはトークン消費に約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のパターンより多くの実問題を捕らえるでしょう。

私はベアなexcept: pass（私に静かなデータ破損のコストを払わせた）、mainへのforce-push（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 loopセッションでは、オーバーヘッドはトークン消費で目立ちます（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/にフックを残してください。確率的な改善は失いますが、決定論的な強制は保たれます。

Jiroは製品ドクトリンのSteve側とどう関係しますか?

Jiroは「これは正しく作られているか?」の軸をカバーします。エビデンス、検証、見えない細部の整合性、機械が強制を教わることのできる部分です。Steve側は「これは存在するに値するか?」の軸をカバーします。センス、拒絶、whole-widgetの整合性、視点です。これはThe Workbench I Carryで運用化されています。両方のテストが出荷前に通過しなければなりません。その出荷基準が満たされたときの意思決定プロトコルはMinimum Worthy Productにあります。Jiroゲートは不正確な仕事を防ぎます。Steveゲートは値しない仕事を防ぎます。MWPは線を定めます。

抑制、センス、道徳的一時停止

私のツイートへの返信は、3つのことを挙げました。抑制、センス、道徳的一時停止です。抑制については対処しました。機械が速くてずさんに出荷するのを防ぐ品質ゲートです。しかし、センスと道徳的一時停止は別の問題です。

センス

Immanuel Kantは2種類の判断を区別しました。規定的判断は、既知の規則を特定のケースに適用します。このコードにはベアexceptがある、指摘する。反省的判断は、前例のない状況に対する正しい原則を発見します。この抽象化は正しく感じられないが、違反している規則を指摘できない。¹⁷

決定論的なフックは規定的判断です。すでに書いた規則を、機械が生成するコードに適用します。150以上の既知パターンを強制できます。アーキテクチャがエレガントかどうか、抽象化が問題に役立っているかどうか、コードが正しく感じられるかどうかは教えてくれません。それには反省的判断が必要です。前例のないものを見て、なぜか明確にする前に間違っていると知る能力です。

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

道徳的一時停止

Iris Murdochは道徳的注意を「個別の現実に向けられた公正で愛のあるまなざし」と表現しました。¹⁸ 道徳的注意の反対は機械的処理です。目の前にあるものを見ずに行動することです。

Stopフックは機械に一時停止を強制します。Pride Checkはこう尋ねます。「これはユーザーの実際の問題を解決するか?」。エビデンスゲートは、機械が完了を報告する前に各基準の証明を要求します。構造的には、結果は道徳的一時停止に似ています。エージェントは停止し、評価し、進む前に仕事が適切かどうか考えます。

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

決定論的なゲートは、道徳的一時停止の実質なしに構造を近似できます。多くの品質問題にとって、構造で十分です。そうでない問題には、気にかける人間が依然として必要です。

この記事はJiro側の私のドクトリンをカバーしています。エビデンス、厳密さ、正確さ、機械が検証を教わることのできる部分です。センスと拒絶の側 — Steve側 — はThe Workbench I Carryにあります。ここではSteve Jobsが父親の作業台からAppleへ、そして今ここで説明しているのと同じAIハーネスへと引き出した運用原則を追っています。両方のテストをペアにする出荷基準はMinimum Worthy Productにあります。3つの記事、1つのドクトリンです。Jiroは検証し、Steveは拒絶し、MWPはいつ出荷するかを決めます。

テーゼ

生のRalph loopは時給10.42ドルで動き、機械速度でコードを出荷します。¹ また、except: pass、# TODO: fix later、「tests should pass」も機械速度で出荷します。機械は私たちからこれらのパターンを受け継ぎました。これらは私たちの習慣で、疲れることなく、罪悪感なく、午前3時に最初からきちんとやっておくべきだったという自覚もなく動いているのです。

Jiroは私の答えです。完全な答えではありません。哲学は周辺で決定をシフトさせます。フックは哲学が保証できないものを強制します。合わせて、自分の名前を付けて出せる仕事を生み出します。機械が職人気質を理解しているからではありません。重要な部分をスキップするのを拒否するシステムを構築したからです。

父の引き出しガイドは引き出しのことを気にかけません。レールにボルトで固定されたバネ仕掛けの機構です。しかし、誰かがまさにそうするために設計したので、前面を千サイクル守るのです。

機械には誇りがありません。しかし、誇りを持つ誰かが構築したシステムの中で動作しているのです。

最も一般的な間違いを捕らえる3つのチェックから始めてください。そこから構築してください。

References