Claude Code ドキュメント自動生成完全ガイド｜JSDoc・README・OpenAPI・Mermaid図・CHANGELOGの生成と保守戦略

# 1ファイルにJSDocを追加
claude "Add JSDoc comments to all functions and classes in src/auth/token.ts.
For each function:
- Describe what it does in one sentence
- Document all parameters with @param and their types/descriptions
- Document return value with @returns
- Document thrown errors with @throws
- Add @example with a realistic usage example
Do not change any logic, only add comments."

# ディレクトリ全体に追加（サブエージェントで並列処理）
claude "Use subagents to add JSDoc comments to all TypeScript files in src/utils/.
Process files in parallel. For each file, follow the same JSDoc standards
as the existing comments in src/auth/token.ts."

/**
 * JWTアクセストークンを検証して、デコードされたペイロードを返す。
 *
 * @param token - 検証するJWT文字列
 * @param options - 検証オプション
 * @param options.ignoreExpiration - 有効期限を無視する場合はtrue（デフォルト: false）
 * @returns デコードされたトークンペイロード
 * @throws {TokenExpiredError} トークンの有効期限が切れている場合
 * @throws {JsonWebTokenError} トークンの署名が不正な場合
 *
 * @example
 * const payload = verifyAccessToken(req.headers.authorization.split(' ')[1]);
 * console.log(payload.userId); // "usr_abc123"
 */
export function verifyAccessToken(
  token: string,
  options: { ignoreExpiration?: boolean } = {}
): TokenPayload {
  return jwt.verify(token, process.env.JWT_SECRET!, options) as TokenPayload;
}

claude "Look at the JSDoc comments in src/auth/user.ts as the style reference.
Then add JSDoc comments to src/payment/checkout.ts following the exact same style:
- Same level of detail in descriptions
- Same format for @param descriptions
- Include @example for public methods
- Add @deprecated tags for any methods that look outdated"

# 関数の実装が変わった際にコメントを更新
claude "The verifyAccessToken function in src/auth/token.ts was updated to support
refresh tokens. Review the current implementation and update the JSDoc comments
to accurately reflect the new behavior, parameters, and return type."

claude "Generate a comprehensive README.md for this project.
Read package.json, src/index.ts, and any existing docs/ folder.
Include these sections:
1. Project name and one-line description
2. Features list (bullet points, max 8 items)
3. Prerequisites (Node.js version, env vars required)
4. Installation steps (numbered, copy-paste ready commands)
5. Quick start example (working code snippet)
6. Configuration options (table: option name, type, default, description)
7. API reference (main exports with brief descriptions)
8. Contributing guidelines
9. License

Use GitHub Flavored Markdown. Add badges for npm version, license, and CI status."

# 新しいエンドポイントが追加された際にAPIリファレンスだけ更新
claude "The API has new endpoints added in src/routes/webhooks.ts.
Update only the 'API Reference' section of README.md to include these endpoints.
Keep all other sections unchanged.
Format: endpoint path, HTTP method, description, request body, response."

claude "Generate a README for this npm library (src/index.ts is the entry point).
Focus on usage examples — write 5 realistic code examples showing the most
common use cases. Each example should be self-contained and copy-paste ready.
Include TypeScript and JavaScript variants where the API differs."

claude "Read all route files in src/routes/ and generate an OpenAPI 3.0
specification in YAML format. Save it as docs/openapi.yaml.

For each endpoint, include:
- HTTP method and path
- Summary and description (infer from function names and logic)
- Request body schema (infer from validation middleware or Zod schemas)
- Response schemas for 200, 400, 401, 404, 500 status codes
- Authentication requirements (check for auth middleware)
- Examples for request and response bodies"

openapi: 3.0.3
info:
  title: User Authentication API
  version: 1.0.0
paths:
  /auth/login:
    post:
      summary: ユーザーログイン
      description: メールアドレスとパスワードで認証し、JWTトークンを返す
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                password:
                  type: string
                  minLength: 8
            example:
              email: user@example.com
              password: "secretpassword"
      responses:
        "200":
          description: 認証成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken:
                    type: string
                  refreshToken:
                    type: string
        "401":
          description: 認証失敗（メールアドレスまたはパスワードが不正）

claude "Our API uses Zod for validation (see src/schemas/).
Generate OpenAPI schemas for each Zod schema in that directory,
and update docs/openapi.yaml with the components/schemas section.
Map Zod types to OpenAPI types: z.string() -> string, z.number() -> number,
z.enum() -> enum, z.object() -> object with properties."

claude "Read src/auth/ and generate a Mermaid sequence diagram showing
the complete authentication flow: from user login to token refresh.
Include all actors (Client, API Server, Database, JWT Service)
and show both the happy path and the token-expired error path."

```mermaid
sequenceDiagram
    participant C as Client
    participant A as API Server
    participant D as Database
    participant J as JWT Service

    C->>A: POST /auth/login {email, password}
    A->>D: SELECT user WHERE email = ?
    D-->>A: User record
    A->>A: bcrypt.compare(password, hash)
    A->>J: sign({userId, role})
    J-->>A: accessToken, refreshToken
    A->>D: INSERT refresh_tokens
    A-->>C: 200 {accessToken, refreshToken}

    Note over C,A: After access token expires (15min)
    C->>A: POST /auth/refresh {refreshToken}
    A->>D: SELECT WHERE token = ? AND expires_at > NOW()
    D-->>A: Valid token record
    A->>J: sign({userId, role})
    J-->>A: newAccessToken
    A-->>C: 200 {accessToken}
```

claude "Read the Prisma schema in prisma/schema.prisma and generate
a Mermaid ER diagram showing all tables, their fields (with types),
and relationships (1:1, 1:N, N:M).
Focus on the core business entities, exclude audit/logging tables."

claude "Read docker-compose.yml and the README to understand the system architecture.
Generate a Mermaid C4 container diagram showing:
- All services and their responsibilities
- How they communicate (REST, gRPC, message queue)
- External dependencies (databases, caches, third-party APIs)
- Which ports are exposed"

# v2.0.0からv2.1.0の変更履歴を生成
claude "Run git log v2.0.0..v2.1.0 --oneline and generate a CHANGELOG.md entry
for version 2.1.0 following Keep a Changelog format (https://keepachangelog.com).
Categorize commits into:
- Added (feat commits)
- Fixed (fix commits)
- Changed (refactor/perf commits)
- Deprecated
- Removed
- Security (security-related fixes)

Write descriptions in Japanese, user-friendly language (not commit message verbatim).
Add today's date as the release date."

# Changelog

## [2.1.0] - 2026-03-25

### Added
- Google OAuthログインに対応
- パスワードリセットメール送信機能を追加
- APIレスポンスに `X-Request-ID` ヘッダーを追加

### Fixed
- セッションタイムアウト後のリダイレクトが正しく動作しない問題を修正
- 日本語ユーザー名でのログインが失敗する文字コード問題を修正

### Changed
- JWTアクセストークンの有効期限を30分から15分に短縮
- ログインAPIのレスポンス形式を変更（`token` -> `accessToken`）

### Security
- bcryptのソルトラウンドを10から12に引き上げ

## [2.0.0] - 2026-02-01
...

# リリース前にCHANGELOGドラフトを確認
claude "Generate a CHANGELOG draft for the upcoming v3.0.0 release.
Look at commits since v2.1.0 and identify:
1. Any breaking changes (API signature changes, config changes)
2. New major features
3. Bug fixes

For breaking changes, explain what the user needs to change in their code.
Save as CHANGELOG.draft.md for review before the official release."

## Documentation Rules

When modifying any file in src/:
1. If you change a public function's signature or behavior, update its JSDoc comment
2. If you add/remove/change an API endpoint, update docs/openapi.yaml
3. If you change a database schema (prisma/schema.prisma), regenerate the ER diagram
4. If the change warrants a CHANGELOG entry, add a note to CHANGELOG.draft.md

After completing code changes, run:
- `npm run type-check` to verify TypeScript types are consistent
- `npm run docs:check` to verify doc examples still compile

# PRマージ前にドキュメントの同期チェック
claude "Review the diff of this branch compared to main (run git diff main..HEAD).
For each changed TypeScript file:
1. Are the JSDoc comments still accurate?
2. Are there any new functions without documentation?
3. Do any examples in the documentation need updating?
List specific lines that need updating, then make the changes."

Update documentation for all recently changed files.

Steps:
1. Run `git diff --name-only HEAD~1 HEAD` to find changed files
2. For each changed .ts/.js file: check JSDoc comments are up-to-date
3. If src/routes/ changed: update docs/openapi.yaml
4. If prisma/schema.prisma changed: regenerate the ER diagram in docs/schema.md
5. Update CHANGELOG.draft.md with a summary of user-facing changes

Focus only on documentation changes, make no code modifications.