Code Documentation Skill

Overview

このスキルは、ソフトウェアプロジェクト、コードベース、ライブラリ、API の専門的で包括的なドキュメントを生成します。React、Django、Stripe、Kubernetes などのプロジェクトからのインダストリベストプラクティスに従い、新しいコントリビューターと経験豊富な開発者の両方にとって正確で構造化された有用なドキュメントを生成します。

出力は単一ファイルの README から複数ドキュメントの開発者ガイドまでの範囲で、常にプロジェクトの複雑さとユーザーのニーズに合わせられます。

Core Capabilities

• badges、インストール、使用法、API リファレンスを含む包括的な README.md ファイルの生成
• ソースコード解析から API リファレンスドキュメントの作成
• ダイアグラムを含むアーキテクチャとデザインドキュメントの生成
• 開発者のオンボーディングとコントリビューションガイドの作成
• コミット履歴またはリリースノートからのチェンジログの生成
• 言語固有の慣例に従うインラインコードドキュメントの作成
• JSDoc、docstrings、GoDoc、Javadoc、Rustdoc フォーマットのサポート
• プロジェクトの言語とエコシステムに合わせたドキュメントスタイルの適応

When to Use This Skill

常にこのスキルを読み込む場合:

• ユーザーが任意のコードに対して「ドキュメント化する」「ドキュメントを作成する」「ドキュメントを書く」と要求した場合
• ユーザーが README、API リファレンス、または開発者ガイドを要求した場合
• ユーザーがコードベースまたはリポジトリを共有し、ドキュメントの生成を望んでいる場合
• ユーザーが既存のドキュメントを改善または更新するように要求した場合
• ユーザーがダイアグラムを含むアーキテクチャドキュメントが必要な場合
• ユーザーがチェンジログまたはマイグレーションガイドを要求した場合

Documentation Workflow

Phase 1: Codebase Analysis

ドキュメントを作成する前に、コードベースを十分に理解します。

Step 1.1: Project Discovery

プロジェクトの基本情報を特定します:

Field	How to Determine
Language(s)	ファイル拡張子、package.json、pyproject.toml、go.mod、Cargo.toml などを確認
Framework	既知のフレームワーク（React、Django、Express、Spring など）の依存関係を確認
Build System	Makefile、CMakeLists.txt、webpack.config.js、build.gradle などを確認
Package Manager	npm/yarn/pnpm、pip/uv/poetry、cargo、go modules など
Project Structure	ディレクトリツリーをマッピングしてアーキテクチャを理解
Entry Points	メインファイル、CLI エントリーポイント、エクスポートされたモジュールを検索
Existing Docs	既存の README、docs/、wiki、またはインラインドキュメントを確認

Step 1.2: Code Structure Analysis

サンドボックスツールを使用してコードベースを探索します:

# ディレクトリ構造を取得
ls /mnt/user-data/uploads/project-dir/

# 主要なファイルを読む
read_file /mnt/user-data/uploads/project-dir/package.json
read_file /mnt/user-data/uploads/project-dir/pyproject.toml

# 公開 API サーフェスを検索
grep -r "export " /mnt/user-data/uploads/project-dir/src/
grep -r "def " /mnt/user-data/uploads/project-dir/src/ --include="*.py"
grep -r "func " /mnt/user-data/uploads/project-dir/ --include="*.go"

Step 1.3: Identify Documentation Scope

分析に基づいて、生成するドキュメントを決定します:

Project Size	Recommended Documentation
Single file / script	インラインコメント + 使用ヘッダー
Small library	API リファレンス付きの README
Medium project	README + API ドキュメント + 例
Large project	README + アーキテクチャ + API + コントリビューション + チェンジログ

Phase 2: Documentation Generation

Step 2.1: README Generation

すべてのプロジェクトが README を必要とします。この構造に従います:

# Project Name

[ワンライナープロジェクト説明 — それが何をするのか、なぜ重要なのか]

[![Badge](link)](#) [![Badge](link)](#)

## Features

- [主要機能 1 — 簡潔な説明]
- [主要機能 2 — 簡潔な説明]
- [主要機能 3 — 簡潔な説明]

## Quick Start

### Prerequisites

- [前提条件 1 とバージョン要件]
- [前提条件 2 とバージョン要件]

### Installation

[コピーペースト可能なコードブロック付きのインストールコマンド]

### Basic Usage

[主要機能を実演する最小限の動作例]

## Documentation

- [別途作成した場合は完全な API リファレンスへのリンク]
- [別途作成した場合はアーキテクチャドキュメントへのリンク]
- [該当する場合は例ディレクトリへのリンク]

## API Reference

[小規模プロジェクトの場合はインライン API リファレンス、または生成されたドキュメントへのリンク]

## Configuration

[環境変数、設定ファイル、またはランタイムオプション]

## Examples

[一般的な使用例をカバーする 2～3 つの実践例]

## Development

### Setup

[開発環境をセットアップする方法]

### Testing

[テストを実行する方法]

### Building

[プロジェクトをビルドする方法]

## Contributing

[コントリビューションガイドまたは CONTRIBUTING.md へのリンク]

## License

[ライセンス情報]

Step 2.2: API Reference Generation

各公開 API サーフェスについて以下を文書化します:

Function / Method Documentation:

### `functionName(param1, param2, options?)`

この関数が何をするかの簡潔な説明。

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `param1` | `string` | Yes | — | param1 の説明 |
| `param2` | `number` | Yes | — | param2 の説明 |
| `options` | `Object` | No | `{}` | 設定オプション |
| `options.timeout` | `number` | No | `5000` | ミリ秒単位のタイムアウト |

**Returns:** `Promise<Result>` — 戻り値の説明

**Throws:**
- `ValidationError` — param1 が空の場合
- `TimeoutError` — 操作がタイムアウトを超えた場合

**Example:**

\`\`\`javascript
const result = await functionName("hello", 42, { timeout: 10000 });
console.log(result.data);
\`\`\`

Class Documentation:

### `ClassName`

クラスとその目的の簡潔な説明。

**Constructor:**

\`\`\`javascript
new ClassName(config)
\`\`\`

| Parameter | Type | Description |
|-----------|------|-------------|
| `config.option1` | `string` | 説明 |
| `config.option2` | `boolean` | 説明 |

**Methods:**

- [`method1()`](#method1) — 簡潔な説明
- [`method2(param)`](#method2) — 簡潔な説明

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `property1` | `string` | 説明 |
| `property2` | `number` | 読み取り専用。説明 |

Step 2.3: Architecture Documentation

中規模以上のプロジェクトでは、アーキテクチャドキュメントを含めます:

# Architecture Overview

## System Diagram

[高レベルのアーキテクチャを示す Mermaid ダイアグラムを含める]

\`\`\`mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Service A]
    B --> D[Service B]
    C --> E[(Database)]
    D --> E
\`\`\`

## Component Overview

### Component Name
- **Purpose**: このコンポーネントが何をするか
- **Location**: `src/components/name/`
- **Dependencies**: 何に依存しているか
- **Public API**: 主要なエクスポート またはインターフェース

## Data Flow

[システムを通じてキー操作のデータがどのように流れるかを説明]

## Design Decisions

### Decision Title
- **Context**: この決定につながった状況
- **Decision**: 何が決定されたか
- **Rationale**: このアプローチが選ばれた理由
- **Trade-offs**: 何が犠牲になったか

Step 2.4: Inline Code Documentation

言語に適したインラインドキュメントを生成します:

Python (Docstrings — Google style):

def process_data(input_path: str, options: dict | None = None) -> ProcessResult:
    """指定されたファイルパスからデータを処理します。

    入力ファイルを読み込み、提供されたオプションに基づいて変換を適用し、
    構造化された結果オブジェクトを返します。

    Args:
        input_path: 入力データファイルへの絶対パス。
            CSV、JSON、Parquet フォーマットをサポートしています。
        options: オプションの設定辞書。
            - "validate" (bool): 入力検証を有効にします。デフォルトは True。
            - "format" (str): 出力フォーマット ("json" または "csv")。デフォルトは "json"。

    Returns:
        変換されたデータとメタデータを含む ProcessResult。

    Raises:
        FileNotFoundError: input_path が存在しない場合。
        ValidationError: 検証が有効で、データが不正な場合。

    Example:
        >>> result = process_data("/data/input.csv", {"validate": True})
        >>> print(result.row_count)
        1500
    """

TypeScript (JSDoc / TSDoc):

/**
 * API からユーザーデータを取得し、表示用に変換します。
 *
 * @param userId - ユーザーの一意の識別子
 * @param options - フェッチ操作の設定オプション
 * @param options.includeProfile - 完全なプロフィールを含めるかどうか。デフォルトは `false`。
 * @param options.cache - キャッシュ期間（秒単位）。`0` に設定して無効化。
 * @returns レンダリング用に準備された変換済みのユーザーデータ
 * @throws {NotFoundError} ユーザー ID が存在しない場合
 * @throws {NetworkError} API に到達できない場合
 *
 * @example
 * ```ts
 * const user = await fetchUser("usr_123", { includeProfile: true });
 * console.log(user.displayName);
 * ```
 */

Go (GoDoc):

// ProcessData は、指定されたパスの入力ファイルを読み込み、指定された変換を適用し、
// 処理結果を返します。
//
// 入力パスは CSV または JSON ファイルへの絶対パスである必要があります。
// options が nil の場合、デフォルトオプションが使用されます。
//
// ProcessData はファイルが存在しない場合またはパースできない場合はエラーを返します。
func ProcessData(inputPath string, options *ProcessOptions) (*Result, error) {

Phase 3: Quality Assurance

Step 3.1: Documentation Completeness Check

ドキュメントが以下をカバーしていることを確認します:

• What it is — 新しい人でも理解できるクリアなプロジェクト説明
• Why it exists — それが解決する問題と価値提案
• How to install — コピーペースト可能なインストールコマンド
• How to use — 最低 1 つの最小限の動作例
• API surface — すべての公開関数、クラス、型が文書化されている
• Configuration — すべての環境変数、設定ファイル、オプション
• Error handling — 一般的なエラーとその解決方法
• Contributing — 開発環境をセットアップし、変更を送信する方法

Step 3.2: Quality Standards

Standard	Check
Accuracy	すべてのコード例は説明されている API で実際に動作する必要があります
Completeness	文書化されていない公開 API サーフェスがない
Consistency	全体を通じて同じフォーマットと構造
Freshness	ドキュメントが古いバージョンではなく現在のコードと一致している
Accessibility	説明のない専門用語やアクロニムがない。初出で定義
Examples	すべての複雑な概念に少なくとも 1 つの実践例がある

Step 3.3: Cross-reference Validation

以下を確認します:

• 言及されているすべてのファイルパスがプロジェクトに存在する
• 参照されているすべての関数とクラスがコードに存在する
• すべてのコード例が正しい関数シグネチャを使用している
• バージョン番号がプロジェクトの実際のバージョンと一致している
• すべてのリンク（内部と外部）が有効である

Documentation Style Guide

Writing Principles

1. Lead with the "why" — 何かの動作方法を説明する前に、なぜそれが存在するのかを説明
2. Progressive disclosure — シンプルに始めて、徐々に複雑さを追加
3. Show, don't tell — 長い説明より、コード例を優先
4. Active voice — 「関数は X を返す」ではなく「The function returns X」
5. Present tense — 「サーバーはポート 8080 で起動します」ではなく「The server starts on port 8080」
6. Second person — 「ユーザーは設定できます」ではなく「You can configure...」

Formatting Rules

• ATX スタイルのヘッダーを使用（#、##、###）
• 言語指定付きのフェンスコードブロックを使用（```python、```bash）
• 構造化情報にはテーブルを使用（パラメーター、オプション、設定）
• 重要な注記、警告、ヒントには admonitions を使用
• 読みやすい行長を保つ（ソースで約 80～100 文字で折り返す）
• 関数名、ファイルパス、変数名、CLI コマンドに code formatting を使用

Language-Specific Conventions

Language	Doc Format	Style Guide
Python	Google-style docstrings	PEP 257
TypeScript/JavaScript	TSDoc / JSDoc	TypeDoc conventions
Go	GoDoc comments	Effective Go
Rust	Rustdoc (///)	Rust API Guidelines
Java	Javadoc	Oracle Javadoc Guide
C/C++	Doxygen	Doxygen manual

Output Handling

生成後:

• ドキュメントファイルを /mnt/user-data/outputs/ に保存
• マルチファイルドキュメントの場合、プロジェクトディレクトリ構造を維持
• present_files ツールを使用して生成されたファイルをユーザーに提示
• 特定のセクションの反復や詳細レベルの調整を提供
• 価値がある可能性のある追加ドキュメントを提案

Notes

• ドキュメントを作成する前に常に実際のコードを分析してください — API シグネチャや動作を推測しないでください
• 既存のドキュメントが存在する場合、ユーザーが明示的に書き直しを要求しない限りその構造を保持
• 大規模なコードベースの場合、最初に公開 API サーフェスと主要な抽象化ドキュメント化を優先
• ドキュメントはプロジェクトの既存ドキュメントと同じ言語で作成してください。存在しない場合は英語をデフォルトとします
• チェンジログを生成する場合、Keep a Changelog フォーマットを使用
• このスキルは、サードパーティの統合または依存関係のドキュメント化のために deep-research スキルと組み合わせるとよく機能します