codebase-documenter

コードベースのドキュメント作成

概要

このスキルを使うと、コードベース向けの包括的で初心者にもわかりやすいドキュメントを作成できます。新しいユーザーがプロジェクトをすばやく理解し、貢献できるように、README、アーキテクチャガイド、コードコメント、API ドキュメントを作成するための構成済みテンプレートとベストプラクティスを提供します。

初心者にもわかりやすいドキュメントの基本原則

新しいユーザー向けにコードを説明する際は、次の基本原則に従ってください。

1. 「なぜ」から始める - 実装の詳細に入る前に、目的を説明します
2. 段階的に情報を提示する - 簡単な内容から複雑な内容へと、段階を追って説明します
3. 背景を説明する - コードが何をするかだけでなく、なぜ存在するのかも説明します
4. 例を含める - それぞれの概念について、具体的な使用例を示します
5. 事前知識がないことを前提にする - 用語を定義し、できる限り専門用語を避けます
6. 視覚的な補助を使う - 図、フローチャート、ファイルツリー構造を活用します
7. すぐに成果を得られるようにする - 5 分以内に何かを実行できるようにします

ドキュメントの種類と使い分け

1. README ドキュメント

作成する場面： プロジェクトのルートディレクトリ、主要な機能モジュール、または独立したコンポーネント向け。

推奨する構成：

# Project Name

## What This Does
[1-2 sentence plain-English explanation]

## Quick Start
[Get users running the project in < 5 minutes]

## Project Structure
[Visual file tree with explanations]

## Key Concepts
[Core concepts users need to understand]

## Common Tasks
[Step-by-step guides for frequent operations]

## Troubleshooting
[Common issues and solutions]

ベストプラクティス：

• プロジェクトの価値を最初に伝えます
• 実際に動作するセットアップ手順を記載します（テストしてください！）
• プロジェクト構成の概要を視覚的に示します
• 詳細なトピックを扱うドキュメントへのリンクを記載します
• ルートの README は、使い始めるための情報に絞ります

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

作成する場面： 複数のモジュール、複雑なデータフロー、または自明ではない設計判断を含むプロジェクト向け。

推奨する構成：

# Architecture Overview

## System Design
[High-level diagram and explanation]

## Directory Structure
[Detailed breakdown with purpose of each directory]

## Data Flow
[How data moves through the system]

## Key Design Decisions
[Why certain architectural choices were made]

## Module Dependencies
[How different parts interact]

## Extension Points
[Where and how to add new features]

ベストプラクティス：

• 図を使って、システムのコンポーネントとその関係を示します
• アーキテクチャ上の判断に至った「理由」を説明します
• 正常な処理フローとエラー処理の両方を説明します
• モジュール間の境界を明確にします
• 注釈付きのファイルツリー構造を視覚的に示します

3. コードコメント

作成する場面： 複雑なロジック、自明ではないアルゴリズム、または背景情報が必要なコード向け。

注釈のパターン：

関数／メソッドのドキュメント：

/**
 * Calculates the prorated subscription cost for a partial billing period.
 *
 * Why this exists: Users can subscribe mid-month, so we need to charge
 * them only for the days remaining in the current billing cycle.
 *
 * @param {number} fullPrice - The normal monthly subscription price
 * @param {Date} startDate - When the user's subscription begins
 * @param {Date} periodEnd - End of the current billing period
 * @returns {number} The prorated amount to charge
 *
 * @example
 * // User subscribes on Jan 15, period ends Jan 31
 * calculateProratedCost(30, new Date('2024-01-15'), new Date('2024-01-31'))
 * // Returns: 16.13 (17 days out of 31 days)
 */

複雑なロジックのドキュメント：

# Why this check exists: The API returns null for deleted users,
# but empty string for users who never set a name. We need to
# distinguish between these cases for the audit log.
if user_name is None:
    # User was deleted - log this as a security event
    log_deletion_event(user_id)
elif user_name == "":
    # User never completed onboarding - safe to skip
    continue

ベストプラクティス：

• 「何を」ではなく「なぜ」を説明します。コードを見れば何をするかはわかります
• エッジケースとビジネスロジックを記録します
• 複雑な関数には例を追加します
• 自明ではないパラメーターを説明します
• 注意点や直感に反する動作を記載します

4. API ドキュメント

作成する場面： HTTP エンドポイント、SDK メソッド、またはパブリックインターフェース向け。

推奨する構成：

## Endpoint Name

### What It Does
[Plain-English explanation of the endpoint's purpose]

### Endpoint
`POST /api/v1/resource`

### Authentication
[What auth is required and how to provide it]

### Request Format
[JSON schema or example request]

### Response Format
[JSON schema or example response]

### Example Usage
[Concrete example with curl/code]

### Common Errors
[Error codes and what they mean]

### Related Endpoints
[Links to related operations]

ベストプラクティス：

• 動作する 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/                    # Source code
│   ├── components/        # Reusable UI components
│   ├── pages/             # Page-level components (routing)
│   ├── services/          # Business logic and API calls
│   ├── utils/             # Helper functions
│   └── types/             # TypeScript type definitions
├── public/                # Static assets (images, fonts)
├── tests/                 # Test files mirroring src structure
└── package.json           # Dependencies and scripts

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

図を使って、番号付きの手順で説明します。

User Request Flow:
1. User submits form → 2. Validation → 3. API call → 4. Database → 5. Response

[1] components/UserForm.tsx
    ↓ validates input
[2] services/validation.ts
    ↓ sends to API
[3] services/api.ts
    ↓ queries database
[4] Database (PostgreSQL)
    ↓ returns data
[5] components/UserForm.tsx (updates UI)

設計上の決定事項のドキュメント化

アーキテクチャ上の選択の「理由」を記録します。

## Why We Use Redux

**Decision:** State management with Redux instead of Context API

**Context:** Our app has 50+ components that need access to user
authentication state, shopping cart, and UI preferences.

**Reasoning:**
- Context API causes unnecessary re-renders with this many components
- Redux DevTools helps debug complex state changes
- Team has existing Redux expertise

**Trade-offs:**
- More boilerplate code
- Steeper learning curve for new developers
- Worth it for: performance, debugging, team familiarity

出力ガイドライン

ドキュメントを作成する際は、次の点に従ってください。

1. 対象読者に合わせて書く - 初心者、中級者、上級者のどのユーザー向けかに応じて、複雑さを調整します
2. 一貫した書式を使う - Markdown の規則に従い、見出しの階層を統一します
3. 動作する例を示す - すべてのコードスニペットとコマンドをテストします
4. ドキュメント間をリンクする - ドキュメントのナビゲーション構造を作成します
5. 保守しやすくする - コードの変更に合わせて、ドキュメントを簡単に更新できるようにします
6. 日付とバージョンを追加する - ドキュメントの最終更新日を記載します

クイックリファレンス

README を生成するコマンド： 「新しい開発者がこのプロジェクトを始められるように、README ファイルを作成してください」

アーキテクチャをドキュメント化するコマンド： 「このコードベースのアーキテクチャをドキュメント化し、各モジュールの連携方法を説明してください」

コードコメントを追加するコマンド： 「新しい開発者がロジックを理解できるよう、このファイルに説明コメントを追加してください」

API をドキュメント化するコマンド： 「このファイル内のすべてのエンドポイントについて、API ドキュメントを作成してください」