README ジェネレーター
コードベースを解析し、的確な質問を投げかけることで、社内/チームのコードリポジトリ向けに洗練された包括的なREADME.mdファイルを作成します。
このスキルが存在する理由
優れたREADMEはコードベースの玄関です。特に内部プロジェクトでは、READMEがない、または薄いと、新しいチームメンバーがプロジェクトの内容、実行方法、参照すべき場所を把握するまでに何時間も費やすことになります。このスキルは面倒な作業を自動化します。コードを読み取り、推測できることは推測し、推測できないことは質問し、開発者がすぐに生産的になれるREADMEを生成します。
ワークフロー
ステップ1: コードベースを解析する
ユーザーに質問する前に、構造化された4フェーズの分析を実行して、可能な限り多くのコンテキストを収集します。これによりユーザーの負担が軽減されます。ユーザーは不足している情報だけを埋めればよく、既に確認できることを説明する必要はありません。
発見した事実にはすべて信頼度ラベルを付けます: [confirmed](ソースから読み取り)、[inferred-high](強力な証拠)、[inferred-low](部分的な証拠)、[unknown]。信頼度が低い、または不明な内容は、ステップ2の明確化質問になります。
詳細なツールアクション、grepパターン、抽出チェックリスト、レコードテンプレートについては、references/analysis-phases.md を参照してください。
フェーズ1 — プロジェクトメタデータスキャン: パッケージマネージャーファイル(pyproject.toml、package.json など)、envテンプレート、Dockerfile、CI/CD設定、ツールチェーンファイルをグロブ検索します。それぞれを読み取り、プロジェクト名/バージョン、言語、依存関係(目的別に分類)、スクリプト/コマンド、環境変数(必須 vs オプション)、CIステージ、ライセンスを抽出します。
フェーズ2 — アーキテクチャスキャン: すべてのソースファイルをグロブ検索してディレクトリ構造をマッピングします。エントリポイントマーカー(if __name__、main() など)をgrepで検索し、各エントリポイントを読み取ります。すべてのソースファイルにわたってimport文をgrepで検索し、インポートグラフを構築します。モジュールをコア(入次数が高い)、リーフ、オーケストレーターに分類します。インジケーターチェックリストを使用してアーキテクチャパターン(パイプライン、MVC、階層型、マイクロサービス、イベント駆動、CLI、モノリス)を特定します。設定読み込みパターンをgrepで検索し、ランタイム設定ファイルを見つけます。
フェーズ3 — 深いモジュール分析: 重要なソースファイルをそれぞれ読み取ります(優先順位: コア → エントリポイント → 最大 → 残り)。各ファイルについて、目的(一文)、主要なエクスポートとシグネチャ、設計ノート(自明でない決定、エッジケース、慣例)、内部依存関係を抽出します。インポートグラフを通じて主要なワークフローをエンドツーエンドでトレースし、モジュール間でどのようなデータ型が流れているかをラベル付けします。ソースファイルが8つ以上のコードベースでは、依存関係クラスターごとに並列サブエージェントをディスパッチします。
フェーズ4 — サポートインフラストラクチャスキャン: テストファイルとフィクスチャをグロブ検索します。各テストファイルの最初の30~50行を読み取り、テストとモジュールのマッピングを構築します。カスタム例外クラスと raise 文をgrepで検索し、エラー階層をマッピングします。テンプレート、アセット、既存のドキュメントをスキャンします。トラブルシューティングテーブル用の一般的なエラーシナリオを抽出します。
ステップ2: 明確化の質問をする
分析後、確信を持って推測できなかった事項についてユーザーに質問します。既にわかっていることを質問しないよう、焦点を絞ってください。よくあるギャップ:
- プロジェクトの目的: このプロジェクトはどの問題を解決しますか?誰が使いますか?(コードから自明でない場合)
- セットアップの落とし穴: 自明でない前提条件、VPN要件、内部パッケージレジストリ、データベースセットアップ手順はありますか?
- 主要なワークフロー: 開発者がこのプロジェクトで最も頻繁に行う2~3の操作は何ですか?
- デプロイ: これはどのように/どこにデプロイされますか?(CI/CD設定から明確でない場合)
- チームの慣例: 命名規則、ブランチ戦略、パターンなどで言及すべきものはありますか?
- 連絡先情報: このプロジェクトの所有者/メンテナーは誰ですか?(連絡先セクション用に名前+メール)
質問は簡潔に提示します。コードベースが単純で分析に自信がある場合は、質問は1~2個、あるいは0個でも構いません。判断してください。
ステップ3: README.md を生成する
以下の構造とガイドラインに従ってREADMEを作成します。
README構造
これをテンプレートとして使用します。すべてのセクションを含めますが、プロジェクトの複雑さに合わせて深さを調整します。主要なセクション間には --- 水平線を使用して視覚的な区切りを作ります。
# Project Name
  
簡潔で明確な説明。キーテクノロジーや製品タイプを **太字** で強調します。
---
## 目次
すべての ## および ### 見出しを含む、詳細なネストされた目次を生成します。サブセクションは親の下にインデントし、読者が全体像を一目で把握できるようにします。これは特に長いREADMEで重要です。目次はナビゲーションツールであると同時に文書全体のアウトラインとして機能します。
期待される深さの例:
- [概要](#概要)
- [アーキテクチャ](#アーキテクチャ)
- [高レベルアーキテクチャ](#高レベルアーキテクチャ)
- [フォルダ構造](#フォルダ構造)
- [モジュール依存関係グラフ](#モジュール依存関係グラフ)
- [はじめに](#はじめに)
- [前提条件](#前提条件)
- [インストール](#インストール)
- [テストの実行](#テストの実行)
- [環境変数](#環境変数)
- [使用方法](#使用方法)
- [例: 主要なユースケース](#例-主要なユースケース)
- [例: 二次的なユースケース](#例-二次的なユースケース)
- [APIリファレンス](#apiリファレンス)
- [リソースA](#リソースa)
- [リソースB](#リソースb)
- [トラブルシューティング](#トラブルシューティング)
- [連絡先](#連絡先)
- [ライセンス](#ライセンス)
文書内のすべての ### 見出しは、親の ## 見出しの下にインデントされたエントリとして表示される必要があります。サブセクションを省略しないでください。徹底的な目次の目的は、読者が文書の任意の部分に直接ジャンプできることです。
---
## 概要
説明を詳しく展開します。キーワードを太字にします。複数ステップのプロセスには番号付きリストを使用します。
---
## アーキテクチャ
### 高レベルアーキテクチャ
```mermaid
graph TD
...
```
フォルダ構造
project-root/
├── src/ # 簡単な注釈
├── tests/ # 簡単な注釈
└── ...
[データフロー / パイプライン / モジュール依存関係 — 追加の図]
...
はじめに
前提条件
インストール
テストの実行
環境変数
| 変数 | 必須 | 説明 |
|---|---|---|
DB_URL | はい | PostgreSQL接続文字列 |
使用方法
最も一般的な2~3の操作に対する実際のコード例。
APIリファレンス
トラブルシューティング
| 症状 | 考えられる原因 | 修正方法 |
|---|---|---|
エラーメッセージ | 何が問題か | 修正方法 |
連絡先
質問やサポートについては、以下までご連絡ください:
- 名前 — [email protected]
ライセンス
内部使用のみ – 会社名
プロプライエタリソフトウェア。© [年] [会社]。全著作権所有。
## Shields.io バッジ
`# Title` 見出しの直後には必ずshields.ioバッジを追加します(言語、フレームワーク、主要ライブラリ、パッケージマネージャー、データベース、インフラストラクチャをカバーする3~6個)。フォーマット、例、カテゴリ別の色提案については、[references/badge-reference.md](references/badge-reference.md) を参照してください。
## Mermaid図のガイドライン
Mermaid図を積極的に使用します。これらはアーキテクチャ、データフロー、プロセスを即座に理解可能にします。一般的なREADMEには**3~6個**の図を含めます。複雑なプロジェクト(データパイプライン、マルチサービスシステム)では**6~10個以上**になる場合があります。各図タイプの使用タイミング、ベストプラクティス、プロジェクトタイプ別の推奨事項については、[references/mermaid-guidelines.md](references/mermaid-guidelines.md) を参照してください。
## ライティングガイドライン
- **一般的な表現よりも具体的な表現を。「開発サーバーを起動する」ではなく「`npm run dev` を実行する」。実際のコマンド、ファイルパス、変数名を含めます。
- **新しいチームメンバーに向けて書きます。** 一般的なエンジニアリングスキルは想定しますが、プロジェクトコンテキストはゼロと想定します。
- **キーワードや製品名は、初出時および概要で太字にします。** 読者のスキャンに役立ちます。
- **順序のあるプロセスには番号付きリストを使用します。「1. Xからデータを**抽出**する。2. それを**変換**する。3. Yに**ロード**する。」— 動詞を太字にします。
- **コード例は実行可能であること。** 可能な限り実際のコードベースからコピーします。
- **環境変数テーブルは必須です。** すべての変数をリストします。
- **トラブルシューティングはテーブル形式(症状 | 考えられる原因 | 修正方法)** — スキャン可能で一貫性があります。
- **フォルダ構造の注釈は簡潔に。** ディレクトリごとに短いフレーズ1つ。
- **必ず連絡先セクションを含めます。** プロジェクトのメンテナーをユーザーに尋ねます。フォーマット: `**名前** — [email protected]`。
- **すべての主要セクション間には `---` 水平線を使用します。** 視覚的な構造のためです。
## 出力
READMEをリポジトリのルート(またはリポジトリルートが特定できない場合は現在の作業ディレクトリ)に `README.md` として保存します。既存のREADME.mdが存在する場合は、上書きする前にユーザーに確認します。ユーザーが一部を保持したい可能性があるためです。