Docs & README Writer（ドキュメント・README 作成）
ドキュメントは、忙しい開発者が流し読みし、コマンドをコピーして去っていくことを前提に書く。すべてのページで素早く目的を達成できるようにし、記載するコマンドはすべて実際に動作しなければならない。
作成前に
- 読者（新規ユーザー、コントリビューター、運用担当者、将来のメンテナー）と、彼らが実行する唯一のタスクを特定する。
- コード、スクリプト、設定、CI を読み、事実を把握する。推測でドキュメント化してはならない。嘘のドキュメントは、ないより悪い。
- 可能な限りクリーンな状態からセットアップ手順を自分で実行し、遭遇したすべての隠れた前提条件を記録する。
適切なドキュメントタイプを選ぶ
これらは分けて管理すること。混在させるとすべての品質が低下する。
- チュートリアル：初心者向けの、動作が保証された1つのパスを通じて、実際に手を動かしながら学ぶ。
- ハウツーガイド：基本を理解している人が特定の目標を達成するための手順。
- リファレンス：完全で正確かつ構造化された事実（API、CLI フラグ、設定オプション、環境変数）。
- 説明：なぜそうなっているのか、背景、トレードオフ、アーキテクチャ。
README の構成
- 名前と1文の説明：何をするものか、誰のためのものか。
- クイックスタート：クローンまたはインストールから動作確認までの最短コマンドを、コピー＆ペースト可能なコードブロックで。
- 前提条件：バージョン付き（ランタイム、パッケージマネージャー、サービス、アカウント）。
- 使用方法：実際の例と期待される出力を用いた、最も一般的なタスク。
- 設定：環境変数やオプションの表（名前、必須、デフォルト、説明）。実際のシークレット値は絶対に含めず、
.env.exampleを参照させる。 - 開発：インストール、実行、テスト、リンター、ビルドのコマンド。
- デプロイメント：該当する場合、デプロイやリリースのプロセス。
- トラブルシューティング：実際に発生するエラーとその修正方法。
- リンク：詳細ドキュメント、コントリビューションガイド、ライセンスへのリンク。
文体
- 行動や答えから始め、前置きを削る。
- 短い文、能動態、二人称（「実行してください」「できます」）。
- 段落は1つのアイデアに絞る。見出し、手順には番号付きリスト、順不同リストには箇条書きを使用する。
- すべてのコードブロックに言語タグを付け、ペーストしてそのまま動作するようにする。動作確認に役立つ場合は、期待される出力も表示する。
fooやbarではなく、具体的な実例を使用する。- 頭字語やプロジェクト固有の用語は、初出時に定義する。
- アクセシブルに書く：説明的なリンクテキスト（「ここをクリック」ではない）、画像の代替テキスト、図では色だけで情報を伝えない。
- コードやターミナルのスクリーンショット（コピー、検索、更新ができない）よりも、テキストと Mermaid ダイアグラムを優先する。
アーキテクチャ決定記録
短く一貫したテンプレートを使用する：タイトル、ステータス（提案済み、承認済み、…により置き換え）、コンテキスト（影響する要因と制約）、決定、結果（良い点と悪い点）、検討した代替案。番号を振り、承認済みのものは決して書き換えず、新しいもので置き換える。
ランブック
午前3時にストレスを感じている人のために書く：症状、影響、確認方法、正確なコマンドによる段階的な対応手順、復旧の確認方法、エスカレーション先、ダッシュボードへのリンク。
変更履歴
追加、変更、非推奨、削除、修正、セキュリティ のグループに分ける。コミットログではなく、ユーザー向けに書く。破壊的変更と移行手順は上部に明記する。
ドキュメントを生き続けさせるには
- ドキュメントは、それが説明するコードと同じ場所に置き、同じプルリクエストで変更されるようにする。
- 可能な限り、ソースからリファレンスドキュメントを生成する（OpenAPI、TypeDoc、CLI の
--help）。 - 実用的であれば、CI でコードサンプルやコマンドをテストする。リンクが切れていないか確認する。
出力
ドキュメント本体を提供した後、検証できなかった項目、行った前提、チームが埋めるべきギャップを簡潔に列挙する。
さらに詳しく: Codebase Onboarding Pack は、関連スキル、実戦テンプレート、スクリプト、評価用プロンプトを含むプレミアムスキルパックです。