コードドキュメンテーションスキル
概要
このスキルは、ソフトウェアプロジェクト、コードベース、ライブラリ、API向けにプロフェッショナルで包括的なドキュメントを生成します。React、Django、Stripe、Kubernetesなどのプロジェクトの業界ベストプラクティスに従い、正確で構造化され、新規コントリビューターと経験豊富な開発者の両方にとって役立つドキュメントを作成します。
出力は単一ファイルのREADMEから複数ドキュメントの開発者ガイドまで多岐にわたり、常にプロジェクトの複雑さとユーザーのニーズに合わせられます。
中核機能
- バッジ、インストール、使用方法、APIリファレンスを含む包括的なREADME.mdファイルを生成
- ソースコード分析からAPIリファレンスドキュメントを作成
- 図を含むアーキテクチャと設計のドキュメントを作成
- 開発者オンボーディングとコントリビューションガイドを作成
- コミット履歴またはリリースノートからチェンジログを生成
- 言語固有の規約に従ったインラインコードドキュメントを作成
- JSDoc、docstring、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: コード構造分析
sandboxツールを使用してコードベースを探索します：
# ディレクトリ構造を取得
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"
ステップ1.3: ドキュメントの範囲を特定
分析に基づいて、作成するドキュメントを決定します：
| プロジェクトサイズ | 推奨ドキュメント |
|---|---|
| 単一ファイル/スクリプト | インラインコメント + 使用方法ヘッダー |
| 小規模ライブラリ | APIリファレンス付きREADME |
| 中規模プロジェクト | README + APIドキュメント + 例 |
| 大規模プロジェクト | README + アーキテクチャ + API + コントリビューション + チェンジログ |
フェーズ2: ドキュメント生成
ステップ2.1: READMEの生成
すべてのプロジェクトにはREADMEが必要です。以下の構造に従います：
# プロジェクト名
[プロジェクトの1行説明 — 何をするのか、なぜ重要なのか]
[](#) [](#)
## 特徴
- [主要機能1 — 簡単な説明]
- [主要機能2 — 簡単な説明]
- [主要機能3 — 簡単な説明]
## クイックスタート
### 前提条件
- [バージョン要件を含む前提条件1]
- [バージョン要件を含む前提条件2]
### インストール
[コピー＆ペースト対応のコードブロックを含むインストールコマンド]
### 基本的な使用方法
[中核機能を示す最小限の動作例]
## ドキュメント
- [別個の完全なAPIリファレンスへのリンク]
- [別個のアーキテクチャドキュメントへのリンク]
- [該当する場合、examplesディレクトリへのリンク]
## APIリファレンス
[小規模プロジェクトの場合はインラインAPIリファレンス、または生成されたドキュメントへのリンク]
## 設定
[環境変数、設定ファイル、ランタイムオプション]
## 例
[一般的なユースケースをカバーする2〜3の実用的な例]
## 開発
### セットアップ
[開発環境のセットアップ方法]
### テスト
[テストの実行方法]
### ビルド
[プロジェクトのビルド方法]
## コントリビューション
[コントリビューションガイドライン、またはCONTRIBUTING.mdへのリンク]
## ライセンス
[ライセンス情報]
ステップ2.2: APIリファレンスの生成
公開APIサーフェスごとに、以下をドキュメント化します：
関数/メソッドのドキュメント：
### `functionName(param1, param2, options?)`
この関数が何を行うかの簡単な説明。
**パラメータ：**
| パラメータ | 型 | 必須 | デフォルト値 | 説明 |
|-----------|------|----------|---------|-------------|
| `param1` | `string` | はい | — | param1の説明 |
| `param2` | `number` | はい | — | param2の説明 |
| `options` | `Object` | いいえ | `{}` | 設定オプション |
| `options.timeout` | `number` | いいえ | `5000` | タイムアウト（ミリ秒） |
**戻り値：** `Promise<Result>` — 戻り値の説明
**スローする例外：**
- `ValidationError` — param1が空の場合
- `TimeoutError` — 操作がタイムアウトを超えた場合
**例：**
```javascript
const result = await functionName("hello", 42, { timeout: 10000 });
console.log(result.data);
```
クラスのドキュメント：
### `ClassName`
クラスとその目的の簡単な説明。
**コンストラクタ：**
```javascript
new ClassName(config)
```
| パラメータ | 型 | 説明 |
|-----------|------|-------------|
| `config.option1` | `string` | 説明 |
| `config.option2` | `boolean` | 説明 |
**メソッド：**
- [`method1()`](#method1) — 簡単な説明
- [`method2(param)`](#method2) — 簡単な説明
**プロパティ：**
| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `property1` | `string` | 説明 |
| `property2` | `number` | 読み取り専用。説明 |
ステップ2.3: アーキテクチャドキュメント
中〜大規模プロジェクトの場合は、アーキテクチャドキュメントを含めます：
# アーキテクチャ概要
## システム図
[ハイレベルアーキテクチャを示すMermaid図を含める]
```mermaid
graph TD
A[クライアント] --> B[APIゲートウェイ]
B --> C[サービスA]
B --> D[サービスB]
C --> E[(データベース)]
D --> E
```
## コンポーネント概要
### コンポーネント名
- **目的**：このコンポーネントが何を行うか
- **場所**：`src/components/name/`
- **依存関係**：依存しているもの
- **公開API**：主要なエクスポートまたはインターフェース
## データフロー
[主要な操作におけるシステム内のデータの流れを説明]
## 設計上の決定
### 決定事項のタイトル
- **背景**：この決定に至った状況
- **決定**：決定された内容
- **根拠**：このアプローチが選ばれた理由
- **トレードオフ**：犠牲にしたもの
ステップ2.4: インラインコードドキュメント
言語に適したインラインドキュメントを生成します：
Python（docstring — Googleスタイル）：
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) {
フェーズ3: 品質保証
ステップ3.1: ドキュメント完全性チェック
ドキュメントが以下をカバーしていることを確認します：
- そのプロジェクトは何か — 初心者が理解できる明確なプロジェクト説明
- なぜ存在するのか — 解決する問題と価値提案
- インストール方法 — コピー＆ペースト対応のインストールコマンド
- 使用方法 — 少なくとも1つの最小限の動作例
- APIサーフェス — すべての公開関数、クラス、型がドキュメント化されている
- 設定 — すべての環境変数、設定ファイル、オプション
- エラーハンドリング — 一般的なエラーとその解決方法
- コントリビューション — 開発環境のセットアップ方法と変更の提出方法
ステップ3.2: 品質基準
| 基準 | チェック内容 |
|---|---|
| 正確性 | すべてのコード例が、説明されたAPIで実際に動作すること |
| 完全性 | 公開APIサーフェスがドキュメント化されていない状態がないこと |
| 一貫性 | 全体で同じ書式と構造が使用されていること |
| 新鮮さ | ドキュメントが現在のコード（古いバージョンではない）と一致していること |
| アクセシビリティ | 説明なしの専門用語がなく、頭字語は最初の使用時に定義されていること |
| 例 | すべての複雑な概念に少なくとも1つの実用的な例があること |
ステップ3.3: 相互参照の検証
以下を確認します：
- 言及されているすべてのファイルパスがプロジェクトに存在する
- 参照されているすべての関数とクラスがコードに存在する
- すべてのコード例が正しい関数シグネチャを使用している
- バージョン番号がプロジェクトの実際のバージョンと一致する
- すべてのリンク（内部および外部）が有効である
ドキュメントスタイルガイド
ライティングの原則
- 「なぜ」を先に述べる — 仕組みを説明する前に、なぜ存在するのかを説明する
- 段階的な開示 — シンプルに始め、徐々に複雑さを追加する
- 説明ではなく、示す — 長い説明よりもコード例を優先する
- 能動態 — 「関数はXを返します」であり、「Xは関数によって返されます」ではない
- 現在形 — 「サーバーはポート8080で起動します」であり、「サーバーはポート8080で起動します（未来形）」ではない
- 二人称 — 「ユーザーは設定できます...」ではなく「あなたは設定できます...」
書式ルール
- ATXスタイルのヘッダー（
#、##、###）を使用 - 言語指定付きのフェンス付きコードブロックを使用（
```python、```bash） - 構造化情報（パラメータ、オプション、設定）にはテーブルを使用
- 重要な注意、警告、ヒントには注意書きを使用
- 行の長さを読みやすく保つ（ソース内では散文を約80〜100文字で折り返す）
- 関数名、ファイルパス、変数名、CLIコマンドには
コード書式を使用
言語固有の規約
| 言語 | ドキュメント形式 | スタイルガイド |
|---|---|---|
| Python | Googleスタイルのdocstring | PEP 257 |
| TypeScript/JavaScript | TSDoc / JSDoc | TypeDoc規約 |
| Go | GoDocコメント | Effective Go |
| Rust | Rustdoc（///） | Rust APIガイドライン |
| Java | Javadoc | Oracle Javadocガイド |
| C/C++ | Doxygen | Doxygenマニュアル |
出力処理
生成後：
- ドキュメントファイルを
/mnt/user-data/outputs/に保存 - 複数ファイルのドキュメントの場合は、プロジェクトのディレクトリ構造を維持
present_filesツールを使用して生成されたファイルをユーザーに提示- 特定のセクションを繰り返し改善したり、詳細レベルを調整したりするオプションを提供
- 価値があると思われる追加のドキュメントを提案
注意事項
- ドキュメントを書く前に常に実際のコードを分析してください — APIシグネチャや動作を推測しないでください
- 既存のドキュメントがある場合は、ユーザーが明示的に書き換えを要求しない限り、その構造を保持してください
- 大規模なコードベースの場合は、公開APIサーフェスと主要な抽象化を最初にドキュメント化することを優先します
- ドキュメントはプロジェクトの既存のドキュメントと同じ言語で記述する必要があります。既存のドキュメントがない場合はデフォルトで英語になります
- チェンジログを生成する場合は、Keep a Changelog 形式を使用してください
- このスキルは、サードパーティの統合や依存関係をドキュメント化するために
deep-researchスキルと組み合わせてうまく機能します