1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

連載:AIに仕事を奪われる不安から始めるハーネス作成入門 第6回 ハーネス用のディレクトリ構成とREADMEを作る

1
Last updated at Posted at 2026-06-18

ハーネス用のディレクトリ構成と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サーバーを『道具箱』として分割する考え方」を予定しています。

1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?