docs-generator

ドキュメントジェネレーター

プロジェクトのドキュメントを明確でアクセスしやすい形に再構成し、整理します。

前提条件

このスキルを実行するには、開始前に各項目を確認する必要があります。いずれかの確認に失敗した場合は、作業を中止してユーザーに確認してください。

• Git の作業ツリー：クリーンであるか、スタッシュ可能であること。まず git status を実行してください。変更がある場合は、ローカルの変更をリベースまたは上書きする可能性のある同期を行う前に、git stash push -u -m "pre-docs-sync" でバックアップしてください。
• 必要なツール：git 2.30 以上、Markdown 対応エディター、および図のエクスポートが必要な場合のみ mermaid-cli（またはレンダラー）。git --version と command -v mmdc で利用可能か確認してください。
• リポジトリの権限：分析には読み取り権限が必要です。書き込み権限を使用できるのは、ユーザーがコミットを明示的に承認した場合のみです。読み取り専用のリポジトリでは、ファイルを書き込まず、差分またはインラインの概要を出力してください。
• ブランチの状態：接続可能な origin リモートがあること（git remote get-url origin）。存在しない場合は、リベースやプルを試みず、ユーザーに確認してください。
• バックアップ：ドキュメントファイルを削除または移動する再構成を行う前に、リポジトリがプッシュ済み、または別の方法でバックアップ済みであることを確認してください。破壊的な rm／git mv を実行する前には、必ず git status で状態を確認し、ユーザーから明示的な確認を得てください。ドライランのプレビューとユーザーの承認なしに、git reset --hard、git push --force、rm -rf を実行してはいけません。
• 安全性に関する既定方針：ドライランのプレビュー（git mv -n、rm -i）を優先し、取り消し不可能な操作の前にユーザーの確認を得てください。

前提条件のいずれかを満たさない場合は、作業を中断し、先に進まずに支障となっている点をユーザーに伝えてください。

編集前のリポジトリ同期（必須）

既存のリポジトリでファイルを作成、更新、削除する前に、現在のブランチをリモートと同期してください。

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

作業ツリーがクリーンでない場合は、先にスタッシュして同期し、その後に変更を復元してください。

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

origin が存在しない場合、プルできない場合、またはリベースやスタッシュで競合が発生した場合は、作業を中止し、続行する前にユーザーに確認してください。

ワークフロー

0. フィーチャーブランチを作成

変更を加える前に、次の手順を行ってください。

1. 現在のブランチを確認します。このタスク用のフィーチャーブランチにすでにいる場合は、スキップしてください。
2. git branch -r | head -20 を実行して、リポジトリのブランチ命名規則（例：feat/、feature/ など）を確認します。
3. リポジトリの規則に従って新しいブランチを作成して切り替えるか、規則がない場合は feat/docs-generator を使用します。

1. プロジェクトを分析

コードベースを調べ、次の項目を特定します。

• プロジェクトの種類：ライブラリ、API、ウェブアプリ、CLI、マイクロサービス
• アーキテクチャ：モノレポ、マルチパッケージ、単一モジュール
• ユーザーペルソナ：エンドユーザー、開発者、運用担当者
• 既存のドキュメント：README ファイル、docs/ フォルダー、インラインコメント、docstring を確認します。
• 不足している点：存在するドキュメントと不足しているドキュメントを一覧にします。

2. ドキュメントを再構成

ルートの README.md — エントリーポイントとして簡潔に整理します。

• プロジェクトの概要と目的
• クイックスタート（インストールと最初の使用方法）
• モジュール／コンポーネントの概要とリンク
• ライセンスと連絡先

コンポーネントの README — モジュール／パッケージ／サービスごとに追加します。

• 目的と担当範囲
• セットアップ手順
• テストコマンド

docs/ に集約 — 該当するカテゴリごとに整理します。

docs/
├── architecture.md      # System design, diagrams
├── api-reference.md     # Endpoints, authentication
├── database.md          # Schema, migrations
├── deployment.md        # Production setup
├── development.md       # Local setup, contribution
├── troubleshooting.md   # Common issues
└── user-guide.md        # End-user documentation

3. 図を作成

すべての視覚的なドキュメントには Mermaid を使用します。

• アーキテクチャ図
• データフロー図
• データベーススキーマ

4. レビューと検証

1. すべての内部リンクが正しく解決されることを確認します。
2. ドキュメント内のコード例が構文的に正しいことを確認します。
3. どこからもリンクされていない孤立したドキュメントがないことを確認します。
4. コミットする前に、変更の概要をユーザーに提示します。

変更をユーザーに提示して承認を得てください。ユーザーから明示的に依頼されない限り、コミットしないでください。

期待される出力

中規模の Node.js API プロジェクトでこのスキルを実行すると、次のようになります。

• プロジェクト概要、クイックスタート、モジュールへのリンク、ライセンスを含む、整理されたルートの README.md
• 各サービスまたはライブラリ用の README.md ファイル
• architecture.md、api-reference.md、deployment.md、development.md などの関連ファイルを含む docs/ フォルダー
• アーキテクチャとデータフローのドキュメントに埋め込まれた Mermaid 図
• チェックした内部リンクと見つかった問題をすべて記載した検証概要

受け入れ基準

以下のすべてを満たすと、実行は合格です。

• ルートの README.md に、概要、クイックスタート（インストールと最初の使用）、コンポーネントまたは docs/ ファイルへのリンクが含まれている。
• docs/ ディレクトリが存在し、architecture.md、api-reference.md、deployment.md、development.md のうち少なくとも 1 つが含まれている。また、プロジェクトの種類に関連するファイルのみが含まれている。
• すべての内部 Markdown リンクが既存のファイルを参照している（[text](path) のリンク切れがない）。
• 孤立したファイルがない。すべての docs/*.md が、README.md または別の docs/ ページから 1 ホップ以内で参照できる。
• アーキテクチャまたはデータフローのドキュメントにある Mermaid 図が、構文エラーなくレンダリングされる（利用可能な場合は mmdc で検証する）。
• main／master にはコミットせず、すべての変更をリポジトリの命名規則に従ったフィーチャーブランチで行う。

エッジケース

• 既存のドキュメントがない場合：コード分析を使って、スキルが一から生成します。まず README.md を作成し、プロジェクトの複雑さに応じて docs/ ファイルを追加します。
• ドキュメントに矛盾や古い情報がある場合：ユーザーに矛盾を知らせます。古いドキュメントよりもコードから導き出した情報を優先し、古くなったセクションにはレビューが必要であることを明記します。
• パッケージ数の多いモノレポの場合：パッケージごとの README.md は、実際に公開 API またはユーザー向け機能を持つものに限って作成し、自動生成またはビルド出力のパッケージは対象外にします。
• プライベート情報や機密情報に隣接する内容の場合：コードコメントにすでに記載されている範囲を超えて、認証情報、トークン、内部専用エンドポイントをドキュメント化しません。
• 読み取り専用リポジトリの場合：git への書き込みアクセスがない場合は、ファイルをコミットする代わりに、差分またはインラインの概要としてドキュメントを出力します。

ステップ完了レポート

各主要ステップの完了後、次の形式でステータスレポートを出力します。

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

チェック名は、そのステップで実際に検証する内容に合わせてください。合格には √、失敗には × を使い、簡単な補足には — を使います。「Criteria」行には、達成した受け入れ基準の数をまとめます。「Result」行には、全体の判定を記載します。

フェーズごとのスキル固有チェック

フェーズ：ブランチの設定 — チェック項目：Branch creation、Repo sync

フェーズ：プロジェクト分析 — チェック項目：Project analysis、Gap identification

フェーズ：ドキュメントの再構成 — チェック項目：Doc restructure、Diagram creation

フェーズ：検証 — チェック項目：Validation pass、Link verification

ガイドライン

• ドキュメントは簡潔で、ざっと目を通しやすいものにします。
• プロジェクトの種類に合わせて構成を調整します（すべてのカテゴリが当てはまるわけではありません）。
• 関連するドキュメント間の相互参照を維持します。
• 冗長または古くなった内容を削除します。
• 既存のドキュメントのうち、正確なものは保持します。