Post
JA EN

【提案】多段階ハーネスエンジニアリング — 3層モデルとデータ層中心の投資戦略

Posted
By
76 min read
【提案】多段階ハーネスエンジニアリング — 3層モデルとデータ層中心の投資戦略
  • 想定読者： ITエンジニア、EM、AI活用リード、組織横断でエージェント基盤を整備するプラットフォーム担当
  • 前提知識： Claude Code / Codex / Cursor 等のコーディングエージェントを業務で使った経験
  • 所要時間： 約15分

本記事の位置づけ: 本記事は 筆者の実装経験に基づく報告ではなく、公開ソースを基にした設計提案 である。OpenAI 等の公開事例と国内外の関連研究を踏まえ、AIエージェントを組織で運用する際のハーネス設計フレームワークを提示する。提案であるため、最後にメリット・デメリット・反証ケースを多角的に検証し、採用条件を明示する。

概要

AIエージェントを本格導入した組織では、最初は CLAUDE.md に規約を1ファイル書くだけで十分機能する。プロジェクトが3つ・5つと増え、メンバーが10人を超えたあたりから、プロジェクトごとにハーネス（エージェントを統御する仕組み一式）が独自進化し、一貫性が崩れ、共有資産が育たず、ガバナンスが効かない症状が現れる。

OpenAIが2026年に公開した社内事例1では、5か月・約100万行・約1,500 PR の開発を手動コード0行で完了している。Codex の賢さではなく、中央集権的なハーネス設計——金科玉条（golden principles）、カスタムlinter、固定アーキテクチャ、observability——が機能した結果だ。

本記事では、この問題への 設計提案 として 「多段階ハーネスエンジニアリング」 を提示する。提案は3つの主張からなる。

  1. 構造の提案: ハーネスを 組織ハーネス（RAG＋ガバナンス）／共用ハーネス（プラットフォーム提供）／プロジェクトハーネス（ドメイン特化） の3層に分離する
  2. 投資戦略の提案: 3層を均等に作らない。データ層（RAG）と外部ツール組織規約に厚く投資し、汎用ワークフローのスクラッチ実装は薄く保つ
  3. 実装パターンの提案: 外部ツール規約は CLI（mycorp-pr 等）として実装してハード強制する。AI による CLI 開発の高速化により、このハードルは下がり続けている

ただしこの提案は 無条件には推奨できない。プラットフォームエンジニアリングは「ゴールデンケージ」「ボトルネック化」のアンチパターンが知られ2、エンタープライズRAG も業界報告で70%以上が本番到達に失敗するとされる3。AIエージェント自体も組織レベルでは生産性パラドックス（92.6%採用×組織生産性10%）に直面している4。

本記事の構成: §1 でハーネス問題と単段階運用が破綻する仕組みを整理し、§2 で3層モデルの構造を、§3 で本記事の核となる投資戦略を、§4 で実装プレイブック、§5 で多角的評価、§6 で限界を扱う。

1. ハーネス問題 — 単段階運用がなぜ組織で破綻するか

「ハーネス」という語が広まったのは、2026年初頭の OpenAI と Martin Fowler の発信が起点だ15。直訳すれば「馬具」だが、ここでは コーディングエージェントの出力方向を制御し、自己修正させるための仕組みの総称 を指す。

Fowler は次のように整理している5。コーディングエージェントには既にシステムプロンプトやコード検索機構など「内蔵ハーネス」が組まれている。その上にユーザーが構築するのが outer harness（外側ハーネス） で、これには2つの目的がある。

  1. エージェントが最初から正しく書ける確率を上げる（プロンプト、ルール、コンテキスト供給）
  2. 本番到達前に問題を自己修正させるフィードバックループを回す（linter、テスト、検証エージェント）

国内では nogataka 氏が、ハーネスを 「CLAUDE.md → AGENTS.md/rules → ハーネスエンジニアリング」 の3段階進化として位置づけている6。第3段階のハーネスエンジニアリングが実行・検証・記憶を統合して初めて、違反を構造的に検知できるようになる。cvusk 氏は実装面で Explore→Plan→Implement ワークフローや最小ツール設計を提案し、LangChain の事例として モデル本体は変えずハーネスの最適化だけで Terminal Bench 2.0 を30位→5位に押し上げたケースを紹介している7。

ここまでの議論には共通の前提がある。「ハーネスは1プロジェクト単位で語られている」 ことだ。これが組織スケールで3つの破綻パターンを生む。

パターン1: 知識のサイロ化 — プロジェクトごとに「うちのドメインではこう書く」が暗黙知化し、隣のプロジェクトに伝播しない。エージェントは各リポジトリのコンテキストしか見ないため、組織全体の知見にアクセスできない。

パターン2: 共有資産の不在 — スキル、フック、テンプレート、検証 linter が各プロジェクトに散らばる。プラットフォームエンジニアリングの2026年トレンド調査8では、73% のプラットフォームチームが既に AI アシスタントを統合しているが、組織コンテキストの配布機構がなければ各チームが車輪の再発明を続ける。

パターン3: ガバナンス不能 — セキュリティ・コンプライアンス・倫理は本来「組織として守らせる」べきだが、CLAUDE.md ベースでは強制力がない。Gartner は2026年にエンタープライズ生成AIプロジェクトの70%以上が幻覚とコンプライアンスリスクの軽減のため構造化検索パイプライン（RAG）を必要とすると予測9。

OpenAI 事例1を逆方向から読むと、これらの破綻を回避する設計が見える。彼らは 全エージェント実行に共通する制約として中央集権的にハーネスを整備した。バックグラウンド Codex タスクが定期的に逸脱を検知し、リファクタリング PR を自動で起こす仕組みになっている。

2. 提案の構造 — 3層モデル

ハーネスを2層に分ける（組織 vs プロジェクト）と、現実の組織では中間に必ず共用層が滲み出る。バックエンドチーム共通、技術スタック共通、セキュリティチームのレビュースキル群——全社共通とまでは言えないが、特定プロジェクトに閉じてもいない。本記事は 3層 を提案する。

flowchart TB
    subgraph ORG["🏢 組織ハーネス — 知識供給とガバナンス"]
        direction TB
        ORG1["RAG基盤<br>社内ドキュメント・ADR・障害履歴"]
        ORG2["最小アクセススキル<br>RAG検索・引用・出典提示"]
        ORG3["Mustレベルlinter<br>セキュリティ・コンプライアンス"]
    end

    subgraph SHARED["🛠 共用ハーネス — プラットフォーム提供"]
        direction TB
        SH1["汎用ワークフロー<br>EPI・レビュー・PR作成"]
        SH2["外部ツール組織規約CLI<br>mycorp-pr・mycorp-deploy"]
        SH3["技術スタック共通<br>テンプレート・フック・CI"]
    end

    subgraph PRJ["📦 プロジェクトハーネス — 設定値とドメイン特化"]
        direction TB
        PRJ1["ドメインルール<br>ビジネスロジック制約"]
        PRJ2["ワークフロー設定値<br>探索パス・検証コマンド"]
        PRJ3["メモリ管理<br>progress.md など"]
    end

    PRJ ==>|必須参照| ORG
    PRJ -->|選択的import| SHARED
    PRJ -.->|昇格PR| SHARED
    SHARED -.->|昇格PR| ORG

2-1. 組織ハーネス（最外層）— 知識供給とガバナンス

組織ハーネスは 「組織知識の供給機構」と「組織規範の強制機構」 の2機能で構成する。

RAG 基盤: 2026年の RAG はもはや「ドキュメント検索」ではなく、検索・検証・推論・アクセス制御・監査ログを統合する knowledge runtime として位置づけられている10。エージェント自身が推論ループの一部として RAG を呼び出す agentic RAG が支配的パターンとされる10。社内 ADR、障害ポストモーテム、設計ドキュメント、API カタログを横断検索する基盤となる。アクセス制御と監査ログの統合により、コンプライアンス要件にも応える。

Must レベル linter: セキュリティ・コンプライアンス・倫理など「全社で破ってはいけない」項目だけを置く。OpenAI 事例1の custom lint は エラーメッセージにエージェント向けの修正手順を注入する 設計で、自己修正ループを構造化している。組織ハーネスの linter は エージェント向けに書く。

組織ハーネス側の スキルは最小に保つ——RAG 検索、引用付き出典提示、機密検出、その程度でよい。リッチなドメインロジックは下層に押し出す。

2-2. 共用ハーネス（中間層）— プラットフォーム提供

中間層は プラットフォームエンジニアリングの領域 だ。Team Topologies の枠組みでは、プラットフォームチームが「ストリームアラインドチーム」に対して低認知負荷のセルフサービスを提供する。AI エージェント時代では、「使えるスキル・テンプレート・golden paths を中央で整備し、各プロジェクトが install して使う」 形になる。

QCon London 2026 の議論では、AI 時代のチーム設計原則として 「bounded agency（境界付き裁量）」 が提示された11——エージェントの行動権限を、ルールとガードレールで意図的に制約する。共用ハーネスはこれを実装する層だ。

Claude Code はこの中間層を OS レベルでサポートする。Skills はパーソナル / プロジェクトに加えて 組織ワークスペース全体に展開できる Organization-level skills を 2025年12月18日にリリース12。マーケットプレイス（marketplace.json を git でホスト）13、SKILL.md のクロスプラットフォーム標準化（30以上のエージェントで動作）14——共用ハーネスへの投資はベンダーロックインを起こさず、組織資産として蓄積できる。

中間層に置くべきものは「複数プロジェクトで再利用可能で、組織全体で強制するほどではない」もの:

  • 汎用ワークフロー: Explore→Plan→Implement、コードレビュー、ADR起票、PR作成、デプロイ
  • 外部ツール組織規約 CLI: GitHub/Slack/Jira の自社利用規約をハード強制する CLI（後述 §3-3）
  • 技術スタック共通: API 雛形、命名規約、テスト戦略、共通フック・CI

中間層は1社にひとつではなく、バックエンド共用 / フロントエンド共用 / セキュリティチーム共用 のように複数並立しうる。研究面では「Learning to Share」論文15が、並列エージェント間で「全部共有」でも「全部分離」でもない選別的共有が効率的と示しており、共用層の設計指針と一致する。

2-3. プロジェクトハーネス（最内層）— 設定値とドメイン特化

最内層は ドメイン特化の知識と、共用ワークフローを動かすための設定値 だけを置く。

  • ドメインルール: ビジネスロジックの不変条件、業界規制への対応
  • ワークフロー設定値: 探索パス、計画テンプレートの内容、検証コマンド（ワークフロー本体は共用層から継承）
  • メモリ管理: progress.md、スクラッチパッド、セッション間記憶

最内層は薄くなるはず という感覚を持つとよい。多くのものは中間層・最外層に押し出せる。プロジェクトハーネスが分厚いと感じたら、それは中間層が貧弱な兆候だ。

2-4. 層の関係性 — 継承ではなく合成

3層モデルを「Project → Shared → Org」の単一継承チェーンとして描くと、現実とずれる。実際には プロジェクトハーネスが組織ハーネスと共用ハーネスを並行して利用する 合成モデル（composition）になる。

  • 組織ハーネス → 全プロジェクトに貫通（必須）: RAG 基盤と Must レベル linter は、共用層を経由せず全プロジェクトが直接従う。社内 RAG への問い合わせも各プロジェクトから直接行く。
  • 共用ハーネス → 選択的に import（任意）: バックエンド共通スキル群を「使えるなら使う」位置づけ。プロジェクト性質に合わなければ参照しない選択もある。
  • 昇格 PR は両方向: プロジェクトで生まれた汎用スキルは共用層へ、共用層で安定した規約は組織層へ昇格する。

組織ハーネスは “infrastructure”（インフラ）、共用ハーネスは “platform service”（プラットフォームサービス） と捉えると整理しやすい。インフラは選べないが、プラットフォームサービスは選べる。

3. 投資戦略 — どこに厚く賭けるか

ここが本記事の核だ。3層を均等にスクラッチ実装すると、構築が終わる頃には共用層・プロジェクト層の自前実装がプラットフォーム機能に追い抜かれている、という事態が起きる。「どの層に厚く投資し、どの層は薄く保つか」を最初に決めておく必要がある。

3-1. 層別の長寿性評価

層ごとに「自前実装の長寿性」を評価すると、判断軸が見えてくる。

層・要素自前実装の長寿性理由
組織RAG＋データ高い組織固有データはベンダーが吸収できない資産。アクセス制御・PII処理・規制対応も外圧として残る。
外部ツール組織規約（GitHub/Slack/Jira の自社利用ルール）高い「うちは squash merge」「PR は CODEOWNERS から2人承認」など、ベンダーは知らない。基礎概念（PR/Issue/チャンネル）も10年単位で安定。
ドメインルール（ビジネスロジック・業界規制）高いベンダーが代替しない。
Must lint（セキュリティ・コンプライアンス）中程度エージェント側のセキュリティ機能で部分吸収。組織固有部分は残る。
自社特化テンプレート中〜高自社命名規約・自社スタックに特化した部分は残る。
プロジェクト固有設定（探索パス・検証コマンド）中程度プロジェクト固有設定の部分は残る。
汎用ワークフロー（EPI・レビュー・PR作成）低いAnthropic 公式マーケットプレイス等でスキル流通が急速整備中12。1〜2年で「install して使う」が標準化する見込み。
外部ツール API ラッパー（GitHub API 直叩き等）低い公式統合に置き換わる。Claude Code には既に GitHub 連携あり13。

戦略は明確だ。「高」の3項目（データ、外部ツール組織規約、ドメインルール）に厚く投資し、「低」の2項目（汎用ワークフロー、API ラッパー）は薄く保つ。

3-2. データ層（RAG）— 二重 ROI で投資を正当化する

データ層は最も長寿な投資先だが、エージェント単独で投資正当化するのは難しい——AIエージェントの組織レベル生産性向上は10%程度に留まる4。ここで強調しておきたいのは、本記事の3層モデルがこの10%ギャップを自動的に埋めると主張しているわけではない点だ。むしろ §5-2 で論じるように、投資判断の前に自組織の生産性ギャップを計測すべきである。本節はあくまで「3層モデルを採用する場合、データ層が最も投資効率の高い起点になる」という条件付き提案だ。

しかし同じ RAG 基盤は、人間にも直接価値を届ける。

  • 社内ナレッジ検索エンジン: 既存 wiki / 検索を置き換える「会話できる検索」。新人オンボーディング、過去の障害事例調査、設計判断の参照などで日常使われる。
  • 学習用の壁打ち相手: 「このアーキテクチャ判断の背景を教えて」「過去の類似実装を要約して」など、ジュニアエンジニアの学習加速ツール。
  • 意思決定の相談相手: 設計に迷ったとき、社内 ADR と障害履歴を踏まえた相談ができる。

ヒューマンインターフェースを最初から組み込む設計にすれば、組織RAG層への投資はエージェント基盤としてだけでなくナレッジマネジメント基盤として独立した ROI を持つ。逆に「エージェントのため専用」と位置づけると、AIエージェントの成果が出るまで誰も価値を実感できず、プラットフォームチームへの予算がすぐ削られる。Microsoft の戦略16も検索ベースから「ガバナンスされたエージェントワークフロー」へのシフトとして同じ方向を示している。

実装の3つの柱:

  1. データインジェスト基盤に最初の予算を集中: ADR、ポストモーテム、設計ドキュメント、API カタログ、Slack/メールアーカイブの継続取り込みパイプラインを最優先で構築。陳腐化しない投資だ。
  2. アクセス制御と監査ログを最初から組み込む: EU AI Act 等の規制要件は強まる方向にある3。後付けすると高くつく。
  3. 検索 UI / Slack ボット / CLI を並走: エージェントの成果が出る前から ROI を立てる。

3-3. 外部ツール組織規約 — CLI でハード強制する

GitHub、Slack、Jira などの外部ツール利用ルールを「スキルファイルに書く」だけでは弱い。スキルはエージェントが解釈する「お願い」であり、無視されうる。代わりに 組織規約を CLI ツールとして実装する——mycorp-pr create、mycorp-deploy、mycorp-incident open のような自社 CLI が、ラベル付与、CODEOWNERS チェック、デプロイ前承認、インシデントチャンネル作成などをハード強制する。

CLI 実装の4つの利点:

  • エージェント間で再利用可能: Claude Code でも Codex でも Cursor でも同じ CLI を呼べる。スキル形式の標準化を待たずに、いま動く抽象として使える。
  • ハード強制ができる: 「ラベルなしの PR 作成」を CLI レベルで拒否できる。スキルは説得が必要だが、CLI は通さなければ通らない。
  • 人間も同じツールを使える: §3-2 の RAG と同じ二重 ROI 構造。手元で mycorp-pr create を叩いても同じガードレールが効く。CLI は人間にもエージェントにも自然なインターフェースだ。
  • 観測可能: exit code、構造化ログ、JSON 出力で監査基盤に直結できる。

スキルとの役割分担: スキルは「いつ・なぜ CLI を呼ぶか」をエージェントに教え、CLI は「組織規約を機械的に強制する」。スキルファイルは数行で済み、CLI が分厚いロジックを担う。スキルが軽いほど、ベンダー公式スキルへの移行コストも軽くなる。

「CLI を作るのは重い投資」という従来の反論は、AI 時代には弱まる。Claude Code / Codex で雛形を生成し、組織規約に合わせて調整するアプローチが取れるため、ゼロから書くよりも初版到達は短期化される。維持コストも、汎用 GitHub API ラッパーをスキル形式で書き続ける手間と大差ない。「ハード強制できる」「人間も使える」「複数エージェント間で再利用できる」という長寿メリットを考えれば、ROI 評価は従来より有利になる。

なお「ハード強制」の実効性は、CLI 経由でない外部ツール直叩きを CI / 監査基盤側で禁止する仕組み（例: GitHub Actions で mycorp-pr 経由でない PR をブロック）と組み合わせて初めて成立する。CLI を用意するだけでは抜け道が残る。

これは Spotify の Honk システム7 が「ツールを3つに絞る」ことで強い制御を実現したのと同じ系統の発想だ。インターフェースを CLI という安定した抽象に固定すれば、その下の実装は自由に変えられる。

3-4. 汎用ワークフローは「公式置き換え」前提で薄く設計

EPI、コードレビュー、ADR起票、PR作成といった汎用ワークフローを共用層に置く際は、「将来 Anthropic 公式スキル / OpenAI 公式 / Cursor 公式に置き換える」前提で設計する。

  • 自社特化部分（命名規約、社内テンプレート、組織知識との接続）と汎用部分（モード遷移、計画ドキュメント構造）を明確に分離する
  • 公式スキルが出たら、汎用部分を捨てて自社特化部分だけ残すマイグレーション計画を最初から持つ
  • 「いま使えるから自前で書く」ではなく「次の四半期で公式置き換えを再評価する暫定実装」と割り切る（公式スキル整備のスピード感1214を踏まえた目安）

この切り分けの実例を §4-2 で EPI ワークフローを使って具体化する。

3-5. 「自前で頑張る境界線」のまとめ

自前で投資すべき（長寿）公式・OSS に任せる（吸収される）
組織固有データのインジェストとアクセス制御LLMモデル本体、エージェントランタイム
外部ツール組織規約の CLI 化（mycorp-pr 等）外部ツール API の汎用ラッパー（公式 GitHub 連携等）
自社命名規約・自社アーキテクチャ規約の linter言語別の標準 linter（ESLint、Ruff など）
ドメイン特化スキル汎用ワークフロー（EPI、レビュー、PR作成）
規制対応（業界固有のコンプライアンス）クロスプラットフォーム標準（SKILL.md、AGENTS.md）

この切り分けを最初に決めておけば、「3層を全部スクラッチで作る」という最も投資効率の悪いパターンを回避できる。

4. 実装プレイブック

4-1. 漸進的整備順序 — プロジェクト → 共用 → 組織

3層を一気に作ろうとすると失敗する。痛みが出ている層から1段階ずつ整備するのが原則だ。

Step A: プロジェクトハーネスを成熟させる

CLAUDE.md を整備し、cvusk 氏のガイド7に沿って Explore→Plan→Implement を試す。progress.md でセッション間記憶を確保する（nogataka 氏の指摘6への対処）。組織RAG・共用層がまだ無くても、プロジェクト単位の outer harness は機能する。

Step B: 重複が出てきたら共用ハーネスを立ち上げる

別プロジェクトで同じスキル・同じ規約をコピペし始めたら、共用層を作る合図。具体的には:

  1. 社内向け marketplace.json リポジトリを作る13
  2. 最初に整備すべきは EPI、コードレビュー、ADR起票、PR作成、デプロイ などの汎用ワークフロー（§4-2 参照）
  3. 並行して 外部ツール組織規約 CLI（mycorp-pr 等）を AI で初版生成（§3-3 参照）
  4. チーム別 / スタック別の共用層を許容（バックエンド共用 / フロントエンド共用 / データチーム共用）。Team Topologies の bounded agency 原則11とも整合する
  5. 昇格 PR フローを整備する。「3プロジェクト以上で参照されたら共用層への昇格を提案」程度のヒューリスティクスでよい。JP Morgan の「friendly FOMO」事例11——強制ではなく共有された成功による自然な拡散——の方が大企業では機能しやすい

Step C: コンプライアンス要件が顕在化したら組織ハーネス

組織が10〜30人を超え、セキュリティ・コンプライアンスのリスクが顕在化したら組織層に着手する:

  1. RAG 基盤を knowledge runtime として設計10: 社内 ADR、ポストモーテム、設計ドキュメント、API カタログをインジェスト。アクセス制御と監査ログを最初から統合
  2. Must レベル linter を組織側で運用: セキュリティ・コンプライアンス・倫理の3カテゴリに絞る。エラーメッセージはエージェント向け1
  3. 監査基盤: 実行ログ、RAG アクセスログ、linter 違反ログを集約

OpenAI の事例1も最初から完成形ではなく、golden principles は「定期スキャン → 違反検知 → 自動 PR」のサイクルで漸進的に磨かれた。

4-2. 具体例 — Explore→Plan→Implement ワークフローの層分け

抽象的な層モデルだけでは「自組織で実際にどう割るか」のイメージが掴みにくい。EPI ワークフロー7を例に、層分けを具体的に確かめる。

EPI は次の3段階からなる: Explore（コードベース理解）→ Plan（計画作成・編集可能）→ Implement（実装・テスト・検証）。一見プロジェクト固有に見えるが、スキル本体は技術スタックにもドメインにも依存しない汎用パターンであり、Spotify のバックエンドでも医療系SaaSのフロントエンドでも同じ骨格で動く。プロジェクトごとに違うのは「設定値」だけだ。

構成要素配置層内容
モード遷移ロジック（Explore→Plan→Implement）共用層エージェントの状態管理、各モードの許可ツール
計画ドキュメントの構造（章立て）共用層「概要 / 影響範囲 / 実装手順 / 検証方法」テンプレート
実装後検証フックの呼び出し方共用層検証コマンド実行、結果のエージェント再注入
探索パス（どのディレクトリから読むか）プロジェクト層src/ か app/ か packages/foo/ か
計画テンプレートの内容プロジェクト層ドメイン固有の確認項目（PII処理、課金フロー等）
検証コマンドプロジェクト層npm test か pytest か go test ./... か
探索時に参照する組織知識組織層（RAG経由）過去の ADR、類似実装の障害履歴、設計原則

この分解から導かれる 層の引き方の原則:

「何を」（ワークフロー本体）は共用層に置き、「このプロジェクトでは具体的にどうやるか」（設定値）だけをプロジェクト層に残す。

同じ論理がコードレビュー、ADR起票、PR 作成など 「ワークフロー型のスキル」全般に当てはまる。EPI のような汎用ワークフローがプロジェクトハーネスに重複している組織は、共用層への昇格 PR を最初の改善ターゲットにするとよい。

ただし §3-4 で述べたように、これらの汎用ワークフローは公式スキルに置き換わる前提で 「3か月持てばよい暫定実装」 として薄く設計する。

4-3. 運用 — ハーネス自体をエージェントで進化させる

3層を作っただけでは陳腐化する。日常運用で機能させるには ハーネスのメンテナンス自体をエージェントワークに組み込む。

  • 週次レビュー: 各層の更新 PR を1件は作成。エージェントに「直近1週間の違反傾向」を集計させ、ルール追加・削除・緩和の提案を生成させる
  • 昇格・降格の判断: 四半期に一度棚卸し。「3プロジェクト以上で参照される共用スキル」「半年以上違反が出ない組織linter」などのトリガー
  • observability ダッシュボード: スキル呼び出し回数、頻発する違反、RAG クエリパターンを可視化

設計→運用→改善の PDCA をエージェントが半自動で回す状態に持ち込めれば、ハーネスは「育つ資産」になる。

5. 多角的評価

5-1. 期待されるメリット（公開エビデンス）

  • オンボーディング短縮: ゴールデンパスの成功指標として オンボーディング時間の短縮、デプロイ頻度の向上、開発者満足度の改善が挙げられている17
  • 再利用性: Anthropic 公式マーケットプレイスを含めて 多数のスキルが配布されており12、SKILL.md は Claude Code・Cursor・Codex・Copilot 等のプラットフォームで動作する14——スキル層に関してはベンダーロックインが弱い（RAG基盤や組織CLIは依然個別実装が必要）
  • ガバナンス: RAG の knowledge runtime10、Microsoft の governed agent workflow 戦略16、EU AI Act 等のコンプライアンス要件への対応3
  • プラットフォームエンジニアリングの実効性: Gartner は 2026年までに大規模ソフトウェア組織の80%がプラットフォームエンジニアリングチームを設置すると予測している（2022年の45%から拡大）2。ゴールデンパスの実装ガイドでは、強制ではなく自然採用が成功条件とされている17

5-2. リスク・反証エビデンス

プラットフォームチームのボトルネック化: 「チケットベースワークフロー化」「テンプレート過剰依存」「Golden Cage」が代表的失敗218。中央チームが手動対応に追われると、プラットフォーム自体が新しいボトルネックになる。

「Them vs Us」と組織分断: 中央プラットフォームと「フィーチャーファクトリー」の対立構造が生まれやすい2。これは技術ではなく組織文化の問題。

RAG運用の本番到達率は厳しい: エンタープライズRAG実装の 70%以上が本番到達に失敗するとの業界報告がある3。原因はリトリーバルアルゴリズムではなく ガバナンス——文書のオーナーシップ不在、クエリ時アクセス制御の欠如、PII処理の未実装、鮮度管理の欠如である3。

ハルシネーションは RAG でも消えない: Stanford HAI の研究では、法務AIで複雑な法務クエリの 58〜82%でハルシネーションが発生したと報告されている19。生成系AIの引用捏造もRAGコミュニティで観測されており、ある業界調査では法務ユースケースで 引用捏造率81% が報告されている20。BadRAG21・TrojanRAG22 のような 毒入り文書による攻撃も学術的に提示されている。組織RAGは「信頼できる中央ソース」のブランドが付くため、むしろ出力の検証バーが下がる心理的副作用を持つ可能性がある。

Agent Sprawl とマーケットプレイス断片化: Gartner は 2026年末までに企業アプリケーションの40%がタスク特化型AIエージェントを搭載すると予測（2025年の5%未満から急増）23。「100社のベンダーから100エージェント」ではなく「適切に統治されたスーパーエージェントを少数」が原則とされる24。共用ハーネスのマーケットプレイスを開放しすぎると重複・浪費・セキュリティギャップが生まれる。

組織レベルの生産性パラドックス: ここが最も重い反証だ。92.6%の開発者が AI を利用しているが、組織レベルの生産性向上は10%程度4。METR 研究では開発者が「AI で20%速くなった」と感じた時に 実測19%遅くなっていた25。ハーネスを精緻化しても、組織レベル生産性は自動的に上がらない。投資判断の前に 「自組織の AI productivity ギャップはどこか」を計測するステップが先になる。

中央集権 vs 分散: 中央集権は「一貫性・コンプライアンス・効率性」、分散は「速度・関連性・創造性」を提供26。両者にトレードオフがあり、近年の合意はフェデレーテッド型（中央が倫理・安全ルールを強制し、現場が実行裁量を持つハイブリッド）が現実解26。本記事の3層モデルもフェデレーテッド型の一実装と見なせるが、「組織層と現場層の権限比率は組織によって大きく異なる」点は強調しておきたい。

5-3. 採用条件と撤退ライン

組織規模推奨スタンス採用判断のシグナル
個人〜2人、1プロジェクトプロジェクトハーネスのみ。CLAUDE.md 1枚で十分。「他プロジェクトと知識を共有する痛み」がない
3〜10人、1〜2プロジェクトプロジェクトハーネスを成熟させる時期。同じスキルを別リポジトリにコピペしている
10〜30人、3プロジェクト以上共用ハーネス層を立ち上げる。組織層は Must lint の最小版から。セキュリティ違反・コンプライアンスリスクが顕在化
30〜100人、複数チーム3層構成の本領発揮。プラットフォームチームを立てる。組織RAGも導入。知識サイロが採用・離職の論点になっている
100人以上組織RAG基盤の専任体制と中間層の継続運用が不可欠。規制対応（EU AI Act 等）が経営課題

撤退すべきシグナル:

  • プラットフォームチームがチケット処理に追われている → ボトルネック化
  • 任意採用率が50%を割っている → ハーネス自体が問題（Golden Cage化）
  • 組織RAG導入後にハルシネーションが減らない → ガバナンス層の運用未整備
  • 中央チームと現場チームに敵対関係 → 技術ではなく組織文化の問題
  • 開発者調査で AI 生産性向上の実感がない → 3層モデル投資より先に計測すべき問題

ハーネス設計はインフラではなく継続投資である。「とりあえず3層作る」は失敗パターンであり、自組織で痛みが出ている層から1段階ずつ整備する漸進アプローチが原則だ。

6. 限界と注意

  • 筆者は本フレームワークを大規模組織で実装した経験を持たない: OpenAI 等の公開事例と関連研究を参照した設計提案であり、ケーススタディではない
  • 3層という分割は議論のための単純化: 実組織ではバックエンド共用層・フロントエンド共用層・セキュリティチーム共用層など、中間層が複数並立しうる。その分割設計自体が組織政治である
  • 数値根拠の混在: 引用したエビデンスには査読論文（METR等）、公式調査、業界メディア記事が混在する。各引用の信頼性レベルは参考資料セクションで明示
  • 政治的・文化的要因はハーネスでは解決しない: 心理的安全性が低くて「ルールに異議を唱えられない」状態なら、ガバナンス強化は窒息に転化する
  • 本記事は2026年5月時点の知見: コーディングエージェントの内蔵ハーネスは急速に進化している。1年後には「組織ハーネスとして自前で組む必要があった項目の半分」がエージェント側に取り込まれている可能性が高い。半年単位で見直す前提で参照してほしい

まとめ

本記事は 多段階ハーネスエンジニアリングの設計提案 である。3つの主張の構造は次の通り。

提案内容反証・リスク
構造組織ハーネス（RAG＋ガバナンス）／共用ハーネス（プラットフォーム提供）／プロジェクトハーネス（ドメイン特化）の3層に分離中央チームのボトルネック化2／組織分断
投資戦略データ層・外部ツール組織規約・ドメインルールに厚く投資、汎用ワークフロー・API ラッパーは薄く保つRAG実装の70%以上が本番到達失敗3、組織レベル生産性10%パラドックス4
実装パターン外部ツール規約は CLI（mycorp-pr 等）でハード強制。AI による CLI 開発高速化で参入障壁は低下スキル/CLI/フックの境界線設計を間違えると保守地獄

中核メッセージを1行で言うと:

3層に分けたうえで、ベンダーが吸収できないもの（組織データ、組織規約、ドメインルール）に厚く賭け、吸収されるもの（汎用ワークフロー、API ラッパー）は薄く保つ。

採用すべきかどうかは組織規模に依存する。10人・3プロジェクトを超えたら検討、30人・複数チームで3層構成の本領発揮、100人で専任体制が不可欠。だが「とりあえず3層作る」は失敗パターンであり、痛みが出ている層から漸進的に整備する判断が必要だ。

今日試せる1アクション: 自プロジェクトの CLAUDE.md を開き、各項目に Org（全社共通） / Shared（チーム共通） / Project（このプロジェクト固有）のラベルを付ける。同時に、各項目について「この項目を中央で運用するコスト > 各プロジェクトで重複するコスト」になっていないかを問う。30分で境界線と採用判断の両方が見えてくる。

関連記事

参考資料

その他参考資料（本文中で番号引用なし）

  1. Harness engineering: leveraging Codex in an agent-first world - OpenAI (2026). 5か月・約100万行・約1,500 PR を手動コード0行で達成した社内事例。golden principles、custom linter、固定アーキテクチャの設計を詳述。【信頼性: 高】 ↩︎ ↩︎2 ↩︎3 ↩︎4 ↩︎5 ↩︎6

  2. 9 Platform Engineering Anti-Patterns That Kill Adoption - Jellyfish (2025). チケットベースワークフロー、テンプレート過剰依存、Golden Cage、Them vs Us 問題などのアンチパターンを整理。Gartner 予測「2026年までに大規模ソフトウェア組織の80%がプラットフォームチームを設置（2022年の45%から拡大）」も同記事および Gartner 公式言及で確認可能27。【信頼性: 中】 ↩︎ ↩︎2 ↩︎3 ↩︎4 ↩︎5

  3. 70% of Enterprise RAG Deployments Fail Before Production. Here’s What Kills Them. - Gabriel Anhaia, dev.to (2025). エンタープライズRAGの70%以上が本番到達に失敗するという業界観察と、原因（ガバナンス、文書オーナーシップ、アクセス制御等）を整理。【信頼性: 中】 ↩︎ ↩︎2 ↩︎3 ↩︎4 ↩︎5 ↩︎6

  4. 93% of Developers Use AI. Why Is Productivity Only 10%? - ShiftMag (2026). 92.6%の開発者がAIアシスタント利用、組織レベル生産性向上は10%程度に留まる「AI生産性パラドックス」を報じる。【信頼性: 中】 ↩︎ ↩︎2 ↩︎3 ↩︎4

  5. Harness engineering for coding agent users - Martin Fowler (2026年4月). outer harness の概念と「正答率向上」「自己修正フィードバックループ」の二目的を整理。【信頼性: 高】 ↩︎ ↩︎2

  6. ハーネスエンジニアリング入門 ── CLAUDE.mdの次に来るAIエージェント制御パラダイム - nogataka (2026年3月). CLAUDE.md → AGENTS.md/rules → ハーネスエンジニアリングの3段階進化と各段階の限界を整理。【信頼性: 中】 ↩︎ ↩︎2

  7. AIエージェント - ハーネスエンジニアリング実践ガイド - cvusk (2026年2月). Explore→Plan→Implement ワークフロー、コンテキスト戦略、LangChain の Terminal Bench 2.0 改善事例（30位→5位）、Spotify Honk システムを紹介。【信頼性: 中】 ↩︎ ↩︎2 ↩︎3 ↩︎4

  8. Platform Engineering Trends 2026: 11 Key Shifts - LeanOps (2026). 73% のプラットフォームチームが AI アシスタントを開発者ワークフローに統合済みとの調査結果。【信頼性: 中】 ↩︎

  9. Gartner 予測（複数2次ソース経由）: 2026年に企業生成AIプロジェクトの70%以上が幻覚・コンプライアンスリスク軽減のため構造化検索パイプライン（RAG）を必要とする見込み。【信頼性: 要検証】 ↩︎

  10. The Next Frontier of RAG: How Enterprise Knowledge Systems Will Evolve (2026-2030) - NStarX (2026). RAG を「knowledge runtime」と捉え、検索・検証・推論・アクセス制御・監査を統合する知識オーケストレーション層として位置づけ。agentic RAG の支配的パターンへの移行を解説。【信頼性: 中】 ↩︎ ↩︎2 ↩︎3 ↩︎4

  11. Team Topologies as the ‘Infrastructure for Agency’ with AI - InfoQ / QCon London (2026年3月). bounded agency 原則、JP Morgan の friendly FOMO 事例、知識拡散モデルを紹介。【信頼性: 中〜高】 ↩︎ ↩︎2 ↩︎3

  12. The Complete Guide to Building Skills for Claude - Anthropic (2026). Personal / Project / Organization レベルのスキル管理、Team・Enterprise プランでの組織スキルプロビジョニング機能（2025年12月18日リリース）を解説。【信頼性: 高】 ↩︎ ↩︎2 ↩︎3 ↩︎4

  13. Create and distribute a plugin marketplace - Claude Code Documentation (2026). marketplace.json ベースのプラグイン配布、/plugin marketplace add による参照を解説。【信頼性: 高】 ↩︎ ↩︎2 ↩︎3

  14. AI Agent Configuration Guide 2026: SKILL.md, Rules, and Configs - Agensi (2026). Skills のクロスプラットフォーム標準化（Claude Code / Codex / Cursor / Gemini CLI / Copilot 30+ プラットフォーム対応）を解説。【信頼性: 中】 ↩︎ ↩︎2 ↩︎3

  15. Learning to Share: Selective Memory for Efficient Parallel Agentic Systems - arXiv:2602.05965 (2026年2月). 並列エージェント間の選別的メモリ共有メカニズム。AssistantBench / GAIA で実行時間削減と性能維持を両立。【信頼性: 中〜高】 ↩︎

  16. Enterprise AI Knowledge Management 2026: Microsoft’s Shift from Search to Governed Agent Workflows - Windows News (2026). Microsoft の検索ベースからガバナンスされたエージェントワークフローへの戦略シフトを報じる。【信頼性: 中】 ↩︎ ↩︎2

  17. What are golden paths? A guide to streamlining developer workflows - Platform Engineering (2025). ゴールデンパスの目的、開発者満足度測定の重要性、オンボーディング時間/デプロイ頻度等の成功指標を解説。【信頼性: 中〜高】 ↩︎ ↩︎2

  18. Platform Building Antipatterns: Slow, Low, and Just for Show - Daniel Bryant, Syntasso (2025). プラットフォーム構築の代表的アンチパターン3類型を整理。【信頼性: 中】 ↩︎

  19. Hallucinating Law: Legal Mistakes with Large Language Models are Pervasive - Matthew Dahl et al., Stanford HAI (2024). 法務AIにおけるハルシネーション率の体系的調査。複雑な法務クエリで58〜82%のハルシネーション率を報告。【信頼性: 高】 ↩︎

  20. 7 Enterprise RAG Audit Failures You Should Know - Generation RAG (2026). RAGコミュニティの観察として、法務ユースケースで引用捏造率81%等の数値を引用している業界記事。【信頼性: 中】 ↩︎

  21. BadRAG: Identifying Vulnerabilities in Retrieval Augmented Generation of Large Language Models - Jiaqi Xue et al., arXiv:2406.00083 (2024). RAGデータベースへの毒入り文書注入による検索結果操作攻撃を提案。【信頼性: 高】 ↩︎

  22. TrojanRAG: Retrieval-Augmented Generation Can Be Backdoor Driver in Large Language Models - Pengzhou Cheng et al., arXiv:2405.13401 (2024). RAG経由のバックドア攻撃を提案。攻撃者が知識データベースに悪意あるテキストを注入し、検索とリトリーバの間に隠れたバックドアを作る。【信頼性: 高】 ↩︎

  23. Gartner Predicts 40 Percent of Enterprise Apps Will Feature Task-Specific AI Agents By 2026, Up From Less Than 5 Percent in 2025 - Gartner Press Release (2025年8月26日). タスク特化型AIエージェントが企業アプリの40%に搭載されるとの公式予測。【信頼性: 高】 ↩︎

  24. Agent Sprawl Is the New IT Sprawl, Here’s How to Control It - Dataiku (2026). エージェント重複・GPU資源浪費・セキュリティギャップなどの sprawl 問題と「少数のスーパーエージェントを統治する」原則を整理。【信頼性: 中】 ↩︎

  25. Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity - METR (2025). 経験ある OSS 開発者がAI利用で20%速くなったと感じた一方、実測では19%遅くなっていたという「AI生産性ギャップ」研究。【信頼性: 高】 ↩︎

  26. Centralized vs. Federated vs. Decentralized AI Governance - Sonika Sharma, InfosecTrain (2025). 中央集権・フェデレーテッド・分散の3型ガバナンスを比較。本記事の3層モデルもフェデレーテッド型の一実装と位置づけられる。【信頼性: 中】 ↩︎ ↩︎2

  27. Platform Engineering Empowers Developers to be Better, Faster, Happier - Gartner Experts. Gartner 公式の Platform Engineering トレンド解説。【信頼性: 高】 ↩︎

AI・テクノロジー
AI ハーネスエンジニアリング Claude Code Codex RAG Platform Engineering
This post is licensed under CC BY 4.0 by the author.