code-documentation

コードドキュメント作成スキル

概要

このスキルは、ソフトウェアプロジェクト、コードベース、ライブラリ、API向けに、プロフェッショナルで包括的なドキュメントを作成します。React、Django、Stripe、Kubernetesなどのプロジェクトで採用されている業界のベストプラクティスに従い、新規コントリビューターにも経験豊富な開発者にも正確で、構成が整っていて、役立つドキュメントを作成します。

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

主な機能

• バッジ、インストール方法、使用方法、APIリファレンスを含む包括的なREADME.mdファイルを作成します
• ソースコードの分析からAPIリファレンスドキュメントを作成します
• 図を用いたアーキテクチャおよび設計ドキュメントを作成します
• 開発者向けのオンボーディングガイドやコントリビューションガイドを作成します
• コミット履歴やリリースノートから変更履歴を生成します
• 言語固有の規約に従ってインラインコードドキュメントを作成します
• JSDoc、docstrings、GoDoc、Javadoc、Rustdocの形式に対応します
• プロジェクトの言語やエコシステムに合わせてドキュメントのスタイルを調整します

このスキルを使用する場面

次の場合は必ずこのスキルを読み込んでください。

• ユーザーが、コードについて「ドキュメント化する」「ドキュメントを作成する」「ドキュメントを書く」と依頼した場合
• ユーザーがREADME、APIリファレンス、開発者ガイドを求めた場合
• ユーザーがコードベースやリポジトリを共有し、ドキュメントの生成を希望した場合
• ユーザーが既存のドキュメントの改善や更新を依頼した場合
• ユーザーが図を含むアーキテクチャドキュメントを必要としている場合
• ユーザーが変更履歴や移行ガイドの作成を依頼した場合

ドキュメント作成ワークフロー

フェーズ 1：コードベースの分析

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

ステップ 1.1：プロジェクトの調査

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

項目	確認方法
言語	ファイル拡張子、package.json、pyproject.toml、go.mod、Cargo.tomlなどを確認します
フレームワーク	依存関係から、既知のフレームワーク（React、Django、Express、Springなど）を調べます
ビルドシステム	Makefile、CMakeLists.txt、webpack.config.js、build.gradleなどを確認します
パッケージマネージャー	npm/yarn/pnpm、pip/uv/poetry、cargo、go modulesなどを確認します
プロジェクト構成	ディレクトリツリーを把握して、アーキテクチャを理解します
エントリーポイント	メインファイル、CLIのエントリーポイント、エクスポートされているモジュールを探します
既存ドキュメント	既存のREADME、docs/、wiki、インラインドキュメントを確認します

ステップ 1.2：コード構成の分析

サンドボックスツールを使ってコードベースを調査します。

# Get directory structure
ls /mnt/user-data/uploads/project-dir/

# Read key files
read_file /mnt/user-data/uploads/project-dir/package.json
read_file /mnt/user-data/uploads/project-dir/pyproject.toml

# Search for public API surfaces
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"

ステップ 1.3：ドキュメントの範囲を特定

分析結果に基づいて、作成するドキュメントを決定します。

プロジェクトの規模	推奨されるドキュメント
単一ファイル／スクリプト	インラインコメント＋使用方法のヘッダー
小規模ライブラリ	APIリファレンスを含むREADME
中規模プロジェクト	README＋APIドキュメント＋使用例
大規模プロジェクト	README＋アーキテクチャ＋API＋コントリビューションガイド＋変更履歴

フェーズ 2：ドキュメントの作成

ステップ 2.1：READMEの作成

すべてのプロジェクトにREADMEが必要です。次の構成に従ってください。

# Project Name

[One-line project description — what it does and why it matters]

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

## Features

- [Key feature 1 — brief description]
- [Key feature 2 — brief description]
- [Key feature 3 — brief description]

## Quick Start

### Prerequisites

- [Prerequisite 1 with version requirement]
- [Prerequisite 2 with version requirement]

### Installation

[Installation commands with copy-paste-ready code blocks]

### Basic Usage

[Minimal working example that demonstrates core functionality]

## Documentation

- [Link to full API reference if separate]
- [Link to architecture docs if separate]
- [Link to examples directory if applicable]

## API Reference

[Inline API reference for smaller projects OR link to generated docs]

## Configuration

[Environment variables, config files, or runtime options]

## Examples

[2-3 practical examples covering common use cases]

## Development

### Setup

[How to set up a development environment]

### Testing

[How to run tests]

### Building

[How to build the project]

## Contributing

[Contribution guidelines or link to CONTRIBUTING.md]

## License

[License information]

ステップ 2.2：APIリファレンスの作成

公開APIごとに、以下を記載します。

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

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

Brief description of what this function does.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `param1` | `string` | Yes | — | Description of param1 |
| `param2` | `number` | Yes | — | Description of param2 |
| `options` | `Object` | No | `{}` | Configuration options |
| `options.timeout` | `number` | No | `5000` | Timeout in milliseconds |

**Returns:** `Promise<Result>` — Description of return value

**Throws:**
- `ValidationError` — When param1 is empty
- `TimeoutError` — When the operation exceeds the timeout

**Example:**

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

クラスのドキュメント：

### `ClassName`

Brief description of the class and its purpose.

**Constructor:**

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

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

**Methods:**

- [`method1()`](#method1) — Brief description
- [`method2(param)`](#method2) — Brief description

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `property1` | `string` | Description |
| `property2` | `number` | Read-only. Description |

ステップ 2.3：アーキテクチャドキュメントの作成

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

# Architecture Overview

## System Diagram

[Include a Mermaid diagram showing the high-level architecture]

\`\`\`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**: What this component does
- **Location**: `src/components/name/`
- **Dependencies**: What it depends on
- **Public API**: Key exports or interfaces

## Data Flow

[Describe how data flows through the system for key operations]

## Design Decisions

### Decision Title
- **Context**: What situation led to this decision
- **Decision**: What was decided
- **Rationale**: Why this approach was chosen
- **Trade-offs**: What was sacrificed

ステップ 2.4：インラインコードドキュメント

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

Python（Docstrings — Googleスタイル）：

def process_data(input_path: str, options: dict | None = None) -> ProcessResult:
    """Process data from the given file path.

    Reads the input file, applies transformations based on the provided
    options, and returns a structured result object.

    Args:
        input_path: Absolute path to the input data file.
            Supports CSV, JSON, and Parquet formats.
        options: Optional configuration dictionary.
            - "validate" (bool): Enable input validation. Defaults to True.
            - "format" (str): Output format ("json" or "csv"). Defaults to "json".

    Returns:
        A ProcessResult containing the transformed data and metadata.

    Raises:
        FileNotFoundError: If input_path does not exist.
        ValidationError: If validation is enabled and data is malformed.

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

TypeScript（JSDoc / TSDoc）：

/**
 * Fetches user data from the API and transforms it for display.
 *
 * @param userId - The unique identifier of the user
 * @param options - Configuration options for the fetch operation
 * @param options.includeProfile - Whether to include the full profile. Defaults to `false`.
 * @param options.cache - Cache duration in seconds. Set to `0` to disable.
 * @returns The transformed user data ready for rendering
 * @throws {NotFoundError} When the user ID does not exist
 * @throws {NetworkError} When the API is unreachable
 *
 * @example
 * ```ts
 * const user = await fetchUser("usr_123", { includeProfile: true });
 * console.log(user.displayName);
 * ```
 */

Go（GoDoc）：

// ProcessData reads the input file at the given path, applies the specified
// transformations, and returns the processed result.
//
// The input path must be an absolute path to a CSV or JSON file.
// If options is nil, default options are used.
//
// ProcessData returns an error if the file does not exist or cannot be parsed.
func ProcessData(inputPath string, options *ProcessOptions) (*Result, error) {

フェーズ 3：品質保証

ステップ 3.1：ドキュメントの網羅性チェック

ドキュメントで以下を網羅していることを確認します。

• 概要 — 初めての人にも理解できる明確なプロジェクトの説明
• 目的 — 解決する問題と提供価値
• インストール方法 — コピーしてすぐ実行できるインストールコマンド
• 使い方 — 少なくとも 1 つの最小限の動作例
• API の範囲 — すべての公開関数、クラス、型の説明
• 設定 — すべての環境変数、設定ファイル、オプション
• エラー処理 — よくあるエラーとその解決方法
• コントリビューション — 開発環境のセットアップ方法と変更の提出方法

ステップ 3.2：品質基準

基準	チェック項目
正確性	すべてのコード例が、説明されている API で実際に動作すること
網羅性	公開 API の範囲に説明漏れがないこと
一貫性	全体を通して書式と構成が統一されていること
最新性	ドキュメントが古いバージョンではなく、現在のコードに対応していること
アクセシビリティ	説明のない専門用語がなく、略語が初出時に定義されていること
例	複雑な概念ごとに、少なくとも 1 つの実用例があること

ステップ 3.3：相互参照の検証

以下を確認します。

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

ドキュメントのスタイルガイド

執筆の原則

1. まず「なぜ」を説明する — 仕組みを説明する前に、その機能が存在する理由を説明します
2. 段階的に情報を提示する — 簡単な内容から始め、徐々に複雑にしていきます
3. 説明より実例を示す — 長い説明よりコード例を優先します
4. 能動態を使う — 「関数は X を返します」とし、「X は関数によって返されます」とはしません
5. 現在形を使う — 「サーバーはポート 8080 で起動します」とし、「サーバーはポート 8080 で起動する予定です」とはしません
6. 二人称を使う — 「設定できます」とし、「ユーザーは設定できます」とはしません

書式ルール

• ATX スタイルの見出し（#、##、###）を使用します
• 言語を指定したフェンス付きコードブロック（```python、```bash）を使用します
• 構造化された情報（パラメーター、オプション、設定）には表を使用します
• 重要な注意事項、警告、ヒントにはアドモニションを使用します
• 読みやすい行の長さを保ちます（ソースでは文章を約 80～100 文字で折り返します）
• 関数名、ファイルパス、変数名、CLI コマンドには コード書式 を使用します

言語ごとの規約

言語	ドキュメント形式	スタイルガイド
Python	Google スタイルの docstring	PEP 257
TypeScript/JavaScript	TSDoc / JSDoc	TypeDoc の規約
Go	GoDoc コメント	Effective Go
Rust	Rustdoc（///）	Rust API Guidelines
Java	Javadoc	Oracle Javadoc Guide
C/C++	Doxygen	Doxygen マニュアル

出力の取り扱い

生成後：

• ドキュメントファイルを /mnt/user-data/outputs/ に保存します
• 複数ファイルのドキュメントでは、プロジェクトのディレクトリ構造を維持します
• present_files ツールを使って、生成したファイルをユーザーに提示します
• 特定のセクションの反復作業や詳細度の調整を提案します
• 追加すると有用なドキュメントを提案します

注意事項

• ドキュメントを書く前に必ず実際のコードを分析します。API のシグネチャや動作を推測してはいけません
• 既存のドキュメントがある場合、ユーザーが明示的に書き直しを依頼しない限り、その構成を維持します
• 大規模なコードベースでは、まず公開 API の範囲と主要な抽象化のドキュメント化を優先します
• ドキュメントはプロジェクトの既存ドキュメントと同じ言語で作成します。既存のドキュメントがない場合は、英語を既定とします
• 変更履歴を生成する場合は、Keep a Changelog 形式を使用します
• このスキルは、サードパーティの統合や依存関係をドキュメント化する際に、deep-research スキルと組み合わせると効果的です