code-documentation

コードドキュメント

このスキルを使用すると、AI エージェントはソースコードを分析し、さまざまな形式で高品質なドキュメントを作成できます。単一関数の docstring からプロジェクト全体の README ファイルまでを対象とし、人間の開発者と後続のツール（IDE、ドキュメント生成ツール）の両方が、一貫性のある正確な説明を活用できるようにします。

ワークフロー

1. コードベースの一覧を作成する: プロジェクトツリーを確認し、公開モジュール、クラス、関数、定数、型定義を一覧にします。どのシンボルにドキュメントがあり、どれが不足しているか、または古くなっているかを記録します。

2. ドキュメントの範囲を決める: ユーザーのリクエストに基づいて、インラインの docstring、独立した API リファレンス、プロジェクトレベルの README、またはそれらの組み合わせのどれを生成するか決定します。出力形式は、プロジェクトで既に使われている規約（JSDoc、Google スタイルの Python docstring、TypeDoc、RDoc など）に合わせます。

3. シグネチャと動作を分析する: 各シンボルについて、パラメーターの型、戻り値の型、デフォルト値、発生する例外、副作用を確認します。意図された使用方法やエッジケースを把握するため、利用可能な場合は関連するテストファイルを読みます。

4. ドキュメントを生成する: 1 行の概要、ロジックが複雑な場合は詳しい説明、型を含むパラメーターと戻り値の説明、例外やエラーの説明、公開 API の使用例を少なくとも 1 つ含むドキュメントを作成します。

5. 該当箇所に挿入または更新する: インラインのドキュメント（docstring、JSDoc コメント）では、生成したテキストを該当するシンボルの直前または内部に挿入します。独立したファイル（README、API リファレンス）では、プロジェクトのルートまたは docs/ ディレクトリに Markdown ファイルを作成するか、既存のファイルを更新します。

6. 検証と相互参照を行う: ドキュメントに記載したパラメーター名が実際のシグネチャと一致すること、参照されている型が存在すること、使用例の構文が正しいことを確認します。不整合があれば、ユーザーが確認できるように指摘します。

対応形式

• Python: Google スタイルの docstring、NumPy スタイルの docstring、Sphinx reStructuredText
• JavaScript / TypeScript: JSDoc（@param、@returns、@throws）、TypeDoc アノテーション
• Java: Javadoc（@param、@return、@throws）
• Go: Godoc コメント規約（宣言の直前に置くコメントブロック）
• Rust: Markdown を含む /// ドキュメントコメント、#[doc] 属性
• Ruby: YARD（@param、@return、@example）
• Markdown: README ファイル、CHANGELOG エントリー、アーキテクチャ決定記録（ADR）

使用方法

ファイル、ディレクトリ、または特定のシンボルをエージェントに指定し、必要なドキュメントを説明します。有効なリクエストの例：

• 「src/services/ 内のすべての公開関数に、Google スタイルの docstring を追加してください。」
• 「このプロジェクトの構成と package.json に基づいて、README を生成してください。」
• 「各メソッドの使用例を含めて、このクラスを JSDoc でドキュメント化してください。」

エージェントは、プロジェクトで既に採用されているドキュメントスタイルに従います。規約を検出できない場合は、使用する形式を尋ねるか、その言語で最も一般的なスタイルを既定で使用します。

例

例 1 — Google スタイルの docstring を使った Python クラスのドキュメント化

ユーザーのリクエスト: 「このクラスとそのメソッドに docstring を追加してください。」

変更前:

class TokenBucket:
    def __init__(self, capacity, refill_rate):
        self.capacity = capacity
        self.tokens = capacity
        self.refill_rate = refill_rate
        self._last_refill = time.monotonic()

    def consume(self, tokens=1):
        self._refill()
        if self.tokens >= tokens:
            self.tokens -= tokens
            return True
        return False

    def _refill(self):
        now = time.monotonic()
        elapsed = now - self._last_refill
        self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)
        self._last_refill = now

変更後:

class TokenBucket:
    """A token-bucket rate limiter.

    Tokens are added at a constant rate and consumed by callers.
    When the bucket is empty, requests are rejected until enough
    tokens have accumulated.

    Args:
        capacity: Maximum number of tokens the bucket can hold.
        refill_rate: Tokens added per second.

    Example:
        >>> bucket = TokenBucket(capacity=10, refill_rate=2)
        >>> bucket.consume(3)
        True
    """

    def __init__(self, capacity: float, refill_rate: float) -> None:
        self.capacity = capacity
        self.tokens = capacity
        self.refill_rate = refill_rate
        self._last_refill = time.monotonic()

    def consume(self, tokens: int = 1) -> bool:
        """Attempt to consume tokens from the bucket.

        Triggers an internal refill based on elapsed time before
        checking availability.

        Args:
            tokens: Number of tokens to consume. Defaults to 1.

        Returns:
            True if the tokens were available and consumed, False otherwise.
        """
        self._refill()
        if self.tokens >= tokens:
            self.tokens -= tokens
            return True
        return False

    def _refill(self) -> None:
        """Refill the bucket based on time elapsed since the last refill."""
        now = time.monotonic()
        elapsed = now - self._last_refill
        self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)
        self._last_refill = now

例 2 — プロジェクト構成から README を生成する

ユーザーのリクエスト: 「このプロジェクトの README を生成してください。」

次の構成のプロジェクトの場合：

myapi/
├── package.json          (name: @acme/myapi, scripts: dev, build, test)
├── src/
│   ├── index.ts          (Express app entry point)
│   ├── routes/
│   │   ├── users.ts
│   │   └── orders.ts
│   └── middleware/
│       └── auth.ts
├── tests/
│   └── users.test.ts
└── Dockerfile

生成された README.md:

# @acme/myapi

A RESTful API service built with Express and TypeScript.

## Getting Started

### Prerequisites

- Node.js >= 18
- npm or yarn

### Installation

git clone https://github.com/acme/myapi.git
cd myapi
npm install

### Running Locally

npm run dev        # Start the dev server with hot reload
npm run build      # Compile TypeScript to dist/
npm test           # Run the test suite

### Docker

docker build -t myapi .
docker run -p 3000:3000 myapi

## API Endpoints

| Method | Path           | Description           |
|--------|----------------|-----------------------|
| GET    | /users         | List all users        |
| POST   | /users         | Create a new user     |
| GET    | /orders        | List all orders       |
| POST   | /orders        | Create a new order    |

## Project Structure

- `src/index.ts` — Application entry point and server bootstrap.
- `src/routes/` — Route handlers grouped by resource.
- `src/middleware/auth.ts` — JWT authentication middleware.
- `tests/` — Jest test files.

## License

MIT

ベストプラクティス

• プロジェクト既存のスタイルに合わせてください。 コードベースで NumPy スタイルの docstring を使っている場合、プロジェクトの途中で Google スタイルに切り替えないでください。個人の好みより、一貫性が重要です。
• 「何を」だけでなく、「なぜ」を説明してください。 パラメーターの型はシグネチャから明らかなことが多いため、意図、制約、分かりにくい動作に重点を置いてください。
• すべての公開 API シンボルに、少なくとも 1 つの例を含めてください。 例はドキュメントの中で最もよく読まれる部分であり、微妙な誤解を防ぐのにも役立ちます。
• README ファイルはざっと読めるようにしてください。 見出し、表、コードブロックを使ってください。開発者は流し読みするため、最も重要な情報（インストール、実行、デプロイ）を最初に記載してください。
• 求められない限り、非公開の内部実装については記載しないでください。 実装の詳細を過剰に記載すると、メンテナンスの負担が増え、不安定な API に読者が依存する原因にもなります。
• コードを変更したら、ドキュメントを再生成してください。 古いドキュメントは、ドキュメントがないよりも悪い場合があります。CI 実行時にドキュメントとシグネチャを照合するツールを使うことをおすすめします。

エッジケース

• 動的に生成される API：ルートやメソッドが実行時に（デコレーターやプラグインシステムなどを介して）登録される場合、静的解析では検出できないことがあります。ユーザーにその点を伝え、実行時のイントロスペクションまたは手動での注釈を提案してください。
• オーバーロード関数やジェネリック関数：TypeScript のオーバーロードや Python の @overload については、シグネチャの各バリエーションを個別に記載し、それぞれに独自のパラメーター説明と例を付けてください。
• モノレポ：リポジトリに複数のパッケージが含まれる場合は、1 つの大規模なドキュメントではなく、パッケージごとの README にリンクするルート README を作成してください。
• 英語以外のコードベース：変数名や既存のコメントが別の言語で書かれている場合は、ドキュメントを英語とプロジェクトの主要言語のどちらにするか、ユーザーに確認してください。
• 独自仕様または機密性の高いコード：公開される可能性のある README の生成時に、内部 URL、認証情報、ビジネスロジックの詳細を含めないでください。必要に応じて、機密情報を削除するか、一般化してください。