@ripla/godd-mcp 1.0.7-canary.9 → 1.0.7

package/templates/notes-docs/007_guides/troubleshooting.md

@@ -0,0 +1,225 @@
+# 困ったときガイド
+
+**画面に出た言葉から探して、書いてあるとおりに試すページ**です。上から読む必要はありません。
+
+ブラウザやエディタの検索（`Cmd + F` / `Ctrl + F`）に、画面に出た言葉をそのまま貼って探してください。
+
+| 探しているもの | 見るところ |
+|---|---|
+| 画面に出たエラーを直したい | このページ |
+| 進めてよいか決めたい | [../006_development_workflow/judgment.template.md](../006_development_workflow/judgment.template.md) |
+| 言葉の意味を知りたい | [glossary.md](./glossary.md) |
+
+> **このページの手順を試して直らなければ、すぐ人に聞いてください。** 20分粘っても進まないなら、聞いたほうが速い場面です。**聞くのは失敗ではありません。**
+
+### 聞くときに伝える4点
+
+これがあると、相手は即答できます。
+
+```text
+1. 何をしようとしていたか   例: #1234 を godd-dev で実装しようとした
+2. 実際に何が起きたか       例: 品質ゲートで止まった
+3. エラーメッセージ         （画面をそのままコピーして貼る。要約しない）
+4. 自分で試したこと         例: ターミナル再起動、このページの「品質ゲート」を試した
+```
+
+---
+
+## セットアップ・起動
+
+### `godd: command not found`
+
+コマンドの置き場所がパソコンに登録されていません。
+
+1. **ターミナルを閉じて開き直す**（これで直ることが大半）
+2. それでも直らない場合は `godd install` をもう一度実行し、再度ターミナルを再起動
+3. まだ直らない → **人に聞く**（PATH の設定が必要）
+
+### macOS で「開発元不明」と出て起動できない
+
+```bash
+xattr -d com.apple.quarantine $(which godd)
+```
+
+### GoDD を認識しない（MCP が繋がらない）
+
+1. **AI エディタを完全に終了して起動し直す**（設定は再起動時に読み込まれる）
+2. 媒体ごとに状態を確認する
+
+   | 媒体 | 確認 |
+   |---|---|
+   | Cursor | `Settings → MCP` で `godd` が Running（緑）か |
+   | Claude Code | 起動時の承認ダイアログで `godd` を承認したか（`claude mcp list` で確認） |
+   | Codex | スキル一覧に `$godd-dev` が出るか |
+
+3. 有効になっていない場合は、プロジェクトのフォルダで `godd init` を実行済みか確認
+4. それでも繋がらない → **人に聞く**
+
+### ライセンスエラーが出る
+
+| メッセージ | 対処 |
+|---|---|
+| `Invalid license key` | ライセンスキーの写し間違い。前後の空白が混ざっていないか確認 |
+| `License has expired` | **管理者に更新を依頼**（自分では直せない） |
+| Registry に接続できない | ネットワーク接続を確認。社内 VPN が必要な場合あり |
+
+### `エラー: Docker および Docker Compose が必要です。`
+
+Docker Desktop が起動していません。Docker Desktop を起動し、クジラのアイコンが「Running」になってから再実行してください。
+
+### `GitHub App ID は必須です。` と言われる
+
+GitHub App の3つの値（App ID / Private Key / Installation ID）が必要です。**PAT（`ghp_...`）では代用できません。**
+
+管理者から3つの値を受け取っていない場合は、**受け取るところから**です。[bot-token-setup.md](./bot-token-setup.md) を参照してください。
+
+### ポートが使用中と言われる / 画面が開かない
+
+同じ番号を別のアプリが使っています。
+
+1. 既に GoDD Notes が起動していないか確認（ブラウザで `http://localhost:5175`）
+2. 起動済みなら、それを使えば OK
+3. そうでなければ `godd notes compose` をやり直し、ポート番号を別の値にする
+
+---
+
+## `godd-dev` が想定どおり動かない
+
+### 質問があって進めなかったと言われた
+
+**未回答の質問があるか、先に終わらせるべき Issue が残っています。** 異常ではありません。
+
+1. その Issue のコメントに理由が書かれているので読む
+2. **質問は Issue のコメントに自動で記録されます。** Slack 連携を導入しているプロジェクトでは、スレッドにも自動で投げられます
+3. その Issue は一旦置いて次に進み、回答が届いたら回答を添えて再開する
+
+   ```text
+   #1234 を実装して。金額の上限は10万円との回答をもらいました
+   ```
+
+### 途中で止まったと言われた
+
+**途中まで実装してローカルに保存された状態です。** 消えてはいません。
+
+1. Issue のコメントに停止理由とブランチ名が書かれているので読む
+2. 理由が解消できるものなら解消して `#<Issue番号> を実装して` で再開する
+3. 理由が分からない → **人に聞く**（ブランチ名を伝える）
+
+> 日付が変わっていても、同じブランチを見つけて続きから再開します。ゼロからやり直しにはなりません。
+
+### 機密情報を検出して全部止まった
+
+**これは安全装置です。自分で解除しないでください。**
+
+漏洩は取り消せないため、誤検知かどうかも含めて人間が判断する設計になっています。**必ず人に聞いてください。**
+
+### `docs/` が無いと言われて止まった
+
+AI エディタに「`docs/` を作って」と言うと、`godd-docs-init` が実行されます。作成後にもう一度実行してください。
+
+### 「作業ツリーが汚れている」と言われて止まった
+
+保存していない変更が残っています。
+
+1. 心当たりのある変更なら、`#<Issue番号> を実装して` で作業を進めてコミットしてもらう
+2. 心当たりがない / 捨ててよいか判断できない → **人に聞く**（**自分で消さない**）
+
+---
+
+## 品質ゲート・CI
+
+### 品質ゲートが失敗した
+
+**PR を出す前に必ず通す必要があります。** 落ちたまま提出しないでください。
+
+1. 失敗したのが何か（整形 / lint / 型チェック / ビルド / テスト）をメッセージから確認する
+2. **`godd-dev` に「品質ゲートが〇〇で落ちた」と伝えて修正してもらう**
+3. 通ったら改めて `godd-submit` を呼ぶ
+
+> `godd-submit` は失敗しても自分では直しません。中断するので、`godd-dev` で直してから呼び直す設計です。
+
+### CI が赤くなった（PR に赤い×が付いた）
+
+自分のパソコンでは通ったのに GitHub 側で落ちた状態です。
+
+1. PR の画面で **Details** を開き、どのチェックが落ちたか見る
+2. 内容を `godd-dev` に伝えて修正してもらう
+3. 修正を push すると CI が再実行される
+4. 意味が分からないエラー → **人に聞く**（PR の URL を伝える）
+
+### コンフリクトが出た
+
+他の人と同じ場所を変更しています。**どちらを残すかは判断が要ります。**
+
+1. まず `godd-sync` で最新を取り込んでみる
+2. それでも解消しない場合、**どちらを残すべきか自分で判断できるかを考える**
+3. 少しでも迷ったら → **人に聞く**（間違えると他の人の作業が消えます）
+
+---
+
+## PR・レビュー
+
+### PR にレビュー指摘が付いた
+
+**指摘は否定ではありません。** 想定どおりの流れです。
+
+1. 指摘内容を読む。分からなければ**その場でコメントで質問してよい**
+2. 直す内容が分かったら `godd-dev` に指摘内容を伝えて修正してもらう
+3. 修正を push する（PR は自動で更新される）
+4. コメントに「対応しました」と返信し、再レビューを依頼する
+
+### 「仕様書も直して」と言われた
+
+コードだけ直して仕様書を放置するのは、このプロジェクトでは**バグ扱い**です。
+
+`godd-docs` を呼ぶと、コード変更に対応するドキュメントを同期してくれます。
+
+### PR が起票されない（Notes での編集が反映されない）
+
+1. 画面右下の同期インジケータを確認。「同期中」のままならリロード
+2. それでも起票されない → **管理者に連絡**（GitHub App の設定側の問題）
+
+---
+
+## やってはいけないこと
+
+迷ったときの安全側の基準です。**これらは実行前に必ず人に聞いてください。**
+
+| やってはいけないこと | なぜ |
+|---|---|
+| `main` に直接 push | レビューを経ずに全員の環境に影響が出る |
+| `--force` を付けて push | 他の人の作業履歴が消える。**取り消せない** |
+| `--no-verify` でチェックを飛ばす | 壊れたコードが入る。CI で結局止まる |
+| 鍵・パスワード・トークンをコミット | 漏洩は取り消せない。削除しても履歴に残る |
+| `.env` をチームに共有・コミット | 同上 |
+| よく分からないファイルを消す | 復旧に時間がかかる。判断できないなら聞く |
+| 中身を確認せず提案されたコマンドを実行 | 特に削除・上書き系は影響が戻せない |
+
+---
+
+## それでも解決しないとき
+
+以下を添えて連絡してください。
+
+```text
+- やろうとしたこと:
+- 実行したコマンド / 呼んだツール:
+- エラーメッセージ（画面のコピー）:
+- 試したこと:
+- 関連する Issue / PR の番号:
+```
+
+> 連絡先はプロジェクトごとに異なります。**チーム参加時に確認して、ここに書き足してください。**
+>
+> - 技術的な質問:
+> - 仕様・要件の質問:
+> - 権限・アカウントの依頼:
+
+---
+
+## 関連ドキュメント
+
+- 用語が分からない: [glossary.md](./glossary.md)
+- 最初のセットアップ: [getting_started.md](./getting_started.md)
+- 毎日の進め方: [../006_development_workflow/daily_flow.template.md](../006_development_workflow/daily_flow.template.md)
+- Notes の使い方: [godd_notes_usage.md](./godd_notes_usage.md)

package/templates/notes-docs/999_ref/README.md

@@ -0,0 +1,23 @@
+# 999_ref — 受領資料の原本保管場所
+
+> 本ドキュメントは `docs/999_ref/README.md` の **テンプレート** です。
+
+本ディレクトリは、クライアント・プロダクトオーナーから受領した資料（zip・議事録・文字起こし・スクリーンショット等）の **原本をそのまま保管する場所** です。`godd-dev` の起票モードが受領資料をここへ格納します。
+
+## 格納ルール
+
+- 格納パス: `docs/999_ref/<YYYYMMDD>/#<Issue番号>/`
+  - `<YYYYMMDD>` は資料を受領（起票）した日付
+  - `#<Issue番号>` は起票時に作成される親 Issue の番号（親を作らない単一起票では、その実装 Issue の番号）。日付だけでは同日に 2 件の受領があったとき衝突するため、必ず Issue 番号までを含める
+- 受領ファイルは **原本のまま（バイナリのまま）** 置く。変換・要約・リネームをしてはならない — 本ディレクトリは「何を受け取ったか」の証跡である
+- 内容を読む必要がある場合は、閲覧用の変換をメモリ上（エージェントの解析中）だけで行い、変換後のコピーで原本を置き換えない
+
+## 例
+
+```text
+docs/999_ref/
+└── 20260822/
+    └── #1234/
+        ├── 定例議事録.pdf
+        └── 画面案.zip
+```

package/templates/notes-docs/GENERATED.md

@@ -20,4 +20,4 @@ docs/003_requirements/Notes/templates/
 
 ## 用途
 
-`godd_docs_init` ツールが実行されたとき、このディレクトリのテンプレートファイルが `docs/` の初期構造生成に使用されます。
+`godd-docs-init` ツールが実行されたとき、このディレクトリのテンプレートファイルが `docs/` の初期構造生成に使用されます。

package/templates/notes-docs/README.md

@@ -1,7 +1,7 @@
 # GoDD Notes ドキュメントテンプレート
 
-本ディレクトリは、`godd_docs_init` で生成される `docs/` 配下の **初期テンプレート群** です。
-新規プロジェクトで `godd init` → `/godd_docs_init` を実行すると、本テンプレートがプロジェクトの `docs/` にコピーされます。
+本ディレクトリは、`godd-docs-init` で生成される `docs/` 配下の **初期テンプレート群** です。
+新規プロジェクトで `godd init` → `/godd/godd-docs-init` を実行すると、本テンプレートがプロジェクトの `docs/` にコピーされます。
 
 本テンプレートの目的は **構成と章立ての標準化** です。具体的な記述内容は各プロジェクトで書き換え前提なので、雛形をそのまま使わず、自プロジェクトの実情に合わせて編集してください。
 
@@ -9,8 +9,7 @@
 
 | 用途 | 参照先 |
 |---|---|
-| ripla 標準の SaaS テンプレ（汎用） | [`ripla-inc/saas-box-manage`](https://github.com/ripla-inc/saas-box-manage) の `saas-box-docs/` |
-| godd 利用前提の埋め方サンプル | [`ripla-inc/box-series`](https://github.com/ripla-inc/box-series) の `docs/` |
+| 埋め方のサンプル | **（プロジェクトで参照できる実例があれば、ここに書き足してください）** |
 
 本テンプレートで提示する章立て (`001_project/` 〜 `007_guides/`) は上記2リポジトリと共通です。両者を見比べると「godd 利用 / 非利用」「最小スケルトン / 詳細記述」のバリエーションを把握しやすくなっています。
 
@@ -26,22 +25,25 @@ docs/
 │   ├── pages.csv                            ## 画面一覧（テーブルノート）と各画面の概要
 │   └── features.csv                         ## 画面ごとの機能一覧（テーブルノート）と各機能の概要
 ├── 002_business_flow/
-│   ├── README.md                            # ビジネスフロー概要
+│   ├── README.md                            ## ビジネスフロー概要
 │   ├── <business_flow_name>.md              # 特定業務のビジネスフローを解説
 │   └── <business_flow_name>.drawio          # 特定業務のビジネスフローを図示
 ├── 003_requirements/
-│   ├── README.md                            # フォルダの説明・requirements 一覧
+│   ├── README.md                            ## フォルダの説明・requirements 一覧
+│   ├── questions.csv                        ## 未回答の質問リスト（unanswered → answered → spec_reflected）
+│   ├── spec/
+│   │   └── README.md                        ## 仕様 SSOT（API 仕様・インフラ仕様等）の説明
 │   └── <Product Name>/
 │       └── <feature_name>.template.md       ## 概要/背景/ユーザーストーリー/画面要件/機能要件/機能詳細/非機能要件/備考
 ├── 004_pages/
-│   ├── README.md                            # フォルダの説明
+│   ├── README.md                            ## フォルダの説明
 │   └── app/
 │       ├── admin/
 │       │   └── corporations/
 │       │       └── <page_name>.template.md  ## 画面ごとの画面要件を記載
 │       └── users/
 ├── 005_architecture/
-│   ├── README.md
+│   ├── README.md                            ## フォルダの説明
 │   ├── stacks/                              # 技術スタック
 │   ├── api/                                 # API 設計（Swagger 等）
 │   ├── db/                                  # DB 設計（ER 図等）
@@ -49,20 +51,32 @@ docs/
 │   └── features/
 │       └── <feature_name>.md                # 機能設計書（データフロー / DB 設計）
 ├── 006_development_workflow/
-│   ├── README.md
-│   ├── git.template.md                      ## Git ルール
-│   └── workflow.template.md                 ## 開発ワークフロー
-└── 007_guides/
-    ├── README.md
-    ├── setup_godd.md                        ## GoDD の始め方
-    ├── godd_usage.md                        ## GoDD のコマンド・MCP ツール・利用方法
-    ├── setup_godd_notes.md                  ## GoDD Notes の構築方法
-    ├── godd_notes_usage.md                  ## GoDD Notes の利用方法
-    ├── setup_local_environment.template.md  ## ローカル環境構築ガイドのテンプレート（box-series サンプル）
-    ├── setup_infra.template.md              ## インフラ CI/CD 構築ガイドのテンプレート（box-series サンプル）
-    ├── setup_aws_accounts.md                ## 顧客向け AWS アカウント構成（Organizations）のセットアップ手順
-    ├── setup_aws_guard_duty.md              ## AWS Organizations 配下アカウントの GuardDuty 設定手順
-    └── setup_aws_cost_alert.md              ## AWS コスト監視（Budgets / Cost Anomaly Detection）の設定手順
+│   ├── README.md                            ## フォルダの入口・読む順
+│   ├── daily_flow.template.md               ## 毎日の進め方
+│   ├── judgment.template.md                 ## 判断に迷ったとき
+│   ├── workflow.template.md                 ## 開発ワークフロー全体
+│   └── git.template.md                      ## Git ルール
+├── 007_guides/
+│   ├── README.md                            ## フォルダの入口・読者別ナビ
+│   ├── getting_started.md                   ## はじめかた（初日に読む）
+│   ├── glossary.md                          ## 用語集
+│   ├── troubleshooting.md                   ## 困ったときガイド
+│   ├── godd_tools.md                        ## GoDD ツール一覧
+│   ├── godd_usage.md                        ## GoDD の使い方
+│   ├── godd_notes_features.md               ## GoDD Notes 機能一覧
+│   ├── godd_notes_usage.md                  ## GoDD Notes の操作方法
+│   ├── setup_godd.md                        ## GoDD の導入手順
+│   ├── setup_godd_notes.md                  ## GoDD Notes の構築手順
+│   ├── setup_local_environment.template.md  ## ローカル環境構築
+│   ├── bot-token-setup.md                   ## GitHub App の設定
+│   └── infra/                               ── インフラ担当向け
+│       ├── README.md                        ## 入口・読む順
+│       ├── setup_infra.template.md          ## インフラ CI/CD 構築
+│       ├── setup_aws_accounts.md            ## AWS アカウント構成
+│       ├── setup_aws_guard_duty.md          ## GuardDuty 設定
+│       └── setup_aws_cost_alert.md          ## コスト監視
+└── 999_ref/
+    └── README.md                            ## 受領資料の原本保管場所（<YYYYMMDD>/#<Issue番号>/ 単位で格納）
 ```
 
 `##` が付いたファイルは **テンプレートとして本ディレクトリで提供** しているもの、`#` のみのファイルは説明用 README または各プロジェクトで個別に作成するファイルです。
@@ -78,8 +92,10 @@ docs/
 | `003_requirements/` | 機能要件（Feature 単位） | PM / エンジニア |
 | `004_pages/` | 画面要件（URL パス単位） | PM / デザイナー |
 | `005_architecture/` | 設計（API / DB / インフラ / 機能） | エンジニア |
-| `006_development_workflow/` | Git / 開発ワークフロー | エンジニア |
-| `007_guides/` | セットアップ / 利用ガイド | エンジニア |
+| `006_development_workflow/` | **毎日の開発の進め方**（動線・判断・ワークフロー・Git ルール） | 実装担当 / PM |
+| `007_guides/` | **セットアップと、たまに引くリファレンス** | 全員 |
+| `007_guides/infra/` | 本番クラウド構築 | インフラ担当 |
+| `999_ref/` | 受領資料の原本保管（`godd-dev` 起票モードが格納） | エージェント |
 
 ---
 
@@ -102,7 +118,7 @@ GoDD Notes はファイル種別に応じて自動でエディタを切り替え
 ```bash
 godd init                # config.godd / .cursor/mcp.json を生成
 # Cursor のチャットから
-/godd_docs_init          # 本テンプレートを docs/ にコピー
+/godd/godd-docs-init          # 本テンプレートを docs/ にコピー
 ```
 
 ### 個別ファイルの更新
@@ -123,7 +139,7 @@ godd init                # config.godd / .cursor/mcp.json を生成
 - **キックオフまで**: PM が `001_project/`・`003_requirements/`・`004_pages/` を整備
 - **キックオフ以降**: 変更・要望・質問はすべて **GitHub Issue で管理**（CSV ベースの質問表は使わない）
 - **SDD（Spec-Driven Development）**: 実装は仕様書（`003_requirements/`）が先。仕様書にない実装は仕様書を先に更新してから着手
-- **PR 時のチェック**: コード変更を含む PR は、関連する仕様書を併せて更新する。`godd_documentation` / `godd_docs_update` で更新箇所を検出可能
+- **PR 時のチェック**: コード変更を含む PR は、関連する仕様書を併せて更新する。`godd-docs` で更新箇所を検出可能
 
 詳細は `006_development_workflow/workflow.template.md` を参照。
 
@@ -150,25 +166,39 @@ flowchart LR
 | 種類 | 起票先 | 例 |
 |---|---|---|
 | プロジェクト固有の仕様変更・要望 | 利用プロジェクトの Issue | 画面追加、ビジネスルール変更、ユーザー個別要望 |
-| **テンプレート自体の改善要望** | **[GoDD リポジトリの Issue](https://github.com/ripla-inc/GoDD/issues)** | 章立ての過不足、雛形の汎用性、サンプル CSV の項目、ベストプラクティスの抜け |
-| godd MCP ツール側のバグ・要望 | GoDD リポジトリの Issue（`type: bug` / `type: feature`） | `godd_dev` が想定通り動かない、新しい補助ツールが欲しい |
+| **テンプレート自体の改善要望** | **GoDD の提供元へ連絡**（連絡先はライセンス提供時の案内を参照） | 章立ての過不足、雛形の汎用性、サンプル CSV の項目、ベストプラクティスの抜け |
+| godd MCP ツール側のバグ・要望 | GoDD の提供元へ連絡 | `godd-dev` が想定通り動かない、新しい補助ツールが欲しい |
 
 ### テンプレ改善 PR を立てる際の注意
 
 - 「特定プロジェクトの事情」ではなく、**他プロジェクトでも有用な汎用化された改善** を反映する（プロジェクト固有の内容は持ち込まない）
 - 構成・章立てを変える場合は、既に godd init 済みのプロジェクトへの影響（差分の取り込み方法）も PR 本文に書く
-- 変更は本テンプレ群（`docs/003_requirements/Notes/templates/`）と、必要に応じて [`saas-box-manage`](https://github.com/ripla-inc/saas-box-manage) / [`box-series`](https://github.com/ripla-inc/box-series) の参照例も併せて見直す
+- 変更は本テンプレ群（`docs/003_requirements/Notes/templates/`）にまとめて反映する
 
 ---
 
 ## 関連ガイド
 
+**はじめて参加する人**
+
+- はじめかた: [007_guides/getting_started.md](./007_guides/getting_started.md)
+
+**日々の開発**
+
+- 毎日の進め方: [006_development_workflow/daily_flow.template.md](./006_development_workflow/daily_flow.template.md)
+- 判断に迷ったら: [006_development_workflow/judgment.template.md](./006_development_workflow/judgment.template.md)
+- 困ったとき: [007_guides/troubleshooting.md](./007_guides/troubleshooting.md)
+- 用語が分からない: [007_guides/glossary.md](./007_guides/glossary.md)
+- 開発ワークフロー全体: [006_development_workflow/workflow.template.md](./006_development_workflow/workflow.template.md)
+- Git ルール: [006_development_workflow/git.template.md](./006_development_workflow/git.template.md)
+
+**導入担当**
+
 - GoDD のセットアップ: [007_guides/setup_godd.md](./007_guides/setup_godd.md)
 - GoDD Notes の構築: [007_guides/setup_godd_notes.md](./007_guides/setup_godd_notes.md)
-- AWS アカウント構成: [007_guides/setup_aws_accounts.md](./007_guides/setup_aws_accounts.md)
-- AWS GuardDuty 設定: [007_guides/setup_aws_guard_duty.md](./007_guides/setup_aws_guard_duty.md)
-- AWS コスト監視: [007_guides/setup_aws_cost_alert.md](./007_guides/setup_aws_cost_alert.md)
 - GoDD の利用: [007_guides/godd_usage.md](./007_guides/godd_usage.md)
 - GoDD Notes の利用: [007_guides/godd_notes_usage.md](./007_guides/godd_notes_usage.md)
-- 開発ワークフロー: [006_development_workflow/workflow.template.md](./006_development_workflow/workflow.template.md)
-- Git ルール: [006_development_workflow/git.template.md](./006_development_workflow/git.template.md)
+
+**インフラ担当**
+
+- 本番クラウドの構築: [007_guides/infra/README.md](./007_guides/infra/README.md)