最小構成の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回）
- 投稿曜日：火曜日（キャリア・設計・概念）/ 金曜日（実装・検証・テンプレート）