ryantsuji.dev

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

14 min read

目次

  1. 連載一覧
  2. いきなり2つのシーンから
  3. シーン1: PRは無人でマージされる
  4. シーン2: 障害は気づく前に直っている
  5. 業界文脈 ── 「ハーネスエンジニアリング」の流れ
  6. 誰が開発しているか
  7. 何が動いているか
  8. 4要素のフライホイール ── cortexのハーネス
  9. ① Product Graph（Guides ── 正しいコンテキストを供給する）
  10. ② Lint / Quality Gates（Guides ── 逸脱を物理的に潰す）
  11. ③ Autoレビュー（Sensors ── 基準に達するまで自動で直す）
  12. ④ Self-Healing（Sensors ── 本番異常を起点へ再投入する）
  13. フライホイールとして何が起きているか
  14. 支える基盤層
  15. 技術基盤
  16. 数字（執筆時点のスナップショット）
  17. PR運用への切り替えで流量が一段変わった
  18. 数字が成立している前提設計
  19. 正直に書いておきたいこと
  20. 次回以降のロードマップ
  21. おわりに

みなさまこんにちは！エアークローゼットで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を出す。

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

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

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

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

自動化された開発と運用の2つのループ

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

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

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

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

業界の合言葉として**"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レビューと自動化が品質ゲートを担う設計になっているので、

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

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

何が動いているか

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

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

規模感:

数
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つの要素が互いに強化し合うフライホイールとして組まれています。

cortexのAIハーネスフライホイール

① 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で影響範囲を辿った上での指摘になっている、というのが効きどころ。例えば実際に飛んでいる指摘を分類すると:

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

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

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

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

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

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

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

支える基盤層

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

技術基盤

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から見たときに大きいです。具体的には:

「この機能の影響範囲は？」を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を使ったから」だけでは成立しません**。前提として、

という設計が先にあって、その上で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つのグラフに統合する

comments (0)

まだコメントはありません。