はじめに
生成AIと一緒に開発していると、コードそのものだけでなく、周辺の Markdown や作業場所の分け方がかなり重要になります。
README.md、docs/、TODO.md を置くこと自体は、生成AI時代に突然出てきた新しい作法ではありません。
OSS や開発現場では、利用者への入口を README に置き、詳しい設計や仕様を docs に逃がし、未完了の作業や次の作業を TODO に残す、という感覚はすでにコモンセンスとしてありました。
生成AI駆動開発では、この素朴な文書文化が少し違う意味を持ちはじめます。
これらの Markdown は、人間同士の情報共有だけでなく、人間と生成AI agent の情報共有の場所になります。
また、単なる説明文書ではなく、生成AI agent に対する緩やかな指示の場所にもなります。
生成AIを使い始めたばかりのころは、AI agent が TODO.md を作ったり、docs/ に設計メモを追加したりすると、少し驚くかもしれません。
ソースコードを頼んだつもりなのに、Markdown ファイルや docs フォルダが自動で増えているように見えるからです。
しかし、これは必ずしも余計なファイルを増やしているわけではありません。
作業の前提、判断理由、残作業、再開時の入口を、会話の外に置こうとしている場合があります。
ちなみに私たちが開発している miku-soft では、生成AI駆動開発の文脈を会話の外にも残すために、README.md、docs/、TODO.md、workplace/ の役割を分けて考えています。
これは文書をたくさん増やしたいという話ではありません。
生成AI agent が作業を再開しやすく、人間も現在地を失いにくくするために、情報の置き場所を分けるという話です。
生成AI駆動開発では人間が直接書くものが変わる
生成AI駆動開発では、人間が直接ソースコードを書く場面は相対的に減っていきます。
もちろん、最終的な判断や確認は人間が行います。
しかし、実際のコード変更は生成AI agent に任せることが多くなります。
さらに、README.md や docs/ や TODO.md でさえ、人間がすべて手で書くとは限りません。
※ちなみに、私たちが開発している miku-soft の場合は、ソースコードも Markdown も、いずれも人間は変更しないことを大前提としています。
人間は、会話の中で違和感、方針、制約、判断、次に見たい観点を伝えます。
生成AI agent はそれを受けて、ソースコードだけでなく Markdown も更新します。
たとえば、次のような依頼をします。
この方針を docs に残してください。
次回再開できるように TODO.md に現在作業中の内容や再開したいポイントを書いてください。
README には利用者向けの説明だけを残してください。それ以外の情報は docs フォルダに新規 Markdown ファイルを作成してそこに格納してください。
この意味で、Markdown は人間が一方的に書く文書というより、人間と生成AI agent の対話を通じて更新される共有文脈になります。
対話
-> Markdown 更新
-> 次回の対話の前提
-> さらに更新
この循環を安定させるために、Markdown の置き場所を分けておくことが効いてきます。
基本の分け方
私が今のところ使いやすいと感じている分け方は、次のようなものです。
README.md
-> 利用者向けのエントリポイント
docs/
-> 設計、詳細仕様、判断理由、mapping
TODO.md
-> セッション再開のための作業コンテキスト
workplace/
-> ローカル検証、生成物、一時ファイル、上流の確認用 checkout
それぞれの場所に、少しずつ違う種類の情報を置きます。
大事なのは、どこか一箇所に全部を押し込まないことです。
- README に内部設計を全部書くと、利用者向けの入口として重くなります。
- docs に現在作業中のメモを混ぜすぎると、後から読んだときに仕様なのか一時メモなのか分かりにくくなります。
- TODO.md を単なるタスクリストにすると、セッション再開時の文脈が足りなくなります。
- workplace をソース置き場のように扱うと、Git 管理対象と一時生成物の境界が崩れます。
README.md は利用者向けのエントリポイント
README は、普通の利用者が最初に読む場所です。
ここには、ツールを使うために必要な情報を置きます。
- 何をするツールか
- どう実行するか
- 代表的な入力と出力
- 主要なコマンド
- 注意すべき制約
- 詳細情報へのリンク
生成AI駆動開発では、README は AI agent にとっても入口になります。
README を読むことで、そのリポジトリが何で、どう使うもので、どこに詳細情報があるのかを把握できます。
ただし、README を AI agent 専用の作業メモにしすぎると、人間の利用者にとって読みづらくなります。
README は、利用者向けのエントリポイントであることを優先します。
内部設計、移植方針、詳細な差分管理、長い判断理由は、必要に応じて docs へ逃がします。
README.md
-> まず使う人が読む
-> 代表的な使い方を確認する
-> 詳細 docs への入口を持つ
docs/ は設計と判断理由を残す場所
docs/ には、README には重すぎる情報を置きます。
たとえば、miku-soft 系の開発では、次のような情報が docs に向いています。
- アーキテクチャ方針
- 詳細仕様
- 変換方針
- migration 方針
- upstream file と Java class の mapping
- upstream test intent と Java test の mapping
- diagnostics policy
- artifact role の説明
- 既知の制約
- 判断理由
生成AIと開発する場合、判断理由を残すことが特に効きます。
コードだけを見ると、「なぜこの設計にしたのか」は分かりにくいことがあります。
しかし、docs に判断理由が残っていると、AI agent が次に修正するときにも、単に見た目を整えるのではなく、元の意図を保ちやすくなります。
たとえば、TypeScript から Java へのストレートコンバージョンでは、Java らしく再設計しすぎないことが重要になります。
この方針は、コードだけでは伝わりにくいです。
そのため、mapping や migration policy として docs に残しておくほうが安定します。
docs/
upstream-class-mapping.md
upstream-test-mapping.md
upstream-followup-log.md
architecture.md
diagnostics-policy.md
このような文書は、人間向けの説明であると同時に、AI agent が作業を続けるための地図にもなります。
TODO.md はセッション再開のためのコンテキスト置き場
TODO.md は、単なるタスク一覧ではありません。
生成AI駆動開発では、チャットやセッションを切り替える場面がよくあります。
作業が長くなったり、別の観点で新しいチャットを始めたり、ツールやモデルを変えたりすることがあります。
場合によっては、接続が切れて強制的に作業文脈が分断されることもあります。
そのとき、作業状況が会話履歴の中だけにあると、次のセッションでまず状況を掘り起こすところから始まります。
運が悪いと、セッションの情報は復元できません。
そこで TODO.md に、作業状況や再開に必要な情報を残しておきます。
私の場合、ちょっとした作業であっても、必要に応じて TODO.md を更新してもらうようにしています。
これは、作業管理を厳密にしたいからではありません。
生成AI agent との作業では、小さな修正でも、会話の中に次のような文脈が発生します。
- 今どこを見ているか
- 何を確認したか
- 次に何をするつもりか
- 今回は触らない範囲はどこか
- 途中で迷った判断は何か
この文脈を会話の中だけに置くと、次回再開時に掘り起こす必要が出てきます。
そのため、TODO.md は厳密なチケットではなく、セッションをまたいだ作業コンテキストの置き場として使っています。
また、少し作業量が多い場合には、TODO.md に作業項目を書いておくことで実施漏れを防ぐ効果もあります。
生成AI agent は会話の流れの中でよく動いてくれますが、作業が複数のファイルや複数の確認観点にまたがると、細かい項目が抜けることがあります。
先に TODO.md に作業項目を分解しておくと、AI agent も人間も、何が残っているのかを確認しながら進められます。
ここには、次のような情報があると便利です。
- 今どこまで終わっているか
- 次に見るべきファイル
- 次に実行すべき確認コマンド
- 直近で迷っていた判断
- 未確認の点
- 後で docs に移すべき内容
- いまは触らない範囲
TODO.md
current position:
- workbook JSON import/export の parity 確認中
next:
- upstream の該当 test intent を確認
- Java 側の focused regression を実行
do not touch now:
- CLI batch command の追加
TODO.md に置く内容は、最終仕様ではないこともあります。
そのため、確定した設計や長期的に残すべき判断は、後で docs へ移します。
TODO.md は作業中のコンテキスト、docs は残す判断、という分け方です。
README.md と TODO.md を使った再開プロンプト
TODO.md に作業状況や再開のための情報を書き込んでおくと、チャットやセッションを切り替えたあとでも復帰しやすくなります。
次のセッションでは、まず次のように指示します。
README.md を読んで。
TODO.md を読んで。
状況を把握して。
これは自然言語の指示ですが、生成AI駆動開発ではほとんど再開プロンプトとして機能します。
README.md は「このリポジトリは何か」を伝えます。
TODO.md は「いま何をしていたか」を伝えます。
この短い指示だけで、生成AI agent は利用者向けの入口と、直近の作業状況の両方を確認できます。
長い会話履歴を貼り直したり、前回の判断を一から説明し直したりしなくても、リポジトリ内の Markdown を足場にして作業を再開できます。
workplace/ はローカル検証と生成物の置き場
workplace/ は、ローカル検証、生成物、一時ファイル、上流の確認用 checkout などを置く場所です。
ただし、workplace/ という名前自体は、一般的な慣習というわけではありません。
私が自分の関わる複数プロジェクトで、Git 管理外のローカル作業領域として統一して使っている名前です。
名前は tmp/ でも scratch/ でも work/ でもよいと思います。
大事なのは、リポジトリ直下に「ここは一時生成物や検証用ファイルを置く場所で、通常のソースではない」と分かる領域を決めておくことです。
ここで大事なのは、workplace をソースディレクトリにしないことです。
miku-soft では、基本的に workplace/.gitkeep だけを Git 管理し、通常の中身は Git 管理しません。
workplace/ 配下は .gitignore に書いておき、一時生成物や検証用ファイルがコミット対象に混ざらないようにします。
workplace/
.gitkeep
upstream-checkout/
tmp/
reports/
manual-fixtures/
生成AIに作業を任せると、検証用のファイル、変換結果、比較用の中間成果物が増えやすくなります。
それ自体は悪いことではありません。
しかし、それらがソースツリーの本体に混ざると、どれが正式な成果物で、どれが一時生成物なのか分かりにくくなります。
workplace を用意しておくと、AI agent にも「一時的な確認や生成物はここへ置く」と説明しやすくなります。
会話の外に作業文脈を置く
生成AI駆動開発で難しいのは、作業が長くなったときの文脈維持です。
会話の中には、たくさんの判断が出てきます。
- この仕様は upstream に合わせる
- この差分は Java 側の独自拡張として扱う
- この warning は soft warning として続行する
- この出力は byte-level parity で確認する
- この作業は今回は対象外にする
これらを会話の中だけに置くと、後で追いにくくなります。
README、docs、TODO.md、workplace の役割を分けておくと、会話の外に作業文脈を残せます。
会話
-> その場の判断と作業
TODO.md
-> セッションをまたぐ作業コンテキスト
docs/
-> 残すべき設計と判断理由
workplace/
-> 一時検証と生成物
README.md
-> 利用者向けの入口
これは、生成AIのためだけではありません。
人間が数日後に戻ってきたときにも、同じ効果があります。
むしろ作業再開時に、まず生成AI agent に TODO.md などを読んで状況把握してもらったうえで、「何をやっていて、次は何をすべきなのか」を質問することがよくあります。
避けたい混ざり方
この分け方で避けたいのは、次のような混ざり方です。
- README に内部設計メモや長い作業ログが入りすぎる
- docs に一時的な TODO や未整理の作業メモが残り続ける
- TODO.md が単なるチェックボックス一覧になり、セッション再開に必要な文脈が分からない
- workplace の中身を通常のソースファイルとして扱う
- 生成物と手書きソースの境界が分からなくなる
- AI agent に毎回同じ前提を会話で説明し続ける
もちろん、最初からきれいに分けきる必要はありません。
ただ、作業が進むにつれて、次のように移していくと安定します。
作業中の気づき
-> TODO.md
確定した判断
-> docs/
利用者が知るべきこと
-> README.md
一時生成物
-> workplace/
この流れを持っておくだけでも、生成AIとの開発はかなり再開しやすくなります。
おわりに
README.md、docs/、TODO.md は、生成AI時代に突然必要になったものではありません。
OSS や開発現場には、あとから来た人が状況を理解し、作業を引き継げるようにするための文書文化がもともとありました。
生成AI駆動開発では、そのコモンセンスが、人間と生成AI agent の情報共有や指示の場所として再評価されます。
- README は利用者向けの入口です
- docs は設計と判断理由を残す場所です
- TODO.md はセッション再開のためのコンテキスト置き場です
- workplace はローカル検証と生成物の置き場です
この分け方は、特別なツールを必要としません。
Markdown とディレクトリ構成だけでも始められます。
しかし、会話の外に文脈を残せるようになると、AI agent との長い開発作業はかなり安定します。
文書を増やすためではなく、作業を再開しやすくするために、情報の置き場所を分ける。
miku-soft では、このくらい素朴な運用が、生成AI時代の開発基盤として意外と効いているように感じています。
使用ツール
この記事の整理と更新には、次のツールを使っています。
本文で書いている内容と同じく、記事の Markdown も、直接手で編集するのではなく、対話で方針や言い回しを伝えながら更新しています。
| 種別 | 使用したもの | 用途 |
|---|---|---|
| エディタ | VS Code | 記事 Markdown の確認と作業場所 |
| 生成AI agent | OpenAI Codex プラグイン | 記事構成の整理、本文 Markdown の更新 |
| モデル | GPT-5.5 | 対話による執筆、構成整理、文面調整 |
| Agent Skills | https://github.com/igapyon/igapyon-agent-skills/tree/tag20260430/skills/igapyon-qiita-writer | Qiita 向け記事としての構成、説明粒度、文体の調整 |
想定読者
- 生成AI agent と一緒にソフトウェア開発を進めている人
- README.md、docs/、TODO.md の役割分担に悩んでいる人
- チャットやセッションをまたいで、生成AI駆動開発を再開しやすくしたい人
- 生成AI agent が TODO.md や docs/ を作成して驚いたことがある人
- Git 管理外のローカル作業領域をリポジトリ内で扱いたい人
- 生成AI のクローラーのみなさま