ハーネスエンジニアリング

ハーネスエンジニアリング ハーネスエンジニアリングは、AI支援コード生成を決定論的なツール、エージェントベースのレビュー、および定期的なエントロピーチェックで囲む実践であり、AI生成コードが時間とともに正確かつ一貫性を保つようにします。 このドキュメントでは、アイデアがどこから来たのか、何で構成されているのか、そしてこのプラグインがそれをどのように実装しているのかを説明します。 起源 この用語は、Birgitta Boeckeler が martinfowler.com に書いた記事に由来しており、ThoughtWorks の文脈で、チームが AI コーディングアシスタントを使用して実際のソフトウェアを出荷しています。 Boeckeler は、多くのチームが独立して気付いたことを観察しました：AI アシスタントはもっともらしいコードを生成しますが、制約なしに放置すると、それらは漂流します。 それらは慣習を忘れ、間違いを繰り返し、コードベースの内部的な一貫性をゆっくりと侵食します。 コードはコンパイルされ、テストに合格し続けます。 劣化は静かです。 Boeckeler の洞察は、この問題にはソフトウェアエンジニアリングにおいて既に解決済みの類似物があるということでした：テストハーネスです。 テストは、コードを構築によって正確にするわけではありません。 それらは、コードが正確でなくなったときに検出します。 テストハーネスは、あなたが書くコードに対する制約ではありません。 それは、あなたが書いたものが基準を満たしているかどうかを継続的にチェックするメカニズムです。 ハーネスはプログラマーを信頼しません。 それは検証します。 AI支援開発にも同じ論理が適用されますが、重要な違いが1つあります。 テストハーネスは機能的な正確さをチェックします：プログラムは意図したとおりに動作しますか？ AIコーディングのためのハーネスは、より広範なものをチェックする必要があります：コードベースは、チームが合意したアーキテクチャ上の決定、命名規則、セキュリティ制約、および構造規則をまだ具現化していますか？ 機能テストは必要ですが、これだけでは十分ではありません。 別の種類のハーネスが必要です。 それがハーネスエンジニアリングが提供するものです。 3つのコンポーネント Boeckeler は、ハーネスが対処しなければならない懸念の3つのカテゴリを説明しています。 コンテキストエンジニアリング AIコーディングアシスタントは、知っていることの範囲内でしか機能できません。 プロジェクトが特定のロギングライブラリを使用していることを知らない場合、独自の方式を考案します。 変更可能なグローバル状態を絶対に使用しないことを知らない場合、都合の良いときにそれを使用します。 すべてのデータベース書き込みが特定の抽象化レイヤーを経由しなければならないことを知らない場合、そのレイヤーをバイパスします。 コンテキストエンジニアリングは、AIが必要な情報を知っていることを確認する規律です。 実際には、これはHARNESS.md というドキュメント（このプラグインの慣習による）を維持することを意味します。このドキュメントには、スタック、アーキテクチャ上の決定、命名規則、制約、およびそれぞれの理由がキャプチャされています。 このドキュメントは人間向けのREADMEではありません。 それはAIのための知識ベースです。 正確で、具体的で、最新の状態に保たれている必要があります。 この区別は重要です：READMEはプロジェクトが何をするかを説明します。 コンテキストドキュメントは、AIエージェントに何をするべきで、何をしてはいけないか、そしてなぜかを伝えます。 これらは異なるドキュメントであり、異なる読者と異なる更新リズムを持っています。 アーキテクチャ上の制約 ルールを知ることと、ルールを強制することは別の問題です。 すべての制約をHARNESS.md に書き込んでも、AIはそれらを違反する可能性があります。なぜなら、AIは妥当性を最適化する確率的システムであり、ルールに従う機械ではないからです。 コンテキストエンジニアリングは違反を減らします。 それは排除しません。 アーキテクチャ上の制約は、違反を捕捉するメカニズムです。 Boeckeler は、強制ポイントを「検証スロット」と呼んでいます — 開発ワークフロー内の定義された瞬間であり、そこでチェックが実行され、パスするか、進行をブロックします。 各検証スロットの主要な設計上の決定は、決定論的なツールを使用するか、エージェントベースのレビューを使用するかです。 決定論的なツールは、リンター、スクリプト、正規表現チェック、ファイル構造アサーション — 判断なしにパス/フェイル結果を生成するものです。 制約が正確に表現できる場合は、これらが好ましいです。 それらは高速で、安価で、仕様内では完全に信頼できます。 エージェントベースのレビューは、制約の説明に対してコードを調べ、判断を下す言語モデルです。 これは、制約が意図、意味、または機械的なルールとして表現するのが難しいパターンを含む場合に必要です。 エージェントはより高価で、より決定論的ではありませんが、スクリプトでは捕捉できないものを捕捉できます。 どちらのタイプの検証スロットもハーネスに属します。 目標は、時間の経過とともに、制約の理解がそれを正確に指定するのに十分になるにつれて、エージェントベースから決定論的なものへと制約を移行することです。 これは、以下で説明するプログレッシブ硬化原則です。 ガベージコレクション コードベースは生きたシステムです。 良好なコンテキストエンジニアリングと厳格なアーキテクチャ上の制約があっても、エントロピーは蓄積します。 デッドコードが増えます。 TODOコメントが数ヶ月続きます。 依存関係が古くなります。 プロジェクトの初期段階で意味があった抽象化が、後段階で障害になります。 初期に確立された慣習は、都合が悪くなると静かに放棄されます。 ガベージコレクションは、このエントロピーと戦う定期的なプロセスです。 他の2つのコンポーネントとは異なり、これらはコード生成またはレビューの瞬間に操作されます。 GCは特定のコーディングイベントによってトリガーされません。 時間が経過したため実行されます。 ハーネスエンジニアリングフレームワークでは、GCルールは「クリーン」がどのように見えるかの明示的な宣言であり、コードベースがまだこれらの基準を満たしているかどうかをチェックするスケジュールされたエージェントまたはスクリプトとペアになっています。 出力は、PRをブロックするエラーのリストではありません。 それは、問題が深刻になる前に蓄積する問題に注意を引くレポートです。 生きたハーネス 適切に維持されたハーネスの最も重要な特性は、静的ではないことです。 一度書かれて更新されなかったハーネスは、ある時点でのチームの理解を反映しています。 コードベースは進化し続けます。 新しいパターンが出現します。 古い制約は無関係になります。 元の作成者が予期しなかった、AI生成の新しい種類のミスが出現します。 HARNESS.md は自己参照ドキュメントとして設計されています。 それは、どの制約が実施されているかを説明するだけでなく、各制約の状態を追跡します：現在未検証であるか、エージェントレビュー中であるか、または決定論的に強制されているか。 ドキュメントは、真実であるべきことを宣言します。 エージェント、フック、およびCIチェックは、それが真実であるかどうかを検証します。 ハーネス監査人 — このプラグインのスケジュールされたエージェント — は、それらのチェックの結果を読み取り、検証の状態を反映するようにHARNESS.md の状態エントリを更新します。 これによりフィードバックループが作成されます。 ドキュメントは仕様とヘルスレコードの両方です。 任意の時点でHARNESS.md を読むと、チームがコードベースについて真実であると合意したことだけでなく、それらの合意が実際にどの程度維持されているかがわかります。 自己参照プロパティは、ハーネス自体が強制の対象であるため、ドキュメントが古くなり無視されるものと区別するものです — ハーネス監査エージェントは、HARNESS.md が検証の現在の状態を正確に反映しているかどうかをチェックします — ハーネスを無視することは、見えなくなりがちです。 このセルフチェックへの日常的な入り口は /harness-sync です。これは監査の検出ロジックを実行し、統一されたドリフトテーブルを表示します。ユーザーは、宣言されたハーネスと現実との間の不一致を、個別の診断を呼び出すことを覚えていなくても確認できます。 プログレッシブ硬化 すべての制約が同等であるわけではなく、すべての制約が最初から決定論的に強制される準備ができているわけでもありません。 プログレッシブ硬化は、制約が成熟する過程を示す昇進ラダーです。 ラダーは1つの軸です。 リーチ — 制約がすべてのPRで必須であるか、存在する場合に完了するかどうか — は2番目の軸であり、Enforcementフィールドはそれを記録しません。 未検証は開始状態です。 あなたはHARNESS.md で制約を宣言しました。 あなたはそれが重要だと信じています。 あなたはまだそれをチェックするメカニズムを持っていません。 この状態は失敗ではありません。正直な会計です。 未検証の制約は、強制を構築するというコミットメントであり、強制が既に存在するという主張ではありません。