Codebase Documenter

概要

このスキルは、コードベースの包括的で初心者向けのドキュメンテーション作成を可能にします。README、アーキテクチャガイド、コメント、API ドキュメンテーション作成のための構造化されたテンプレートとベストプラクティスを提供し、新規ユーザーがプロジェクトを迅速に理解し、貢献できるようにします。

初心者向けドキュメンテーションの基本原則

新規ユーザーのためにコードを文書化する場合、以下の基本原則に従ってください:

1. 「なぜ」から始める - 実装の詳細に入る前に目的を説明する
2. 段階的な情報開示を使用する - 情報をシンプルから複雑へと層状に提示する
3. コンテキストを提供する - コードが何をするか、なぜ存在するかを説明する
4. 例を含める - すべての概念に具体的な使用例を示す
5. 前提知識を仮定しない - 用語を定義し、可能な限り専門用語を避ける
6. ビジュアル補助材料 - 図、フローチャート、ファイルツリー構造を使用する
7. クイックウィン - ユーザーが 5 分以内に何かを実行できるようにする

ドキュメンテーションのタイプと使用場面

1. README ドキュメンテーション

作成時期: プロジェクトのルートディレクトリ、メジャーな機能モジュール、またはスタンドアロンコンポーネントの場合。

従うべき構造:

# プロジェクト名

## これが何をするか
[1～2 文の平易な英語での説明]

## クイックスタート
[5 分以内にユーザーがプロジェクトを実行できるようにする]

## プロジェクト構造
[説明付きのビジュアルファイルツリー]

## 主要コンセプト
[ユーザーが理解する必要のあるコアコンセプト]

## よくあるタスク
[頻繁な操作のステップバイステップガイド]

## トラブルシューティング
[よくある問題と解決策]

ベストプラクティス:

• プロジェクトの価値提案で始める
• 実際に機能するセットアップ手順を含める (テストする!)
• プロジェクト構造の視覚的な概要を提供する
• より詳しい情報は、より深いドキュメンテーションにリンクする
• ルート README はゲッティングスタートに焦点を当てる

2. アーキテクチャドキュメンテーション

作成時期: 複数のモジュール、複雑なデータフロー、または非自明な設計判断を持つプロジェクトの場合。

従うべき構造:

# アーキテクチャ概要

## システムデザイン
[高レベルの図と説明]

## ディレクトリ構造
[各ディレクトリの目的を含めた詳細な内訳]

## データフロー
[データがシステム全体でどのように移動するか]

## 主要な設計判断
[特定のアーキテクチャ上の選択がなされた理由]

## モジュール依存関係
[異なる部分がどのように相互作用するか]

## 拡張ポイント
[新機能を追加する場所と方法]

ベストプラクティス:

• 図を使用してシステムコンポーネントと関係を表示する
• アーキテクチャ上の決定の背後にある「なぜ」を説明する
• 幸福パスとエラーハンドリングの両方をドキュメント化する
• モジュール間の境界を特定する
• 注釈付きのビジュアルファイルツリー構造を含める

3. コードコメント

作成時期: 複雑なロジック、非自明なアルゴリズム、またはコンテキストが必要なコードの場合。

注釈パターン:

関数/メソッドドキュメンテーション:

/**
 * 部分的な請求期間のプロレーテされたサブスクリプション費用を計算します。
 *
 * これが存在する理由: ユーザーは月の途中でサブスクリプション登録できるため、
 * 現在の請求サイクルで残っている日数に対してのみ請求する必要があります。
 *
 * @param {number} fullPrice - 通常の月額サブスクリプション料金
 * @param {Date} startDate - ユーザーのサブスクリプション開始日
 * @param {Date} periodEnd - 現在の請求期間の終了日
 * @returns {number} 請求するプロレーテされた金額
 *
 * @example
 * // ユーザーが 1 月 15 日に登録、期間は 1 月 31 日に終了
 * calculateProratedCost(30, new Date('2024-01-15'), new Date('2024-01-31'))
 * // 返すもの: 16.13 (31 日中 17 日)
 */

複雑なロジックドキュメンテーション:

# このチェックが存在する理由: API は削除されたユーザーに対して null を返しますが、
# 名前を設定したことのないユーザーに対しては空文字列を返します。監査ログのために
# これらのケースを区別する必要があります。
if user_name is None:
    # ユーザーが削除された - これをセキュリティイベントとしてログに記録する
    log_deletion_event(user_id)
elif user_name == "":
    # ユーザーがオンボーディングを完了しなかった - スキップしても安全
    continue

ベストプラクティス:

• 「何」ではなく「なぜ」を説明する - コードが何をするか示している
• エッジケースとビジネスロジックをドキュメント化する
• 複雑な関数に例を追加する
• 自明でないパラメータを説明する
• 落とし穴または直感的でない動作に注記する

4. API ドキュメンテーション

作成時期: HTTP エンドポイント、SDK メソッド、またはパブリックインターフェースの場合。

従うべき構造:

## エンドポイント名

### これが何をするか
[エンドポイントの目的の平易な英語での説明]

### エンドポイント
`POST /api/v1/resource`

### 認証
[必要な認証と提供方法]

### リクエスト形式
[JSON スキーマまたはサンプルリクエスト]

### レスポンス形式
[JSON スキーマまたはサンプルレスポンス]

### 使用例
[curl/コードの具体的な例]

### よくあるエラー
[エラーコードとその意味]

### 関連エンドポイント
[関連操作へのリンク]

ベストプラクティス:

• 動作する curl の例を提供する
• 成功時とエラー時の両方のレスポンスを表示する
• 認証を明確に説明する
• レート制限と制約をドキュメント化する
• よくある問題のトラブルシューティングを含める

ドキュメンテーション ワークフロー

ステップ 1: コードベースを分析する

ドキュメンテーション作成前に:

1. エントリーポイントを特定する - メインファイル、インデックスファイル、アプリ初期化
2. 依存関係をマップする - モジュール間の関係
3. コアコンセプトを見つける - ユーザーが理解する必要のあるキー抽象化
4. 設定を見つける - 環境セットアップ、設定ファイル
5. 既存のドキュメントを確認する - 重複させず、既存の内容に基づいて構築

ステップ 2: ドキュメンテーションタイプを選択する

ユーザーのリクエストとコードベース分析に基づいて:

• 新規プロジェクトまたは欠落 README → README ドキュメンテーションで始める
• 複雑なアーキテクチャまたは複数モジュール → アーキテクチャドキュメンテーションを作成する
• 紛らわしいコードセクション → インラインコードコメントを追加する
• HTTP/API エンドポイント → API ドキュメンテーションを作成する
• 複数のタイプが必要 → この順序で対応: README → アーキテクチャ → API → コメント

ステップ 3: ドキュメンテーションを生成する

assets/templates/ からテンプレートを使用して出発点とする:

• assets/templates/README.template.md - プロジェクト README 用
• assets/templates/ARCHITECTURE.template.md - アーキテクチャドキュメント用
• assets/templates/API.template.md - API ドキュメンテーション用

特定のコードベースに基づいてテンプレートをカスタマイズする:

1. プロジェクト固有の情報を入力する - プレースホルダーを実際のコンテンツに置き換える
2. 具体的な例を追加する - プロジェクトから実際のコードを使用する
3. ビジュアル補助材料を含める - ファイルツリー、図、フローチャートを作成する
4. 手順をテストする - セットアップステップが実際に機能するか確認する
5. 関連ドキュメントをリンクする - ドキュメンテーション部分を一緒に接続する

ステップ 4: 明確性をレビューする

ドキュメンテーションを最終化する前に:

1. 初心者として読む - プロジェクトコンテキストなしで意味があるか?
2. 完全性を確認する - 説明に不足している部分はないか?
3. 例を検証する - コード例は実際に機能するか?
4. 手順をテストする - 誰かがセットアップステップに従えるか?
5. 構造を改善する - 情報は見つけやすいか?

ドキュメンテーションテンプレート

このスキルには assets/templates/ に開始構造を提供するいくつかのテンプレートが含まれています:

利用可能なテンプレート

• README.template.md - クイックスタート、プロジェクト構造、よくあるタスクのセクションを備えた包括的な README 構造
• ARCHITECTURE.template.md - システムデザイン、データフロー、設計判断を含むアーキテクチャドキュメンテーションテンプレート
• API.template.md - リクエスト/レスポンス形式と例を含む API エンドポイントドキュメンテーション
• CODE_COMMENTS.template.md - 効果的なインラインドキュメンテーションの例とパターン

テンプレートの使用

1. assets/templates/ から適切なテンプレートを読む
2. 特定のプロジェクト用にカスタマイズする - プレースホルダーを実際の情報に置き換える
3. プロジェクト固有のセクションを追加する - 必要に応じてテンプレートを拡張する
4. 実際の例を含める - コードベースから実際のコードを使用する
5. 関連のないセクションを削除する - 適用されない部分を削除する

ベストプラクティスリファレンス

詳細なドキュメンテーションのベストプラクティス、スタイルガイド、および高度なパターンについては、以下を参照してください:

• references/documentation_guidelines.md - 包括的なスタイルガイドとベストプラクティス
• references/visual_aids_guide.md - 効果的な図とファイルツリーの作成方法

以下の場合にこれらのリファレンスを読み込みます:

• 複雑なエンタープライズコードベース用のドキュメンテーション作成
• 複数の利害関係者要件への対応
• 高度なドキュメンテーションパターンが必要
• 大規模なプロジェクト全体でドキュメンテーションを標準化

よくあるパターン

ファイルツリー構造の作成

ファイルツリーは新規ユーザーがプロジェクト構成を理解するのに役立ちます:

project-root/
├── src/                    # ソースコード
│   ├── components/        # 再利用可能な UI コンポーネント
│   ├── pages/             # ページレベルコンポーネント (ルーティング)
│   ├── services/          # ビジネスロジック API 呼び出し
│   ├── utils/             # ヘルパー関数
│   └── types/             # TypeScript 型定義
├── public/                # 静的資産 (画像、フォント)
├── tests/                 # src 構造を反映したテストファイル
└── package.json           # 依存関係とスクリプト

複雑なデータフローの説明

番号付きステップと図を使用:

ユーザーリクエストフロー:
1. ユーザーがフォームを送信 → 2. 検証 → 3. API 呼び出し → 4. データベース → 5. レスポンス

[1] components/UserForm.tsx
    ↓ 入力を検証
[2] services/validation.ts
    ↓ API に送信
[3] services/api.ts
    ↓ データベースをクエリ
[4] データベース (PostgreSQL)
    ↓ データを返す
[5] components/UserForm.tsx (UI を更新)

設計判断をドキュメント化する

アーキテクチャ上の選択の背後にある「なぜ」を捉える:

## Redux を使用する理由

**判断:** Context API ではなく Redux を使用した状態管理

**コンテキスト:** ユーザー認証、ショッピングカート、UI 設定にアクセスする必要がある
50 個以上のコンポーネントがあります。

**理由:**
- Context API はこのような多くのコンポーネントで不要な再レンダリングを引き起こす
- Redux DevTools は複雑な状態変更のデバッグに役立つ
- チームには既存の Redux の専門知識がある

**トレードオフ:**
- より多くのボイラープレートコード
- 新規開発者にとって陡しい学習曲線
- 価値がある場合: パフォーマンス、デバッグ、チームの習熟度

出力ガイドライン

ドキュメンテーション生成時:

1. ターゲットオーディエンスのために書く - 初心者、中級、上級ユーザー向けかどうかに基づいて複雑さを調整
2. 一貫した形式を使用する - Markdown 規約に従い、一貫した見出し階層
3. 動作する例を提供する - すべてのコードスニペットとコマンドをテストする
4. ドキュメント間をリンクする - ドキュメンテーションナビゲーション構造を作成する
5. 保守可能に保つ - コード変更に応じてドキュメンテーションを簡単に更新できるようにする
6. 日付とバージョンを追加する - ドキュメンテーションが最後に更新されたときを記録する

クイックリファレンス

README を生成するコマンド: 「このプロジェクト用の README ファイルを作成し、新規開発者がゲッティングスタートするのに役立つようにしてください」

アーキテクチャをドキュメント化するコマンド: 「このコードベースのアーキテクチャをドキュメント化し、異なるモジュール間の相互作用を説明してください」

コードコメントを追加するコマンド: 「新規開発者がロジックを理解するのに役立つ説明コメントをこのファイルに追加してください」

API をドキュメント化するコマンド: 「このファイルのすべてのエンドポイント用に API ドキュメンテーションを作成してください」