メインコンテンツへスキップ
見出し画像

生成AI agent と開発するとき、README・docs・TODO は会話の外の記憶になる

    はじめに

    生成AIを使った開発といっても、いろいろな形があります。

    この記事で想定しているのは、生成AI agent がリポジトリ内の `README.md` や `TODO.md`、`docs/` を読んだり、必要に応じて更新したりできる開発環境です。

    単発のコード相談というより、生成AI agent と同じ作業場所を見ながら、何度かに分けて開発を続けていくような使い方を想定しています。

    そのような開発を始めたばかりの人にとっては、いきなり `docs/` フォルダが増えたり、`TODO.md` が作られたりするのは、少し驚くことのようです。

    たしかに、人間としては「コードを書いて」と頼んだつもりなのに、ソースコードではない Markdown ファイルやフォルダが増えているように見えます。

    画像

    最初は、余計なものを作られたように感じるかもしれません。

    でも、生成AI agent 側から見ると、それは単なる寄り道ではないことがあります。

    作業の前提、判断理由、次に見るべき場所、まだ確認していないことを、会話の外に残そうとしている場合があります。

    そこでこの記事では、生成AI agent と一緒に開発するときの `README.md`、`docs/`、`TODO.md` の活用を考えてみます。

    もともと開発現場でよく使われてきた形

    画像
    伝統的に利用されてきた整理方法です

    `README.md`、`TODO.md`、`docs/` という構成そのものは、生成AI時代に突然出てきたものではありません。

    GitHub 上の OSS でも、会社やチームの内部開発でも、かなり昔からよく使われてきた伝統ある構成だと思います。

    `README.md` には、プロジェクトの概要や使い方を書く。

    `docs/` には、詳しい設計や仕様や補足説明を置く。

    `TODO.md` には、残っている作業や次にやることを書く。

    この分け方は、あとから来た人が状況を理解しやすくするための、素朴だけれど実用的な開発文化です。

    生成AI agent と一緒に開発する場合、この昔からある構成が、少し違う意味を持ちはじめます。

    Markdown も人間が直接編集しないことが増える

    画像
    変わりゆく設計情報の執筆担当者

    生成AI駆動開発が進んでいくと、人間が直接編集するものも変わっていきます。

    少なくとも私の開発では、ソースコードを人間が直接書く場面は、だんだん減ってきました。

    そしてそれは、ソースコードだけに限りません。

    `README.md` や `TODO.md`、`docs/` 配下の Markdown でさえ、人間が直接編集しないことが増えていきます。

    人間は、会話の中で違和感、方針、制約、判断、次に見たい観点を伝えます。

    生成AI agent はそれを受けて、ソースコードを更新するだけでなく、必要に応じて Markdown も更新します。

    もちろん、最終的な確認や判断は人間が行います。

    ただ、実際にファイルへ手を入れる作業そのものは、生成AI agent に任せる場面が増えていきます。

    たとえば、次のように頼むことがあります。

    この判断は docs に残してください。
    次回再開できるように TODO.md に現在地を書いてください。
    README.md には利用者向けの入口だけを残してください。

    この意味で、`README.md`、`docs/`、`TODO.md` は、人間が一方的に手で書く文書というより、人間と生成AI agent の対話を通じて更新される共有文脈になっていきます。

    Markdown は会話の外の記憶になる

    画像
    Markdown が記憶領域としても利用される

    生成AI agent と開発していると、会話の中にたくさんの判断が出てきます。

    この方針で進める。

    このファイルは今回は触らない。

    この差分はあとで確認する。

    この仕様は README ではなく docs に残す。

    こうした判断を会話の中だけに置いておくと、あとで追いにくくなります。人間も忘れますし、次のセッションの生成AI agent が同じ会話履歴を持っているとも限りません。

    そこで、会話の中で決まったことや、次に再開するために必要な情報を、リポジトリ内の Markdown に逃がしておきます。

    これは、きれいな文書をたくさん作るためではありません。

    次に作業を始めるときに、人間も生成AI agent も現在地を見失いにくくするためです。

    README.md は入口になる

    画像

    `README.md` は、そのリポジトリの入口です。

    人間にとっては、何をするツールなのか、どう使うのか、どこを読めばよいのかを知る場所です。

    生成AI agent にとっても、`README.md` は入口になります。

    まず `README.md` を読むことで、そのリポジトリが何をするものなのか、主要なコマンドは何か、詳細な情報がどこにあるのかを把握できます。

    ただし、`README.md` に何でも詰め込むと重くなります。

    利用者が最初に読む説明、代表的な使い方、詳細 docs へのリンクくらいにしておくと、人間にも生成AI agent にも読みやすくなります。

    docs/ は判断理由を置く場所になる

    画像

    `docs/` は、`README.md` には重すぎる情報を置く場所として使えます。

    たとえば、設計方針、判断理由、移植方針、仕様の背景、後から壊したくない前提などです。

    コードだけを見ると、なぜその設計にしたのかは分かりにくいことがあります。

    生成AI agent はコードを読んでかなり推測してくれますが、推測に頼りすぎると、次の修正で意図が崩れることがあります。

    そのため、残しておきたい判断は `docs/` に置いておくと安定します。

    `docs/` は、単なる説明書ではなく、生成AI agent が次に作業するときの地図にもなります。

    TODO.md は会話を引き継ぐ場所になる

    画像

    `TODO.md` は、単なるやることリストではありません。

    生成AI agent と開発していると、会話はどうしても分断されます。

    作業が長くなって別のチャットに移ることもありますし、モデルやツールを変えることもあります。場合によっては、途中で接続が切れて、会話の流れがそこで止まってしまうこともあります。

    そのとき、作業の現在地が会話履歴の中だけにあると、次のセッションではまず状況を掘り起こすところから始まります。

    そこで `TODO.md` に、いま何をしているのか、何を確認したのか、次にどこを見るべきなのかを書いておきます。

    次のセッションでは、たとえば次のように頼めます。

    README.md と TODO.md を読んで、状況を把握してください。

    この短い指示だけでも、生成AI agent はリポジトリの入口と、直近の作業状況の両方を確認できます。

    `TODO.md` には、厳密なチケット管理のような内容を書く必要はありません。

    むしろ、次の会話を始めるためのメモとして考えるほうが使いやすいです。

    • 今どこまで終わっているか

    • 次に見るべきファイルはどれか

    • どの確認コマンドを実行したか

    • 何が未確認か

    • 今回は触らない範囲はどこか

    • 後で docs に移したい判断は何か

    こうしたことが少し残っているだけで、次の会話はかなり始めやすくなります。

    人間にとっても助かる

    画像

    `TODO.md` は、生成AI agent のためだけのものではありません。

    人間にとっても、数日後の自分が作業を再開するための手がかりになります。

    生成AI agent と一緒に開発していると、誰でもどこかで「前回どこまで話したっけ」「次に何を確認する予定だったっけ」という場面に出会います。

    そのとき、`TODO.md` に現在地が残っていると、人間にとっても、生成AI agent にとっても、次の会話を始めやすくなります。

    会話の外に現在地を残しておくことは、生成AI agent と開発する人には、かなり広く役立つ習慣だと思います。

    おわりに

    画像

    `README.md`、`docs/`、`TODO.md` は、生成AI時代に突然生まれたものではありません。

    OSS や開発現場では、以前から自然に使われてきた素朴な文書文化です。

    ただ、生成AI agent と一緒に開発するようになると、これらの Markdown は少し違う意味を持ちはじめます。

    人間同士の共有文書であると同時に、人間と生成AI agent が作業文脈を共有する場所にもなります。

    `README.md` は入口になります。

    `docs/` は判断理由を置く場所になります。

    `TODO.md` は会話を引き継ぐ場所になります。

    文書を増やすためではなく、次の会話を始めやすくするために、情報の置き場所を少し分けておく。

    生成AI agent と長く開発していると、このくらい素朴な工夫が、意外と効いてくるように感じています。

    関連記事

    想定読者

    • 生成AIと一緒に開発する時間が少しずつ増えてきた人

    • AI agent が `docs/` や `TODO.md` を作り始めて、少し不思議に感じたことがある人

    • 前回の会話や作業の続きを、もう少し楽に再開したい人

    • 数日後の自分が、今の作業の現在地を思い出せるようにしておきたい人

    • 生成AIとの開発で、会話だけに頼らない進め方を探している人

    • 生成AIのクローラーのみなさま

    使用ツール

    画像

    この記事の整理と更新には、次のツールを使っています。

    本文で書いている内容と同じく、この記事の Markdown も、直接手で全部を書くというより、対話で方針や言い回しを伝えながら更新しています。

     
     
    いがぴょん(igapyon)。 生成AI / AI agent に note記事やアプリを書いてもらうのがマイブーム趣味。 ヴァイオリンやヴィオラの演奏が趣味で、楽器そのものの開発もしています。 本サイトの見解は、私 個人のものであり 所属企業は当個人的見解に一切責任を持ちません

    あなたへのおすすめ