AIと作るREADMEの書き方
はじめに
README は新規チームメンバー、外部コントリビューター、未来の自分が最初に読むドキュメントです。AI に README 作成を任せるときは、正確な情報とプロジェクト特有の判断が必要です。本記事では、AI と一緒に README を作る方法を解説します。
README の基本構成
# プロジェクト名
ワンライナーで何のプロジェクトか説明
## 概要
2-3 段落で詳細説明
## インストール
セットアップ手順
## 使い方
基本的な使用例
## 開発セットアップ
開発者向けの環境構築
## テスト
テスト実行方法
## 制約・既知の問題
制限事項、今後の改善予定
## ライセンス
ライセンス情報
AI に README を作らせるときの情報提供
ステップ1：プロジェクト情報を整理
人間が準備すべき情報：
1. プロジェクトの目的
- 何を解決するのか
- ターゲットユーザーは誰か
- なぜこのプロジェクトが必要か
2. 技術スタック
- 言語、フレームワーク
- DB、API、外部サービス依存
3. セットアップ手順
- 前提条件
- インストール手順
- 初期設定
4. 使用例
- よくあるユースケース
- コード例
5. 制約・既知の問題
- サポート対象外
- バグ、今後の改善予定
- パフォーマンス制限
ステップ2：ChatGPT に README ドラフトを作成させる
ChatGPT への依頼：
「以下のプロジェクト情報に基づいて、
README.md を作成してください。
【プロジェクト名】
AI-assisted development tool
【目的】
個人開発者が AI（Claude Code、ChatGPT）を
安全かつ効率的に使うための実務ガイド
【対象ユーザー】
プログラミング経験 1 年以上の個人開発者
【内容】
- AI ツールの紹介
- ベストプラクティス集
- 実装例
- トラブルシューティング
【技術】
- Astro（静的サイトジェネレータ）
- Markdown（コンテンツ）
- GitHub Pages（公開）
【セットアップ】
npm install
npm run dev
【使い方】
localhost:3000 でローカルサーバー開始
以下の構成で README を作成：
# [プロジェクト名]
## 概要
## インストール
## 使い方
## 開発方法
## 制約
## ライセンス
」
ステップ3：ChatGPT のドラフトを人間が修正
ChatGPT が作成したドラフト例：
# AI-assisted development tool
このプロジェクトは、個人開発者が AI を
安全かつ効率的に使うためのガイドです。
## インストール
npm install でインストール
## 使い方
npm run dev でローカルサーバー開始
...
人間が確認すべき点：
❌ 「AI を安全に使う」が曖昧
✅「Claude Code と ChatGPT の役割分担」に具体化
❌ 「ガイド」が曖昧
✅「実装パターン 20 個とトラブルシューティング集」に具体化
❌「セットアップ」だけ
✅「必要な環境、Node.js バージョン要件」を追加
セクション別の注意点
概要セクション
❌ 曖昧な説明：
「AI を使った開発ガイド」
✅ 具体的な説明：
「Claude Code と ChatGPT を組み合わせて、
個人開発の生産性を 3 倍に高めるための
実務的なベストプラクティス 25 個」
インストール セクション
❌ 不完全：
npm install
✅ 完全：
## インストール
### 前提条件
- Node.js 18.0 以上
- npm 9.0 以上
- Git
### ステップ
1. リポジトリをクローン
git clone https://github.com/...
2. 依存パッケージをインストール
npm install
3. 環境変数を設定
cp .env.example .env
.env を編集
### 確認
npm run dev で localhost:3000 に接続可能か確認
使い方 セクション
❌ 不十分：
npm run dev で開始
✅ 充実：
## 使い方
### ローカル開発
npm run dev
http://localhost:3000 でアクセス
### 本番ビルド
npm run build
dist/ に静的ファイルが生成
### 記事を追加
1. src/content/articles/ に Markdown ファイルを作成
2. frontmatter に title, slug, category を指定
3. npm run build で自動生成
4. git commit して完成
### 例
[具体的なコマンド例]
制約・既知の問題 セクション
## 制約・既知の問題
### 現在の制限
- 記事数上限なし
- 検索機能未実装（Issue #42）
- ダークモード対応予定（Issue #43）
### 既知バグ
- 環境によって build 失敗することあり（Issue #50）
→ Node.js 18.0 を使用すると解決
### パフォーマンス
- 記事 1000 個超えでビルド時間が 30 秒以上（Issue #51）
- 静的サイトのため実行時パフォーマンスは影響なし
### サポート対象外
- Windows での開発（Linux/macOS 推奨）
- IE 11 以下のブラウザ
### 今後の改善予定
- Issue リストを参照
AI に任せて OK な部分 vs 人間が確認すべき部分
【AI に任せて OK】
- フォーマット・整形
- 段落の文体統一
- マークダウン記法
【人間が確認すべき】
- 技術的正確性
- プロジェクト固有の情報
- セキュリティ情報（API キーなど記載していないか）
- バージョン番号（最新か確認）
- リンク切れ（docs へのリンク確認）
- 制約・既知の問題（漏れなく記載）
実際のワークフロー
【ステップ1】人間がプロジェクト情報を整理
【ステップ2】ChatGPT がドラフト作成
【ステップ3】人間が確認・修正
- 技術的正確性確認
- プロジェクト固有情報追加
- 既知の問題・制約確認
【ステップ4】Claude Code でコード例を追加
- 実装例を README に組み込み
【ステップ5】最終確認と公開
- リンク切れ確認
- Version 情報確認
- git commit
README の品質チェックリスト
【基本情報】
- [ ] プロジェクト名が明確か
- [ ] ワンライナーで説明できるか
- [ ] 対象ユーザーが明記されているか
【セットアップ】
- [ ] 前提条件が全て記載されているか
- [ ] ステップが実行可能か
- [ ] バージョン要件が明記されているか
【使い方】
- [ ] 基本的な使用例がコピー&ペースト可能か
- [ ] 一般的なユースケースがカバーされているか
【開発】
- [ ] 開発環境セットアップが明確か
- [ ] テスト実行方法が記載されているか
【制約】
- [ ] 既知の問題が全て記載されているか
- [ ] 未実装機能が明記されているか
- [ ] パフォーマンス制限が記載されているか
【保守性】
- [ ] Issue リンクが正確か
- [ ] 外部ドキュメントへのリンク切れないか
- [ ] Version 番号が最新か
まとめ
AI と一緒に README を作るコツ：
AI の役割：
- ドラフト作成
- フォーマット・整形
- 段落の統一
人間の役割：
- 情報の正確性確認
- プロジェクト固有の詳細追加
- 制約・既知の問題の記載
- 最終承認
チェックリスト：
- セットアップが実行可能か
- 使用例がコピー&ペースト可能か
- 既知の問題が全て記載されているか
AI 開発で作業ログを残すメリットと合わせることで、プロジェクトの全貌が新規メンバーに一目瞭然になります。