readme-maker

@rules/project-discovery.md @rules/section-design.md @rules/validation.md @references/readme-templates.md

README 作成ツール

プロジェクトを注意深く調査し、そのプロジェクトにふさわしい README を作成します。

<output_language>

ユーザー向けの成果物、保存済みアーティファクト、レポート、計画、生成ドキュメント、要約、引き継ぎメモ、コミット／メッセージの草案、検証メモは、元のスキルファイルが英語で書かれていても、デフォルトですべて韓国語にしてください。

ソースコードの識別子、CLI コマンド、ファイルパス、スキーマキー、JSON／YAML のフィールド名、API 名、パッケージ名、固有名詞、引用したソースの抜粋は、指定された言語または原文のまま保持してください。

ユーザーが明示的に別の言語を指定した場合、既存の対象アーティファクトの一貫性を保つため別の言語を維持する必要がある場合、または機械可読な契約で正確な英語のトークンが要求される場合に限り、別の言語を使用してください。ローカライズ済みのテンプレートやリファレンス（例：*.ko.md や *.ko.json）がある場合は、ユーザー向けアーティファクトにそれを優先して使用してください。

</output_language>

• 定型文ではなく、実際のコードベースに基づいたプロジェクトの README.md を作成します。
• 古くなった README や汎用的な README を改訂し、インストール方法、使用方法、構成、例を現在のコードに合わせます。
• プロジェクトの形態（CLI、ライブラリ、ウェブアプリ、モノレポ、プラグイン、フレームワーク、ドキュメントサイト、サービス）に応じて、セクションの選択と詳しさを調整します。
• 根拠を明確にします。インストールコマンド、スクリプト、バッジ、例はすべてリポジトリ内のファイルに基づいている必要があります。

<routing_rule>

主な成果物がプロジェクト、ライブラリ、CLI、プラグイン、ワークスペース、フレームワーク、ドキュメントサイト、サービスのルートまたはサブパッケージの README.md である場合は、readme-maker を使用してください。

関連する作業は、出力の形態に応じて別の方法に振り分けてください。

• 一般的なドキュメント、運用手順書、手順のベース、ハーネスルールのパックは README ではなく、ドキュメントアーティファクトです。
• プロダクト計画一式（PRD、図、機能仕様、ユーザーフロー、ワイヤーフレーム）は計画アーティファクトです。
• SEO／AEO／GEO 監査やマーケティングページの最適化は、検索最適化アーティファクトです。
• README アーティファクトを作成しない純粋な事実調査は、リサーチタスクです。
• バージョン更新やリリースノート一式は、リリースアーティファクトです。
• 完成した README のコミットは、README の執筆ではなく、バージョン管理の作業です。

次の場合は readme-maker を使用しないでください。

• ユーザーが CHANGELOG.md、CONTRIBUTING.md、LICENSE、その他 README 以外のファイルだけを求めている場合
• ユーザーがソースコードの編集、リファクタリング、機能実装を求めており、README への言及は付随的なものにすぎない場合
• ユーザーが README アーティファクトを必要とせず、外部の最新情報の調査を求めている場合
• ユーザーが AI 向けの指示ドキュメントやハーネスルールのパックを求めている場合（これらはドキュメントアーティファクトです）

</routing_rule>

<instruction_contract>

項目	契約
意図	対象プロジェクトの実際の構成、インストール方法、使用方法、制約を反映した README.md を作成または改善します。
範囲	対象の README.md（ルートまたはパッケージ）と短い概要を担当します。ユーザーから依頼がない限り、ソースコード、設定、ライセンス、無関係なドキュメントは編集しません。
優先順位	ユーザーの指示とプロジェクト内のドキュメント（AGENTS.md、CLAUDE.md、ルートの README、パッケージマニフェスト）は、一般的な README の慣例や外部テンプレートより優先されます。
根拠	インストールコマンド、スクリプトの実行方法、ファイルパス、バッジ、機能に関する記述は、すべてプロジェクト内の実在するファイルを根拠にします。コマンドや API を捏造しません。
ツール	プロジェクト内でのみ、読み取り／編集／書き込みとシェル検索（find、grep、ls）を使用します。README の作成中に、インストール、ビルド、デプロイ、リリースのコマンドは実行しません。
作業サイクル	なし。依頼ごとに1回だけ作業します。プロジェクトの調査、セクションの計画、草案の作成、検証、報告を行い、その後は停止します。ユーザーから別の README の作成やセクションの更新を依頼された場合にのみ、再度実行します。
出力	作成または更新した README.md を1つと、調査したファイルおよび変更したセクションを記した短い概要を出力します。
検証	完了前に、rules/validation.md に記載されたプロジェクト調査、構成、言語、根拠の各チェックを実行します。
停止条件	チェックに合格し、不確かな記述に `` の印が付けられたら完了です。プロジェクトの構成が曖昧な場合、ライセンスが不明な場合、またはリポジトリからコマンドを検証できない場合は、エスカレーションします。

</instruction_contract>

<activation_examples>

肯定的な例：

• 「このプロジェクトをよく調べて、README.md を作成してください。」
• 「現在の CLI コマンドに合うように README を書き直してください。」
• 「このモノレポの packages/color ワークスペース用に README を作成してください。」
• 「新しいエントリーポイントに合わせて README のインストール方法と使用方法のセクションを更新してください。」
• 「프로젝트 README.md 만들어줘.」（韓国語での作成依頼。対象となります。）
• 「이 저장소를 꼼꼼히 읽고 README를 다시 써줘.」（韓国語での書き直し依頼。対象となります。）

否定的な例：

• 「コミットログから CHANGELOG を作成してください。」出力はリリース成果物であり、README ではありません。
• 「このライブラリの API ドキュメントを書いてください。」出力はドキュメント成果物であり、README ではありません。
• 「このプロジェクトの次のリリースを計画してください。」出力は計画成果物であり、README ではありません。
• 「이 코드베이스에 새 기능을 추가해줘.」（韓国語での機能追加依頼。README 作成ではありません。）

境界の例：

• 「このプロジェクトのドキュメントを書いてください。」 出力が README.md の場合にのみ readme-maker を使用します。ガイド、ランブック、手順書はドキュメント成果物のため、対象外です。
• 「この README を書き直して、変更をコミットしてください。」 README 自体には readme-maker を使用します。その後のコミットは、README 作成とは別のバージョン管理操作です。
• 「이 README 리팩터하고 커밋도 같이 해줘.」（韓国語での境界例。まず readme-maker で README を作成し、その後、別のバージョン管理操作としてコミットします。）

</activation_examples>

<trigger_conditions>

状況	モード
プロジェクトに README.md がない	作成
README.md が存在するが、古い、一般的すぎる、または現在のコードと矛盾している	書き直し
機能追加、名称変更、移動後に特定のセクションを更新する必要がある	更新
モノレポ内のサブパッケージまたはワークスペースに専用 README が必要	作成
README を基本的に韓国語にそろえる必要がある、または明示的に指定／既存のドキュメント言語を維持する必要がある	書き直し

</trigger_conditions>

<supported_targets>

• アプリ、ライブラリ、CLI、プラグイン、フレームワーク、ドキュメントサイト、サービスのルート README.md。
• モノレポのワークスペース内にあるパッケージレベルの README.md。
• 現在のコードをもとに各セクションを再構成する README の書き直し。
• インストール方法、使用方法、設定、スクリプト、例、プロジェクト構成に関する README の更新。
• 基本的に韓国語にそろえる対応。ただし、ユーザーが別の言語を指定した場合、または既存の README と整合させる必要がある場合に限り、その言語を維持します。

</supported_targets>

| フェーズ | タスク | 出力 | |------|------|------| | 0 | 成果物が `README.md` であることを確認し、`create`／`refactor`／`update` を選択する | モードの決定 | | 1 | プロジェクト構造を確認し、形状を検出する（`rules/project-discovery.md`） | プロジェクトのプロファイル | | 2 | 既存の README、`AGENTS.md`、`CLAUDE.md`、ライセンス、マニフェスト、エントリーポイントを読む | 根拠となる情報 | | 3 | セクション、順序、詳しさ、韓国語を既定とする言語の扱い方を選ぶ（`rules/section-design.md`） | セクション計画 | | 4 | 根拠のある例と、韓国語を既定とするテンプレート（`references/readme-templates.md`／`.ko.md`）を使って `README.md` を作成またはリファクタリングする | 更新された README | | 5 | 検証チェック（`rules/validation.md`）を実行し、完了の概要を作成する | 最終版 README と概要 |

フェーズ 4 の執筆ルール

• 先に読み、後から書きます。インストールコマンド、スクリプト、環境変数、API を決して捏造しないでください。
• README の本文は、既定で韓国語で書きます。ユーザーが別の言語を指定した場合、または既存の対象 README のドキュメント言語を維持する必要がある場合に限り、別の言語を使用してください。
• 憶測に基づく例を 3 つ挙げるより、正確な例を 1 つ示してください。
• README はざっと把握できる構成にします。タイトル、説明、インストール、クイックスタートは最初に表示される範囲に配置してください。
• 長い詳細解説は README から移動してリンクします。README の目的は概要を伝えることであり、網羅することではありません。
• プロジェクトで既に公開されている場合を除き、検証できないバッジ（CI ステータス、カバレッジ、npm のバージョン）を追加しないでください。

create モード

• プロジェクトのプロファイルを起点に、適合するテンプレートを選びます。既定では references/readme-templates.md を韓国語に翻訳するか、利用可能な場合は references/readme-templates.ko.md を使用します。
• リポジトリ内に実際の根拠があるセクションのみを含めます。
• 不明な情報は捏造せず、`` を使って明示します。

refactor モード

• 正しい既存の内容を維持し、コードから逸脱したセクションのみを書き換えます。
• インストール、使用方法、スクリプト、構造に関するセクションは、現在のファイルを基に再検証します。
• 有効なリンク、バッジ、本文は維持し、無効なリンクや古いコマンドは削除します。

更新モード

• ユーザーが指定したセクション、または差分から変更が必要だと判断できるセクションのみを編集します。
• プロジェクトの README に変更履歴がすでにある場合に限り、日付付きの項目を追加します。

カテゴリ	避けること
捏造	リポジトリに存在しないインストールコマンド、スクリプト、環境変数、API
内容の乖離	古いスクリーンショット、リンク切れ、非推奨コマンドの放置
情報過多	API リファレンス全体、長いチュートリアル、設計ドキュメントを README に埋め込むこと
トーン	マーケティング的な誇張、曖昧な最上級表現、コードが裏付けていない誇大表現
副作用	README の作成中にソースコード、設定ファイル、ライセンスを編集すること
余分なファイル	ユーザーから依頼されない限り、CHANGELOG.md、CONTRIBUTING.md などのドキュメントを作成すること

カテゴリ	必須事項
根拠	インストール／使用方法に関するすべての記述は、リポジトリ内のマニフェスト、スクリプト、ソースファイル、または既存ドキュメントに基づいていること
構成の一致	セクションの選定が、検出されたプロジェクトの種類に合っていること
言語の一致	README の本文はデフォルトで韓国語とするか、対象言語の維持が必要な場合はユーザーが指定した言語または既存の対象言語に合わせること
見つけやすさ	タイトル、一文の説明、インストール方法、クイックスタートを冒頭に配置すること
検証	完了を報告する前に検証チェックリストを実施すること

<structure_blueprint>

デフォルトの韓国語 README の構成（references/readme-templates.md／.ko.md に従い、プロジェクトの種類に応じて調整します）：

1. タイトル＋一文の説明
2. 任意のバッジ（検証可能なもののみ）
3. 特徴または主なポイント（箇条書きで最大3～7項目）
4. インストール
5. クイックスタート／使用方法
6. 設定／環境
7. コマンドまたは API サーフェス（CLI、ライブラリ、プラグイン）
8. 例
9. 開発（ビルド、テスト、開発サーバー、スクリプト）
10. プロジェクト構成（複雑な場合のみ）
11. 貢献（プロジェクトで手順が文書化されている場合のみ）
12. ライセンス

</structure_blueprint>

チェック項目	ルール
根拠	README 内の各コマンドとパスがリポジトリに存在すること
構成	選択したテンプレートが実際のプロジェクトの種類に合っていること
言語	README はデフォルトで韓国語とし、韓国語以外の出力はユーザーから明示的な依頼がある場合、または既存の対象言語を維持する場合に限ること
冒頭への配置	タイトル、説明、インストール方法、クイックスタートが最初の画面内に表示されること
捏造なし	API、スクリプト、環境変数、外部バッジを新たに作り出していないこと
簡潔な本文	長い内容は埋め込まず、リンクで案内すること
翻訳の整合性	スキル自体またはその他の Markdown を編集した場合、英語版と韓国語版の内容が一致していること

必須基準：

• プロジェクトの種類を特定し、完了報告に記録していること
• 検証済みのインストールコマンドと使用例が、それぞれ少なくとも1つあること
• 正確な既存 README セクション（リファクタリング／更新モード）が維持されていること
• 不明点には `` を使用し、捏造しないこと
• 新しい草稿にリンク切れや削除済みスクリプトが残っていないこと