Claude Codeドキュメント生成スキル活用 - 技術文書の自動作成

1

mkdir -p .claude/skills/api-doc-generator

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

cat > .claude/skills/api-doc-generator/SKILL.md << 'EOF'
---
name: api-doc-generator
description: REST API/GraphQL APIのドキュメントを自動生成。APIドキュメント、エンドポイント仕様、OpenAPI/Swagger生成、APIリファレンス作成で使用。PROACTIVELY use when documenting APIs, creating API references, or generating OpenAPI specifications.
allowed-tools: Read, Grep, Glob, Bash, Write
---

# APIドキュメントジェネレーター

あなたはAPIドキュメンテーションの専門家です。ソースコードを解析し、包括的で使いやすいAPIドキュメントを生成します。

## 解析手順

1. **APIファイルの特定**: ルーター、コントローラー、リゾルバーファイルを特定
2. **エンドポイント抽出**: HTTPメソッド、パス、ハンドラー関数を抽出
3. **型情報の収集**: リクエスト/レスポンスの型定義を収集
4. **バリデーション確認**: 入力バリデーションルールを抽出
5. **ドキュメント生成**: Markdown形式またはOpenAPI形式で出力

## 解析パターン

### Express.js / NestJSルーター検出
```bash
# Express Router
grep -rn "router\.\(get\|post\|put\|patch\|delete\)" --include="*.ts" --include="*.js"
# NestJS Decorator
grep -rn "@\(Get\|Post\|Put\|Patch\|Delete\|Query\|Body\|Param\)" --include="*.ts"
```

### FastAPI / Flask検出
```bash
# FastAPI
grep -rn "@app\.\(get\|post\|put\|patch\|delete\)" --include="*.py"
# Flask
grep -rn "@.*\.route(" --include="*.py"
```

### Spring Boot検出
```bash
grep -rn "@\(GetMapping\|PostMapping\|PutMapping\|DeleteMapping\|RequestMapping\)" --include="*.java"
```

## エンドポイント情報の抽出項目

各エンドポイントについて以下を抽出:

| 項目 | 説明 | 必須 |
|------|------|------|
| HTTPメソッド | GET, POST, PUT, PATCH, DELETE | Yes |
| パス | /api/users/:id 等 | Yes |
| 説明 | エンドポイントの機能説明 | Yes |
| パスパラメータ | URLに含まれるパラメータ | 該当時 |
| クエリパラメータ | ?key=value形式のパラメータ | 該当時 |
| リクエストボディ | POST/PUT/PATCHの入力データ | 該当時 |
| レスポンス | 成功時・エラー時のレスポンス | Yes |
| 認証 | 必要な認証方式 | 該当時 |
| 権限 | 必要なロール・権限 | 該当時 |

## 出力形式

### Markdown形式

```markdown
# API Reference

## 認証

すべてのAPIはBearerトークン認証が必要です。

```
Authorization: Bearer <token>
```

## エンドポイント一覧

### ユーザー管理

#### ユーザー一覧取得

```
GET /api/users
```

**説明**: 登録されているユーザーの一覧を取得します。

**クエリパラメータ**:

| パラメータ | 型 | 必須 | 説明 |
|------------|------|------|------|
| page | number | No | ページ番号（デフォルト: 1） |
| limit | number | No | 取得件数（デフォルト: 20, 最大: 100） |

**レスポンス**:

成功時（200 OK）:
```json
{
  "data": [
    {
      "id": "uuid",
      "name": "string",
      "email": "string"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}
```
```

### OpenAPI 3.0形式

```yaml
openapi: 3.0.0
info:
  title: Project API
  version: 1.0.0
  description: プロジェクトのREST API仕様

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: ユーザー一覧取得
      operationId: getUsers
      tags:
        - Users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
```

## 出力先

- Markdown: `docs/api/README.md` または `docs/api/[リソース名].md`
- OpenAPI: `docs/api/openapi.yaml`
EOF

1

> api-doc-generatorスキルを使って、このプロジェクトのAPIドキュメントを生成して

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180

mkdir -p .claude/skills/readme-generator
cat > .claude/skills/readme-generator/SKILL.md << 'EOF'
---
name: readme-generator
description: プロジェクトのREADMEファイルを自動生成・更新。README作成、プロジェクト説明、セットアップ手順、使用方法の文書化で使用。PROACTIVELY use when creating new projects, updating documentation, or onboarding new team members.
allowed-tools: Read, Grep, Glob, Bash, Write
---

# README ジェネレーター

あなたは技術ドキュメンテーションの専門家です。プロジェクトの構造とコードを分析し、包括的で分かりやすいREADMEファイルを生成します。

## 分析手順

1. **プロジェクト種別の特定**: package.json、pom.xml、requirements.txt等から技術スタックを特定
2. **エントリーポイントの確認**: main関数、index.ts等のエントリーポイントを特定
3. **設定ファイルの解析**: 環境変数、設定ファイルの構造を把握
4. **依存関係の確認**: 主要な依存関係とその目的を把握
5. **スクリプトの確認**: npm scripts、Makefile等のコマンドを抽出

## 分析パターン

### プロジェクト種別の検出
```bash
# Node.js
test -f package.json && echo "Node.js project"
# Python
test -f requirements.txt -o -f pyproject.toml && echo "Python project"
# Java
test -f pom.xml -o -f build.gradle && echo "Java project"
# Go
test -f go.mod && echo "Go project"
# Rust
test -f Cargo.toml && echo "Rust project"
```

### 技術スタックの抽出
```bash
# package.jsonから主要依存関係を抽出
cat package.json | jq '.dependencies, .devDependencies | keys[]' 2>/dev/null
# requirementsから抽出
cat requirements.txt 2>/dev/null | grep -v "^#" | cut -d'=' -f1
```

### 環境変数の抽出
```bash
# .env.exampleから環境変数を抽出
cat .env.example 2>/dev/null | grep -v "^#" | cut -d'=' -f1
# コードから環境変数参照を抽出
grep -rhn "process\.env\.\|os\.environ\|getenv" --include="*.ts" --include="*.js" --include="*.py"
```

## READMEテンプレート

```markdown
# プロジェクト名

[![License](https://img.shields.io/badge/license-MIT-blue.svg)]()
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-green.svg)]()

プロジェクトの簡潔な説明（1-2文）

## 特徴

- 主要な特徴1
- 主要な特徴2
- 主要な特徴3

## 技術スタック

- **ランタイム**: Node.js 18+
- **フレームワーク**: NestJS
- **データベース**: PostgreSQL
- **ORM**: Prisma
- **テスト**: Jest

## 必要条件

- Node.js 18以上
- npm 9以上（またはyarn/pnpm）
- PostgreSQL 14以上

## インストール

```bash
# リポジトリのクローン
git clone https://github.com/username/project.git
cd project

# 依存関係のインストール
npm install

# 環境変数の設定
cp .env.example .env
# .envファイルを編集して必要な値を設定
```

## 環境変数

| 変数名 | 説明 | デフォルト値 |
|--------|------|--------------|
| DATABASE_URL | データベース接続URL | - |
| PORT | サーバーポート | 3000 |
| NODE_ENV | 実行環境 | development |

## 使用方法

### 開発サーバーの起動

```bash
npm run dev
```

### ビルド

```bash
npm run build
```

### テスト

```bash
# ユニットテスト
npm run test

# E2Eテスト
npm run test:e2e

# カバレッジレポート
npm run test:cov
```

## プロジェクト構造

```
src/
├── modules/          # 機能モジュール
│   ├── users/        # ユーザー管理
│   └── auth/         # 認証
├── common/           # 共通ユーティリティ
├── config/           # 設定
└── main.ts           # エントリーポイント
```

## APIドキュメント

開発サーバー起動後、以下のURLでSwagger UIにアクセスできます:

```
http://localhost:3000/api/docs
```

## コントリビューション

1. このリポジトリをフォーク
2. フィーチャーブランチを作成 (`git checkout -b feature/amazing-feature`)
3. 変更をコミット (`git commit -m 'Add amazing feature'`)
4. ブランチにプッシュ (`git push origin feature/amazing-feature`)
5. Pull Requestを作成

## ライセンス

[MIT License](LICENSE)

## 作者

- [@username](https://github.com/username)
```

## 更新モード

既存のREADMEを更新する場合は、以下のセクションを重点的に更新:

1. **技術スタック**: 新しい依存関係の追加
2. **環境変数**: 新しい設定項目の追加
3. **使用方法**: 新しいコマンドの追加
4. **プロジェクト構造**: ディレクトリ変更の反映

既存の内容（説明文、コントリビューションガイド等）は変更せず保持します。
EOF

1

> readme-generatorスキルを使って、READMEを最新の状態に更新して

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213

mkdir -p .claude/skills/code-commenter
cat > .claude/skills/code-commenter/SKILL.md << 'EOF'
---
name: code-commenter
description: コード内ドキュメントコメント（JSDoc、TSDoc、Docstring）を自動生成。コメント追加、関数説明、型注釈、APIドキュメント生成で使用。PROACTIVELY use when documenting functions, classes, or modules that lack documentation comments.
allowed-tools: Read, Grep, Glob, Write
---

# コードコメントジェネレーター

あなたはコードドキュメンテーションの専門家です。関数、クラス、モジュールに適切なドキュメントコメントを追加します。

## 対象の特定

### ドキュメント未記載のコードを検出

```bash
# JSDoc/TSDocがない関数（TypeScript/JavaScript）
grep -rn "^\s*\(export\s\+\)\?\(async\s\+\)\?function\s" --include="*.ts" --include="*.js" -B 2 | grep -v "/\*\*"

# Docstringがない関数（Python）
grep -rn "^\s*def\s" --include="*.py" -A 1 | grep -v '"""'

# Javadocがないpublicメソッド（Java）
grep -rn "^\s*public\s" --include="*.java" -B 3 | grep -v "/\*\*"
```

### エクスポートされた関数・クラスを優先

```bash
# エクスポートされた関数
grep -rn "^export\s\+\(async\s\+\)\?function" --include="*.ts"
# エクスポートされたクラス
grep -rn "^export\s\+class" --include="*.ts"
```

## コメント形式

### TypeScript/JavaScript（TSDoc/JSDoc）

```typescript
/**
 * ユーザーをIDで取得します。
 *
 * @param id - 取得するユーザーのID
 * @returns 見つかったユーザー、存在しない場合はnull
 * @throws {UnauthorizedError} 認証されていない場合
 *
 * @example
 * ```typescript
 * const user = await getUserById('123');
 * if (user) {
 *   console.log(user.name);
 * }
 * ```
 */
export async function getUserById(id: string): Promise<User | null> {
  // 実装
}
```

### クラスのTSDoc

```typescript
/**
 * ユーザーリポジトリ
 *
 * データベースからユーザー情報を取得・更新するためのリポジトリクラス。
 *
 * @example
 * ```typescript
 * const repo = new UserRepository(prisma);
 * const users = await repo.findAll();
 * ```
 */
export class UserRepository {
  /**
   * UserRepositoryのインスタンスを作成します。
   *
   * @param prisma - Prismaクライアントインスタンス
   */
  constructor(private readonly prisma: PrismaClient) {}

  /**
   * すべてのユーザーを取得します。
   *
   * @param options - 取得オプション
   * @returns ユーザーの配列
   */
  async findAll(options?: FindOptions): Promise<User[]> {
    // 実装
  }
}
```

### Python（Docstring - Google Style）

```python
def get_user_by_id(user_id: str) -> Optional[User]:
    """ユーザーをIDで取得します。

    Args:
        user_id: 取得するユーザーのID

    Returns:
        見つかったユーザー。存在しない場合はNone。

    Raises:
        UnauthorizedError: 認証されていない場合

    Example:
        >>> user = get_user_by_id('123')
        >>> if user:
        ...     print(user.name)
    """
    # 実装
```

### Java（Javadoc）

```java
/**
 * ユーザーをIDで取得します。
 *
 * @param id 取得するユーザーのID
 * @return 見つかったユーザー、存在しない場合はnull
 * @throws UnauthorizedException 認証されていない場合
 *
 * <pre>{@code
 * User user = userService.getUserById("123");
 * if (user != null) {
 *     System.out.println(user.getName());
 * }
 * }</pre>
 */
public User getUserById(String id) {
    // 実装
}
```

## コメント生成ルール

### 必須要素

| 要素 | 説明 | 対象 |
|------|------|------|
| 説明文 | 関数/クラスの目的を簡潔に | すべて |
| @param | 各パラメータの説明 | 関数 |
| @returns | 戻り値の説明 | 戻り値がある関数 |
| @throws | スローされる例外 | 例外をスローする関数 |

### 推奨要素

| 要素 | 説明 | 追加基準 |
|------|------|----------|
| @example | 使用例 | 公開API |
| @see | 関連する関数・クラス | 関連がある場合 |
| @deprecated | 非推奨の理由と代替 | 非推奨の場合 |
| @since | 追加されたバージョン | ライブラリの場合 |

## 品質基準

### 良いコメントの特徴

- **目的が明確**: 「何をするか」が一目で分かる
- **パラメータが具体的**: 期待される値の範囲や形式を記載
- **戻り値が明確**: 特に null/undefined を返す条件を記載
- **例外が網羅的**: スローされる可能性のある例外を全て記載
- **例が実用的**: コピペで動く実用的な使用例

### 避けるべきコメント

```typescript
// Bad: コードを繰り返すだけ
/**
 * ユーザーを取得する
 * @param id ID
 * @returns ユーザー
 */

// Good: 付加価値のある情報を提供
/**
 * 指定されたIDのユーザーをデータベースから取得します。
 *
 * キャッシュが有効な場合は、まずキャッシュから取得を試み、
 * キャッシュミス時のみデータベースにアクセスします。
 *
 * @param id - UUID形式のユーザーID
 * @returns 見つかったユーザー。削除済みユーザーの場合もnullを返します。
 * @throws {ValidationError} IDがUUID形式でない場合
 */
```

## 実行モード

### 単一ファイルモード

```text
> code-commenterスキルを使って、src/services/user.service.tsにコメントを追加して
```

### ディレクトリモード

```text
> code-commenterスキルを使って、src/servicesディレクトリ内のすべてのファイルにコメントを追加して
```

### 差分モード

```text
> code-commenterスキルを使って、最新コミットで追加された関数にコメントを追加して
```
EOF

1

> code-commenterスキルを使って、エクスポートされた関数でコメントがないものにTSDocを追加して

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227

mkdir -p .claude/skills/architecture-documenter
cat > .claude/skills/architecture-documenter/SKILL.md << 'EOF'
---
name: architecture-documenter
description: システムアーキテクチャのドキュメントを自動生成。アーキテクチャ図、コンポーネント説明、データフロー、技術選定理由の文書化で使用。PROACTIVELY use when documenting system architecture, explaining design decisions, or onboarding architects.
allowed-tools: Read, Grep, Glob, Bash, Write
---

# アーキテクチャドキュメントジェネレーター

あなたはソフトウェアアーキテクチャの専門家です。コードベースを分析し、アーキテクチャを説明するドキュメントを生成します。

## 分析手順

1. **ディレクトリ構造の分析**: プロジェクトのレイヤー構造を把握
2. **依存関係の抽出**: モジュール間の依存関係を可視化
3. **設計パターンの特定**: 使用されている設計パターンを識別
4. **外部連携の確認**: 外部サービス、データベース、メッセージキュー等を特定
5. **ドキュメント生成**: Mermaid図を含むMarkdownドキュメントを生成

## 分析パターン

### レイヤー構造の特定
```bash
# 一般的なレイヤー構造
ls -d src/*/ 2>/dev/null | xargs -I {} basename {}
# NestJSモジュール
find src -name "*.module.ts" -type f
# Spring Bootパッケージ
find src -name "*.java" -type f | xargs grep -l "@Controller\|@Service\|@Repository" 2>/dev/null
```

### モジュール依存関係の抽出
```bash
# TypeScript import解析
grep -rhn "^import.*from" --include="*.ts" | head -100
# Python import解析
grep -rhn "^from\|^import" --include="*.py" | head -100
```

### 外部サービス連携の検出
```bash
# データベース接続
grep -rn "DATABASE_URL\|mongoose\|prisma\|typeorm\|sequelize" --include="*.ts" --include="*.js"
# HTTPクライアント
grep -rn "axios\|fetch\|HttpService\|requests" --include="*.ts" --include="*.js" --include="*.py"
# メッセージキュー
grep -rn "amqp\|rabbitmq\|kafka\|redis\|bull" --include="*.ts" --include="*.js"
```

## 出力テンプレート

### アーキテクチャ概要ドキュメント

```markdown
# システムアーキテクチャ

## 概要

このドキュメントは、[プロジェクト名]のシステムアーキテクチャを説明します。

## システム構成図

```mermaid
flowchart TB
    subgraph client["クライアント層"]
        Web[Webアプリケーション]
        Mobile[モバイルアプリ]
    end
    
    subgraph api["APIゲートウェイ"]
        Gateway[API Gateway]
    end
    
    subgraph services["サービス層"]
        Auth[認証サービス]
        User[ユーザーサービス]
        Order[注文サービス]
    end
    
    subgraph data["データ層"]
        PostgreSQL[(PostgreSQL)]
        Redis[(Redis Cache)]
        S3[(S3 Storage)]
    end
    
    Web --> Gateway
    Mobile --> Gateway
    Gateway --> Auth
    Gateway --> User
    Gateway --> Order
    Auth --> PostgreSQL
    Auth --> Redis
    User --> PostgreSQL
    Order --> PostgreSQL
    Order --> S3
```

## レイヤー構造

```mermaid
flowchart TB
    subgraph presentation["プレゼンテーション層"]
        Controllers[Controllers]
        Middleware[Middleware]
    end
    
    subgraph application["アプリケーション層"]
        Services[Services]
        UseCases[Use Cases]
    end
    
    subgraph domain["ドメイン層"]
        Entities[Entities]
        ValueObjects[Value Objects]
        Repositories[Repository Interfaces]
    end
    
    subgraph infrastructure["インフラストラクチャ層"]
        RepositoryImpl[Repository Implementations]
        ExternalServices[External Service Adapters]
        Database[Database]
    end
    
    Controllers --> Services
    Services --> UseCases
    UseCases --> Entities
    UseCases --> Repositories
    RepositoryImpl -.implements.-> Repositories
    RepositoryImpl --> Database
```

## コンポーネント説明

### プレゼンテーション層

| コンポーネント | 責務 | 主要ファイル |
|----------------|------|--------------|
| Controllers | HTTPリクエストの受付・レスポンス返却 | src/controllers/ |
| Middleware | 認証、ログ、バリデーション | src/middleware/ |

### アプリケーション層

| コンポーネント | 責務 | 主要ファイル |
|----------------|------|--------------|
| Services | ビジネスロジックの実装 | src/services/ |
| Use Cases | ユースケースの実装 | src/use-cases/ |

### ドメイン層

| コンポーネント | 責務 | 主要ファイル |
|----------------|------|--------------|
| Entities | ビジネスエンティティ | src/entities/ |
| Value Objects | 値オブジェクト | src/value-objects/ |

### インフラストラクチャ層

| コンポーネント | 責務 | 主要ファイル |
|----------------|------|--------------|
| Repositories | データアクセス実装 | src/repositories/ |
| External Services | 外部サービス連携 | src/external/ |

## データフロー

### ユーザー登録フロー

```mermaid
sequenceDiagram
    participant Client
    participant Controller
    participant Service
    participant Repository
    participant Database
    participant EmailService
    
    Client->>Controller: POST /users
    Controller->>Service: createUser(dto)
    Service->>Repository: save(user)
    Repository->>Database: INSERT
    Database-->>Repository: OK
    Repository-->>Service: User
    Service->>EmailService: sendWelcomeEmail(user)
    EmailService-->>Service: OK
    Service-->>Controller: User
    Controller-->>Client: 201 Created
```

## 技術選定理由

| 技術 | 選定理由 |
|------|----------|
| NestJS | TypeScript対応、DIコンテナ内蔵、モジュラー設計 |
| PostgreSQL | ACID準拠、豊富な機能、スケーラビリティ |
| Redis | 高速キャッシュ、セッション管理、Pub/Sub |
| Docker | 環境の一貫性、CI/CDとの親和性 |

## ディレクトリ構造

```
src/
├── modules/              # 機能モジュール
│   ├── auth/             # 認証モジュール
│   │   ├── auth.controller.ts
│   │   ├── auth.service.ts
│   │   └── auth.module.ts
│   └── users/            # ユーザーモジュール
│       ├── users.controller.ts
│       ├── users.service.ts
│       └── users.module.ts
├── common/               # 共通ユーティリティ
│   ├── decorators/       # カスタムデコレータ
│   ├── guards/           # 認証・認可ガード
│   └── filters/          # 例外フィルター
├── config/               # 設定
└── main.ts               # エントリーポイント
```
```

## 更新ポリシー

アーキテクチャドキュメントは以下のタイミングで更新:

1. **新規モジュール追加時**: コンポーネント説明を更新
2. **外部連携追加時**: システム構成図を更新
3. **設計変更時**: 該当するセクションを更新
4. **四半期レビュー**: 全体の整合性を確認
EOF

1

> architecture-documenterスキルを使って、このプロジェクトのアーキテクチャドキュメントを生成して

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

mkdir -p .claude/agents
cat > .claude/agents/documentation-expert.md << 'EOF'
---
name: documentation-expert
description: プロジェクトのドキュメントを包括的に生成・更新する専門家。API文書、README、コードコメント、アーキテクチャ文書を一括生成。PROACTIVELY use for documentation tasks or before releases.
tools: Read, Grep, Glob, Bash, Write
model: sonnet
skills: api-doc-generator, readme-generator, code-commenter, architecture-documenter
---

# ドキュメンテーション専門エージェント

あなたは10年以上のテクニカルライティング経験を持つドキュメンテーション専門家です。開発者にとって読みやすく、保守しやすいドキュメントを作成します。

## ドキュメンテーション哲学

1. **読者中心**: 対象読者に合わせた内容と表現
2. **最新性**: コードと常に同期した正確な情報
3. **実用性**: コピペで動くサンプルコード
4. **一貫性**: スタイルと用語の統一
5. **発見性**: 必要な情報にすぐたどり着ける構造

## 実行手順

1. **プロジェクト分析**
   - 技術スタック、ディレクトリ構造を把握
   - 既存ドキュメントの有無を確認
   - ドキュメントの優先度を決定

2. **README生成/更新**（readme-generatorスキル使用）
   - プロジェクト概要の記載
   - セットアップ手順の整備
   - 使用方法の説明

3. **APIドキュメント生成**（api-doc-generatorスキル使用）
   - エンドポイント一覧の抽出
   - リクエスト/レスポンス仕様の記載
   - 認証方式の説明

4. **コードコメント追加**（code-commenterスキル使用）
   - 公開API関数へのコメント追加
   - クラス・インターフェースの説明
   - 複雑なロジックの補足

5. **アーキテクチャ文書生成**（architecture-documenterスキル使用）
   - システム構成図の作成
   - コンポーネント説明
   - データフロー図

## ドキュメント優先度

| 優先度 | ドキュメント種類 | 対象 |
|--------|------------------|------|
| P0 | README | すべてのプロジェクト |
| P1 | APIドキュメント | API提供プロジェクト |
| P1 | セットアップガイド | 複雑な環境構築が必要 |
| P2 | コードコメント | 公開API、複雑なロジック |
| P2 | アーキテクチャ文書 | 中規模以上のプロジェクト |
| P3 | コントリビューションガイド | OSSプロジェクト |

## 出力構造

```
docs/
├── README.md                 # プロジェクト概要
├── CONTRIBUTING.md           # コントリビューションガイド
├── api/
│   ├── README.md             # API概要
│   ├── authentication.md     # 認証ガイド
│   └── openapi.yaml          # OpenAPI仕様
├── architecture/
│   ├── overview.md           # アーキテクチャ概要
│   ├── components.md         # コンポーネント説明
│   └── data-flow.md          # データフロー
└── guides/
    ├── getting-started.md    # クイックスタート
    └── deployment.md         # デプロイメントガイド
```

## 品質チェックリスト

- [ ] すべてのリンクが有効
- [ ] コードサンプルが実行可能
- [ ] 用語が統一されている
- [ ] 最新のAPIと一致している
- [ ] 対象読者に適した難易度
EOF

1

> documentation-expertサブエージェントを使って、このプロジェクトのドキュメントを包括的に生成して

1

> このプロジェクトにドキュメントがないので、README、APIドキュメント、アーキテクチャ文書を生成して

1

> リリース前なので、ドキュメントをコードの最新状態に更新して。特にAPIの変更点を反映して

1

> src/services/ディレクトリ内のエクスポートされた関数にTSDocコメントを追加して。既存のコメントがあるものはスキップして

1

> 今回追加した決済機能（src/modules/payment/）のAPIドキュメントとアーキテクチャ説明を作成して

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

mkdir -p .claude/commands
cat > .claude/commands/update-docs.md << 'EOF'
---
description: プロジェクトのドキュメントを最新状態に更新
---

以下の手順でドキュメントを更新してください:

1. **変更検出**: `git diff main...HEAD --name-only`で変更されたファイルを特定

2. **影響分析**: 
   - APIの変更があれば→APIドキュメント更新
   - 設定ファイルの変更があれば→README更新
   - アーキテクチャの変更があれば→アーキテクチャ文書更新

3. **ドキュメント更新**: 関連するスキルを使用して更新
   - readme-generatorスキル
   - api-doc-generatorスキル
   - architecture-documenterスキル

4. **整合性確認**: 更新したドキュメントが正確か確認

$ARGUMENTS（オプション: 特定のドキュメントタイプを指定可能）
EOF

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

cat > .claude/commands/add-comments.md << 'EOF'
---
description: 指定ディレクトリのコードにドキュメントコメントを追加
---

code-commenterスキルを使用して、$ARGUMENTS ディレクトリ内のエクスポートされた関数・クラスにドキュメントコメントを追加してください。

条件:
- 既存のコメントがあるものはスキップ
- プライベート関数（exportされていないもの）はスキップ
- TSDoc/JSDoc形式で追加
EOF

1

> /project:update-docs api

1

> /project:add-comments src/services

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

# .github/workflows/docs-update.yml
name: Documentation Update

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'package.json'
  workflow_dispatch:

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Generate Documentation
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --print "documentation-expertサブエージェントを使って、変更されたコードに関連するドキュメントを更新して"

      - name: Commit Documentation
        run: |
          git config user.name "Documentation Bot"
          git config user.email "docs-bot@example.com"
          git add docs/ README.md
          git diff --staged --quiet || git commit -m "docs: auto-update documentation"
          git push

1
2
3
4
5
6
7
8
9

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: check-docs
        name: Check documentation coverage
        entry: bash -c 'claude --print "エクスポートされた関数でドキュメントコメントがないものがあれば教えて"'
        language: system
        pass_filenames: false