AIのハーネスを徹底的に整えたら、レビューもシステム運用も自動化され、非エンジニアも開発に参加できるようになった話 ── 連載総論

English Version is here

みなさまこんにちは！エアークローゼットでCTOをしている辻です。

これまでに社内MCP群の全体像、DB Graph MCP、Biz Graph、Google Meet録画のデータ化、Sandbox MCP、MCPの退避パターン、そして直近のAgentic Graph RAG MCPのススメと、社内向けの個別アプリ・MCPサーバー・設計原則を順に紹介してきました。

これらは全部、cortexと名付けた社内向けのAI開発プラットフォームの上で動いています。今回は、そのcortexそのものについて書きます。今回から数回に分けて、その仕組みを公開していく予定で、本記事はその初回・総論編です。

連載一覧

#	テーマ	キーシーン	記事
1	総論：cortexのハーネス	PRが無人マージ / 障害が気づく前に治っている	本記事 ←現在地
2	Product Graph (cpg)	コード・ドキュメント・DB・インフラを1グラフに統合	cortex-product-graph
3	AI PRレビュー	webhook → AIレビュー → 自動修正 → squash merge	cortex-auto-review
4	Self-Healing + Observability + 自動lint追加	アラート → AI調査 → 修正PR + 新規lint/型gate → 自動再デプロイで同じ書き方を機械的に弾く	cortex-self-healing
5	改修フェーズの民主化	業務要件を把握している人が本番に直接PR、ハーネスが品質を担保	cortex-non-engineer-prs
6	連載総括	根底にある思想（何を捨てて何を取ったか / なぜこの設計か）を中心に、失敗と学びも振り返る	準備中

いきなり2つのシーンから

シーン1: PRは無人でマージされる

月曜の朝、エンジニアがローカルで機能を実装し、ブランチをプッシュしてPRを出す。

• 数分後、AIレビュアーからREQUEST_CHANGESが付く。指摘は複数:
  • 「同じデータ整形を共有パッケージのformatRow()がすでに実装しているので重複しています。共通化してください」
  • 「APIのレスポンス型を変更していますが、関連するドキュメント（docs/api/...）の記述が古いままです」
• AI対応エージェントがworktreeを切って、修正をコミット、プッシュ
• 再度のレビューでAPPROVE
• 自動でsquash merge
• 変更されたスタックだけがGitHub Actionsで検出され、Cloud Run / Cloudflare Pagesへデプロイ

ここまで人間ノータッチで完了します。エンジニアはPRのタブを更新して、「あ、マージされてる」と気づく。

シーン2: 障害は気づく前に直っている

朝7時、Grafanaのアラートが飛ぶ。「BQパイプラインが3回連続で失敗」。

• AIがwebhookを受け取り、Grafana MCP経由でLokiからエラーログを取得
• Product Graph（実装名: cortex-product-graph。cortexのコード・docs・DBスキーマ・インフラ定義を1つのグラフに統合した知識基盤。本記事の後半とPart 2で詳述）で当該パイプラインのコード・依存テーブル・関連docsを辿り、根本原因を特定
• 修正PRを作ってプッシュ
• AIレビュアーがAPPROVE → 自動squash merge → 自動再デプロイ

9時に出社してSlackを見ると「pipeline直っといたよ」とログが流れている。エンジニアが対応するのはAIがどうしても解けない一部の難しいケースだけになります。

この2つのシーンを支えているのが、これから紹介する開発環境です。

業界文脈 ── 「ハーネスエンジニアリング」の流れ

cortex自体の話に入る前に、業界の文脈を1段落だけ書かせてください。直近半年、AIエージェントを実務で使うための土台づくりが、海外の主要企業からひとつのトレンドとして言語化されてきました。

「ハーネス」自体は新語ではなく、AI領域では2020年にEleutherAIが公開したlm-evaluation-harness（LLMの評価フレームワーク）から使われていた言葉です。それが**LLMエージェント文脈の「ハーネスエンジニアリング」**として、ひとつのエンジニアリング領域に昇格したのが直近半年の出来事:

• 2026年2月: OpenAIが"ハーネス Engineering: leveraging Codex in an agent-first world"を公開。社内の少人数チームがCodexを主導役に5ヶ月で100万行を書いた、という事例
• 数日後、Mitchell Hashimoto（HashiCorp共同創業者 / Terraform作者）がAgent = Model + Harnessという公式に蒸留
• 2026年4月: Martin Fowler（『リファクタリング』著者 / ThoughtWorks Chief Scientist）が"ハーネス Engineering for Coding Agent Users"で**Guides（事前制御）/ Sensors（事後制御）**の分類を確立
• 同4月、Anthropic / Cursorも独自のハーネス記事を公開

業界の合言葉として**"2025 was the year of agents. 2026 is the year of harnesses."**が浸透しつつあります。

要は、モデル単体は急速にコモディティ化している（Claude / GPT / Geminiの差は使う側からは縮まっている）。差がつくのは「AIを本番で動かすための土台＝ハーネスをどう設計するか」だ、という認識です。

cortexは、この「ハーネス」を社内で本気で作ってみた事例として読んでもらえると素直に伝わります。本記事ではFowlerのGuides / Sensorsの枠組みでcortexを整理して紹介します。

ここからは、「モデルよりハーネスで差がつく」という世界線を、cortex上でどう具現化しているかを見ていきます。

誰が開発しているか

cortexの最初の数ヶ月は、自分が100%、1人で開発していました。「ハーネスが整わないと他人がPRを出すのは難しい」というレベルではなく、そもそも誰も乗りこなせない段階だった、というのが正確なところです。

当時すでに、Google Meet録画のデータ化、17 MCPサーバーのうちの半分、それ以外の記事化していない機能まで含めると、全部で50近いアプリケーションが疎結合に動いていました。各機能の目的・背景・データフローはドキュメントに手厚く残していましたが、量が膨大すぎて、仮にAIを使っても関連docsを逐一読ませて理解させるのは現実的ではない状況でした。要は、人にもAIにも一度に把握させきれないコードベースになっていた。

直近、ハーネスが組み上がってきたことで、エンジニアではないメンバー（事業サイドのマネージャー、PMOなど）もcortexにPRを出せるようになってきました。執筆時点での累計コミット比率は約91%が自分、残りの9%が直近の他メンバー寄与です。

非エンジニアが本番リポジトリにPRを出すと聞くと「品質が保てるのか」と思うのが普通ですが、cortexではAIレビューと自動化が品質ゲートを担う設計になっているので、

• 注釈やテストやlintが足りないPRはAIレビュアーにREQUEST_CHANGESを付けられる
• 修正はAI対応エージェントが代行する
• 直らないとマージされない

という流れで、書いた人がエンジニアであろうとなかろうと、マージされる時点では同じ品質基準を満たしている状態が作れます。重要なのは、**「自由にコードが書ける」のではなく「逸脱できないレールの上で書ける」**こと。書く側の責任は「やりたいことを正確に伝える」ところまでで、コードの正しさはハーネスが担保しています。

「その人だから書けた」ではなく「cortexの上だから書ける」── これはハーネスを組み上げたことで初めて成立する性質で、cortex設計の根幹です。

何が動いているか

cortexで動いているアプリ（マイクロサービス・ジョブ・MCPサーバー・Webフロント・Cloudflare Workerなど）は、執筆時点で123個あります。これまでの記事で紹介してきた機能はそれぞれ複数のアプリの組み合わせで成立しているのですが、機能ベースで合算しても**全体の約10%**に留まっていて、残り9割は記事化していない機能です。例えば:

• プロダクトUX計測の集約Web ── UXメトリクス・画面分析・ファネル・エラー分析をひとつにまとめて可視化
• 開発組織のポータルWeb ── KPI（バグ発生率など）/ メンバー別のGitHub Activity / QA評価結果を可視化し、KPIに対する自然言語質問をAgentic RAGで返すAIチャット付き
• 業務支援系のSlack Bot群:
  • 各種ジョブ設定（DB / 勤怠SaaS / Google Driveなど）をSlackから直接管理する設定管理Bot
  • 請求書OCRから会計SaaSの支払依頼・経費精算申請の下書きを自動作成する経理アシストBot
  • チャンネル情報検索・課題管理・要望管理・ミーティング作成を担う社内ナレッジBot、BigQuery横断RAG Bot、Google Drive横断RAG Bot
  • BigQueryのマーケデータからインサイト（トレンド・クリエイティブ分析）を返すマーケBot
• APM自動分析エージェント ── 監視SaaSのAPMデータを毎日分析し、性能問題を自動検出して課題管理SaaSにチケットを作成
• AI Bot監査Bot ── 上記Slack Bot群のコマンド応答を自動E2Eテストして仕様逸脱を検出

など。シリーズの後半で順に各論を書いていく予定です。

規模感:

	数
apps（マイクロサービス・ジョブ・MCP・Web等）	123
packages（共有ライブラリ）	66
MCPサーバー	19
Pulumiスタック	110
TypeScriptコード（実装）	約63万行
テストコード	約56万行
ドキュメント（Markdown）	約11万行 / 389ファイル
期間	約5ヶ月（本格開発は約4ヶ月）
マージ済PR	約790

4要素のフライホイール ── cortexのハーネス

「本格開発4ヶ月でほぼひとり」と「非エンジニアもこの環境に直接コードを足せる」が両立できているのは、全レイヤーで品質をAIと自動化に委譲するハーネス設計をしているからです。

cortexのハーネスは、FowlerのGuides（事前制御）/ Sensors（事後制御）の4つの要素が互いに強化し合うフライホイールとして組まれています。

① Product Graph（Guides ── 正しいコンテキストを供給する）

cortex全体は、コード・ドキュメント・DBスキーマ・インフラ定義が1つのグラフに統合された状態でリアルタイムにインデックスされています。MCP経由でセマンティック検索できる。

「このKPIを計算しているコードはどこ？」「そのコードが触っているBQテーブルは？」「そのテーブルのカラム定義は？」「関連ドキュメントは？」── これらを1つの問い合わせで辿れるグラフが、AIのあらゆる作業の文脈源になります。

これは、AIが**「迷う頻度を構造的に減らす」**ための土台です。grepが「文字列がある場所」しか教えてくれないのに対して、Product Graphは「何が、なぜ、どう繋がっているか」を返す。実装の話は次回（Part 2）で詳しく書きます。

② Lint / Quality Gates（Guides ── 逸脱を物理的に潰す）

eslint-disable / oxlint-disableをリポジトリ全体で禁止。実装コード上の: any / as any / TODO / FIXMEも、自動生成ファイルや外部ライブラリ起因のやむを得ないケースを除いて0件です。**型チェック（tsgo ── TypeScriptのGo移植版コンパイラでtsc比で10倍前後高速。CI時間を抑えるため採用）**も全コード対象にCIで強制しています。

加えて、テストカバレッジはstatements / branches / functions / linesすべて90%以上をCIで強制。閾値を下げてカバーする運用は禁止で、テストを書くしかない。

逃げ道を全部塞いであるので、AIが間違ったコードを書いてもマージされない。AIレビューの判定もこれによって安定します。

③ Autoレビュー（Sensors ── 基準に達するまで自動で直す）

冒頭のシーン1がこれそのものです。仕組み側の補足としては、AIレビューは単なるlintの延長ではなく、Product Graphで影響範囲を辿った上での指摘になっている、というのが効きどころ。例えば実際に飛んでいる指摘を分類すると:

• [Graph] Critical ── 注釈漏れによってグラフのエッジが欠落するパターン
• [Impact] Critical ── BQ MERGE文が既存テーブルに存在しないカラムを参照、本番で失敗するパターン
• [Doc] Critical ── コード変更に関連docsが追従していないパターン
• [Security] Minor ── execSyncで環境変数を文字列展開しコマンドインジェクションが可能になるパターン

「AIレビュー」と聞いて連想されるような表面的なものではなく、コードベース全体を文脈として保ったうえでの指摘が出るのが、Product Graphと組み合わさることの本質です。

エンジニアの介在は「AIレビューが詰まる難しいケース」だけ。普段のPRは、プッシュしてからマージまで触ることなく完結します。

④ Self-Healing（Sensors ── 本番異常を起点へ再投入する）

冒頭のシーン2がこれそのものです。Grafanaアラートを起点にAIがProduct Graph + Loki + git blameで根本原因を特定し、修正PRを ③ のAutoレビューに流して自動マージまでいく。異常を起点に戻して再投入する ── これがSensorsの本質です。詳細は別回で。

フライホイールとして何が起きているか

この4要素は互いに強化し合います。

• ① Product Graphがあるから、③ Autoレビューは影響範囲を踏まえた指摘ができる
• ② Lintがあるから、③ Autoレビューは「全コードが基準を満たしている」前提で動ける
• ③ Autoレビューがあるから、新しいコードが ① Product Graphに正しいセマンティック注釈付きで取り込まれる
• ④ Self-Healingが拾った本番異常も、③ を通すことで品質基準を維持しながら ① に戻る

コードが増えるほど、ハーネスの効きが強くなる構造です。

支える基盤層

この4要素を成立させるための土台として、3つの基盤があります（Part 4で詳しく書きます）:

• テストとカバレッジ: 実装コード約63万行に対してテストコードが約56万行（実装：テスト ≒ 1.13 : 1）
• ドキュメント: 約11万行 / 389ファイル。人間とAIの両方が読む前提で書き、Product GraphのDocumentノードとしても取り込まれる
• Observability: フロント=Faro、バックエンド=OTel、インフラ・CIも含めて全部Grafanaに集約。人間が見るのと同じものを、AIも見ている。Gemini APIのトークン使用量とコストはPrometheusで別途計測

技術基盤

cortexは、フルTypeScriptのモノレポです。

レイヤー	技術
アプリケーション（apps/）	TypeScript（Hono, TanStack Router, Vite, etc.）
共有パッケージ（packages/）	TypeScript
インフラ（infra/）	TypeScript（Pulumiで書く）
エッジ（worker/）	TypeScript（Cloudflare Workers）
Lintプラグイン	TypeScript
docsスクリプト	TypeScript（tsx）

すべて1言語で書ける状態にしてあるメリットはAIから見たときに大きいです。具体的には:

• AST / 型定義をそのままAIのコンテキストに食わせられる ── 言語境界で文脈が分断されない
• リファクタが言語境界をまたがない ── ESLintプラグイン1つでapps / packages / infra全部を一括で検査・自動修正できる
• Product Graphに乗せたときにエッジが切れない ── 例えばCloud Runのサービス定義（infra/TS）から、それが叩くAPIのHonoルート（apps/TS）まで、1つのグラフで繋がる

「この機能の影響範囲は？」をAIに聞いたとき、infra → apps → packagesを行き来して1ホップで答えが返るのは、これらが土台になっています。

ビルドはTurborepoとpnpm workspacesで並列化、デプロイはGitHub Actionsで変更されたスタックだけを検出してPulumiで並列適用しています。

数字（執筆時点のスナップショット）

	値
期間	約5ヶ月（本格開発は約4ヶ月）
コミット数	約4,000
マージ済PR	約790
そのうち自分が書いたコミットの比率	約91%
apps	123
packages	66
MCPサーバー	19
Pulumiスタック	110
TypeScript（実装）	約63万行
TypeScript（テスト）	約56万行
Markdownドキュメント	約11万行 / 389ファイル
手書きコードのas any / TODO / 無理由lint-disable	0（自動生成・外部ライブラリ起因を除く）
Coverage強制ライン	90%（statements / branches / functions / lines）

PR運用への切り替えで流量が一段変わった

実は4月までは、自分が手元でAIを使いながら徹底的にレビューして、そのまま直接mainにコミットするスタイルでした。レビューの厳しさは落とさない代わりに、捌ける本数は自分の手作業に律速される構造です。

4月からPR単位の細粒度運用（自動レビュー → 自動修正 → 自動マージ）に切り替えたことで、月別マージ済PRが劇的に変わりました:

月	マージ済PR
2026-02	10
2026-03	23
2026-04	518
2026-05（10日時点）	235

3月から4月で約22倍。コミット数自体は逆に減っている（main直接コミットからPR経由に変わったため）ので、これは「書く量が増えた」のではなく「手作業のレビューがハーネスに置き換わって、捌ける流量が一段上がった」結果です。この22倍は、人間レビュアーがAutoレビューに置き換わった瞬間そのものであり、コードが増えるほど効きが強くなるフライホイールの性質がはっきり出ています。

数字が成立している前提設計

ここまでの数字は**「AIを使ったから」だけでは成立しません**。前提として、

• フルTypeScriptモノレポ ── コード・テスト・インフラ・スクリプトを1言語の静的解析で横断
• Composable Architecture ── packages/に再利用可能な部品を置き、apps/は部品を組み合わせて構成。apps/間の直接importは禁止し、必ずpackages/経由で接続することで互いに干渉しない設計を担保
• strictな品質ゲート ── lint / coverage / 注釈は「下げない・回避させない」運用
• 統合グラフ ── コード・docs・DB・インフラを1つのグラフに乗せ、AIが文脈を踏まえて動ける土台
• 自動PRレビュー / 自動修正 / 自動マージ / 自動自己修復 ── 律速段階を人間の手からAIに置き換えるハーネス
• 統合Observability ── 人間が見るのと同じデータをAIも見る（OTel + Faro + Prometheus）

という設計が先にあって、その上でAIが動いているから、量と質が両立しています。

特にComposable Architectureは手数の多さに直結していて、各コンポーネントが互いに干渉しないからこそ、Claude Codeを並列に走らせて別々の場所を同時に開発できる。実運用では最大10並列ほどで動かしていた時期もあり、これがハーネスの効きと掛け算になっています。

**「魔法」ではなく「システム設計」**の結果です。各論はこの後の連載で順に取り上げます。

正直に書いておきたいこと

ここまで読むと「全自動で完璧」に見えるかもしれませんが、現実はそこまでではないので、3つだけ正直に書いておきます。

1. コード品質が高くてもバグは起こる

ハーネスが守れるのは**「コードの正しさ」であって「仕様の正しさ」**ではありません。実装が綺麗に書かれていても、仕様の解釈を間違えたら結局バグは出ます。AIレビューが拾えるのは「コードと仕様（docs / コメント）が矛盾している」までで、その仕様自体が間違っていればすり抜けます。ここは引き続き人間の責務です。

2. 役割分担は明確に分けている

外部APIとの接続が必要な新規パイプライン開発や、Secureな情報を扱う部分はエンジニアが担当。非エンジニアは基本的にすでに作られている機能の改修が中心です。実際に最近マージされた事業側メンバーのPRを見ると、KPIダッシュボードに新しい指標カラムを足す、既存集計の絞り込み条件を直す、グラフUIに前週比カラムを追加する、UIの表示を整える、といった粒度です。「非エンジニアも開発できる」というのは、ハーネスが「逸脱しないレール」を提供しているから、改修フェーズで安全に手を入れられる、という話で、ゼロから何でも作れるという話ではありません。

3. 社内基盤だからこのレベルまでできた

cortexがデプロイまで全自動にできているのは、もちろんComposable Architectureでアプリケーション / インフラが分離できていることもありますが、正直なところ社内向け基盤であることが大きいです。トラブルが起きても困るのは社員だけで、即座に巻き戻せばいい。ToCのプロダクトや、WMSのように停止が即Criticalになるシステムで同じことはできません。少しでも近づける動きは別途始めているので、それはまた別の機会に書きます。

次回以降のロードマップ

このシリーズは全6回を予定しています。

Part 1: 総論（本記事）
cortexがどんな環境で、なぜ「ハーネス」という形で機能するかの全体像。シリーズ全体の地図役。

Part 2: Product Graph ── コード・docs・DB・インフラを1つのグラフに統合する ★最初に読み進めるおすすめ
この統合グラフがどう構築・維持されているかの実装編。直前のAgentic Graph RAG MCPの記事で書いた設計原則をcortex全体に適用するとどうなるか。

Part 3: AIがPRをレビューし、修正し、マージし、デプロイする
GitHub webhook → AIレビュー → REQUEST_CHANGESならworktreeでAI修正 → 自動squash merge → 変更スタック検出 → 並列デプロイ、までの全フロー。

Part 4: 障害が自動で直り、ガードレールが自動で増える
Grafanaアラート → AI調査（Loki + Product Graph + git blame）→ 修正PR + 新規lint/型gateの追加 → 自動マージ → 自動再デプロイ、の自動自己修復システム。フルOTel + Loki + Mimir + Tempo + Faro構成と、品質ゲートが「下げない・回避させない・自動で増える」設計になっている話まで含む。

Part 5: ハーネスをtoCサービスに広げる
前半で「事業メンバーがcortexに直接PRを出せている運用」の実態と限界（既存pipelineへの追加はできる / 新規pipelineやアーキ変更は人のloopが必要）を扱い、後半でcortexで作った型をプロダクト組織全体（複数サービス・複数stack・複数チーム）に展開するロードマップと思想を書く。

それぞれ単独でも読めるように書きますが、Part 2（Product Graph）は他の各論の前提になるので、Part 1 → Part 2 → 任意の順で読むのがおすすめです。

公開ペースは火または木の朝8〜10時JSTを予定しています。

おわりに

cortexを作っていて感じるのは、AI時代の開発環境では「書く側の負担を減らす」よりも「書いたあとを全部受け止める」方が効くということです。テスト・lint・型・カバレッジ・コードレビュー・障害対応 ── これらを「邪魔だから減らす」ではなく「全部AIに任せて代わりに徹底する」と決めると、品質を上げながら同時に開発速度も上がる、という反直感的な状態が成立します。

そしてそれは、ひとりのエンジニアが書ける量や、エンジニア以外が参加できる範囲を、これまでよりも大きく押し上げてくれます。これが、cortexの上に組み上げた「ハーネス」の手触りです。

次回からは、これを実現している個別の仕組みを順に見ていきます。

→ Part 2: Product Graph ── コード・ドキュメント・DB・インフラを1つのグラフに統合する

---

私がCTOをしている株式会社エアークローゼットでは、AIと共に新しい開発体験を作り上げていくエンジニアを募集しています。興味のある方は、ぜひエンジニア採用サイトエアクロクエストをご覧ください！