平野 空暉 の記事一覧

はじめに こんにちは。GMOインターネットの平野です。 以前、ハーネスエンジニアリングの紹介記事では、ConoHa VPS MCPサーバー開発で実践したハーネスエンジニアリングの具体的な仕組みを紹介しました。「何をやったか」の話です。今回は一段メタな視点で、「なぜそうなるのか」を掘り下げます。ハーネスエンジニアリングとは、結局のところ何をしているのか。その本質と思想を整理します。 本質: 従来の開発規律の再設計 ハーネスエンジニアリングの本質は、新しい規律の発明ではありません。 テスト、CI、リンター、コードレビュー、ADR （Architecture Decision Records）──これらは従来からやるべきだった開発規律です。ハーネスエンジニアリングの新しさは、これらをエージェントが end-to-end で回せるように再設計している点にあります。 4 つの再設計軸 従来の開発とハーネスエンジニアリングの違いを、4 つの軸で整理します。 再設計軸従来ハーネスエンジニアリング実行環境人間がローカルで実行エージェントが Hooks・CI で自律的に駆動知識配置Wiki等に記述的に蓄積メタデータ付きのMarkdownファイル検証ループCI → 人間レビュー → 修正PostToolUse（ms）→ プリコミット（s）→ CI（min）で自己修正運用経済人間の時間が律速、慎重にマージエージェントの実行時間が律速、「修正は安価、待機は高コスト」 この 4 軸は、ハーネスエンジニアリングを考えるときの基本的なフレームワークになります。 制御なき AI コーディングの課題 ハーネスなしで AI に自由にコーディングさせると、以下の問題が構造的に発生します。 一貫性の欠如: ファイルごとに実装パターンがずれる、命名規約に揺れが出るアーキテクチャの崩壊: 境界を越えた import が紛れ込む、レイヤー設計が壊れる技術的負債のサイロ化: エントロピーが増大し、各セッションが独立した負債を生産する これらは AI の能力不足ではなく、制約の不在が引き起こす構造的問題です。人間の開発者でも、レビューやルールがなければ同様のことが起きます。AI の場合、速度が速いぶん、問題の蓄積も速くなるだけです。 プロンプトの限界とハーネスの複利効果 「AI に良いコードを書かせたいなら、良いプロンプトを書けばいい」──これは直感的には正しく聞こえます。しかし、この方法には構造的な限界があります。 プロンプト依存の限界: AI に高品質を求めるほど、指示が肥大化する指示が肥大化するほど、品質担保が「人間がプロンプトを正しく書けたか」に依存するプロンプトは毎回書き直す消耗品であり、セッションをまたいで蓄積しない 一方、ハーネスは一度作れば繰り返し品質を安定供給できます。たとえば、リンタールールを 1 つ追加すれば、以降すべてのセッションでそのミスが防がれます。 プロンプトは単利、ハーネスは複利です。 もちろん、プロンプトが不要になるわけではありません。プロンプトは「何をつくるか」の方向づけに不可欠です。ただし、「どう品質を守るか」をプロンプトに頼り続けるのは、スケールしない方法だということです。 6 つの核心原則 ハーネスエンジニアリングの設計を支える原則を 6 つに整理します。 品質の源泉は「仕組み」: プロンプトではなく、ハーネスで品質の不確実性を除去する速度こそが品質: フィードバックループの速さが品質を規定する。ms 単位でエラーを発見できれば、修正コストは限りなく小さくなる制約がエージェントを導く: 自由度ではなく「制約」で一貫性と予測可能性を両立させるルールは陳腐化が前提: ルールの鮮度の自動検証、AI レビューを実施する機械的に検証しづらい品質も測る: 機械的に検証しづらい品質基準も言語化し、AI に提供することで、機械的検証の死角をカバーする自律に耐えうる設計: ルール自体の運用（追加・変更・廃止）を、エージェントが実行できるように明示する 原則 6 は特に重要です。ルールを作るだけでなく、ルールのメタ運用自体もエージェントが参加できるよう設計する。これによって、ルール体系そのものが自律的に進化し続けるための土台ができます。 広義と狭義のハーネスエンジニアリング 広義: 3 つの柱の統合 ハーネスエンジニアリングを広義に捉えると、3 つの柱で構成されます。 コンテキストエンジニアリング ──エージェントに「何を守るべきか」を正しく伝える CLAUDE.md の設計（50行以下、詳細はオンデマンドロード）計画と実行の分離（エージェントに計画を立てさせ、人間がレビューしてから実行）Skillsやコーディングパターンのドキュメントのメタデータ設計 ハーネス（制約） ──不変条件を機械的に検証し、違反をブロックする リンター、テスト etc...Hooks による開発時ガード構造テストによるアーキテクチャ不変条件の固定 ガベージコレクション ──ルール体系そのものの劣化を検知し、鮮度を保つ ルールの鮮度チェックADR によるルール変更経緯の記録 この 3 つの柱は独立しているのではなく、互いに依存しています。コンテキストエンジニアリングがなければ制約は伝わらず、制約がなければ品質は守れず、ガベージコレクションがなければ制約は陳腐化します。 狭義: 制約で狭める 狭義のハーネスエンジニアリングは、2 番目の柱──制約による品質担保──に焦点を当てます。 エージェントの解決空間を広げるのではなく、狭めることで一貫性と予測可能性を高める「自由にやらせて後でレビュー」ではなく、「最初から選択肢を絞り、逸脱を即座に検知」制約がエージェントを弱くするのではなく、制約がエージェントを強くする ここでのポイントは、今すぐ機械で判定できないルールであっても、言語化しておく価値があるということです。定義さえあれば、将来のツール改善によって自動化が可能になります。定義がなければ、永遠に暗黙知のまま残ります。 運用思想: 人間とエージェントの役割分担 人間の役割──方向づけと判断 優先順位付け: 何を先にやるか、何を後回しにするか受け入れ基準の定義: 完了条件を曖昧にせず言語化する成果検証: エージェントの出力が意図と合致しているか確認例外判断: ルールから外れるべきケースの判断（ADR として記録） 人間は主にプロンプトで方向づけし、エージェントが実装・レビュー対応・修正まで進めます。 エージェントの役割──実行と自己修正 エージェントは、人間が設計した制約の中で、end-to-end の実行ループを自律的に回します。 実装レビュー指摘への対応テスト修正 重要なのは、エージェントに「何でもできる自由」を与えることではなく、「制約の中で確実に動ける仕組み」を提供することです。 暗黙知の排除原則 すべてのルールはまず知識として全情報をAIに渡します。人間だけが感覚で知っている状態を排除する──これが運用思想の根幹です。 人間が暗黙的に持っている品質基準を、明示的に言語化してAIに渡す「わかっているはず」「常識だろう」という前提を排除し、すべてを機械可読な形で記述する 暗黙知の排除は、AI のためだけの施策ではありません。新しいチームメンバーのオンボーディングにも、同じ形で効きます。 運用経済: 「修正は安価、待機は高コスト」 従来の開発では、人間の時間が最も高コストでした。だからこそ「慎重にレビューし、確実にマージする」ことが合理的でした。 エージェント駆動開発では、この経済構造が反転します。 観点従来の開発エージェント駆動開発最も高コストなもの人間の時間エージェントの待機時間マージ戦略慎重にレビューを行うお客様影響がないと言い切れるものはレビューを最小限にし、スループットを上げる この経済観から導かれる設計判断 人間の承認待ちがボトルネックにならないよう、自動マージ可能な範囲を広げるフィードバックループの高速化を行うために、PostToolUse（ms）で直せるものを CI（min）まで待たせない フィードバック速度のパラダイムシフト 従来は人間によるレビュー（数時間）が品質の最終防衛線でした。ハーネスエンジニアリングでは、この防衛線をツール実行（数ミリ秒）へシフトさせます。 レイヤー速度性質PostToolUsems機械的・即時Pre-commitsローカル環境CIminリモート環境Human Reviewh人間的・遅延 CI で落ちてから気づくのではなく、開発ループの中で「その場で正される」即効性が品質を生みます。できるだけ多くのチェックを、最も速いレイヤー（ms）に移動させることがハーネス設計の基本原則です。 まとめ ハーネスエンジニアリングの本質は、「新しい規律の発明」ではなく「既存の開発規律を、エージェントが回せるように再設計すること」です。この記事の要点を 2 つに整理します。 1. 制約がエージェントを強くする エージェントの能力を引き出すのは自由度ではなく制約です。制約を強め、逸脱を即座に検知する仕組みが、一貫性と予測可能性を生みます。プロンプトによる毎回の指示（単利）ではなく、ハーネスという仕組みへの投資（複利）が、長期的に品質を安定させます。 2. 暗黙知を排除し、すべてを機械可読にする 人間だけが感覚で知っている状態を排除し、ルールを明示的に言語化する。今すぐ自動化できなくても、デジタルで定義しておくことで、将来の自動化への道が開けます。ルールの追加・変更・廃止というメタ運用も含めて、機械可読に設計することが、自律的に進化するルール体系の土台になります。 以前紹介した記事の実践は、この思想の具体的な表現です。個々のテクニックとして消費するのではなく、「従来の開発規律の再設計」というフレームで捉えることで、自分たちのプロジェクトに合った仕組みを設計するヒントになれば幸いです。 また、ハーネスエンジニアリングについての弊社の取り組みについて、インタビュー記事も公開されました。よかったら合わせてご覧いただけますと幸いです。

はじめに こんにちは。GMOインターネットの平野です。 前回の記事では、AIコーディングエージェントの出力品質を「構造」で担保するハーネスエンジニアリングの考え方と、4段階エスカレーションラダー（L1〜L4）の実装について紹介しました。 このハーネスをしばらく運用してきて、自然と浮かんできた問いがあります。 「ここまで構造で品質を守れるなら、人間のコードレビューはどこまで必要なのか？」という問いです。 先に結論を言うと、コードレビューを全廃できるとは考えていません。ただし、レビューが拾っているものを分類してみると、その大部分はハーネスとAIで代替できる作業であり、人間が本当に見るべき領域はもっと狭い、ということがわかってきました。この記事では、その分類と、移行をどう判断するかについて整理します。 レビューがボトルネックになる構造 AIにコードを書かせると、コーディングの速度は確実に上がります。一方で、レビューの速度は人間の処理能力に縛られたままです。 開発スタイルコーディング速度レビュー速度ボトルネック人間が書き、人間がレビュー1x1xなし（均衡）AIが書き、人間がレビュー5~10x1xレビューが律速AIが書き、ハーネス+AIがレビュー5~10x自動化解消 この構造を放置すると、「レビューを省略して速度を取るか、レビューを維持して品質を取るか」という二択に追い込まれます。どちらも望ましくありません。必要なのは、レビューの中身を分解して、自動化できるものとできないものを仕分けることです。 コードレビューが拾うものを分類する コードレビューで指摘される内容を整理すると、大きく4つのカテゴリに分かれます。 カテゴリ内容自動化Aハーネス違反の検出可能B-1ハーネス自体の矛盾不可B-2ハーネス不足不可C要件・設計の妥当性スコープ外 カテゴリA: ハーネス違反の検出 命名規約やアーキテクチャ境界、実装パターンへの準拠など、既存のルールに対する違反を見つける作業です。「camelCaseになっていない」「レイヤーを越えたimportがある」「パターンファイルで定義した実装方針と違う」といった指摘がここに入ります。 カテゴリB-1: ハーネス自体の矛盾 ルール体系そのものに矛盾がある場合です。たとえば、あるルールは「すべてのスキーマに.strict()をつける」と言い、別のルールは「外部APIレスポンスには.passthrough()を許容する」と言っている。外部APIのレスポンスをバリデーションするスキーマはどちらに従うべきでしょうか。こうした矛盾は、ルールを個別に見るだけでは気づけません。特に、新しいルールを追加するとき、ルール体系をリファクタリングするときに発生しやすくなります。パターンファイルが推奨するディレクトリ構造と、別のパターンファイルが前提とするインポートパスが噛み合わなくなる、といった事態は、ルールが増えるほど起きやすくなります。 カテゴリB-2: ハーネス不足 ハーネスがまだカバーしていない領域の発見です。たとえば、新しいライブラリやフレームワークが追加されたのに、それに対するルールが整備されていないとき、また、既存ルールの粒度では捕捉できないクラスのバグが起きたとき、「ルールを足すべきだった」と事後的に気づくケースもあります。AIは「既存ルールに違反していない」ことは判定できますが、「ルールが足りない」ことは判定できません。「ルールが無いから通過」と「ルールが不要だから通過」の区別がつかないのです。 カテゴリC: 要件・設計の妥当性 そもそもこの実装が問題を正しく解決しているか、アーキテクチャ上の判断は妥当か、という問いです。これはコードレビューというより設計レビューであり、判断基準もタイミングも異なります。設計レビューは本来、実装に入る前に行うべきものです。コードレビューの場で「そもそもこの方針で合ってるのか」が議論になるのは、設計レビューとコードレビューが混同されている兆候であり、プロセス自体を見直すべきサインです。本稿ではカテゴリCをスコープ外とし、コードレビューの中で扱うべきA・B-1・B-2に焦点を当てます。 機械に任せられるもの、人間が見るべきもの カテゴリA: ハーネス違反の検出 ハーネス違反は、決定論的なものと確率的なものに分類できます。リンター等による決定論的な検出は、見落としがなく、人間も疲れません。確率的な検出は現時点では人間と同等かやや劣る可能性がありますが、ここは後述する並行運用で検証できます。 カテゴリB-1: ハーネス自体の矛盾 一方、ハーネス自体の矛盾の検知を自動化できない理由は構造的なものです。ハーネス矛盾（B-1）について言えば、AIはルールを公理として受け取ります。公理は「従うもの」であり「疑うもの」ではありません。公理系の内部矛盾を検出するには、その系の外に立ち、ルール同士の関係を俯瞰する視点が必要です。これは本質的にメタレベルの作業であり、現状のAIにはこの自発的な「一歩引いた視点」が欠けています。 矛盾が特に発生しやすいのは、次のようなタイミングです。 新ルールの追加時（既存ルールとの整合性チェックが漏れる）ルールの昇格時（執行レベルの変更による副作用が見えにくい）ルール体系のリファクタリング時（分割・統合で前提が崩れる） だからこそ、ハーネス自体を変更するPRには、必ず人間のレビューを通す必要があります。ハーネス変更のレビューは省略してはいけません。 カテゴリB-2: ハーネス不足 ハーネス不足（B-2）について言えば、AIは「ルールがないから通過」と「ルールが不要だから通過」の区別がつきません。ルールが存在しない領域では、AIは何もフラグを立てずに通過させます。 これはAIの欠陥ではなく、ルールベースなシステムの構造的な限界です。経験あるエンジニアがレビューで拾うのは、まさにこの「ルールがまだない領域」の問題であることが多い。「このパターン、うちのコードベースに入ったの初めてだけど、ルール化しなくて大丈夫？」「この新しいライブラリの使い方、パターンファイルに追加しておいたほうがよくないか？」といった問いかけは、ハーネスの外にいる人間にしかできません。こうした指摘は、ハーネスを育てる上で最も価値のあるフィードバックになります。 カテゴリC: 要件・設計の妥当性 カテゴリC（設計の妥当性）については、ハーネスの守備範囲外です。「このAPIの設計は利用者にとって使いやすいか」「この機能の責務配置は将来の拡張に耐えられるか」といった問いは、コードの正しさではなく設計の判断に関わるものです。こうした問いは実装に入る前の設計段階で扱うべきであり、コードレビューの場に持ち込むと、レビューの焦点がぼやけます。設計レビューとコードレビューを明確に分けることで、それぞれのプロセスが本来の役割に集中できるようになります。 カテゴリBとCを整理すると、人間がレビューで注力すべき領域がはっきりします。この構造は、自動テストの普及がQAの役割を変えた流れに似ています。手動テストが自動テストに置き換わったとき、QAは「テストを実行する人」から「テスト戦略を設計する人」になりました。同様に、コードレビュアーは「違反を検出する人」から「違反を検出する仕組みを設計する人」へと役割が変わっていくと考えています。 統計で判断する: 並行運用モデル カテゴリAが自動化可能だとしても、「いつ人間レビューをやめるか」を感覚で決めるべきではありません。並行運用でデータを取り、統計的に判断するアプローチを考えています。 フェーズ1では、人間レビュアーとAIハーネスの両方がすべてのPRをレビューします。人間レビュアーはAIの結果を見ずに独立してレビューし、両者の指摘を記録して差分を分類します。そして、以下のメトリクスを計測します。 メトリクス定義目標AIの見落とし数人間が検出したがAIが見逃した違反低下傾向人間の見落とし数AIが検出したが人間が見逃した違反ベースライン偽陽性率AIが指摘したが人間が却下したもの / AIの全指摘数閾値以下 ここで重要なのは、人間見落とし数を計測する点です。人間もまた見落とすことは多々あります。AIの見落とし数が人間の見落とし数を下回れば、AIに委譲する統計的な根拠が成立します。 フェーズ2においてAIの見落とし数が人間の見落とし数をN週連続で下回った時点で、カテゴリAの人間レビューを任意化します。ただし、まず低リスクなPR（小規模変更、既知パターンのみ）から人間レビューを省略し、段階的にスコープを広げます。異常があればフェーズ1に戻ります。セキュリティやデータ損失に関わる重大な違反については、統計的にAIが優勢でもサンプリングベースで人間レビューを継続することを想定しています。稀だが重大な問題は、統計の平均値だけでは捉えきれないからです。 条件閾値判定AI見落とし数 < 人間見落とし数N週連続で達成カテゴリAの人間レビューを任意化偽陽性率X%以下を維持レビュアーの信頼が維持される重大違反の見落とし0件移行の前提条件 まとめ コードレビュー不要論の核心は、「レビューをやめる」ことではなく、レビューの対象を再定義することです。今回の議論は、次の3つに整理できます。 1. レビューの分類が自動化の出発点 コードレビューが拾うものは一枚岩ではありません。ハーネス違反の検出、ハーネス自体の矛盾、ハーネスの不足、設計の妥当性。分類して初めて、何が自動化でき、何に人間の判断が必要かが見えてきます。 2. ハーネスの「中」は機械、「外」は人間 既知のルールに対する適合チェックは、レビューの最大ボリュームでありながら、構造的に自動化可能な作業です。一方、ルール体系自体の矛盾や不足は、ルールの外に立つ視点でしか見つけられません。人間のレビューは、この「外」を見ることに集中すべきです。 3. 移行はデータで判断する 「AIのほうが賢そうだから」は、移行の根拠になりません。並行運用で人間とAIの見落とし率を比較し、統計的にAIが人間と同等以上であることを確認してから移行する。このプロセスを踏むことで、感覚ではなくエビデンスに基づいた判断ができます。 コードレビューが不要になるのではなく、コードレビューの対象が「コード」から「ハーネス」に移行する。レビュアーの役割は消えるのではなく、より高いレイヤーへ移る。これが、ハーネスエンジニアリングを運用してきた先に見えてきた景色です。 また、ハーネスエンジニアリングについての弊社の取り組みについて、インタビュー記事も公開されました。よかったら合わせてご覧いただけますと幸いです。

AIコーディングエージェントによって、実装のスピードは確かに上がりました。設計し、試し、修正する。その試行回数を増やせることは、AI駆動開発の大きな価値です。一方で、コード品質のばらつきや設計の揺れといった課題も見えてきました。そこで私たちは、AIの出力品質を人の注意力ではなく、構造で支える仕組みとして「ハーネスエンジニアリング」を導入しました。本記事では、その実践内容を紹介します。 はじめに こんにちは。GMOインターネットの平野です。 ConoHa VPSではMCP（Model Context Protocol）サーバーを、Claude Codeを活用したAI駆動開発で構築しています。この開発スタイルをしばらく続けてきて、AI コーディングエージェントに実装の多くを任せ、開発スピードはたしかに上がったと実感しています。 これは単に人間がコードを書く量が減る、という話ではなく、設計して、試して、修正する。その往復が速くなり、試行回数を増やせるのが大きいと感じています。 一方で、運用を続けるうちに、見過ごせない課題もはっきりしてきました。AIが出力するコードの品質に、どうしてもばらつきが出でしまいます。ファイルごとに実装パターンが少しずつずれたり、命名規約に揺れが出たり、アーキテクチャ境界を越えたimportが紛れ込んだりする。しかも、そのズレを最後に拾うのは、PRレビューをする人間の注意力でした。この状態だと、AIに任せるほど開発は速くなる一方で、品質保証のしわ寄せが人間に集中してしまいます。 そこで、AIの出力品質を人の頑張りではなく、構造で担保する仕組みを整えました。そのベースに置いたのが、ハーネスエンジニアリングという考え方です。この記事では、その実践内容を紹介します。 ハーネスエンジニアリングとは ハーネスエンジニアリングは、AI コーディングエージェントを“自由に走らせる”のではなく、守るべき制約を明示し、逸脱したら検知・修正・停止できるようにする考え方です。名前のとおり、「手綱（harness）」のメタファーに近いものです。 中心になるのは、次の 3 つです。 コンテキストエンジニアリング: AIに「何を守るべきか」を正しく伝えるアーキテクチャ制約: 不変条件を機械的に検証し、違反をブロックするガベージコレクション: ルール体系そのものの劣化を検知し、鮮度を保つ この考え方を、「ドキュメント → AI セマンティック → CI → 構造テスト」という 4 段階のエスカレーションラダーとして実装しました。現在は、12 カテゴリ・48 ルールをこの体系で管理しています。 カテゴリー内容ルール数Aファイル構造3Bクライアントモジュール6Cスキーマ4Dレスポンスフォーマッター5Eテストファイル6FJSDoc3Gインポートルール4H命名規則4Iアーキテクチャ境界5Jコード衛生2Kセキュリティ・品質3Lドキュメント整合性3 4段階エスカレーションラダー このフレームワークの核になるのは、ルールの執行レベルを段階的に引き上げることです。すべてのルールは、まずL1のドキュメントから始めます。そのうえで、違反の頻度や、自動検出のしやすさに応じて、より強いレベルへ昇格させていきます。 最初からすべてをCIやテストに押し込むわけではありません。まずは言語化し、繰り返し問題になるものだけを、より強い執行手段へ移していく。この段階設計が、実際に回る仕組みをつくるうえで重要でした。 L1: ドキュメント: すべてのルールの出発点 最初の段階では、ルールを15個のパターンファイル（harness/patterns/*.md）に分けて定義しています。各ファイルには YAML フロントマターを持たせ、enforcement-levelやrelated-rulesといったメタ情報も一緒に管理しています。つまり、ルールを単なる読み物として書くのではなく、あとから機械的に扱える前提で整理している、ということです。 ここで大事なのは、「何を守るべきか」を曖昧にしないことです。AIに品質を求める前に、人間側が品質基準を明文化しておく必要があります。地味に見える作業ですが、ここが曖昧だと、その先の自動化はどこかで破綻します。 L2: AI セマンティック: AIの判断力を執行に使う 機械的に判定しづらいルールは、AI のセマンティックな理解を使って執行します。 開発時（予防）: CLAUDE.mdにルールを記述し、Claude Codeが開発中に参照するPR時（検知）: Claude Code Review CIが差分をレビューし、違反を指摘する このレベルの強みは定量化しにくい品質基準まで扱えることです。 たとえば、「APIレスポンスは、利用者が次のアクションを判断するのに必要な情報だけを返す」「エラーメッセージには、何が起きたかだけでなく、次にどうすればよいかも含める」といった基準です。こうしたものはlintや単体テストでは扱いづらい一方で、実際の使い勝手には大きく影響します。 だからこそ、これらを単なる“書き方の好み”で片づけず、品質基準として AI に共有しておくことが重要になります。 L3: CI ツール: 機械的に検出できるものは止める 違反が繰り返し発生し、しかも機械的に検出できるルールは、CI に移して自動でブロックします。 ツール検出対象CI種別Biomeフォーマット・リンティングblockingdependency-cruiser循環依存・アーキテクチャ境界blockingknip未使用ファイル・未使用エクスポートblockingnpm audit高リスク脆弱性blockingjscpdコード重複advisorystrykerミューテーションスコアadvisory ここでは、違反時にマージを止めるblockingと、改善の参考情報として扱うadvisoryを分けています。この線引きは、現場で運用するうえで意外と重要です。今すぐ直さないといけないものと、継続的に改善していくものが混ざると、だんだん全部がノイズになってしまうからです。 L4: 構造テスト: アーキテクチャの不変条件を固定する 最上位のL4では、architecture.test.tsに23個のアーキテクチャ不変条件をVitestで実装しています。npm testを実行するだけで、たとえば次のようなプロジェクト固有ルールを検証できます。 ファイル名が命名規約に従っているかスキーマ定義に.strict()が付いているかエクスポート関数がcamelCaseに従っているか ここまで来ると、ルールは「読めばわかるもの」ではなく、破ったらテストが落ちるものになります。レビュー担当者の気づきに頼るのではなく、構造として守られる状態をつくれるのが、このレベルの大きな価値です。 開発フローの中で効かせる: Claude Code Hooks 4 段階のラダーは、主に CI やテストで効く仕組みです。ただ、実際に運用してみると、それ以上に効果を感じたのは、CIに届く前のローカル開発段階でもルールが作用することでした。そこでClaude Codeの Hooksを使い、3つのガードを設定しています。 Hookタイミング役割harness-guardファイル編集前ハーネスファイル編集時に「Architecure Decision Record（ADR）の作成が必要かもしれない」と警告biome-autofixファイル編集後Biomeの自動修正を即時適用Stop promptAI作業完了時typecheck/testの実行漏れやKDR検討漏れを確認 これによって、AIがコードを書いた直後にフォーマットが整い、作業を終えようとした時点でテスト実行漏れも指摘されます。CIで落ちてから気づくのではなく、開発ループの中でその場で修正される。この即効性は、実際に回してみるとかなり効きました。 昇格の判断と実例 ルールを上位レベルへ昇格させる最終判断は人間が行います。ただし、その判断材料の収集は自動化できると考えています。 現在実装を進めているのが、Claude Code Review CIが付与するpattern-violation:*ラベルを週次で集計し、3回以上検出されたL2ルールについてGitHub Issueを自動作成するエスカレーショントラッカー（escalation-tracker.yaml）です。これが稼働すれば、「このルールはL3に上げるべきか」「構造テストにすべきか」を、開発者がデータに基づいて判断しやすくなります。判断の経緯は、Architecure Decision Record（ADR）として残す運用を想定しています。 実例をひとつ挙げると、プロジェクト初期にはCODING_PATTERN.mdという 681 行の単一ファイルでルールを管理していました。しかし、この形だと AI がコンテキストとして読み込むコストが高く、メンテナンスもしづらい。そこで16個の独立したパターンファイルに分割し、それぞれにメタデータを付ける設計へ移行しました。 これは単なるファイル整理ではありません。AIが参照しやすく、人間も保守しやすいルール体系へ作り直した、という意味で大きな転換でした。 エントロピー管理: ルールは書いて終わりではない ルールは、一度作れば終わりではありません。むしろ時間がたつほど、現場に合わなくなったり、形骸化したり、守る意味が薄れたりします。放っておくと、品質を守るための仕組みそのものが、現場の負債になっていきます。 そこで現在、週次のエントロピースキャンを GitHub Actions で定期実行する仕組みの導入を検討しています。具体的には、次のようなチェックを計画しています。 パターン鮮度チェック: 各パターンファイルの最終レビュー日を90日の閾値で確認する依存関係ドリフトの検出: npm audit、knip、dependency-cruiserを PR 時以外にも定期実行する違反検出時の自動起票: 問題をGitHub Issueに起票し、対応漏れを防ぐ また、このフレームワークがどう変化してきたかは、Architecure Decision Record（ADR）として残しています。エスカレーションラダーを導入した理由、L3ツール群の選定基準、どのルールをどのタイミングで昇格させたのか。そうした判断の背景まで残しておくことで、運用が属人化しにくくなります。 仕組みを続けるうえで大事なのは、「良いルールを作ること」だけではありません。そのルールが今も有効かを見直し続けることだと考えています。 まとめ AI 駆動開発で品質を担保するうえで大切なのは、AI を過度に信用することでも、逆に必要以上に疑うことでもありません。AIが守るべき制約を人間側が設計し、その制約を段階的に執行できるようにすることです。今回紹介したハーネスエンジニアリングの要点は、次の3つに整理できます。 1. ルールは段階的に強くする 最初はドキュメントとして言語化し、必要に応じてAIレビュー、CI、構造テストへと昇格させる。こうすることで、運用コストと実効性のバランスを取りながら、ルールを育てていけます。 2. 定量化しにくい品質も扱う Taste Invariants──リンターや構造テストでは検出しづらいが、UXや設計意図に直結する品質基準を、AIが検知・遵守できる形で明文化した不変条件──のような基準を言語化して共有しておくことで、機械的な検証だけでは拾いにくい品質も扱えるようになります。使いやすさやわかりやすさのような価値は、こうした層で効いてきます。 3. ルールそのものも保守対象にする 週次スキャンやArchitecure Decision Record（ADR）を通じて、ルールの鮮度と判断の背景を継続的に管理する。これをやらないと、どんなに立派な仕組みも、時間とともに形だけのものになってしまいます。 今後は、Claude Code Review CIで検出された違反ラベルを集計し、昇格候補のルールを自動で見つける仕組みや、エントロピースキャンで見つかった問題を自動修正につなげるワークフローも整えていく予定です。 AIコーディングエージェントは、これからさらに進化していくはずです。だからこそ、それを支える“手綱”の側も、固定されたルールとして置いておくのではなく、実際に使いながら育てていく必要と考えています。 ConoHa VPS MCPサーバー はこちらからご利用できます。 ConoHa VPS MCPは、ConoHa VPSの公開APIを日本語で簡単に操作できるオープンソースのModel Context Protocol (MCP) サーバーです。Claude Code、GitHub Copilot、ClineなどのAIエージェントと連携することで、自然言語によるVPS・オブジェクトストレージの操作が可能になります。ぜひ使ってみてください! また、ハーネスエンジニアリングについての弊社の取り組みについて、インタビュー記事も公開されました。よかったら合わせてご覧いただけますと幸いです。