readme

README スキル

明確で包括的な README ファイルとプロジェクトドキュメントの作成を専門としています。開発者が効果的なプロジェクト紹介、セットアップガイド、使用方法のドキュメントを作成できるよう支援します。 - プロジェクトの情報をもとに、包括的な README ファイルを生成する - 明確なインストール手順とセットアップ手順を作成する - 使用例と API ドキュメントを作成する - プロジェクトの構成とアーキテクチャを説明する - 目次とナビゲーションを生成する - コントリビューションガイドラインとトラブルシューティングのセクションを作成する - 書式と視覚的な構成を工夫して読みやすさを高める

使用する場面

次のような場合に、このスキルを使用します。

• 新しい README やドキュメントファイルを作成する
• 新機能に合わせて既存の README を更新する
• プロジェクトのセットアップ、インストール、設定を説明する
• 使用例や API リファレンスを作成する
• コントリビューションガイドラインやクイックスタートガイドを作成する
• ドキュメントの明確さと構成を改善する

基本的なワークフロー

ステップ 1：プロジェクト情報を収集する

プロジェクトを分析して、次の点を把握します。

1. プロジェクトの目的：どのような問題を解決しますか？
2. 対象読者：利用者は誰ですか（開発者、ユーザー、コントリビューターなど）？
3. 主な機能：このプロジェクトの特長は何ですか？
4. 技術スタック：言語、フレームワーク、依存関係
5. プロジェクトの構成：コードはどのように整理されていますか？

ステップ 2：README の構成を作成する

次の標準的な構成を使用します。

# Project Name

Brief description (1-2 sentences)

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

[Setup instructions]

## Quick Start

[Basic usage example]

## Documentation

[Link to detailed docs]

## API Reference

[Key endpoints/functions]

## Examples

[Working examples]

## Configuration

[Setup options]

## Troubleshooting

[Common issues and solutions]

## Contributing

[How to contribute]

## License

[License information]

ステップ 3：明確な内容を書く

• 具体的にする：曖昧な説明ではなく、具体例を使う
• 説明するより、実例を示す：コード例やスクリーンショットを含める
• 段階的に情報を示す：簡単な内容から始め、徐々に複雑な内容を加える
• 論理的に整理する：関連する情報をまとめる
• 書式を活用する：読みやすくするため、見出し、リスト、コードブロックを使う

ステップ 4：例を追加する

実用的で動作する例を含めます。

• インストール例
• 基本的な使用方法のスニペット
• 複雑な機能のデモ
• よくあるユースケース
• コピーしてすぐに使えるコード

ステップ 5：品質を確認する

完了前に、次の点を確認します。

• 最初の段落でプロジェクトの目的が明確に説明されている
• インストール手順が網羅されている
• 例が実行できる
• 目次が各セクションと一致している
• すべてのリンクが機能する
• 書式に一貫性がある
• 誤字や文法上の誤りがない

README の構成要素リファレンス

プロジェクト名と説明

# Project Name

One-liner explaining what this project does.

Long paragraph (2-3 sentences) describing problem solved and approach.

機能のセクション

## Features

- ✅ Feature with emoji for visual interest
- ✅ Key capability with brief description
- ✅ Unique advantage over alternatives

インストール

## Installation

### Requirements

- Node.js 18+
- pnpm 8+

### Steps

\`\`\`bash
pnpm install project-name
\`\`\`

クイックスタート

最小限の内容にします（コードは最大 5～10 行）。

## Quick Start

\`\`\`javascript
import { feature } from 'project-name';

const result = feature({ option: 'value' });
console.log(result);
\`\`\`

例

現実的で、コピーしてすぐに使える例にします。

## Examples

### Basic Usage

\`\`\`typescript
// Simple example with real output
const instance = new MyClass();
instance.doSomething(); // Output: expected result
\`\`\`

### Advanced Configuration

\`\`\`typescript
// Complex example showing options
const instance = new MyClass({
option1: true,
option2: 'value'
});
\`\`\`

ベストプラクティス

1. 価値を最初に示す：最初の段落で「これを使うべき理由」に答える
2. 動作する例を示す：コード例は実行可能なものにする
3. インストールを簡単にする：複雑なセットアップには専用のガイドを用意する
4. 依存関係を説明する：必要なものを最初に列挙する
5. スクリーンショットを含める：UI を持つプロジェクトでは視覚的な例を示す
6. 拾い読みしやすく書く：内容をざっと確認できるよう、見出しを使う
7. 詳細なドキュメントにリンクする：README は概要として、詳細なドキュメントにリンクする
8. 最新の状態を保つ：機能を追加したら README も更新する
9. 制限事項を正直に伝える：対象外の内容やサポートされていない機能を説明する
10. コントリビューションガイドラインを含める：問題の報告方法や PR の提出方法を説明する

アンチパターン

パターン	問題	修正方法
文字の壁	内容を把握できません	見出しとリストを使います
セットアップ手順がない	読者がインストールできません	手順を追った説明を含めます
例がない	使い方がわかりません	動作するコード例を追加します
情報が古い	ユーザーに誤解を与えます	リリースに合わせて更新します
詳細すぎる	読者を圧倒します	代わりに詳細なドキュメントへリンクします
目次がない	移動しにくくなります	冒頭にセクションへのリンクを追加します
リンク切れ	ユーザー体験が損なわれます	外部リンクをすべてテストします
マーケティング的な美辞麗句	内容がありません	誇張ではなく、何ができるかに焦点を当てます

鉄則

1. 必ず価値提案から始めてください。最初の段落では、インストールやセットアップの手順より先に「どのような問題を解決するのか」に答える必要があります。
2. **クイックスタートのセクションを10行より長くしてはいけません。**セットアップにそれ以上必要な場合は、初めて読む人を圧倒しないよう、詳細なガイドにリンクしてください。
3. 必ず動作する、コピーしてすぐに使えるコード例を含めてください。実行できない疑似コードの例は、読者の時間を無駄にするため、例がないよりも悪影響があります。
4. **機能リリース後にREADMEを古いままにしてはいけません。**インストールコマンドが古かったり、例が動かなかったりすると、ユーザーの信頼をすぐに損ないます。
5. **READMEを完成とする前に、外部リンクとコード例をすべて必ずテストしてください。**リンク切れや動かない例は、READMEで最もよく見られる失敗の原因です。

アンチパターン

アンチパターン	失敗する理由	正しい方法
説明の前に長い機能一覧を記載する	読者はプロジェクトが何なのかわからず、機能の意味も理解できません	機能を列挙する前に、1〜2文の価値提案から始めます
疑似コードやプレースホルダーの例を使う	読者に実際のAPIを推測させ、フラストレーションや利用の断念につながります	実際のインポート、関数名、想定される出力を含む、実行可能なコードを示します
クイックスタートに20段階のインストールガイドを載せる	圧倒されるセットアップはユーザーを遠ざけ、「クイック」スタートにも反します	クイックスタートは1〜3個のコマンドにし、詳細なセットアップは別のガイドにリンクします
技術的な事実ではなく、マーケティング文句を書く	「驚くほど高速」のような曖昧な表現では、実用的な情報が得られません	「10k LOCでの測定でビルド時間を40%短縮」のように、データを含む具体的な主張を使います
機能を変更してもREADMEを更新しない	古いコマンドは何も通知せずに失敗し、ユーザーはドキュメントではなくプロジェクトのせいだと考えます	READMEをコードとして扱い、機能変更のたびに同じPRで更新します

統合ポイント

関連スキル：

• doc-generator - コードからのドキュメント自動生成
• writing-skills - 文章の品質に関するガイドライン
• technical-writer - 専門的なドキュメントを作成するエージェント

関連エージェント：

• technical-writer - ドキュメント作成にこのスキルを使用します
• developer - 新しいプロジェクトのREADMEを作成します

メモリプロトコル（必須）

開始前： .claude/context/memory/learnings.mdを読みます

完了後：

• 新しいパターン → .claude/context/memory/learnings.md
• 見つかった問題 → .claude/context/memory/issues.md
• 決定事項 → .claude/context/memory/decisions.md

中断を前提にしてください。メモリに記録されていないことは、起きていないのと同じです。