最小構成のAIハーネスをMermaidで設計してみる

連載：AIに仕事を奪われる不安から始めるハーネス作成入門
全24回（週2回・12週間）｜第2回 / 24

この連載は、AIによるキャリア不安を持つプログラマ・SEに向けて、AIエージェントを安全に制御・検証・運用するための「ハーネス」を作る技術を、段階的に学ぶシリーズです。

はじめに：この記事で扱う不安

この記事は連載「AIに仕事を奪われる不安から始めるハーネス作成入門」の 第2回 です。

前回（第1回）では、AI時代のキャリア不安を整理し、「ハーネス作成」という学習方針を紹介しました。今回は、その全体像から最小構成を切り出し、Mermaid図で可視化するテーマについて整理します。

この記事で扱う不安は、次のようなものです。

AIハーネスの必要性は理解したが、全体像が大きすぎて、具体的にどこから作り始めればよいかわからない。

この不安は自然です。第1回で紹介した全体像には、AIエージェント・MCPサーバー・Knowledge・ログ・品質ゲート・Human-in-the-loopなど、多くの要素が含まれていました。全部を一度に作ろうとすると、手が止まります。

この記事では、「どの要素から始めるか」の判断基準を示し、最小構成をMermaid図で設計します。

対象読者

第1回を読んでハーネスの考え方に興味を持ったが、何から始めればよいか迷っているエンジニア
「設計図を描く前にコードを書き始めてしまう」タイプのプログラマ
Mermaid図でアーキテクチャを可視化する経験がまだ少ないSE

結論

先に結論を書くと、全体像から「AIエージェント」「MCPサーバー」「task_request / task_result」の3点セットを切り出すことが、最小構成の出発点 です。

要点は以下です。

全部を一度に作るのではなく、「動く最小構成」を先に定義する
最小構成をMermaid図で可視化すると、何を作るか・何を後回しにするかが明確になる
SE・プログラマの設計経験（責務分離・インターフェース設計）が、そのままハーネス設計に活きる

なぜ最小構成から始めるのか

全体像の拯復

第1回で紹介した全体像を再掲します。

この図には、AIエージェント・MCPサーバー・Knowledge / RAG・ログ・品質ゲート・レビュー承認・入出力契約など、多くの要素が含まれています。

これを一度に全部作ろうとすると、何から手をつければよいかわからなくなります。これは、実務で大規模システムを設計するときにも起きる問題です。

「最小で動く」を切り出す考え方

ソフトウェア設計では、大きなシステムを一度に作るのではなく、最小限の動作可能な構成（MVP: Minimum Viable Product） から始めることが一般的です。

AIハーネスでも同じです。全体像の中から、「この3つがあれば最低限動く」という要素を見つけます。

その判断基準は次の通りです。

判断基準	説明
AIエージェントに指示を出せるか	タスクを委任できなければハーネスとして成立しない
AIエージェントがツールを使えるか	MCPサーバーがないとAIは「考えるだけ」で「動く」ことができない
指示と結果が構造化されているか	task_request / task_resultがないと再現性が確保できない

この3つが揃えば、最小限「AIに仕事を渡して、結果を受け取る」ができます。Knowledge / RAG、ログ、品質ゲート、Human-in-the-loopは、この最小構成が動いた後から追加します。

既存のSE / プログラマ経験をどう活かせるか

最小構成を設計するプロセスは、SE・プログラマが実務で行っている作業と重なります。

既存経験	最小構成設計での活かし方
コンポーネント分割・責務分離	「AIエージェント」「MCPサーバー」「入出力契約」をそれぞれ独立した役割として設計する
API設計・インターフェース定義	task_request / task_resultの入出力スキーマを定義する
システム構成図・ブロック図の作成	Mermaidでアーキテクチャを可視化し、チーム共有可能な形にする
MVP開発・段階的リリース	全部作る前に「まず動く最小」を定義し、そこから拡張する

特に、「大きなシステムを小さく分割し、各コンポーネントの責務を明確にする」経験は、AIハーネス設計でそのまま使えます。

最小構成の設計

3つのコンポーネント

全体像から切り出した最小構成は、以下の3つのコンポーネントで構成されます。

コンポーネント	役割	第1回での対応
task_request / task_result	AIへの指示と結果の構造化	入出力契約
AIエージェント	タスクを実行する存在	AIエージェント
MCPサーバー	AIに渡す道具箱	MCPサーバー群

最小構成に含めないもの（今は）

以下の要素は重要ですが、最小構成が動いた後に追加します。

要素	後回しの理由	追加予定
Knowledge / RAG	最初はAIの標準知識で動かし、必要になってから専用知識を追加	第9〜10回
ログ / 監査	まず「動く」を確認し、次に「記録する」を追加	第13〜14回
品質ゲート	出力の傾向を把握してからゲート基準を設定	第17〜18回
Human-in-the-loop	最初は全結果を人間が確認、徐々に自動化	第15〜16回

これは、「全部作ってから動かす」ではなく「動かしながら育てる」アプローチです。実務での段階的リリースと同じ考え方です。

最小構成のMermaid図

以下が、最小構成のAIハーネスをMermaidで表現したアーキテクチャ図です。これが今回の最も重要な成果物です。

図の読み方

この図のフローは次の通りです。

人間がタスクを指示：task_request JSONで「何をしてほしいか」を構造化して渡す
AIエージェントが受け取る：task_requestの内容に従ってタスクを開始
MCPサーバーのツールを呼び出す：必要に応じてツールを使い、実際の処理を実行
ツールから結果を受け取る：各ツールの処理結果をAIエージェントが統合
task_resultとして出力：構造化された結果を返す
人間が結果を確認：現時点では全結果を人間が目視確認する

全体像との差分

全体像と最小構成の違いを明確にします。

要素	全体像	最小構成
task_request / task_result	✅	✅
AIエージェント	✅	✅
MCPサーバー	✅	✅
Knowledge / RAG	✅	―（後追加）
ログ / 監査	✅	―（後追加）
品質ゲート	✅	―（後追加）
Human-in-the-loop	✅	―（全結果を目視で代替）

各コンポーネントの責務

task_request / task_result

AIエージェントへの「契約」です。「何をしてほしいか」と「何が返ってくるか」をJSONで構造化します。

{
  "task_request": {
    "task_id": "harness_design_001",
    "task_type": "generate_mermaid",
    "input": {
      "target": "最小AIハーネスのアーキテクチャ図",
      "format": "mermaid_flowchart",
      "constraints": ["コンポーネント3つ以内", "subgraphでグループ化"]
    }
  },
  "task_result": {
    "status": "completed",
    "output": {
      "mermaid_code": "flowchart LR ...",
      "component_count": 3
    }
  }
}

API設計やインターフェース定義の経験がある人にとって、この「入力と出力を明確に定義する」という作業は馴染みのあるものです。task_request / task_resultの詳細は、第4回で拡張します。

AIエージェント

task_requestを受け取り、MCPサーバーのツールを使いながらタスクを実行し、task_resultを返す存在です。

最小構成では、以下を決めれば十分です。

どのLLMを使うか（外部API or ローカル）
どのMCPサーバーに接続するか

モデル選択の判断基準は第11〜12回で詳しく扱います。現時点では、「まず動く」ことを優先します。

MCPサーバー

AIエージェントに渡す「道具箱」です。ツールを通じてAIが実際に処理を実行できます。

最小構成ではMCPサーバーを1つ、ツールを2〜3個から始めます。例えば、この連載自体が使っている note-qiita-article-mcp がその一例です。

MCPサーバーの分割設計については、第7〜8回で詳しく扱います。

実装・設計時の注意点

注意点	理由	対策
Mermaid図だけで満足しない	図は設計の出発点であり、実装しないと検証できない	次回以降で各コンポーネントを実装する
最小構成を長期間そのまま使わない	ログや品質ゲートがないままだと、問題が起きたときに調査できない	連載に沿って段階的に拡張する
MCPサーバーのツールを詰め込みすぎない	1つのMCPサーバーに全機能を入れると、保守性が下がる	責務ごとにMCPサーバーを分割する（第7回で詳細）

今回の小さな成果物

上の最小構成Mermaid図を自分のGitHubリポジトリのREADME.mdに貼る
自分の業務でAIに任せたいタスクを1つ決め、task_requestのJSONを書いてみる
全体像と最小構成の差分表を眺め、「次に追加したい要素」を1つ決める

まとめ

この記事では、第1回で紹介したAIハーネスの全体像から最小構成を切り出し、Mermaid図で設計しました。

重要なのは、全部を一度に作ろうとしないこと です。「AIエージェント」「MCPサーバー」「task_request / task_result」の3点セットがあれば、最低限のハーネスは動きます。そこからKnowledge、ログ、品質ゲート、Human-in-the-loopを段階的に追加していくのが、この連載のロードマップです。

SE・プログラマの「コンポーネント分割」「インターフェース設計」「MVP開発」の経験は、この設計プロセスでそのまま活きます。

次回予告

第3回：AIにコードを書かせるだけでは足りない理由（火曜日公開予定）

次回は、AIを「使う」こととAIを「運用する」ことの違いを整理します。

次回扱う内容：

AI単体利用とハーネス運用の違いを複数の観点で比較
「コード生成」だけでは業務成果に接続できない理由
「運用」という視点で見たときに必要になる設計要素

次回の成果物：

役割比較表（AI単体利用 vs ハーネス運用）

次回までに試しておくと良いこと：

今回のMermaid図を眺め、「次に追加したい要素」を1つ決めておく
自分の業務でAIに「コードを書かせた」経験があれば、そのとき「何が足りなかったか」を振り返ってみる

連載目次

回	タイトル	状態
1	AIに仕事を奪われる不安から「ハーネス作成」を学ぶ理由	✅
2	最小構成のAIハーネスをMermaidで設計してみる（この記事）	📖
3	AIにコードを書かせるだけでは足りない理由	次回
4	task_request / task_resultでAIエージェントの仕事を契約化する	─
5	SEの設計経験をAIエージェント制御に転用する	─
6	ハーネス用のディレクトリ構成とREADMEを作る	─
...	全24回の連載を予定しています	─

連載情報

連載名：AIに仕事を奪われる不安から始めるハーネス作成入門
全24回（12週間・週2回）
投稿曜日：火曜日（キャリア・設計・概念）/ 金曜日（実装・検証・テンプレート）