ハーネス用のディレクトリ構成とREADMEを作る
連載:AIに仕事を奪われる不安から始めるハーネス作成入門
全24回(週2回・12週間)|第6回 / 24
この連載は、AIに仕事を奪われるかもしれないという不安を「ハーネス(AIエージェント制御の仕組み)」を自分で作る行動に変えるシリーズです。
はじめに:この記事で扱う不安
「ハーネスを作りたいが、どこから手をつければいいかわからない」——この悲鳴は、多くのエンジニアに共通するものです。
前回(第5回)では、SE経験がAIハーネス設計に転用できることを確認しました。しかし、「転用できるとわかった」だけでは、まだ動き出せません。今回は、その最初の一歩として「プロジェクトの骨格を作る」ことに集中します。
SE経験がある方なら「プロジェクトの初期構造」は馴染みのある作業でしょう。その経験を活かして、AIハーネスプロジェクトのディレクトリ構成とREADMEを設計します。
対象読者
- SE・プログラマ経験3年以上の方
- 「作りたいけどどこから」で止まっている方
- Git / GitHubの基本操作ができる方
- 前回までの連載を読んでいる方(未読でもOK)
結論
ハーネスプロジェクトのディレクトリ構成は、SEが日常的に行う「プロジェクト初期設計」そのものです。今回提示する構成案をベースに、自分のプロジェクトに合わせてカスタマイズすれば、その日のうちに骨格が完成します。
なぜこのテーマが必要なのか
プロジェクトのディレクトリ構成は「地味だが重要な土台」です。SEなら経験的に知っていると思いますが、最初の構成が悪いと後からの拡張が困難になります。
AIハーネスプロジェクトでは、特に以下の理由で初期構成が重要です。
- MCPサーバーが複数存在する: 各サーバーのコード置き場を明確にする必要がある
- 設定ファイルが多い: プロンプト、スキーマ、環境変数などが分散しやすい
- ドキュメントが重要: AIエージェント自体がREADMEやドキュメントを読んで動作することがある
既存のSE / プログラマ経験をどう活かせるか
| SE経験 | ハーネスプロジェクトへの活用 |
|---|---|
| プロジェクト初期設定の経験 | ディレクトリ設計の判断基準をそのまま使える |
| モジュール分割の経験 | MCPサーバーごとのディレクトリ分割に活かせる |
| README / 設計書作成 | プロジェクトの「なぜ」と「どう」を明確にする |
| .gitignore の設計 | 秘密情報や一時ファイルの除外ルール |
| CI/CD環境構築 | ビルド・テスト・デプロイの分離 |
提案するディレクトリ構成
以下は、AIハーネスプロジェクトのディレクトリ構成案です。そのまま使う必要はなく、自分のプロジェクトに合わせて調整してください。
ai-harness/
├── README.md # プロジェクト概要・セットアップ手順
├── LICENSE # ライセンスファイル
├── .gitignore # Git除外設定
├── .env.example # 環境変数のテンプレート
├── pyproject.toml # Pythonプロジェクト設定
│
├── docs/ # ドキュメント
│ ├── design/ # 設計メモ
│ ├── adr/ # Architecture Decision Records
│ └── knowledge/ # Knowledge MCP登録用マークダウン
│
├── src/ # メインソースコード
│ ├── harness/ # ハーネス本体
│ │ ├── __init__.py
│ │ ├── orchestrator.py # オーケストレータ
│ │ ├── task_request.py # task_requestモデル
│ │ └── task_result.py # task_resultモデル
│ └── mcp_servers/ # MCPサーバー群
│ ├── article_mcp/ # 記事作成MCP
│ ├── knowledge_mcp/ # 知識管理MCP
│ └── review_mcp/ # レビューMCP
│
├── prompts/ # プロンプトテンプレート
│ ├── system/ # システムプロンプト
│ └── task/ # タスク別プロンプト
│
├── schemas/ # JSON Schema定義
│ ├── task_request.json
│ └── task_result.json
│
├── tests/ # テスト
│ ├── unit/
│ ├── integration/
│ └── fixtures/
│
└── scripts/ # ユーティリティスクリプト
├── setup.sh
└── run_harness.py
各ディレクトリの設計意図
README.mdの構造
README.mdは「プロジェクトの顔」です。SEなら「読む人が最初に知りたいこと」を考えるのは得意でしょう。以下の構造を提案します。
# 🧰 AI Harness - AIエージェント制御フレームワーク
## このプロジェクトは何か
AIエージェントを制御するための「ハーネス」を構築するフレームワークです。
## クイックスタート
1. リポジトリをクローン
2. 依存ライブラリをインストール
3. 環境変数を設定
## ディレクトリ構成
(上記の構成図)
## 使い方
(基本的な使い方)
## 開発ガイド
- ブランチ戦略
- コミット規約
- テストの実行方法
## ライセンス
MIT License
実装・設計時の注意点
| 注意点 | 理由 | 対策 |
|---|---|---|
| 最初から完璧を目指さない | 構成はプロジェクトの成長とともに変わる | 最小限の構成で始め、必要に応じて拡張 |
| .envをGitに含めない | APIキー等の秘密情報が漏洩する | .env.exampleのみコミット、.gitignoreに.envを追加 |
| MCPサーバーは独立させる | 各MCPの責務が混在すると保守性が下がる | mcp_servers/以下にサーバーごとのディレクトリを切る |
| ドキュメントはコードと同居させる | docs/が別リポジトリだと同期が取れない | 同一リポジトリ内のdocs/に置く |
| テストの場所を最初から用意 | 後から追加すると「置き場所がない」問題が起きる | tests/ディレクトリを初日から作る |
今回の小さな成果物(チェックリスト)
- 上記のディレクトリ構成をベースに、自分のプロジェクト名でディレクトリを作成する
- README.mdを上記の構造で書く(内容は仮でOK)
- .gitignoreに.env、pycache、.venvを追加する
- .env.exampleを作成し、必要な環境変数をリストアップする
-
git initと最初のコミットを行う - (発展)GitHubにプッシュする
まとめ
今回は、AIハーネスプロジェクトのディレクトリ構成とREADMEの設計を行いました。
キーポイント
- ディレクトリ構成はSEの「プロジェクト初期設計」の経験がそのまま使える
- 最初から完璧を目指さず、「拡張可能な最小構成」で始める
- READMEはプロジェクトの「顔」。「何が」「なぜ」「どう使う」を明確に
- .envの管理、テストディレクトリの準備は初日にやる
「作りたいけどどこから」の答えは、このディレクトリ構成を作ることです。今日のうちに、骨格を作ってみましょう。
次回予告
第7回「MCPサーバーを『道具箱』として分割する考え方」 では、ディレクトリ構成の中の mcp_servers/ に焦点を当てます。
扱う内容
- MCPサーバーの責務分割の考え方(「1MCP=1責務」の原則)
- マイクロサービス的な分割 vs モノリス的な構成のトレードオフ
- 実際のハーネスでどんなMCPサーバーが必要か
得られる成果物
- MCP責務表(各MCPの役割と入出力をまとめた表)
試しておくこと
- 今回作ったディレクトリ構成の
mcp_servers/に、自分が使いたいMCPサーバーの名前を仮でいいので書いておく - 普段使っているツールを「機能別」にグルーピングしてみる(それがMCP分割のヒントになります)
連載目次
| 回 | タイトル | 状態 |
|---|---|---|
| 第1回 | AIに仕事を奪われる不安から「ハーネス作成」を学ぶ理由 | ✅ |
| 第2回 | 最小構成のAIハーネスをMermaidで設計してみる | ✅ |
| 第3回 | AIにコードを書かせるだけでは足りない理由 | ✅ |
| 第4回 | task_request / task_resultでAIエージェントの仕事を契約化する | ✅ |
| 第5回 | SEの設計経験をAIエージェント制御に転用する | ✅ |
| 第6回 | ハーネス用のディレクトリ構成とREADMEを作る | 📖 |
| 第7回 | MCPサーバーを「道具箱」として分割する考え方 | 次回 |
| 第8回 | MCPサーバーの最小実装 — FastMCPで最初のツールを作る | ─ |
| 第9回 | RAG / Knowledge MCPがSE経験者に向いている理由 | ─ |
| 第10回 | 設計メモをKnowledge MCPへ登録する前提のMarkdownテンプレート | ─ |
| 第11回 | ローカルLLMを使うべき場面と外部LLMに任せる場面 | ─ |
| 第12回 | 中間レビュー — ここまでの構成を振り返る | ─ |
| 第13〜24回 | (以降の回) | ─ |
連載:AIに仕事を奪われる不安から始めるハーネス作成入門
著者: @singula00991| 週2回更新
次回は「MCPサーバーを『道具箱』として分割する考え方」を予定しています。