yodogawa 2.0.0 → 2.1.1

package/skills/a-001-setup-doc-structure/SKILL.md

@@ -1,100 +1,67 @@
----
-name: a-001-setup-doc-structure
-description: プロジェクトのドキュメントディレクトリ構造を作成し、README で構成を説明する軽量セットアップワークフロー
-auto_execution_mode: 1
----
-
-# SetupDocStructure (a-001)
-
-## 目的
-
-- プロジェクトルートに標準化されたドキュメントディレクトリ構造を作成する。
-- `docs/README.md` を作成し、ドキュメント構成と更新方針を明文化する。
-
-## 前提
-
-- プロジェクトのルートディレクトリへの書き込み権限があること。
-- `docs/` ディレクトリが存在しない、または既存の構造を拡張したいこと。
-
-## 手順
-
-### 1. スクリプトの実行
-
-- ドキュメント構造セットアップのために、環境に応じたスクリプトを実行してください。
-
-  ```bash
-  # 環境を自動検出してスクリプトを実行
-  if [ -d ".agent" ]; then
-    SCRIPT_DIR=".agent"
-  elif [ -d ".cursor" ]; then
-    SCRIPT_DIR=".cursor"
-  elif [ -d ".claude" ]; then
-    SCRIPT_DIR=".claude"
-  elif [ -d ".codex" ]; then
-    SCRIPT_DIR=".codex"
-  else
-    echo "エラー: AI coding assistant ディレクトリが見つかりません"
-    exit 1
-  fi
-
-  bash "$SCRIPT_DIR/scripts/setup-docs.sh"
-  ```
-
-### 2. 結果の確認
-
-- スクリプトの実行結果を確認し、エラーがないことを確認してください。
-- 生成された構造：
-
-  ```
-  docs/
-  ├── README.md
-  ├── project/
-  │   ├── 01-requirements/
-  │   ├── 02-behavior/
-  │   ├── 03-domain/
-  │   └── 04-design/
-  └── tasks/
-  ```
-
-### 3. Git への追加（オプション）
-
-- ユーザーに確認：「作成したディレクトリ構造を Git に追加しますか？」
-- 「はい」の場合、以下を実行：
-
-  ```bash
-  git add docs/
-  git status
-  ```
-
-- Git status の結果を表示し、コミットメッセージの提案をする：
-
-  ```
-  推奨コミットメッセージ:
-  ドキュメント構造の初期化
-
-  - 標準的な構造を持つ docs/ ディレクトリを追加
-  - ドキュメント構成を説明する docs/README.md を追加
-  ```
-
-### 4. 完了条件の確認
-
-- 以下の完了条件を満たしているか、チェックリストで確認してください：
-  - [ ] スクリプトが正常に終了した
-  - [ ] `docs/` ディレクトリ構造が正しく作成されている
-
-## 完了条件
-
-- プロジェクトルートに `docs/` ディレクトリが作成されている。
-- `docs/project/` 配下に `01-requirements/`, `02-behavior/`, `03-domain/`, `04-design/` ディレクトリが存在する。
-- `docs/tasks/` ディレクトリが存在する。
-- `docs/README.md` が作成されている。
-- ユーザーに作成結果が報告されている。
-
-## エスカレーション
-
-- 既存の `docs/` ディレクトリが存在し、重要なファイルが含まれている場合：
-  - 「既存のドキュメント構造が検出されました。上書きや削除のリスクがあるため、手動で確認してください。」と警告し、処理を中断する。
-- ファイルシステムの権限エラーが発生した場合：
-  - 「ディレクトリの作成に失敗しました。書き込み権限を確認してください。」とユーザーに通知する。
-- Git リポジトリでない場合に Git 追加を試みた場合：
-  - 「このディレクトリは Git リポジトリではありません。Git の初期化が必要な場合は `git init` を実行してください。」と案内する。
+---
+name: a-001-setup-doc-structure
+description: docs/ 配下にプロジェクト/タスク用のディレクトリ構造と README を作成する。新規リポジトリでドキュメント基盤を初期化する際に使用。
+disable-model-invocation: true
+allowed-tools: Read, Write, Bash, Glob
+---
+
+# SetupDocStructure (a-001)
+
+## 目的
+
+- プロジェクトルートに標準化されたドキュメントディレクトリ構造を作成する。
+- `docs/README.md` を作成し、ドキュメント構成と更新方針を明文化する。
+
+## 前提
+
+- プロジェクトのルートディレクトリへの書き込み権限があること
+- `docs/` ディレクトリが存在しない、または既存の構造を拡張したいこと
+
+## 手順
+
+### 1. スクリプトの実行
+
+環境に応じたスクリプトを実行。スクリプト本体とフォールバック実装は [reference/directory-structure.md](reference/directory-structure.md#スクリプト実行コマンド) を参照。
+
+```bash
+SCRIPT_DIR=$(for d in .claude .agents; do [ -d "$d" ] && echo "$d" && break; done)
+bash "$SCRIPT_DIR/scripts/setup-docs.sh"
+```
+
+### 2. 結果の確認
+
+スクリプト実行結果にエラーがないこと、および期待した構造が生成されていることを確認。生成構造と各ディレクトリの用途は [reference/directory-structure.md](reference/directory-structure.md#生成されるディレクトリ構造) を参照。
+
+### 3. Git への追加（オプション）
+
+ユーザーに確認し、「はい」なら:
+
+```bash
+git add docs/
+git status
+```
+
+推奨コミットメッセージは [reference/directory-structure.md](reference/directory-structure.md#git-追加時の推奨コミットメッセージ) を参照。
+
+### 4. 完了条件の確認
+
+- [ ] スクリプトが正常に終了した
+- [ ] `docs/` ディレクトリ構造が正しく作成されている
+
+## 完了条件
+
+- プロジェクトルートに `docs/` ディレクトリが作成されている
+- `docs/project/` 配下に `01-requirements/`, `02-behavior/`, `03-domain/`, `04-design/` が存在する
+- `docs/tasks/` ディレクトリが存在する
+- `docs/README.md` が作成されている
+- ユーザーに作成結果が報告されている
+
+## エスカレーション
+
+- **既存の `docs/` が存在し重要ファイルを含む**: 「既存のドキュメント構造が検出されました。上書きや削除のリスクがあるため、手動で確認してください。」と警告し処理を中断
+- **権限エラー**: 「ディレクトリの作成に失敗しました。書き込み権限を確認してください。」
+- **Git リポジトリでない**: 「このディレクトリは Git リポジトリではありません。必要なら `git init` を実行してください。」
+
+## 参考
+
+- [reference/directory-structure.md](reference/directory-structure.md) — 生成構造、各ディレクトリの用途、スクリプト詳細、推奨コミットメッセージ

package/skills/a-001-setup-doc-structure/reference/directory-structure.md

@@ -0,0 +1,48 @@
+# docs ディレクトリ構造とコミットメッセージ
+
+SKILL.md 手順2〜3で参照する生成構造とコミットメッセージテンプレート。
+
+## 生成されるディレクトリ構造
+
+```
+docs/
+├── README.md
+├── project/
+│   ├── 01-requirements/
+│   ├── 02-behavior/
+│   ├── 03-domain/
+│   └── 04-design/
+└── tasks/
+```
+
+### 各ディレクトリの用途
+
+- `project/01-requirements/` — 要件定義（システム概要、機能要件、非機能要件、ユーザーストーリー）
+- `project/02-behavior/` — 振る舞い定義（Gherkin シナリオ）
+- `project/03-domain/` — ドメインモデル、ユビキタス言語
+- `project/04-design/` — 画面設計、データモデル、API 仕様、アーキテクチャ等
+- `tasks/` — 個別タスク（`task{ID}-{SLUG}/` 形式）
+
+## Git 追加時の推奨コミットメッセージ
+
+```
+ドキュメント構造の初期化
+
+- 標準的な構造を持つ docs/ ディレクトリを追加
+- ドキュメント構成を説明する docs/README.md を追加
+```
+
+## スクリプト実行コマンド
+
+```bash
+if [ -d ".claude" ]; then
+  SCRIPT_DIR=".claude"
+elif [ -d ".agents" ]; then
+  SCRIPT_DIR=".agents"
+else
+  echo "エラー: .claude または .agents ディレクトリが見つかりません"
+  exit 1
+fi
+
+bash "$SCRIPT_DIR/scripts/setup-docs.sh"
+```

package/skills/a-002-initialize-project/SKILL.md

@@ -1,289 +1,125 @@
----
-name: a-002-initialize-project
-description: プロジェクトのシステム概要・機能要件・非機能要件・ユーザーストーリーを体系的にヒアリングし、詳細なドキュメントを作成するワークフロー
-auto_execution_mode: 1
----
-
-# InitializeProject (a-002)
-
-## 目的
-
-- プロジェクトの目的・背景・機能要件を詳細にヒアリングし、具体的で実装可能なドキュメントを作成する。
-- システム概要・実装済み機能・予定機能・非機能要件・ユーザーストーリーを網羅する。
-- 抽象的・曖昧な表現を避け、ユーザーとの対話を通じて具体的な数値・期限・制約・優先度を明確化する。
-- 後続の設計・実装フェーズで参照できる、チーム全体が理解できる要件定義書を整備する。
-
-## 前提
-
-- `docs/project/requirements/` ディレクトリが存在すること（存在しない場合は先に `SetupDocStructure` (a-001) ワークフローを実行）。
-- プロジェクトリポジトリの `docs/` ディレクトリに書き込み権限があること。
-- ユーザーがプロジェクトの概要と主要な機能について基本的な情報を提供できること。
-
-## 手順
-
-### 1. ドキュメントディレクトリの確認
-
-- `docs/project/requirements/` ディレクトリの存在を確認：
-
-  ```bash
-  ls -la docs/project/requirements/ 2>/dev/null || echo "ディレクトリが存在しません"
-  ```
-
-- ディレクトリが存在しない場合：
-  - ユーザーに通知：「`docs/project/requirements/` ディレクトリが見つかりません。先に `SetupDocStructure` (a-001) を実行してディレクトリ構造を作成してください。」
-
-### 2. コードベースの自動分析と提案
-
-1. **コードベースの規模確認**:
-
-   - プロジェクトのルートにあるファイルやディレクトリを確認する。
-
-     ```bash
-     ls -F
-     ```
-
-   - **スキップ判断**:
-     - ファイルがほとんど存在しない（例: `.git` ディレクトリのみ、あるいは `README.md` だけなど）、または有意なソースコードが見当たらない場合は、このステップをスキップする。
-     - スキップする場合、ユーザーに「コードベースが空、または十分な情報がないため、自動分析をスキップします。」と通知し、次のステップへ進む。
-
-2. **詳細調査と分析（コードが存在する場合）**:
-   - `README.md`, `package.json`, および主要なソースコードを読み込む。
-
-     ```bash
-     cat package.json 2>/dev/null
-     cat README.md 2>/dev/null
-     find src app lib -maxdepth 2 2>/dev/null
-     ```
-
-   - 読み込んだ情報を基に、以下の内容を分析・推測し、ユーザーに提示する。
-     - **システム概要**: プロジェクトの目的、主要な技術スタック。
-     - **実装済み機能**: ファイル構造やコードから推測される機能。
-     - **ユーザーストーリー**: 想定されるユーザー像と利用シーン。
-   - この分析結果は、後続のステップ（システム概要の作成、機能一覧の作成など）の基礎情報として活用する。
-
-### 3. システム概要の作成
-
-1. **テンプレートの準備**:
-
-   ```bash
-   SCRIPT_DIR=$(for d in .agent .cursor .claude .codex; do [ -d "$d" ] && echo "$d" && break; done)
-   cp "$SCRIPT_DIR/templates/project/01-requirements/01-system-overview.md" "docs/project/requirements/01-system-overview.md"
-   ```
-
-2. **ヒアリングと記入**:
-   以下の質問を行い、その回答で `docs/project/requirements/01-system-overview.md` を更新する。
-
-   #### 背景
-
-   - 「このシステムで解決しようとしている**具体的な問題や課題**は何ですか？」
-   - 「その問題はなぜ重要ですか？放置した場合のリスクは？」
-   - 「問題の影響を受けるステークホルダー（ユーザー、組織、チームなど）は誰ですか？」
-   - 「具体的な数値やデータ（例：作業時間、コスト、離脱率など）があれば教えてください。」
-
-   #### 目的
-
-   - 「このシステムが提供する**具体的な価値や解決策**は何ですか？」
-   - 「期待される成果や変化を、測定可能な形で表現できますか？（例：作業時間 50%削減）」
-   - 「どのように問題を解決するか、具体的なメカニズムや仕組みを教えてください。」
-
-### 4. 実装済み機能一覧の作成
-
-1. **テンプレートの準備**:
-
-   ```bash
-   SCRIPT_DIR=$(for d in .agent .cursor .claude .codex; do [ -d "$d" ] && echo "$d" && break; done)
-   cp "$SCRIPT_DIR/templates/project/01-requirements/02-features-implemented.md" "docs/project/requirements/02-features-implemented.md"
-   ```
-
-2. **コードベースの調査と提案**:
-
-   - プロジェクト内のソースコードを簡易検索し、実装済みの兆候を探す。
-
-     ```bash
-     # 主要なソースディレクトリの構造を確認（例）
-     find src app lib -maxdepth 2 -type d 2>/dev/null
-     # 特徴的なファイル名を検索
-     find . -type f -name "*Controller*" -o -name "*Service*" -o -name "*Component*" | head -n 20
-     ```
-
-   - 検出されたディレクトリ名やファイル名から機能を推測し、ユーザーに提案する。
-     - 「`src/auth` ディレクトリが見つかりました。認証機能（ログイン、登録など）は実装済みですか？」
-     - 「`PaymentController` があります。決済機能は稼働していますか？」
-
-3. **ヒアリングと記入**:
-   提案内容へのフィードバックを含め、以下の質問を行う。回答をテーブル形式で `docs/project/requirements/02-features-implemented.md` に記入する（該当なしの場合は「なし」と記載）。
-
-   - 「既に実装済みの機能はありますか？（提案した機能含む）ある場合、以下の情報を教えてください：」
-     - **Category 1**（大分類：ユーザー管理、コンテンツなど）
-     - **Category 2**（中分類：認証、プロフィールなど）
-     - **機能名**（ユーザー視点の名称）
-     - **説明**（何ができるか）
-     - **機能 ID**（FN-XXX 形式、連番）
-
-### 5. 予定機能一覧の作成
-
-1. **テンプレートの準備**:
-
-   ```bash
-   SCRIPT_DIR=$(for d in .agent .cursor .claude .codex; do [ -d "$d" ] && echo "$d" && break; done)
-   cp "$SCRIPT_DIR/templates/project/01-requirements/03-features-planned.md" "docs/project/requirements/03-features-planned.md"
-   ```
-
-2. **要件ギャップ分析と提案**:
-
-   - 「システム概要」で確認した目的・スコープと、「実装済み機能」の差分を分析する。
-   - 未実装と思われる主要機能をリストアップし、ユーザーに提案する。
-     - 「システム概要で『〇〇機能』への言及がありましたが、まだ実装されていないようです。これを予定機能に追加しますか？」
-     - 「現在の実装には『××』が含まれていますが、これに関連する『△△ 機能』は将来的に必要になりますか？」
-
-3. **ヒアリングと記入**:
-   提案内容へのフィードバックを含め、以下の質問を行う。回答をテーブル形式で `docs/project/requirements/03-features-planned.md` に記入する。
-
-   - 「今後実装予定の機能をリストアップしてください（提案した機能含む）。各機能について以下を明確にします：」
-
-     - **Category 1**（大分類）
-     - **Category 2**（中分類）
-     - **機能名**（アイデア段階でも可）
-     - **説明**（目的や価値を中心に）
-
-     ※テンプレートの方針に従い、**機能 ID**や**優先度**はこの段階では確定させず、柔軟性を重視して記載しない。
-
-### 6. 非機能要件一覧の作成
-
-1. **テンプレートの準備**:
-
-   ```bash
-   SCRIPT_DIR=$(for d in .agent .cursor .claude .codex; do [ -d "$d" ] && echo "$d" && break; done)
-   cp "$SCRIPT_DIR/templates/project/01-requirements/04-non-functional-requirements.md" "docs/project/requirements/04-non-functional-requirements.md"
-   ```
-
-2. **必要性の確認と標準提案**:
-
-   - ユーザーに定義の必要性を確認する：
-
-     - 「現段階で非機能要件（パフォーマンス、セキュリティなど）を詳細に定義する必要がありますか？『標準的な設定』で仮置きして後で調整することも可能です。」
-
-   - 必要または仮置きの場合、一般的なベストプラクティスを提案する：
-     - 「Web アプリケーションの標準的な目標値として、以下を提案します。これで問題ないか確認してください：」
-       - **パフォーマンス**: ページ読み込み 3 秒以内、API 応答 500ms 以内
-       - **セキュリティ**: HTTPS 必須、パスワードはハッシュ化、基本認証/OAuth
-       - **可用性**: 日次バックアップ、稼働率 99.5%（平日日中）
-
-3. **ヒアリングと記入**:
-   提案内容への合意、または独自の要件がある場合、以下の観点で**定量的な目標**を確認し、回答で `docs/project/requirements/04-non-functional-requirements.md` の各テーブルを更新する。
-
-   #### パフォーマンス
-
-   - 「ページ読み込み時間の目標は？」
-   - 「API レスポンス時間の目標は？」
-   - 「想定される同時接続ユーザー数、データ量は？」
-
-   #### セキュリティ
-
-   - 「認証方式、機密データの扱い、コンプライアンス要件は？」
-
-   #### 可用性・信頼性
-
-   - 「稼働率目標、許容ダウンタイム、バックアップ要件は？」
-
-   #### スケーラビリティ
-
-   - 「ユーザー数の成長予測、ピーク時のトラフィック想定は？」
-
-   #### ユーザビリティ・保守性
-
-   - 「アクセシビリティ、対応言語、デバイス、ブラウザは？」
-   - 「ログ・監視要件、デプロイ頻度は？」
-
-### 7. ユーザーストーリーの作成
-
-1. **テンプレートの準備**:
-
-   ```bash
-   SCRIPT_DIR=$(for d in .agent .cursor .claude .codex; do [ -d "$d" ] && echo "$d" && break; done)
-   cp "$SCRIPT_DIR/templates/project/01-requirements/05-user-stories.md" "docs/project/requirements/05-user-stories.md"
-   ```
-
-2. **分析と提案**:
-
-   - ここまで作成した「システム概要」「機能一覧（実装済み/予定）」を分析し、主要なユーザージャーニーを抽出する。
-   - ユーザーに代表的なストーリーを提案する：
-     - 「『〇〇機能』に基づき、以下のストーリーが考えられますが、いかがでしょうか？」
-       - 「[役割]として、[〇〇機能]を使いたい、なぜなら[価値]だから」
-
-3. **ヒアリングと記入**:
-   提案内容へのフィードバックを含め、以下の質問を行う。回答をテーブル形式で `docs/project/requirements/05-user-stories.md` に記入する。
-
-   - 「他に主要なユーザージャーニーがあれば教えてください（[役割]として、[目的]がしたい、なぜなら[理由]）。」
-   - 各ストーリーの優先度、受け入れ基準を確認する。
-
-### 8. 全体レビュー
-
-- 作成した全てのドキュメントをユーザーに提示し、内容の正確性を確認する。
-  - 「記載内容に誤りや漏れはありませんか？」
-  - 「抽象的すぎる記述や、後で解釈が分かれそうな表現はありますか？」
-  - 「テンプレートのコメントや不要な例示は適切に処理（残す/削除）されていますか？」
-
-### 9. 完了条件と構造の確認
-
-- 以下の完了条件を満たしていて、且つドキュメントの構造が適切であることを確認します。
-
-  1. **ファイルの存在と構造確認**:
-     各ファイルが存在し、テンプレートの主要な構造（見出しやテーブル）が維持されているか検証する。
-
-     ```bash
-     # 01-system-overview.md: 主要セクションの確認
-     grep "## 背景" docs/project/requirements/01-system-overview.md && echo "OK" || echo "MISSING: 背景"
-     grep "## 目的" docs/project/requirements/01-system-overview.md && echo "OK" || echo "MISSING: 目的"
-
-     # 02-features-implemented.md: テーブルヘッダーの確認
-     grep "| 機能ID | Category 1 |" docs/project/requirements/02-features-implemented.md && echo "OK" || echo "MISSING: Table Header"
-
-     # 03-features-planned.md: テーブルヘッダーの確認
-     grep "| Category 1 | Category 2 |" docs/project/requirements/03-features-planned.md && echo "OK" || echo "MISSING: Table Header"
-
-     # 04-non-functional-requirements.md: テーブルヘッダーの確認
-     grep "| カテゴリ | 要件 |" docs/project/requirements/04-non-functional-requirements.md && echo "OK" || echo "MISSING: Table Header"
-
-     # 05-user-stories.md: テーブルヘッダーの確認
-     grep "| ストーリーID | ストーリー |" docs/project/requirements/05-user-stories.md && echo "OK" || echo "MISSING: Table Header"
-     ```
-
-  2. **チェックリスト**:
-     - [ ] すべてのファイルが存在する
-     - [ ] 各ファイルがテンプレートの基本構造を維持していて、主要なセクションやテーブルが適切に記載されている
-     - [ ] プレースホルダーが適切な内容に置き換わっていいる
-
-### 10. Git への追加（オプション）
-
-- ユーザーに確認：「作成した要件定義ドキュメントを Git に追加しますか？」
-- 「はい」の場合、以下を実行：
-
-  ```bash
-  git add docs/project/requirements/
-  git status
-  ```
-
-- Git status の結果を表示し、コミットメッセージの提案をする：
-
-  ```
-  推奨コミットメッセージ:
-  docs: 要件定義ドキュメントの作成
-
-  - システム概要、機能要件、非機能要件、ユーザーストーリーを追加
-  ```
-
-## 完了条件
-
-- `docs/project/requirements/` 配下に一連の要件定義ドキュメントが作成されている。
-- すべてのドキュメントで抽象的な表現が最小化され、具体的な数値・期限・制約が記載されている。
-- ユーザーがドキュメント内容を確認し、承認またはフィードバックを提供している。
-
-## エスカレーション
-
-- ユーザーが重要な情報を提供できない場合：
-  - 「この情報は後続の設計・実装で必須です。確認できる担当者や資料はありますか？」と確認し、TODO として記録する。
-- 競合する要件や矛盾が発見された場合：
-  - 「以下の要件が競合しています：[詳細]。優先順位や調整方針を確認させてください。」と報告する。
-- 想定工数が非現実的に大きい場合：
-  - 「現在の計画では実現が困難です。スコープ縮小や優先度調整を検討しませんか？」と提案する。
+---
+name: a-002-initialize-project
+description: プロジェクトの要件を対話形式で収集し、システム概要・機能要件・非機能要件・ユーザーストーリーのドキュメントを生成する。新規プロジェクト開始時、または要件が未整備の場合に使用。
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# InitializeProject (a-002)
+
+## 目的
+
+- プロジェクトの目的・背景・機能要件を詳細にヒアリングし、具体的で実装可能なドキュメントを作成する。
+- システム概要・実装済み機能・予定機能・非機能要件・ユーザーストーリーを網羅する。
+- 抽象的・曖昧な表現を避け、対話を通じて具体的な数値・期限・制約・優先度を明確化する。
+
+## 前提
+
+- `docs/project/01-requirements/` ディレクトリが存在すること（なければ先に `/a-001-setup-doc-structure` を実行）
+- `docs/` に書き込み権限があること
+- ユーザーがプロジェクト概要と主要機能の基本情報を提供できること
+
+## 手順
+
+### 1. ドキュメントディレクトリの確認
+
+```bash
+ls -la docs/project/01-requirements/ 2>/dev/null || echo "ディレクトリが存在しません"
+```
+
+存在しない場合: 「`docs/project/01-requirements/` がありません。先に `/a-001-setup-doc-structure` を実行してください。」
+
+### 2. テンプレート一括コピー
+
+要件定義に必要な 5 ファイルのテンプレートを `docs/project/01-requirements/` に一括コピーする。既存ファイルはスキップされる（冪等）。
+
+```bash
+SCRIPT_DIR=$(for d in .claude .agents; do [ -d "$d" ] && echo "$d" && break; done)
+bash "$SCRIPT_DIR/scripts/init-project-docs.sh" requirements
+```
+
+コピーされるファイル:
+
+- `01-system-overview.md`
+- `02-features-implemented.md`
+- `03-features-planned.md`
+- `04-non-functional-requirements.md`
+- `05-user-stories.md`
+
+### 3. コードベースの自動分析と提案
+
+**規模確認**:
+
+```bash
+ls -F
+```
+
+ファイルがほとんど無い／ソースコードが無い場合はスキップし、ユーザーへ通知。
+
+**詳細調査**（コードがある場合）:
+
+```bash
+cat package.json 2>/dev/null
+cat README.md 2>/dev/null
+find src app lib -maxdepth 2 2>/dev/null
+```
+
+結果から以下を推測・提示: システム概要（目的・技術スタック）、実装済み機能（ファイル構造からの推測）、想定ユーザー像。
+
+### 4. システム概要の記入
+
+`01-system-overview.md` を開き、「背景」「目的」をヒアリングして記入する。質問例は [reference/hearing-questions.md](reference/hearing-questions.md) を参照。
+
+### 5. 実装済み機能一覧の記入
+
+`02-features-implemented.md` に、コードベース調査で検出したディレクトリ/ファイル名から機能を提案し、ヒアリング結果をテーブルに記入する（Category 1/2、機能名、説明、機能 ID）。
+
+コード調査コマンドとヒアリング項目は [reference/hearing-questions.md](reference/hearing-questions.md#手順4-実装済み機能一覧) を参照。
+
+### 6. 予定機能一覧の記入
+
+`03-features-planned.md` に、システム概要と実装済み機能のギャップを分析して未実装機能を提案し、ヒアリング結果をテーブルに記入する（機能 ID・優先度は未確定のまま）。
+
+### 7. 非機能要件の記入
+
+`04-non-functional-requirements.md` に、詳細定義が必要か確認の上、パフォーマンス/セキュリティ/可用性/スケーラビリティ/ユーザビリティ・保守性の観点で**定量的な目標**をヒアリングして記入する。不要なら標準ベースライン（[examples/nfr-baseline.md](examples/nfr-baseline.md)）で仮置きする。
+
+### 8. ユーザーストーリーの記入
+
+`05-user-stories.md` に、作成済みドキュメントから主要ユーザージャーニーを抽出してストーリー案を提示し、ヒアリング結果をテーブルに記入する（優先度・受け入れ基準含む）。
+
+ストーリーテンプレート: 「[役割]として、[〇〇機能]を使いたい、なぜなら[価値]だから」
+
+### 9. 全体レビュー
+
+- 作成した全ドキュメントをユーザーに提示し、以下を確認:
+  - 「記載内容に誤りや漏れはありませんか？」
+  - 「抽象的すぎる記述や、解釈が分かれそうな表現はありますか？」
+  - 「テンプレートのコメントや不要な例示は適切に処理されていますか？」
+
+### 10. 完了条件と構造の確認
+
+- ファイルの存在と主要セクション/テーブル構造を検証。
+- 検証コマンド・チェックリスト・Git コミット手順は [reference/structure-check.md](reference/structure-check.md) を参照。
+
+### 11. Git への追加（オプション）
+
+詳細は [reference/structure-check.md](reference/structure-check.md#git-への追加オプション) を参照。
+
+## 完了条件
+
+- `docs/project/01-requirements/` に 5 つの要件定義ドキュメントが作成されている
+- すべてのドキュメントで抽象的表現が最小化され、具体的な数値・期限・制約が記載されている
+- ユーザーがドキュメント内容を確認し、承認またはフィードバックを提供している
+
+## エスカレーション
+
+- **ユーザーが重要な情報を提供できない**: 「この情報は後続の設計・実装で必須です。確認できる担当者や資料はありますか？」と確認し、TODO として記録。
+- **競合する要件や矛盾**: 「以下の要件が競合しています: [詳細]。優先順位や調整方針を確認させてください。」と報告。
+- **想定工数が非現実的に大きい**: 「現在の計画では実現が困難です。スコープ縮小や優先度調整を検討しませんか？」と提案。
+
+## 参考
+
+- [reference/hearing-questions.md](reference/hearing-questions.md) — 手順4〜8のヒアリング質問集
+- [reference/structure-check.md](reference/structure-check.md) — 手順10の構造チェックコマンドと Git コミット手順
+- [examples/nfr-baseline.md](examples/nfr-baseline.md) — 非機能要件の標準ベースライン提案値