| name | code-documentation |
| description | コードや API の意図を短時間で共有できるドキュメントの書き方をガイドする。 |
| license | MIT |
| source | wshobson/agents |
| compatibility | コードや設定ファイルを参照できる環境で利用する。 |
| metadata | [object Object] |
| allowed-tools | Read |
Goal
読者が数分で目的・前提・使い方を把握し、安全にコードや API を利用できる状態にする。
When to use
- 新機能や API を追加したときの README/ドキュメント更新
- 既存機能の使い方が伝わりにくい、問い合わせが多いとき
- 外部/社内向けに公開インターフェースを説明するとき
Steps
- 読者と目的を明確にする（誰が何を達成したいか、必要な前提は何か）。
- README を構成する。
- 冒頭に概要と対応バージョン。
- Quick Start: インストール/起動コマンドを最短で。
- Usage: 典型的な呼び出し例と期待される出力。
- Configuration: オプション一覧を表でまとめ、例の値はダミーにする。
- API ドキュメントを書く。
- シグネチャ、引数、返り値、エラーを箇条書き。
- 最低 1 つの実行可能なサンプルコードを載せる（型/エラーハンドリングを含める）。
- インラインコメントは「なぜ」を説明する。
- ビジネスルールやワークアラウンド、非自明なアルゴリズムの理由を残す。
- 明白な処理や型情報の繰り返しは避ける。
- 検証する。
- コード例を実行/ビルドして壊れていないか確認。
npm run lintやテキスト系 linter（markdownlint/textlint）が通るかを確認。
Edge cases
- 環境変数や秘密情報は必ずダミー値で記載し、
.env*はコミットしない。 - バージョン差異がある場合は対象バージョンを明記し、互換性が無い場合の回避策を書く。
- 大規模変更前なら簡潔な概要＋ TODO で構わないが、公開前に詳細を補完する。