# バッチ設計書 23-code-to-docs.sh

## 概要

本ドキュメントは、libuvプロジェクトの `.claude/code-to-docs.sh` の バッチ設計書である。このスクリプトは、Claudeヘッドレスモードを活用してプロジェクトコードから包括的なドキュメント群を自動生成する大規模自動化バッチである。

### 本バッチの処理概要

`code-to-docs.sh` は、20ステップの順次・並列処理を組み合わせてプロジェクトのソースコードを解析し、README、データベース設計書、各種一覧（画面・機能・バッチ・通知・帳票）、設計書群（画面・機能・バッチ・通知・帳票・API・インフラ・セキュリティ・アーキテクチャ）、テストケース一覧、コードリーディングガイドライン等のドキュメントを自動生成するBashスクリプトである。Claudeエージェントのヘッドレスモード（`claude -p`）を使用し、複数のエージェントを並列実行することでドキュメント生成を高速化する。

**業務上の目的・背景**：大規模プロジェクトのドキュメント整備は膨大な工数を要する作業である。本バッチは、AIエージェント（Claude）を活用してソースコードから包括的なドキュメント群を自動生成することで、ドキュメント作成の工数を大幅に削減し、コードとドキュメントの同期を促進することを目的とする。リバースエンジニアリング的なアプローチで既存コードからドキュメントを生成するため、ドキュメントが存在しないプロジェクトの文書化にも適用可能である。

**バッチの実行タイミング**：手動実行。プロジェクトのドキュメント一括生成が必要なタイミングで開発者が実行する。

**主要な処理内容**：
1. ステップ1: README.md生成
2. ステップ2: データベース設計書生成
3. ステップ3: 各種一覧並列生成（画面・機能・バッチ・通知・帳票の5エージェント並列）
4. ステップ4: 画面機能マッピング生成
5. ステップ5: プログラム設計書（プランナー＋ワーカー、`--program-design` オプション時のみ）
6. ステップ6: 画面設計書（プランナー＋ワーカー＋レビュー＋リトライ）
7. ステップ7: 機能詳細設計書（プランナー＋ワーカー＋レビュー＋リトライ）
8. ステップ8: バッチ・通知・帳票・API設計書並列生成（4設計書を並列実行＋レビュー）
9. ステップ9: 業務要件一覧生成
10. ステップ10: 運用マニュアル・非機能要件定義書並列生成
11. ステップ11: インフラ設計書・セキュリティ設計書・アーキテクチャ設計書並列生成
12. ステップ12: テスト方針書生成
13. ステップ13: 単体テストケース一覧生成（プランナー＋ワーカー＋CSV統合）
14. ステップ14: 結合・受入・非機能テストケース一覧並列生成
15. ステップ15: セキュリティ診断レポート生成（`--skip-optional` でスキップ可能）
16. ステップ16: 改善提案書生成（`--skip-optional` でスキップ可能）
17. ステップ17: コードリーディングガイドライン生成
18. ステップ18: 設計意図書並列生成（10エージェント並列、`--skip-optional` でスキップ可能）
19. ステップ19: ドキュメント一覧生成
20. ステップ20: 後片付け（一時ファイル・レビューディレクトリ・plan.mdファイルの削除）

**前後の処理との関連**：本バッチは他のバッチへの依存はなく、独立して実行される。ただし、バッチ設計書（No.21以前のバッチ群）のドキュメントを生成する処理を含んでおり、メタ的な関係がある。

**影響範囲**：`docs/code-to-docs/` ディレクトリ配下に全てのドキュメントが出力される。既存ファイルは上書きされる。

## バッチ種別

ドキュメント生成 / 大規模自動化バッチ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動実行） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動（開発者がシェルから実行） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Claude CLIの利用可能性 | `claude` コマンドがPATH上で利用可能であること |
| プロジェクト構成 | `.claude/` ディレクトリ配下にスクリプトが配置され、その親ディレクトリがプロジェクトルートであること |
| macOS環境（推奨） | `caffeinate` コマンドによるスリープ防止機能を利用（macOS以外でも動作可能） |
| Python 3 | レビュー機能の失敗項目JSONパースに使用 |
| Bash 3.2以上 | macOS標準のBash 3.2を考慮した実装（連想配列不使用） |

### 実行可否判定

スクリプトは `set -e` で厳格なエラーハンドリングを行う。前提条件が満たされない場合（特に `claude` コマンドが利用不可の場合）、最初のエージェント実行時にエラーで停止する。`--from N` オプションで途中のステップから再開可能であり、`--only N` オプションで特定ステップのみを実行できる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --no-confirm / -y | フラグ | No | false（インタラクティブ） | 確認なしで全ステップを実行 |
| --from N | 整数 | No | 1 | ステップNから開始（1-20） |
| --only N | 整数 | No | 0（無効） | ステップNのみを実行（1-20） |
| --max-retries N | 整数 | No | 3 | エージェント失敗時の最大リトライ回数 |
| --retry-delay N | 整数 | No | 30 | リトライ間隔の初期値（秒、指数バックオフ） |
| --skip-review | フラグ | No | false | レビューをスキップ |
| --auto-retry | フラグ | No | false | 失敗時に自動リトライ（確認なし） |
| --max-retry-rounds N | 整数 | No | 2 | リトライラウンドの最大回数 |
| --parallel N | 整数 | No | 10 | ワーカーの同時実行数上限 |
| --review-fix TARGET | 文字列 | No | なし | レビュー＆欠落分再生成のみ実行（all/screen/function/batch/notification/report） |
| --skip-optional | フラグ | No | false | オプショナルドキュメントをスキップ（セキュリティ診断・改善提案書・設計意図書） |
| --program-design | フラグ | No | false | プログラム設計書を生成 |
| --help / -h | フラグ | No | - | ヘルプを表示して終了 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| プロジェクトソースコード | 各種 | Claudeエージェントが解析するプロジェクト全体のソースコード |
| `.claude/` 配下のスキル定義 | Markdown | 各エージェントのSKILL.md（テンプレート・指示） |
| 各種plan.md | Markdown | プランナーエージェントが生成するワーカー分割計画 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| `docs/code-to-docs/README.md` | Markdown | プロジェクトREADME |
| `docs/code-to-docs/データベース設計書/` | Markdown | データベース設計書 |
| `docs/code-to-docs/画面一覧/` | CSV/Markdown | 画面一覧 |
| `docs/code-to-docs/機能一覧/` | CSV/Markdown | 機能一覧 |
| `docs/code-to-docs/バッチ一覧/` | CSV/Markdown | バッチ一覧 |
| `docs/code-to-docs/通知一覧/` | CSV/Markdown | 通知一覧 |
| `docs/code-to-docs/帳票一覧/` | CSV/Markdown | 帳票一覧 |
| `docs/code-to-docs/画面機能マッピング/` | Markdown | 画面機能マッピング |
| `docs/code-to-docs/画面設計書/` | Markdown | 画面設計書群 |
| `docs/code-to-docs/機能設計書/` | Markdown | 機能設計書群 |
| `docs/code-to-docs/バッチ設計書/` | Markdown | バッチ設計書群 |
| `docs/code-to-docs/通知設計書/` | Markdown | 通知設計書群 |
| `docs/code-to-docs/帳票設計書/` | Markdown | 帳票設計書群 |
| `docs/code-to-docs/API設計書/` | Markdown | API設計書 |
| `docs/code-to-docs/業務要件一覧/` | Markdown | 業務要件一覧 |
| `docs/code-to-docs/運用マニュアル/` | Markdown | 運用マニュアル |
| `docs/code-to-docs/非機能要件定義書/` | Markdown | 非機能要件定義書 |
| `docs/code-to-docs/インフラ設計書/` | Markdown | インフラ設計書 |
| `docs/code-to-docs/セキュリティ設計書/` | Markdown | セキュリティ設計書 |
| `docs/code-to-docs/アーキテクチャ設計書/` | Markdown | アーキテクチャ設計書 |
| `docs/code-to-docs/テスト方針書/` | Markdown | テスト方針書 |
| `docs/code-to-docs/単体テストケース一覧/` | CSV/Markdown | 単体テストケース一覧 |
| `docs/code-to-docs/結合テストケース一覧/` | Markdown | 結合テストケース一覧 |
| `docs/code-to-docs/受入テストケース一覧/` | Markdown | 受入テストケース一覧 |
| `docs/code-to-docs/非機能要件テストケース一覧/` | Markdown | 非機能要件テストケース一覧 |
| `docs/code-to-docs/セキュリティ診断レポート/` | Markdown | セキュリティ診断レポート（オプション） |
| `docs/code-to-docs/改善提案書/` | Markdown | 改善提案書（オプション） |
| `docs/code-to-docs/コードリーディングガイドライン.md` | Markdown | コードリーディングガイドライン |
| `docs/code-to-docs/設計意図書/` | Markdown | 設計意図書群（10ファイル、オプション） |
| `docs/code-to-docs/ドキュメント一覧.csv` | CSV | 全ドキュメントの一覧 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 各ドキュメントの命名規則に従う |
| 出力先 | `docs/code-to-docs/` 配下のサブディレクトリ |
| 文字コード | UTF-8 |
| 区切り文字 | Markdown形式またはCSV形式 |

## 処理フロー

### 処理シーケンス

```
1. 初期化処理
   ├─ stdoutパイプのブロッキングモード設定（Node.js/Electron対策）
   ├─ macOSスリープ防止（caffeinate経由で再実行）
   ├─ コマンドライン引数の解析
   ├─ プロジェクトルートの特定（スクリプト位置の親ディレクトリ）
   └─ 一時ディレクトリ（.claude/tmp）の作成

2. ステップ1-2: 単独エージェント実行
   ├─ README.md生成
   └─ データベース設計書生成

3. ステップ3: 並列エージェント実行（5エージェント）
   ├─ 画面一覧 / 機能一覧 / バッチ一覧 / 通知一覧 / 帳票一覧
   └─ 全エージェント完了待機

4. ステップ4: 単独エージェント実行
   └─ 画面機能マッピング生成

5. ステップ5: プランナー＋ワーカー（オプション）
   └─ プログラム設計書（--program-design指定時のみ）

6. ステップ6-7: プランナー＋ワーカー＋レビュー＋リトライ
   ├─ 画面設計書（run_design_with_review）
   └─ 機能詳細設計書（run_design_with_review）

7. ステップ8: 並列プランナー＋ワーカー＋レビュー
   ├─ API設計書（単独エージェント）
   ├─ バッチ設計書（プランナー＋ワーカー）
   ├─ 通知設計書（プランナー＋ワーカー）
   ├─ 帳票設計書（プランナー＋ワーカー）
   └─ 各設計書のレビュー＋リトライ

8. ステップ9-12: 単独/並列エージェント実行
   ├─ 業務要件一覧
   ├─ 運用マニュアル＋非機能要件定義書（2並列）
   ├─ インフラ＋セキュリティ＋アーキテクチャ設計書（3並列）
   └─ テスト方針書

9. ステップ13-14: テストケース一覧
   ├─ 単体テストケース（プランナー＋ワーカー＋CSV統合）
   └─ 結合・受入・非機能テストケース（3並列）

10. ステップ15-18: オプショナルドキュメント
    ├─ セキュリティ診断レポート（--skip-optionalでスキップ可）
    ├─ 改善提案書（--skip-optionalでスキップ可）
    ├─ コードリーディングガイドライン
    └─ 設計意図書（10並列、--skip-optionalでスキップ可）

11. ステップ19: ドキュメント一覧生成
    └─ 全ドキュメントのCSV一覧

12. ステップ20: 後片付け
    ├─ .claude/tmp/ の一時ファイル削除
    ├─ .review/ ディレクトリ削除
    └─ plan.md ファイル削除
```

### フローチャート

```mermaid
flowchart TD
    A[スクリプト開始] --> B[初期化・引数解析]
    B --> C{--review-fix?}
    C -->|Yes| D[レビュー＆修正モード]
    C -->|No| E[ステップ1: README]
    E --> F[ステップ2: DB設計書]
    F --> G[ステップ3: 5一覧並列生成]
    G --> H[ステップ4: 画面機能マッピング]
    H --> I{--program-design?}
    I -->|Yes| J[ステップ5: プログラム設計書]
    I -->|No| K[ステップ6: 画面設計書]
    J --> K
    K --> L[ステップ7: 機能設計書]
    L --> M[ステップ8: バッチ等4設計書並列]
    M --> N[ステップ9-12: 要件・運用・テスト方針]
    N --> O[ステップ13-14: テストケース]
    O --> P{--skip-optional?}
    P -->|No| Q[ステップ15-18: オプショナル文書]
    P -->|Yes| R[ステップ17: コードリーディング]
    Q --> S[ステップ19: ドキュメント一覧]
    R --> S
    S --> T[ステップ20: 後片付け]
    T --> U[完了・経過時間表示]
    D --> U
```

## データベース操作仕様

### 操作別データベース影響一覧

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | 本バッチはドキュメント生成処理であり、データベース操作は行わない |

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| EXIT 1 | Claudeエージェント実行失敗 | `claude -p` コマンドがMAX_RETRIES回連続で失敗した場合 | エラーログを確認し、Claude CLIの状態・認証情報・ネットワーク接続を確認する |
| EXIT 1 | 不明なオプション | コマンドライン引数に不明なオプションが指定された場合 | `--help` で有効なオプションを確認する |
| EXIT 1 | 前提ファイル不存在 | ステップ1-2で必須ファイルが生成されなかった場合 | 前段ステップのエラーログを確認し再実行する |
| WARNING | 並列エージェント失敗 | 並列実行中の一部エージェントが失敗した場合 | 警告を出力し残りのステップを続行する |
| WARNING | レビュー失敗項目 | レビューで品質基準を満たさない項目が検出された場合 | `--auto-retry` で自動リトライ、または手動で対象項目を修正する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | MAX_RETRIES（デフォルト: 3回） |
| リトライ間隔 | RETRY_DELAY（デフォルト: 30秒）から指数バックオフ（30s→60s→120s） |
| リトライ対象エラー | Claudeエージェントの実行失敗（`claude -p` の非ゼロ終了コード） |

### 障害時対応

1. エラーログ（`.claude/tmp/` 配下の各ワーカーログファイル）を確認し、失敗原因を特定する
2. `--from N` オプションで失敗したステップから再実行する
3. 特定のステップのみ再実行する場合は `--only N` オプションを使用する
4. レビュー失敗項目のみ再生成する場合は `--review-fix TARGET` オプションを使用する

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | ステップ単位（各ステップは独立して実行される） |
| コミットタイミング | 各エージェントの完了時にファイルが書き出される |
| ロールバック条件 | エージェント失敗時は出力ファイルが不完全な状態となる場合がある。`--from N` で再実行により上書き修正可能 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 20ステップ、数十～数百のドキュメントファイル |
| 目標処理時間 | プロジェクト規模に依存（大規模プロジェクトでは数時間） |
| メモリ使用量上限 | Claudeエージェントのプロセス数 x プロセスあたりメモリ使用量に依存 |

## 排他制御

同一プロジェクトディレクトリでの同時実行は禁止。複数のインスタンスが同時に実行された場合、`docs/code-to-docs/` ディレクトリ内のファイルが競合して不整合な状態になる。ステップ20の後片付け処理が並行実行中のワーカーの一時ファイルを削除する可能性もあるため、単一インスタンスでの実行を前提とする。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | プロジェクトルート、並列実行数、実行オプション情報 |
| 経過時間ログ | 各ステップ開始/完了時 | `[経過 HH:MM:SS]` 形式のタイムスタンプ付きメッセージ |
| 成功ログ | エージェント/ステップ完了時 | `[成功]` プレフィックス付きの完了メッセージ（緑色） |
| 警告ログ | 一部エージェント失敗時 | `[警告]` プレフィックス付きの警告メッセージ（黄色） |
| エラーログ | エージェント失敗時 | `[エラー]` プレフィックス付きのエラーメッセージ（赤色） |
| ワーカーログ | 各ワーカー実行時 | `.claude/tmp/` 配下に個別ログファイルとして出力 |
| 総実行時間 | バッチ終了時 | `[総実行時間] HH:MM:SS` 形式 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| スクリプト終了コード | != 0 | 標準エラー出力（手動実行のため直接確認） |
| 失敗エージェント数 | > 0 | 標準出力（`[エラー]` メッセージ） |
| レビュー失敗項目数 | > 0 | 標準出力（`[警告]` メッセージ） |

## 備考

- macOS環境では `caffeinate -dims` を使用して長時間実行中のスリープを防止する。`CAFFEINATED` 環境変数で二重実行を防ぐ
- Node.js/Electron経由で実行された場合のstdoutパイプ非ブロッキングモード対策として、Python3で `fcntl` を使用してブロッキングモードに戻す処理が冒頭に含まれる
- インタラクティブモード（デフォルト）では各ステップ完了後に次のステップへの確認プロンプトが表示される。`--no-confirm` / `-y` で非インタラクティブモードに切り替え可能
- プランナー＋ワーカーパターンでは、プランナーがplan.mdを生成し、そこに記載されたグループ範囲に基づいてワーカーが並列実行される。plan.mdのグループテーブルは `<!-- GROUPS_START -->` / `<!-- GROUPS_END -->` マーカーで囲まれた形式
- 単体テストケース一覧はモジュール単位でワーカーが生成し、最終的にCSVファイルを統合（merge_unit_test_csvs関数）する
- レビュー機能は `code-to-docs-reviewer` エージェントを使用し、失敗項目は `.review/failed-items.json` に記録される
- 許可されたツール: `Read`, `Write`, `Edit`, `Grep`, `Glob`, `Bash`, `Task`（`--allowedTools` で制限）
- Bash 3.2互換性を確保するため、連想配列の代わりにcase文（`get_design_info` 関数）を使用している
