| name | setup-doc-structure |
| description | プロジェクトのディレクトリをスキャン・分類し .doc_structure.yaml を対話的に生成する。
forge が文書を参照するための必須初期設定。
トリガー: "forge の初期設定", "doc structure を作成", "ドキュメント構成", "setup"
|
| user-invocable | true |
| argument-hint | |
/forge:setup-doc-structure
概要
対話的に .doc_structure.yaml をプロジェクトルートに作成・更新する。
このファイルはドキュメントの所在を宣言し、他のツール（Doc Advisor, forge 等）がドキュメントを参照できるようにする。
実行規則
- プランモードが有効な場合は解除すること。プランモードの解除についてユーザーへの確認は不要。
.doc_structure.yaml がすでに存在する場合はレビューモードに切り替えること（現在の内容を表示し、変更を提案する）。
Procedure
Step 1: 既存ファイルの確認
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/doc_structure/check_doc_structure.py
JSON 出力に応じて分岐する:
exists: false → Step 2 へ。error あり → エラー内容をユーザーに報告して終了。exists: true →
needs_migration: true の場合 → AskUserQuestion を使用して「.doc_structure.yaml を v{detected_version} → v{current_version} にマイグレーションしますか？」と確認
- Yes →
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/doc_structure/migrate_doc_structure.py <path> で変換結果を取得し、Write で書き出す
- No → 手順 2 へ
content を表示し、AskUserQuestion を使用して方針を確認する
- 更新する → Step 2 へ（既存の分類結果をベースにスキャン・再分類）
- 再生成する → 既存ファイルを削除し、Step 2 へ（ゼロから生成）
- このまま使う → 完了（変更なし）
Step 2: ディレクトリスキャン + 候補リスト作成
2-1: 自動スキャン
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/doc_structure/classify_dirs.py
スキャン結果（JSON）を取得する。readme_only: true のディレクトリは分類対象外としてスキップする。
注意: classify_dirs.py は浅いスキャン（親ディレクトリに .md ファイルがある場合、サブディレクトリは検出されない）のため、後続の「空ディレクトリの補完」Glob 探索は必須。
空ディレクトリの補完: ドキュメント系の親ディレクトリ（docs/, rules/, specs/ 等）配下のサブディレクトリを Glob で探索し、スキャン結果にないものも候補に追加する。
2-2: AI 分類判定 [MANDATORY]
同ディレクトリの classification_rules.md を Read し、そのルールに従ってスキャン結果の各ディレクトリに category と doc_type を割り当てる。
進捗表示 [MANDATORY]: 各ディレクトリの判定ごとに結果をユーザーに表示すること。
2-3: 推奨ディレクトリの補完
スキャン結果に含まれない推奨ディレクトリを「未検出（推奨）」として候補リストに追加する。
推奨ディレクトリ（スキャンで検出されなかった場合のみ追加）:
| パス | doc_type | 説明 |
|---|
docs/specs/ | — | 仕様書ベースディレクトリ（requirements/design/plan の親） |
docs/rules/ | rule | 開発ルール・規約 |
docs/reference/ | reference | 参考文献・技術調査メモ（今後利用予定） |
docs/adr/ | — | Architecture Decision Record（今後利用予定） |
スキャンで類似ディレクトリが検出済みの場合（例: rules/ が既にある場合に docs/rules/ は推奨しない）、重複する推奨は追加しない。
Feature ディレクトリについて: 既存の Feature ディレクトリ（docs/specs/{feature}/requirements/ 等）は Step 2 のスキャンで自動検出し、glob パターン（例: docs/specs/*/requirements/）として .doc_structure.yaml に設定する。ただし、まだ存在しない Feature の空ディレクトリをここで作成はしない。新規 Feature のディレクトリは start-requirements / start-design / start-plan が作業開始時に作成する。
Step 3: 候補の対話的確認 [MANDATORY]
スキャン結果と推奨ディレクトリを統合した候補リストをユーザーに提示する。
重要: スキャン結果はあくまで候補である。ユーザーが見ていない場所にディレクトリがある可能性もある。全ての候補について確認を取り、ユーザーの指示に従う。
3-1: パターン A — ディレクトリが検出された場合
テキスト出力:
## ドキュメントディレクトリ候補
検出済み:
1. ✅ docs/rules/ — rule
2. ✅ docs/specs/login/design/ — design
3. ✅ docs/specs/login/requirements/ — requirement
→ glob パターン: docs/specs/**/design/, docs/specs/**/requirements/
未検出（推奨）:
4. ☐ docs/specs/**/plan/ — 計画書
5. ☐ docs/reference/ — 参考文献（今後利用予定）
6. ☐ docs/adr/ — Architecture Decision Record（今後利用予定）
AskUserQuestion を使用して方針を確認する:
| 選択肢 | 説明 |
|---|
| この候補で確定 | 検出済みディレクトリのみで .doc_structure.yaml を生成 |
| 不足ディレクトリを作成して追加 | 未検出（推奨）から選択し、.gitkeep 付きで作成 |
| 候補を修正 | 分類の変更、パスの追加・除外など |
| （Other） | 別のパスを指定したい等 — 自動提供 |
3-2: パターン B — ディレクトリが検出されなかった場合
テキスト出力:
## ドキュメントディレクトリ候補
ドキュメントディレクトリが検出されませんでした。
推奨構成を提案します:
☐ docs/specs/ — 仕様書ベースディレクトリ（requirements/design/plan の親）
☐ docs/rules/ — 開発ルール・規約
☐ docs/reference/ — 参考文献（今後利用予定）
☐ docs/adr/ — Architecture Decision Record（今後利用予定）
AskUserQuestion を使用して方針を確認する:
| 選択肢 | 説明 |
|---|
| 推奨構成を全て作成 | specs/ + rules/ + reference/ + adr/ を .gitkeep 付きで作成 |
| 選択して作成 | 作成するディレクトリを個別に選択 |
| 作成しない | ディレクトリ作成をスキップ（.doc_structure.yaml も生成しない） |
| （Other） | 自分でパスを指定したい等 — 自動提供 |
3-3: 詳細選択（条件分岐）
「不足ディレクトリを作成して追加」または「選択して作成」の場合:
AskUserQuestion（multiSelect）で作成するディレクトリを選択させる。
選択肢は未検出項目または推奨項目から動的に生成する（最大4件。超過時は複数回に分割）。
選択されたディレクトリを Step 4 で作成する。
「候補を修正」の場合:
AskUserQuestion を使用して修正内容を確認する:
| 選択肢 | 説明 |
|---|
| 分類を変更 | 既存ディレクトリの category/doc_type を修正（例: 2番を plan に変更） |
| ディレクトリを除外 | 候補から除外するディレクトリを指定 |
| ディレクトリを追加 | 候補にないパスを追加 |
修正を適用後、再度候補リストを表示して方針選択に戻る（確認ループ）。
ユーザーが追加したパスが存在しない場合 → 作成するか AskUserQuestion を使用して確認する。
Feature の扱い
- 既存 Feature（
docs/specs/login/, docs/specs/auth/ 等）はスキャンで自動検出する
- AI が glob パターン（
docs/specs/**/design/ 等）を推定し、.doc_structure.yaml に設定する
- ユーザーが「Other」で新しい Feature パスを指定した場合 → 存在しなければ作成を提案
- Feature 名を引数として受け取らない（Feature はテンポラリーであり、スキャンで検出するもの）
Step 4: ディレクトリ作成
Step 3 で作成を選択されたディレクトリについて:
mkdir -p でディレクトリを作成- 空ディレクトリに
.gitkeep を配置
- 作成結果を一覧表示
ディレクトリを作成しました:
✅ docs/specs/.gitkeep
✅ docs/rules/.gitkeep
✅ docs/reference/.gitkeep
作成したディレクトリを候補リストの「検出済み」に追加し、Step 5 へ進む。
Step 3 でディレクトリ作成が不要だった場合（「この候補で確定」「作成しない」選択時）、この Step はスキップする。
Step 5: .doc_structure.yaml の生成
確定した分類結果から .doc_structure.yaml を生成し、プロジェクトルートに書き出す。
forge が使用するフィールド（root_dirs / doc_types_map / patterns）のみを生成する（Quick reference のテンプレートを参照）。
Step 6: 結果表示
生成したファイルの内容を表示し、次のステップを案内する:
.doc_structure.yaml を作成しました。
作成したディレクトリ:（Step 4 で作成した場合のみ表示）
- docs/specs/requirements/
- docs/specs/plan/
次のステップ:
- forge が .doc_structure.yaml を直接参照してレビュー・修正時の参考文書を収集します
- .doc_structure.yaml をバージョン管理にコミットしてください
Schema Reference
See: ${CLAUDE_PLUGIN_ROOT}/docs/doc_structure_format.md
Quick reference
rules:
root_dirs:
- <dir_path>
doc_types_map:
<dir_path>: <doc_type>
patterns:
target_glob: "**/*.md"
exclude: []
specs:
root_dirs:
- <dir_path>
doc_types_map:
<dir_path>: <doc_type>
patterns:
target_glob: "**/*.md"
exclude: []
生成例（Feature-Based）
rules:
root_dirs:
- docs/rules/
doc_types_map:
docs/rules/: rule
patterns:
target_glob: "**/*.md"
exclude: []
specs:
root_dirs:
- "docs/specs/**/design/"
- "docs/specs/**/plan/"
- "docs/specs/**/requirement/"
doc_types_map:
"docs/specs/**/design/": design
"docs/specs/**/plan/": plan
"docs/specs/**/requirement/": requirement
patterns:
target_glob: "**/*.md"
exclude: []
glob パターン（* または **）を使う場合、root_dirs と doc_types_map の両方に同じパターンを記述する。* は1階層のみ、** は任意の深さにマッチする。サブ Feature がある場合は ** を推奨。
doc_type 定義（固定。全プロジェクト・全プラグインで共通）
| category | doc_type | 意味 | 含まれる文書の例 |
|---|
| rules | rule | 開発プロセスのルール・規約・手順 | コーディング規約、命名規則、Git ワークフロー、レビュー手順、CI/CD ルール |
| specs | requirement | 「何を実現するか」のゴール定義 | ユーザーストーリー、機能要件、非機能要件、ビジネスルール、受入条件 |
| specs | design | 「どう構成するか」の技術的構造 | アーキテクチャ設計、DB スキーマ設計、画面設計、シーケンス図、状態遷移図 |
| specs | plan | 「どの順で作るか」の作業計画 | タスク分割、実装順序、マイルストーン、スプリント計画、移行計画 |
| specs | api | 外部インターフェースの契約 | REST エンドポイント定義、リクエスト/レスポンス仕様、OpenAPI/Swagger、GraphQL スキーマ |
| specs | reference | 判断の根拠となる補助文書 | 技術調査メモ、比較検討資料、外部仕様の要約、議事録、用語集 |
| specs | spec | 上記に該当しない仕様文書（デフォルト） | 分類不明な仕様文書の一時的な受け皿 |
