生成AIの利用について
本記事の文章作成にはChatGPTを使用しています。
内容は、筆者が作成したAIDD SkeletonのREADME、リポジトリ内のドキュメント、開発時のコミット履歴を基に構成しています。
この記事は、AIDD Skeletonを作り始めた時期の設計と考え方を記録したものです。
はじめに
AIコーディングエージェントを利用すると、コードの作成や修正をかなり短時間で進められるようになりました。
一方で、同じリポジトリを継続的に開発していると、コードを書くこととは別の問題が気になるようになりました。
例えば、
- 要件や設計と実装の内容が一致しなくなる
- 調査中のメモと正式なドキュメントが混在する
- AIが生成した一時ファイルがリポジトリ内に残る
- 会話やAIツールが変わるたびに、プロジェクトの前提を説明し直す必要がある
- テストしていない範囲まで、検証済みとして扱われる
- AIとユーザーの判断範囲が曖昧になる
といった問題です。
一度きりのコード生成であれば、それほど問題にならないこともあります。
ただ、数日、数週間と同じプロジェクトを続けたり、複数のAIセッションをまたいで作業したりすると、
プロジェクトの状態や判断基準を、会話だけに置いておくのは難しい
と感じるようになりました。
そこで、AIと開発者が共通して参照できるリポジトリ構造と作業ルールを用意するために作り始めたのが、AIDD Skeletonです。
AIDDは、ここでは AI-Driven Development の略称として使用しています。
最初は「置き場所を分ける」ところから始めた
AIDD Skeletonを考え始めたとき、最初にやろうとしたことはかなり単純でした。
AIが扱う情報を、役割ごとに分けておけばいいのではないか。
最初期には、トップレベルを次の4領域に分けていました。
docs/
etc/
prototypes/
src/
大まかには、
-
docs/：要件や設計などの正式な文書 -
etc/：実行環境や開発環境 -
prototypes/：検討や技術検証のための試作 -
src/：正式な実装
という分類です。
一般的なリポジトリ構成に近いところから始めつつ、正式な実装と一時的な試作を分離することを意識していました。
外部から与えられた資料を分ける
構成を考えていくと、もう一つ性質の違う情報がありました。
例えば、
- ユーザーから提供された仕様書
- サンプルデータ
- 画面デザイン
- 外部システムの資料
などです。
これらは重要な情報源ですが、プロジェクト自身が管理する正式な要件や設計とは少し性質が違います。
そこで、外部から提供された原資料を扱うためにreferences/を追加しました。
docs/
etc/
prototypes/
references/
src/
ここで、トップレベルを5つの領域に分ける形になりました。
references/に資料が存在することと、その内容をプロジェクトの正式な仕様として採用することは別と考えています。
採用した内容は正式な文書へ反映し、原資料そのものは参照物として扱います。
docsとsrcをplansとproductsへ変えた
次に見直したのが、docs/とsrc/という名前でした。
docs/という名前だと、単にMarkdownなどの文書を置く場所に見えます。
しかし、ここで管理したかったのは文書というファイル形式ではなく、
プロジェクトとして採用した要件、設計、テスト方針、状態などの情報
です。
同じようにsrc/も、単なるソースコード置き場というより、
正式な実装、テスト、成果物
を扱う場所として考えていました。
そこで、
docs/ → plans/
src/ → products/
と変更しました。
構成は、
plans/
etc/
prototypes/
references/
products/
となります。
このあたりから、ファイルの種類ではなく、その情報がどのような役割を持っているかを基準に配置する考え方が強くなりました。
2026年7月29日に公開版のAIDD Skeletonを作成した時点では、すでにこの構成を採用しています。
prototypesからworkbenchへ
最初のprototypes/は、要件や設計、技術的な実現可能性などを確認するための試作を置く領域でした。
例えば、
- 技術的なPoC
- UIの試作
- 設計案を確認するコード
- ライブラリの比較実装
などです。
ただ、AIを使って作業すると、正式採用前に発生するものは試作コードだけではありません。
例えば、
- 調査メモ
- 比較結果
- 設計の下書き
- 実装計画
- 一時スクリプト
- データ変換結果
- 他のセッションへ渡すための作業資料
- 検証途中の結果
なども発生します。
これらをすべてprototypeと呼ぶのは少し無理がありました。
そこでprototypes/を、より広い作業領域としてworkbench/へ変更しました。
prototypes/
↓
workbench/
workbench/では、試作だけでなく、調査、比較、下書き、準備、検証、引き継ぎなども扱います。
ただし、workbench/に置かれた内容は、それだけで正式な要件や実装になるわけではありません。
正式に採用するときに、対応する領域へ反映します。
この変更を経て、記事公開時点では次の構成になっていました。
plans/
products/
references/
workbench/
etc/
各領域の役割
plans
plans/は、プロジェクトの正式な情報を管理する領域です。
例えば、
- プロジェクトの目的
- 要件
- 設計
- テスト方針
- 現在の状態
- 用語
- トレーサビリティ
- 開発や運用の手順
などを配置します。
実装コードだけを見て仕様を推測するのではなく、要件や設計を確認したうえで実装との整合性を判断できる状態を目指しています。
実装を変更する前にSource of Truthを確認するというルールも、この時期に明確にしました。
products
products/は、正式な実装、テスト、成果物を管理する領域です。
例えばWebアプリケーションであれば、
products/
└── apps/
└── household-book/
├── src/
├── tests/
└── package.json
のような構成を想定しています。
src/やtests/といった一般的な構造を使わないという意味ではなく、正式成果物の責任を持つproducts/の下に配置する考え方です。
references
references/は、外部から提供された原資料を管理する領域です。
例えば、
- 仕様書
- 画面デザイン
- サンプルデータ
- PDF資料
- 外部システムの資料
などです。
ここに置かれた資料は判断材料であり、存在するだけでプロジェクトの正式な仕様になるわけではありません。
採用した内容は、対応する正式な文書へ反映します。
workbench
workbench/は、作業途中の資料を置く領域です。
例えば、
- 調査メモ
- 比較資料
- プロトタイプ
- 技術的なスパイク
- 実験コード
- 設計の下書き
- 実装計画
- 一時的なスクリプト
- 検証途中の出力
- 作業の引き継ぎ資料
などです。
重要なのは、詳細に書かれていることと、正式に採用されていることは別という点です。
例えば調査結果から要件を採用する場合は、
調査
↓
workbench/
↓
採用
↓
plans/
試作コードを正式実装にする場合は、
試作
↓
workbench/
↓
採用
↓
products/
という形で扱います。
etc
etc/は、開発環境や実行環境に関する設定を管理する領域です。
例えば、
- Dev Container設定
- Dockerなどの実行環境
- 開発ツール設定
- 外部サービスの設定
- 環境構築用スクリプト
などを配置します。
認証情報、秘密鍵、アクセストークンなどはリポジトリに保存しません。
AGENTS.mdでAIとの作業ルールを共有する
ディレクトリ構成と合わせて、AIがリポジトリをどう扱うかについてもルールを用意しました。
AIDD Skeletonでは、リポジトリ直下と各領域にAGENTS.mdを配置しています。
ルートのAGENTS.mdでは、例えば、
- AIとユーザーの権限
- 作業前に確認する情報
- 要件、設計、実装、検証の関係
- AIが判断してよい範囲
- ユーザー確認が必要な操作
- 作業範囲
- 完了報告
- 未検証事項の扱い
などを定義します。
各領域のAGENTS.mdでは、その領域固有の配置や変更ルールを定義します。
つまりAGENTS.mdは、プロジェクトそのものの仕様を書く場所ではなく、
AIがそのリポジトリでどう作業するかを定める規約
として使っています。
初期化
AIDD Skeletonをテンプレートとして使って新しいプロジェクトを作った直後は、まだプロジェクト固有の情報がありません。
そこで最初に、AIがリポジトリやユーザーから与えられた情報を確認し、プロジェクトを開始するために必要な内容を整理する工程を設けました。
例えば、
- プロジェクトの目的
- 対象ユーザー
- 対応範囲
- 対象外
- システムやアプリケーションの責任
- 前提条件
- 未決事項
- 要件、設計、テスト方針
- 完了条件
などです。
内容を確認したうえで、プロジェクト固有の文書を作成します。
記事公開時点では、例えば次のような構成を使っていました。
plans/
├── CURRENT_STATUS.md
├── GLOSSARY.md
├── TRACEABILITY.md
├── system/
│ ├── documentation_language.md
│ └── system_index.md
└── apps/
最初からすべての文書を埋めるというより、プロジェクトに必要な情報を正式な場所へ記録していくことを目的としています。
TRACEABILITYを増やし続けない
初期版では、要件、設計、実装、検証などの対応関係をTRACEABILITY.mdで管理していました。
ただ、単純に変更履歴や対応関係を追加し続けると、ファイル自体が大きくなり続けます。
そのため、作り始めた段階ですでに、TRACEABILITY.mdを無制限に肥大化させないためのルールも追加しました。
参考
9be3f708 - Prevent TRACEABILITY.md from growing without bound
リポジトリに情報を残すことだけでなく、その情報を継続して扱える状態にしておくことも意識しています。
実装されたことと検証されたことを分ける
AIDD Skeletonを作るうえで、特に明示したかったことの一つが、
実装されたことと、検証されたことを分ける
という点です。
例えば、プログラムのファイルを作成しただけでは、実際に動作することまでは確認できていません。
構文チェックが成功しても、機能全体が正常に動作することまでは証明できません。
そのため完了報告では、
変更内容:
- 支出登録APIを実装
- 入力値検証を追加
- 単体テストを追加
検証結果:
- 単体テスト成功
- 静的解析成功
未検証事項:
- 本番環境相当のDBでの動作
- 複数ユーザーによる同時実行
のように、実際に確認した範囲を分けます。
テストが成功していても、そのテストで確認していないことまで検証済みとは扱いません。
このルールについても、開発初期に検証証拠の範囲を見直しました。
GitHub Templateとして使う
記事公開時点では、AIDD SkeletonをGitHub Repository Templateとして使う方法を主な導入方法としていました。
GitHubでAIDD Skeletonを開き、
- Use this template
- Create a new repository
- Owner、Repository name、Visibilityを設定
- 作成したリポジトリをAI開発環境で開く
- AIへ最初のメッセージを送る
という流れです。
最初のメッセージは、例えば、
こんにちは！
だけでも開始できます。
作りたいものが決まっている場合は、
個人向けの家計簿Webアプリを作成したいです。
対象ユーザーは、自分の支出を簡単に記録したい人です。
最初のバージョンでは、
- 支出の登録
- 支出の一覧表示
- 月別の支出集計
を実装したいです。
のように、概要から渡すこともできます。
記事公開日の2026年8月7日には、READMEもGitHub Templateからの利用を主な導線とする形に整理しました。
動作確認環境
記事公開時点では、以下の環境で利用を確認していました。
- GitHub Repository Template
- Codex
- GPT-5.6
- Antigravity
- Gemini 3.6 Flash
利用するモデルによって、ドキュメントの読み取り、変更範囲の判断、検証結果の整理などには差が出る場合があります。
小規模な作業には向かない場合もある
AIDD Skeletonは、すべてのAI利用で使うことを想定したものではありません。
例えば、
- 数行のスクリプトを書く
- 一度だけ技術検証する
- 短時間で捨てるコードを書く
といった作業では、この構造自体が過剰になることがあります。
想定しているのは、
- 数日以上継続する
- 複数のAIセッションをまたぐ
- 要件、設計、実装、テストを扱う
- 後から現在状態や判断根拠を確認したい
といったプロジェクトです。
おわりに
AIDD Skeletonは、最初から完成した構造を決めて作ったものではありません。
最初は、
docs/
etc/
prototypes/
src/
という構成から始めました。
そこから、
docs → plans
src → products
prototypes → workbench
references → 追加
etc → 継続
という形で、実際に役割を考えながら整理していきました。
記事公開時点では、
plans/
products/
references/
workbench/
etc/
という5領域になっています。
変化の中で共通していたのは、
ファイルの種類ではなく、その情報がどのような責任を持っているかで分ける
という考え方です。
また、リポジトリ構造だけでなく、
- 正式な情報と作業途中の情報を分ける
- 外部資料と採用済みの仕様を分ける
- 要件、設計、実装、検証を区別する
- AIとユーザーの判断範囲を決める
- 検証した証拠以上のことを検証済みとしない
- プロジェクトの状態を会話だけに依存させない
といったルールも合わせて整理しました。
AIDD Skeletonは、こうした考えをリポジトリ自体に持たせて、AIと人間が同じ前提を参照しながら継続的に開発するためのテンプレートとして作り始めたものです。