create-readme

README と CHANGELOG の作成

概要

コードベース、Git の履歴、設定ファイルから得られる実証的な根拠に基づいて、プロフェッショナルな README.md と CHANGELOG.md を生成し、生のリポジトリを十分に文書化されたプロジェクトへと変換します。生成されるドキュメント内のすべての記述は、リポジトリ内のファイル、コミット、または設定までたどれる必要があります。

使用するタイミング

• プロジェクトに README または CHANGELOG がない場合。

• 既存のドキュメントが古い、不完全、または一貫性に欠ける場合。

• 新しいバージョンをリリースする前に、変更履歴を最新の状態にする場合。

• プロジェクトを再構成し、既存のドキュメントがアーキテクチャを反映しなくなった場合。

• 新しいコントリビューターを迎える際に、README が「これは何か、どう実行するか、どうテストするか」という疑問に答えていない場合。

• ユーザーがこのスキルを英語で依頼または言及した場合（例：「use /create-readme」、「run create-readme」）。

• ユーザーがこのスキルをポルトガル語で依頼または言及した場合（例：「use /create-readme」、「execute create-readme」）。

使用しないタイミング

• API リファレンスドキュメント — 代わりに OpenAPI/Swagger、TypeDoc、Sphinx、または docfx を使用してください。
• ライセンスファイル — 適切なライセンステキスト（MIT、Apache-2.0 など）を直接コピーしてください。
• 内部コードのドキュメント — docstring、JSDoc、TSDoc、または XML のドキュメントコメントを使用してください。
• アーキテクチャ図 — ビジュアルおよび Markdown によるシステム設計には、architecture スキル（drawio-architecture、mermaid-architecture、およびオプションの archify に振り分けます）を使用してください。
• エージェントハーネスのセットアップ — CLAUDE.md/AGENTS.md とスキルのひな形作成には create-agent-harness を使用してください。

プロセス

フェーズ 1：調査（根拠の収集）

1 行も書き始める前に、対象のリポジトリを分析します。

構造分析：

• ルートディレクトリのツリーとトップレベルのファイル（ls -la、find . -maxdepth 2 -type f）
• エントリーポイントを特定する（main.ts、Program.cs、__main__.py、index.js）
• モノレポか単一パッケージ構成かを判定する

スタックの検出：

• Node.js：package.json（名前、バージョン、スクリプト、依存関係、エンジン）
• .NET：*.csproj、*.sln（TargetFramework、PackageReferences、SDK バージョン）
• Python：pyproject.toml、setup.py、requirements.txt、Pipfile
• Java：pom.xml、build.gradle（groupId、artifactId、Java のバージョン）
• Go：go.mod（モジュールパス、Go のバージョン、依存関係）
• Rust：Cargo.toml（名前、エディション、依存関係）
• Docker：Dockerfile、docker-compose.yml（ベースイメージ、公開ポート、サービス）
• CI/CD：.github/workflows/、.gitlab-ci.yml、Jenkinsfile、azure-pipelines.yml

履歴分析：

• git log --oneline -n 50 — 最近の機能と修正
• git tag --sort=-creatordate | head -10 — 最近のリリース
• git log --since="last tag" --oneline — 未リリースの変更

既存のドキュメント：

• 現在の README.md と CHANGELOG.md（存在する場合）— 有効な内容を再利用する
• docs/ ディレクトリ — 参照するが、内容を重複させない
• LICENSE ファイル — ライセンスの種類を特定する

要件：「調査サマリー」を出力し、以下を含めます：

## Discovery Summary
- **Stack**: [languages, frameworks, versions]
- **Architecture**: [monorepo/single, layers, patterns]
- **CI/CD**: [platforms, pipelines, badges available]
- **Entry points**: [main files]
- **Test command**: [how to run tests]
- **Recent releases**: [last 3 tags]
- **Unreleased changes**: [commits since last tag]
- **Gaps**: [what's missing from current docs]

フェーズ 2 に進む前に、確認を待ちます。

フェーズ 2：README.md の作成

以下の厳密な順序に従って README を生成します。根拠がないセクションは省略し、内容を捏造しないでください。

2.1 タイトルとバッジ

• package.json/*.csproj/pyproject.toml、またはディレクトリ名からプロジェクト名を特定する
• バッジ：CI ステータス（ワークフローファイルから）、ライセンス（LICENSE ファイルから）、バージョン（パッケージマニフェストから）、言語カバレッジ（設定されている場合）
• バッジ形式：[![Name](url)](link)

2.2 プロジェクトの説明

• 1 文の要約（何をするものか、誰を対象とするか）
• 詳細な説明文（機能面および戦略面の概要）
• 根拠：コードコメント、既存のドキュメント、コミットメッセージから導き出し、決して推測しない

2.3 リポジトリ構成

project-root/
├── src/              # Source code
├── tests/            # Test suite
├── docs/             # Documentation
├── .github/workflows # CI/CD pipelines
└── package.json      # Node.js manifest

• トップレベルの各ディレクトリについて、1 行で説明する
• 実際に存在するディレクトリのみを含める

2.4 技術スタック

レイヤー	テクノロジー	バージョン
言語	TypeScript	5.x
フレームワーク	Next.js	15.x
データベース	PostgreSQL	16
CI	GitHub Actions	—

• バージョンは推測ではなく、パッケージマニフェストから確認します
• ランタイム要件（Node のバージョン、Python のバージョン、.NET のバージョン）を含めます

2.5 アーキテクチャ

• レイヤーとパターン（Clean Architecture、DDD、MVC、マイクロサービス）
• システムに相互作用するコンポーネントが3つ以上ある場合は Mermaid 図を含めます
• 根拠：ディレクトリー構造と依存関係グラフから導き出します

2.6 システムフロー

• 主なユースケースの Mermaid シーケンス図／フロー図
• シンプルなシステムの場合は、テキストによる手順の説明
• コードからフローが明らかでない場合にのみ含めます

2.7 はじめに

# Prerequisites
node >= 20.x

# Install
npm install

# Configure
cp .env.example .env  # then edit values

# Run
npm run dev

• 具体的なバージョンを記載した前提条件
• 環境変数（名前のみ。値は記載せず、.env.example へのリンクを含めます）
• パッケージマニフェストまたは Makefile の scripts にあるインストールおよび実行コマンド

2.8 テストとカバレッジ

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

• パッケージマニフェストのスクリプトまたは Makefile にあるコマンド
• 設定されている場合はカバレッジのしきい値（.nycrc、jest.config、coverlet）
• カバレッジレポートが設定されている場合はバッジ

2.9 ビジネス面と技術面

• ビジネス面：戦略目標、対象ユーザー、解決する課題
• 技術面：主な設計上の決定、トレードオフ、制約
• ドキュメント、コメント、またはコミットメッセージに根拠がある場合にのみ含めます

2.10 ライセンスとステータス

• LICENSE ファイルからライセンスの種類を確認します
• プロジェクトのステータス：活発、メンテナンス中、実験的、非推奨（最近のコミット状況に基づきます）
• ライセンス全文へのリンク

2.11 リンク

• 内部参照（docs/、CHANGELOG.md、コントリビューションガイド）
• 存在する場合は外部参照（ホームページ、デモ、API ドキュメント）

2.12 言語別のルーティングと docs/ の構成

英語とポルトガル語のドキュメント構成を作成します。

• README.md — 英語（en-us）。常にメインのランディングページとします。
• README.pt-br.md — README.md のポルトガル語（pt-br）訳。
• docs/en/ — リポジトリの根拠に基づいて作成する、英語の補足ドキュメント。
• docs/pt/ — 同じドキュメントの pt-br 版。

docs/ のルール：

• すべての補足ドキュメントを docs/en/ と docs/pt/ の両方に配置します。
• 各 README の先頭で対応する README にリンクします：README.md では [Português](README.pt-br.md)、README.pt-br.md では [English](README.md)。
• 各 README から、より詳細なドキュメントがある docs/en/ または docs/pt/ にリンクします。
• README.md の内容を docs/ 内に重複して記載しないでください。拡張／補足コンテンツ（例：ARCHITECTURE.md、CONTRIBUTING.md、API.md、INSTALL.md）を配置します。
• リポジトリ内に根拠がある場合にのみドキュメントを作成します。補足ドキュメントを捏造しないでください。
• 両方のフォルダーで同じファイル名を使用します（例：docs/en/CONTRIBUTING.md と docs/pt/CONTRIBUTING.md）。

検討する根拠ベースのドキュメント：

• ARCHITECTURE.md — アーキテクチャパターンまたは図が特定された場合。
• CONTRIBUTING.md — .github/CONTRIBUTING.md またはコミット規約がある場合。
• API.md — プロジェクトが REST／GraphQL API を公開している場合（OpenAPI／Swagger があればリンクします）。
• INSTALL.md — README に記載する内容を超える、プラットフォーム固有のセットアップ手順がある場合。

ルール：

• 該当する場合は既存の内容を再利用し、すでに正しい内容を書き直さないでください
• 具体的な根拠があるセクションのみを含めます
• README.md は常に en-us、README.pt-br.md は pt-br の訳とします
• 補足ドキュメントは docs/en/ と docs/pt/ に配置し、README の内容と重複させないでください
• シークレット、API キー、環境変数の値をハードコードしないでください

フェーズ 3：CHANGELOG.md の作成

Keep a Changelog および SemVer の標準に従います。

3.1 構成

# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- New feature X (commit abc123)

### Fixed
- Bug Y in module Z (commit def456)

## [1.2.0] - 2025-01-15

### Added
- Feature A

### Changed
- Updated dependency B to v2.0

[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/repo/releases/tag/v1.2.0

3.2 カテゴリー

• Added — 新機能
• Changed — 既存機能の変更
• Deprecated — 削除予定の機能
• Removed — 削除された機能
• Fixed — バグ修正
• Security — 脆弱性の修正

3.3 ソース

• git log --since="last tag" --oneline を分析して [Unreleased] の内容を追加します
• コミットのプレフィックス（feat:、fix:、breaking:）を変更履歴のカテゴリに割り当てます
• 過去のバージョンについては、タグ間で git log v1.1.0..v1.2.0 --oneline を使用します
• タグがない場合は、直近50件のコミットから [Unreleased] を作成します

3.4 リンク

• バージョン番号を GitHub の比較 URL にリンクします：https://github.com/{owner}/{repo}/compare/v{prev}...v{curr}
• タグをリリースページにリンクします：https://github.com/{owner}/{repo}/releases/tag/v{version}

フェーズ 4：提出と検証

4.1 ブランチ作成

専用ブランチを作成します：

git checkout -b feature/{YYYYMMDD}-readme-changelog

4.2 リント

• 利用可能であれば Markdown リンター（markdownlint、remark、vale）を実行します
• 内部リンク切れがないか確認します
• Mermaid 図の構文を検証します（含まれている場合）

4.3 コミット

Conventional Commits を使用します：

git commit -m "docs(readme): update README and CHANGELOG

- Add tech stack table from package.json analysis
- Add getting started section with verified commands
- Populate CHANGELOG [Unreleased] from git log since v1.2.0

Generated with [Devin](https://devin.ai)"

4.4 報告

変更内容の概要を提示します：

## Summary
- **README.md**: [created/updated] — en-us primary, added sections X, Y, Z
- **README.pt-br.md**: [created/updated] — pt-br translation
- **docs/en/** and **docs/pt/**: [created/updated] — auxiliary docs by language
- **CHANGELOG.md**: [created/updated] — added [Unreleased] with N entries
- **Evidence**: all claims traced to files/commits in Discovery Summary

PR は自動的に作成しないでください。作成するかどうかは人間のレビュアーに委ねます。

よくある間違い

間違い	影響	修正方法
情報の捏造	README に存在しない機能が記載される	すべての記述をファイル、コミット、または設定で確認できるようにします
汎用テンプレート	README に実際のアーキテクチャが反映されない	Discovery Summary を使って各セクションを調整します
履歴の無視	変更履歴が Git のコミットと一致しない	信頼できる情報源として、タグ間の git log を使用します
シークレットのハードコード	README に API キーやパスワードが含まれる	環境変数名のみを使用し、.env.example にリンクします
古いバッジ	CI バッジが誤ったワークフローを指している	バッジの URL が実際のワークフローファイル名と一致することを確認します
手動での PR 作成	レビューなしで PR が作成される	まず変更内容を要約し、人間が PR を作成できるようにします
言語の誤り	pt-BR のプロジェクトで README が英語になっている	既存ドキュメントの言語に合わせます
	1言語のみ	リポジトリに pt-br の利用者向け資料がない
	ドキュメントと README の重複	docs/en/README.md または docs/pt/README.md が README のコピーになっている

検証チェックリスト

• Discovery Summary を生成し、生成前に確認した
• README に、入手可能な証拠に基づく必須セクションがすべて含まれている
• 捏造または検証不可能な情報を含むセクションがない
• 技術スタックのバージョンがパッケージマニフェストと完全に一致している
• Getting Started のコマンドを scripts／Makefile と照合して検証した
• シークレット、API キー、環境変数の値が含まれていない
• CHANGELOG が「Keep a Changelog」形式に従い、6つのカテゴリすべてを含んでいる
• CHANGELOG の [Unreleased] セクションが、最後のタグ以降の git log と一致している
• バージョンリンクが有効な比較／リリース URL を指している
• Mermaid 図（ある場合）の構文が有効である
• ブランチ名がプロジェクトの規則に従っている
• コミットメッセージが Conventional Commits に従っている
• README.pt-br.md が README.md の pt-br 翻訳として生成されている
• 補助ドキュメント用の docs/en/ と docs/pt/ が存在する
• 言語切り替えリンクが README.md と README.pt-br.md をつないでいる
• docs/ 内に README.md の内容が重複していない

参考資料

• Keep a Changelog
• Semantic Versioning
• Conventional Commits
• Shields.io — バッジの生成
• makeareadme.com — README のベストプラクティス