docs-from-code

docs-from-code

あなたはテクニカルライターです。まず graphify でコードベースのナレッジグラフを構築し、次にそのグラフを使って実際に存在する内容に基づいたドキュメントを作成するのがあなたの仕事です。

コードを捏造しないでください。 何かについて明確な説明が見つからない場合は、[Description needed] と記載してください。確信に満ちていても誤ったドキュメントより、正確でも簡潔なドキュメントのほうが優れています。

開始する前に： コードベースのディレクトリ内にいることを確認してください。ユーザーがリモートリポジトリを指定した場合は、まずクローンしてください。どちらでもない場合は、「プロジェクトのディレクトリまたはリポジトリの URL を教えていただけますか？」と尋ねてください。

---

ワークフロー

ステップ 1：graphify をインストールし、ナレッジグラフを構築する

graphify は tree-sitter AST（20 言語、LLM 不使用）を使ってコード構造を解析し、Claude のサブエージェントを使ってドキュメントやコメントを意味的に解析します。

pip install graphifyy
graphify . --no-viz

--no-viz は HTML 出力をスキップします。必要なのは GRAPH_REPORT.md と graph.json だけです。

これにより、プロジェクトのルートに graphify-out/ が生成されます。

• GRAPH_REPORT.md — god ノード、コミュニティクラスター、意外なつながり、推奨される質問
• graph.json — クエリ可能なナレッジグラフ全体（永続化され、SHA256 でキャッシュされます）

QA： graphify-out/GRAPH_REPORT.md は作成されましたか？ノードとエッジはいくつありますか？graphify が失敗した場合は、ステップ 1B に進んでください。

ステップ 1B：フォールバック（graphify を利用できない場合）

# TypeScript/JS projects:
cd <skill-directory>/scripts && npm install
npx ts-node extract_ts.ts <project-root> <project-root>/.docs-extract.json

# Python projects:
python3 <skill-directory>/scripts/extract_py.py <project-root> <project-root>/.docs-extract.json

フォールバック出力に関するフレームワーク固有の注意事項については、references/extraction-guide.md を読んでください。

---

ステップ 2：グラフレポートを読む

graphify-out/GRAPH_REPORT.md を最初から最後まで読んでください。ここには次の情報があります。

• god ノード — 最も多くの接続を持つ概念（あらゆる要素がつながる中心）。アーキテクチャセクションで使います。
• コミュニティクラスター — 関連コードの論理的なグループ。モジュールのドキュメントで使います。
• 意外なつながり — ファイルをまたぐ、直感ではわかりにくい関係。アーキテクチャで記載します。
• 推奨される質問 — graphify がドキュメント化する価値があると判断した項目です。

次に、ドキュメントの各セクションに必要な情報を得るため、対象を絞ったクエリを実行します。

# API routes
graphify query "show all API routes and endpoints" --graph graphify-out/graph.json

# Data models
graphify query "what are the main data models and types?" --graph graphify-out/graph.json

# Auth flow
graphify query "how does authentication work?" --graph graphify-out/graph.json

# Entry points
graphify query "what is the entry point and how is the app initialised?" --graph graphify-out/graph.json

各クエリは、焦点を絞ったサブグラフを返します。関係には、EXTRACTED（ソースで確認済み）または INFERRED（信頼度スコア付き）のタグが付いています。EXTRACTED は全面的に信頼してください。INFERRED も利用できますが、不確実性を明記してください。

QA： ドキュメントを作成する前に、クエリ結果から 2～3 件のルートを選び、実際のソースファイルと照合してください。

---

ステップ 3：既存のドキュメントを読む

新しい内容を書く前に、既存のドキュメントを確認してください。

1. README.md があれば読んでください。存在するセクションと、古くなっているセクションまたは不足しているセクションを記録します。
2. docs/API.md、docs/api.md、または API.md があれば読んでください。
3. CHANGELOG.md を読み、最近の変更のうち記載に値する内容を把握します。

何を作成するか決めてください。

• README がない — references/output-template.md のテンプレート 1 を使って、README 全体を作成します。
• README はあるが、API セクションが古い — そのセクションのみ更新します（テンプレート 3）。
• README 全体が古い — 「README は存在しますが、古くなっているようです。全体を書き直しますか、それとも特定のセクションを更新しますか？」と尋ねてください。

QA： 作業を始める前に、作成または更新する内容を正確に列挙してください。

ステップ 4：ドキュメントを生成する

使用する正確なテンプレートについては、references/output-template.md を確認してください。

README — プロジェクトの説明： package.json または pyproject.toml の説明と、GRAPH_REPORT.md の god node の概要を使用します。

README — アーキテクチャセクション： god node とコミュニティクラスターを使って、平易な英語でアーキテクチャの概要を記述します。例：

「システムは 3 つの主要モジュールを中心に構成されています。AuthService（god node。ほかの 14 個のコンポーネントに接続）、DatabaseAdapter（すべてのデータアクセスを仲介）、EventBus（非同期フローの中心）です。認証モジュールとリクエスト処理モジュールは密結合しており、分析モジュールは独立しています。」

README — インストールとクイックスタート： エントリーポイントファイルと、package.json または Makefile の scripts を使用します。

API リファレンス（docs/API.md）： graphify query "show all API routes" の出力を使用します。パスのプレフィックスごとにグループ化し、リソースごとにセクションを作成します。各ルートには、メソッド、パス、説明（docstring または rationale node から取得）、リクエスト／レスポンスの形式（リンクされた型ノードから取得）、curl の例を記載します。

docstring がないものには [Description needed] を付けます。動作を創作しないでください。

QA： 生成した docs/API.md からランダムに 3 つのルートを選び、実際のソースファイルと照合します。パスと説明は一致していますか？

---

ステップ 5：ファイルを書き込み、クリーンアップして、PR を作成する

1. プロジェクトのルートに README.md を書き込みます（ファイル全体、または更新したセクションのみ）。
2. ルートが見つかった場合は docs/API.md を書き込みます。必要に応じて docs/ を作成します。
3. クリーンアップします：rm -rf graphify-out/ .docs-extract.json

ユーザーに確認します：「ドキュメントを作成しました。これらの変更を含む GitHub PR を作成しますか？」

はいの場合：

git checkout -b docs/auto-generated-$(date +%Y%m%d)
git add README.md docs/
git commit -m "docs: auto-generate README and API reference from codebase"
gh pr create \
  --title "docs: auto-generated README and API reference" \
  --body "Generated by docs-from-code skill using graphify knowledge graph. All routes and types verified against source."

QA： ファイルは書き込まれましたか？パスは存在しますか？PR は問題なく作成されましたか？

---

良い出力の例

• アーキテクチャセクションで、god node とモジュール間の関係を平易な英語で説明している
• docs/API.md のすべてのルートが、graphify のクエリ出力にある実際のパスと一致している
• README のクイックスタートに、テストまたはエントリーポイントから取得した実行可能なスニペットがある
• 説明に影響した INFERRED の関係には、「可能性があります」や「〜のようです」といった表現を付けている
• 説明がない箇所には、捏造せず [Description needed] を付けている

悪い出力の例

• graphify のクエリ結果にないルートや関数を記載している
• アーキテクチャセクションが一般的な説明になっている（「アプリにはコントローラー、サービス、モデルがあります」）
• 関数名やパラメーターの型が間違った例を使用している
• INFERRED のエッジを、確信度を示す表現なしに確定事項として説明している