npm - @ripla/godd-mcp - Versions diffs - 1.0.7-canary.9 → 1.0.7 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (92) hide show

package/templates/notes-docs/006_development_workflow/workflow.template.md CHANGED Viewed

@@ -1,289 +1,264 @@
 # 開発ワークフロー
-本ドキュメントは、`godd init` で展開される **新規プロジェクトの開発ワークフロー雛形** です。
-ripla の標準フローを構成・章立てとして共通化することを目的とし、ツール選定・ブランチ命名・レビュー要件などプロジェクト固有の差分は、本ファイルを各チームで書き換えて運用してください。
+**開発全体がどう流れていて、その中で自分がどこを担当するのか**を示すページです。
-> **書き換え前提**: 本ファイルは「構成と章立ての標準化」を目的とした雛形です。実プロジェクトでの埋め方の参考として [`ripla-inc/saas-box-manage` の `saas-box-docs/007_development/`](https://github.com/ripla-inc/saas-box-manage/tree/main/saas-box-docs/007_development) も併せて参照してください。
-> **godd 利用は Optional**: 本ワークフローは godd を使わなくても成立します。godd 利用時の自動化手段は各ステップ末尾に `_(Optional / godd 利用時)_` として補足します。
+毎日の手順は [daily_flow.template.md](./daily_flow.template.md) にあります。**日々の作業はそちらだけで進みます。** このページは、次のようなときに開いてください。
----
-## 原則: SDD（仕様書駆動開発）
-本ワークフローは **SDD（Spec-Driven Development）** を前提とします。コードではなく **仕様書を SSOT** として扱い、Issue・PR・実装はすべて Spec の差分を解決するために存在します。
-- **書く前に仕様を整える**: 要求 → 仕様（API / UI / DB / Feature / Usecase）を整理し、`docs/003_requirements/` 配下に確定させてから着手する
-- **コードと仕様を同時に更新する**: 実装中に仕様とのズレが生じたら、コード修正と同じ PR で仕様側も更新する
-- **PR では仕様書更新の漏れを必ずチェックする**: マージ前に「Spec と整合しているか」「仕様書の更新が必要な範囲を抑えているか」を確認する。PR テンプレの「仕様書更新チェック」項目を必ず埋める（詳細は `git.template.md`）
-- **設計判断は ADR に残す**: 後から「なぜこうしたか」を辿れるよう、トレードオフが発生した判断は ADR として記録する
-仕様書を後追いで書くのではなく、**仕様書を先に書き・実装で乖離させない**ことを徹底します。
+| こんなとき | 見るところ |
+|---|---|
+| 自分の担当がどこまでか知りたい | 「役割分担」「担当範囲の外」 |
+| 資料から Issue ができるまでを知りたい | 「A. 資料を受け取ったとき」 |
+| 誰が何を確認するのか知りたい | 「フェーズ別チェックポイント」 |
-> _(Optional / godd 利用時)_ `godd_spec` / `godd_documentation` / `godd_docs_update` / `godd_adr` で本原則の各ステップを自動化できます。詳細は `007_guides/godd_usage.md`。
+> **書き換え前提**: 本ファイルは「構成と章立ての標準化」を目的とした雛形です。ブランチ命名・レビュー要件などプロジェクト固有の差分は、各チームで書き換えて運用してください。
+>
+> **godd 利用は Optional**: 本ワークフローは godd を使わなくても成立します。godd を使わない場合は末尾の「[godd を使わない場合](#godd-を使わない場合)」を参照してください。
 ---
-## フェーズ分け
-プロジェクトの進行に応じて、要件・タスクの管理方法を切り替えます。
-| フェーズ | 期間 | 主担当 | 管理単位 | 場所 |
-|---|---|---|---|---|
-| キックオフ前 | 商談確定 〜 開発キックオフ | PM | **Requirements 文書** | `docs/003_requirements/` |
-| キックオフ後 | 開発開始 〜 リリース・運用 | PM / 開発 | **GitHub Issue** | `Issues` |
+## 大前提: 仕様書が正しい
-### キックオフ前（要件定義フェーズ）
+> **仕様書** = 「何を作るか」を書いた文書。`docs/003_requirements/` にあります。
+> **SSOT（エスエスオーティー）** = 「正しいものは1つだけ」という考え方。この現場では**仕様書が正**です。
-- PM がクライアントとすり合わせながら、要求を **Requirements 文書**として `docs/003_requirements/` 配下に整備する
-- ここでは Issue 化せず、章立て・粒度・受け入れ条件のドキュメント構造化に集中する
-- 完了条件は「キックオフ時点で開発着手できる粒度まで仕様が落ちていること」
+プログラムと仕様書が食い違っていたら、**直すのはプログラムのほう**です。Issue も PR も実装も、すべて「仕様書のとおりになっていない部分」を埋めるために存在します。
-### キックオフ後（実装フェーズ）
+- **書く前に仕様を整える** — 要求を仕様に落とし、`docs/003_requirements/` に確定させてから着手する
+- **コードと仕様を同時に更新する** — 実装中にズレが生じたら、同じ PR で仕様側も直す
+- **PR で仕様書更新の漏れを必ず確認する** — PR テンプレの「仕様書更新チェック」を必ず埋める
+- **設計判断は ADR に残す** — 後から「なぜこうしたか」を辿れるようにする
-- Requirements の各項目を **GitHub Issue** に分解し、以降は Issue 単位で進行管理する
-- 仕様変更・追加要望も原則 Issue として起票し、必要に応じて Requirements 文書へバックポートする
-- Issue → ブランチ → PR の流れは下記「全体像」以降の手順に従う
+**仕様書の更新漏れは「後回しにしてよい宿題」ではなく、バグと同じ扱い**です。
 ---
 ## 全体像
 ```mermaid
-flowchart LR
-    A[Spec/Issue 確認] --> B[main 同期]
-    B --> C[ブランチ作成]
-    C --> D[実装]
-    D --> E[品質ゲート]
-    E --> F[責務単位コミット]
-    F --> G[push & PR]
-    G --> H[レビュー]
-    H --> I{合格?}
-    I -->|Yes| J[Squash merge]
-    I -->|No| D
-    J --> K[Canary リリース]
-    K --> L[本番リリース]
+flowchart TD
+    A[資料を渡して godd-dev] --> B[起票モード]
+    B --> B1[親Issue + 子Issue を作成<br/>曖昧点は子Issue にコメントで質問]
+    B1 --> C{実装ループ<br/>子Issue を番号昇順に}
+    C -->|未回答 / 依存待ち| S[skipped<br/>理由を Issue にコメント]
+    C -->|実装できる| D[実装 → 品質ゲート → コミット]
+    D --> E[godd-docs → godd-submit]
+    E --> F[PR → レビュー → マージ]
+    C -->|詰まった| G[blocked<br/>ローカルにコミット<br/>push も PR もしない]
+    S -.->|回答が届いたら| H[godd-dev #番号 と回答]
+    G -.->|回答が届く / 原因が解ける| H
+    H --> D
 ```
-各ステップは下記「1. 着手前」以降で詳細化します。
 ---
-## 役割分担とチェック体制
+## A. 資料を受け取ったとき（起票モード）
-PR / コミットの責任範囲と、フェーズごとの最終確認者をあらかじめ役割で揃えておきます。プロジェクトごとに人員配置が異なる場合は、本表の役割を兼任者にマッピングしてください。
+> **この節は主に PM の作業です。** 開発事務さんは、ここで作られた Issue を受け取るところから始まります（B へ）。
-### 役割と主な責務
+議事録や受領資料を渡すと、**Issue の作成から実装までが一度に進みます。途中で承認は求められません。**
-| 役割 | 担当領域 | 主な責務 |
-|---|---|---|
-| PM | 要件定義 / Issue 管理 / 受け入れ | Requirements 整備、Issue 起票・優先順位付け、受け入れテストの合否判定 |
-| アーキテクト | 設計 / 横断 | ADR 起票、設計レビュー、技術スタック判断、横断的な影響範囲確認 |
-| FE エンジニア | フロントエンド実装 | 画面要件に沿った UI 実装、フロント側 unit / e2e、デザイン整合 |
-| BE エンジニア | バックエンド実装 / DB / インフラ | API・DB スキーマ実装、サーバ側 unit / integration、IaC 整合 |
-| QA | テスト戦略 / E2E | テスト計画策定、シナリオベース E2E、不具合トリアージ |
-| レビュアー | コード / 仕様レビュー | コード品質・テスト網羅・仕様整合のレビュー、ADR 妥当性確認 |
+1. **起票** — 親 Issue を作り、受領資料を `docs/999_ref/<日付>/#<親Issue番号>/` に原本のまま保管し、1 PR でレビューできる粒度に分解して子 Issue を作る。曖昧な点は該当する子 Issue にコメントで質問する
+2. **資料の PR** — 受領資料だけの PR が別に作られる。マージを待たずに次へ進む
+3. **実装ループ** — 子 Issue を番号の昇順に1件ずつ実装し、Issue ごとに PR を作る
-### フェーズ別チェックポイント
-| フェーズ | チェック実施者 | チェック項目 |
-|---|---|---|
-| 着手前 | PM + アーキテクト | Spec / Requirements が確定しているか、影響範囲が洗い出されているか |
-| 実装中 | FE / BE | 仕様との乖離が出ていないか、必要な ADR を起票したか |
-| 提出前 | 作者 | quality-gate（format / lint / typecheck / build）通過、テスト追加、PR 本文に仕様書更新チェック記入 |
-| レビュー | レビュアー + QA | 設計妥当性、型安全、テスト網羅、セキュリティ、仕様書更新の漏れ |
-| マージ前 | マージ実行者 | CI 通過、レビュー承認、コンフリクト解消 |
-| デプロイ後 | QA + 作者 | Canary 動作確認、本番疎通、リリースノート反映 |
+ループが1件を終えるたびに `godd-docs`（ドキュメント同期）と `godd-submit`（push と PR 作成）が**自動で走ります。個別に呼ぶ必要はありません。**
-### FE / BE 分担の指針
+終わったら、Issue ごとの結末が報告されます。
-| 観点 | FE 側で担保 | BE 側で担保 |
+| 結末 | 意味 | 次にすること |
 |---|---|---|
-| 画面表示 / 状態管理 | ✅ | — |
-| 入力バリデーション | ✅（UX 側の即時フィードバック） | ✅（仕様整合 / セキュリティ側の最終検証） |
-| 認可 | （UI 制御のみ） | ✅（権限判定の本体） |
-| エラーハンドリング | ✅（ユーザー提示） | ✅（ログ・監視・リトライ） |
-| API スキーマ | （契約に沿う） | ✅（定義・破壊的変更管理） |
-| DB / マイグレーション | — | ✅ |
-| 性能 | ✅（描画 / バンドル） | ✅（クエリ / N+1 / インデックス） |
-仕様書の「機能要件 / 画面要件」と「API / DB 設計」の境界に合わせて担当を分けるのが原則です。
+| **done** | PR まで作成済み | PR をレビューする |
+| **skipped** | 未回答の質問がある、または依存する Issue が未完了 | 質問をPMに確認する。理由は Issue のコメントにも残っている |
+| **blocked** | 途中まで実装してローカルにコミット済み（push はしていない） | Issue のコメントに停止理由とブランチ名がある |
 ---
-## 1. 着手前
-### 1.1 Issue / Spec を確認する
+## B. Issue を1件実装する（実装モード）
-- 着手対象 Issue と、それが指す Spec（`docs/003_requirements/` 配下）が確定しているかを確認する
-- Spec が不足している場合は **先に Spec を整備**する（実装着手前の必須条件）
-- 影響範囲（変更対象の画面・API・DB）と、必要なテストの種類（unit / integration / e2e）を洗い出す
+> **開発事務さんが日々行うのはこちらです。** 実際に打つ文字列は [daily_flow.template.md](./daily_flow.template.md) にあります。
-> _(Optional / godd 利用時)_ `godd_spec` で要求 → 仕様化、`godd_impact` で影響範囲、`godd_test_plan` でテスト計画を自動生成。
+**1 Issue = 1 ブランチ = 1 PR** です。B を Issue の数だけ繰り返します。
-### 1.2 main を最新化
+内部では次のツールがこの順で動きます。
-```bash
-git checkout main
-git pull origin main
+```text
+1. godd-dev      回答を Issue へ記録 → 未回答なら中断
+                 → ブランチ作成 → ATDD 実装 → 品質ゲート → コミット
+2. godd-review   自己レビュー（任意）
+3. godd-docs     ドキュメント・仕様を同期
+4. godd-submit   品質チェック → push → PR 作成
 ```
-コンフリクトは **SSOT（仕様書）準拠側を優先**して解決します。
+> **実際にチャットへ打つ文字列は [daily_flow](./daily_flow.template.md) にあります。** ツール名をそのまま打つ必要はありません（「#1234 を実装して」「ドキュメントを合わせて」「PR を出して」）。
-> _(Optional / godd 利用時)_ `godd_sync` で main 同期 + 作業中変更の退避・復元を自動化。
+- 中断していた作業があれば、**日付が変わっていても同じブランチを見つけて続きから再開します**（`feat/#<Issue番号>-*` で検索）。ゼロからやり直しにはなりません
+- `godd-dev` がブランチを作るため **`godd-new-branch` は不要**です
+- 実装差分は `godd-dev` が、ドキュメント差分は `godd-docs` がそれぞれ責務別にコミットするため、`godd-submit` に渡る時点で作業ツリーはクリーンです
+- このモードでは `godd-docs` と `godd-submit` は**自動実行されません**。案内に従って自分で呼びます
-### 1.3 ブランチを切る
+### 回答が「未定」だったとき
-`git.template.md` のブランチ命名規則に従って作成します。
+PMが「未定」「拡張性を持たせて」と答えた場合は、**回答待ちにはならず**、周辺のコードと要件から妥当な解釈で実装が進みます。
-```bash
-git checkout -b feat/<topic>-<issue>-<YYYYMMDD>
-```
-> _(Optional / godd 利用時)_ `godd_new_branch` がストア退避 → main 同期 → ブランチ作成 → 退避復元を一括実行。さらに `godd_git_workflow` を呼ぶと **sync + branch + commit** までをまとめて実行できる。
+そのとき `undecided` ラベルの Issue が別に起票され、何をどう仮定したか・なぜそう判断したかが記録されます。PR 本文の「残リスク / 未確定事項」にも同じ内容が載るため、レビュー時にどこが暫定かが分かります。要件が正式に決まったら、その Issue から修正できます。
 ---
-## 2. 実装
+## C. 途中で止まる条件
-- Spec を起点に実装する。Spec にない要求が発生した場合は **先に Spec を更新**してから着手する
-- 設計上のトレードオフが発生した場合は **ADR** として `docs/005_architecture/adr/` に記録する
-- 実装中に Spec とのズレが発生した場合は、本 PR 内で **仕様書側も更新**する（事後対応にしない）
+全自動で回りますが、以下は例外として止まります。
-> _(Optional / godd 利用時)_ `godd_dev` が **仕様確認 → 影響調査 → 実装 → 品質ゲート → PR 本文生成** を一気通貫で実行。`godd_adr` で ADR 起票、`godd_documentation` / `godd_docs_update` でドキュメント同期。
+| 状況 | 挙動 | 対応 |
+|---|---|---|
+| 機密情報を検出した | **ループごと停止** | 漏洩は取り消せないため、誤検知かどうかも含めて**人間が判断する**。自分で解除しない |
+| `docs/` が未作成 | `godd-docs-init` を案内して停止 | `godd-docs-init` を実行してから再開 |
+| 作業ツリーが汚れている / `git fetch` が失敗する | Issue を1つも作らずに停止 | 未コミットの変更を整理してから再開（孤立した Issue を GitHub に残さないための設計） |
 ---
-## 3. 品質担保
+## コミットは誰がするか
-### 3.1 提出前チェック項目
-| 項目 | 内容 |
+| ツール | コミットするもの |
 |---|---|
-| Spec 整合 | 仕様書と実装にズレがないか |
-| テスト | 影響範囲を unit / integration / e2e でカバーできているか |
-| Lint / 型チェック | プロジェクトの quality-gate（format / lint / typecheck / build）が通るか |
-| 互換性 | 既存 API・DB スキーマとの後方互換 |
-| セキュリティ | 機密情報の漏出・OWASP 観点 |
+| `godd-dev` | 実装差分。実装中は未コミットのまま保ち、完了後に責務別（schema / migration・backend・frontend・tests・docs）へ分割する |
+| `godd-docs` | 自身が更新したドキュメント差分 |
+| `godd-submit` | **コミットしない。** 作業ツリーがクリーンであることを前提に、push と PR 作成だけを行う |
-### 3.2 品質ゲート（必須）
-**ローカルで quality-gate を通したものを PR に出す**ことを提出条件とします。CI 上でも同等のゲートが走ります。
-サンプル（pnpm 系プロジェクトの場合）:
+`godd-submit` は提出前チェックが失敗しても **自分では直しません**。中断するので、`godd-dev` で修正してから呼び直します。
-```bash
-pnpm quality-gate    # format / lint / typecheck / build を一括実行
-pnpm preflight       # 環境前提（Docker / Node / Python / uv 等）を検証
-```
+---
-> プロジェクト固有のスタックに合わせて、上記コマンドを `make`、`go test ./... && go vet ./...`、`pytest && ruff check` 等に置き換えてください。
+## 役割分担
-> _(Optional / godd 利用時)_ `godd_check` で **Spec 整合 + テスト + Lint + 互換性 + セキュリティ** を一括検証、`godd_review` で設計・型・テスト・運用観点の AI 自己レビューを実施。
+プロジェクトごとに人員配置が異なる場合は、本表の役割を兼任者にマッピングしてください。
----
+| 役割 | 担当領域 | 主な責務 |
+|---|---|---|
+| PM | 要件定義 / Issue 管理 / 受け入れ | 要件整備、Issue の優先順位付け、**質問への回答**、受け入れ判定 |
+| **実装担当** | Issue 単位の実装 | `godd-dev` での実装、品質ゲート通過、PR 作成、レビュー指摘への対応 |
+| アーキテクト | 設計 / 横断 | ADR 起票、設計レビュー、技術スタック判断 |
+| レビュアー | コード / 仕様レビュー | 設計・テスト網羅・仕様整合のレビュー |
+| QA | テスト戦略 / E2E | テスト計画、シナリオベース E2E、不具合の切り分けと優先順位付け |
-## 4. コミット
+> **実装担当はエンジニア経験を前提としません。** `godd-dev` が実装・品質ゲート・コミットを行うため、担当者が行うのは「Issue を渡す」「結果を確認する」「指摘に対応する」ことです。判断に迷う場面と相談先は [daily_flow.template.md](./daily_flow.template.md) に定義しています。
-- **1 コミット = 1 責務**（フィーチャー / 修正 / リファクタ / docs 等を混ぜない）
-- メッセージ規則・プレフィックス・本文の書き方は `git.template.md` のコミットメッセージ章を参照
+### フェーズ別チェックポイント
-> _(Optional / godd 利用時)_ 責務が混在している場合は `godd_commit` で責務単位の自動分割と規約準拠のメッセージ生成を行える。
+| フェーズ | 確認者 | 確認項目 |
+|---|---|---|
+| 起票後 | PM | 子 Issue の粒度が適切か、質問に回答したか |
+| 実装後 | 実装担当 | 品質ゲートを通過し、どう終わったか（できた / 質問で止まった / 途中で止まった）を確認したか |
+| レビュー | レビュアー + QA | 設計妥当性、テスト網羅、セキュリティ、**仕様書更新の漏れ** |
+| マージ前 | マージ実行者 | CI 通過、レビュー承認、コンフリクト解消 |
+| デプロイ後 | QA + 実装担当 | 動作確認、リリースノート反映 |
 ---
-## 5. 提出
+## 品質ゲート
-### 5.1 一般フロー
+**ローカルで品質ゲートを通したものを PR に出す**ことを提出条件とします。CI 上でも同等のゲートが走ります。
-| 手順 | 内容 |
+| 項目 | 内容 |
 |---|---|
-| 1. quality-gate を通す | ローカルで通過してから提出 |
-| 2. push する | `git push -u origin <branch>` |
-| 3. PR を作成する | `git.template.md` の PR テンプレに沿って本文を記入 |
-PR 本文には **仕様書更新チェック（SDD 必須項目）** を必ず記入します。
+| Spec 整合 | 仕様書と実装にズレがないか |
+| テスト | 影響範囲を unit / integration / e2e でカバーできているか |
+| Lint / 型チェック / ビルド | プロジェクトの品質ゲートが通るか |
+| 互換性 | 今動いているものを壊していないか（API・データベースの作りとの互換） |
+| セキュリティ | 鍵やパスワードが混ざっていないか、よくある攻撃への備えができているか |
-### 5.2 _(Optional / godd 利用時)_
+サンプル（pnpm 系プロジェクトの場合）:
-```text
-godd_submit   # 品質チェック → push → PR 作成 を一括実行
+```bash
+pnpm quality-gate    # format / lint / typecheck / build を一括実行
+pnpm preflight       # 環境前提（Docker / Node / Python 等）を検証
 ```
-個別に進めたい場合は `godd_push` / `godd_push_execute` / `godd_pr_create` を順に呼び出します。
+> プロジェクトのスタックに合わせて、`make`、`go test ./... && go vet ./...`、`pytest && ruff check` 等に置き換えてください。
+失敗した場合の対処は [../007_guides/troubleshooting.md](../007_guides/troubleshooting.md) を参照してください。
 ---
-## 6. レビュー → マージ
+## レビュー → マージ
 | 役割 | アクション |
 |---|---|
-| 作者 | Draft で PR 起票 → 自己レビュー完了後 Ready for Review に変更 |
-| レビュアー | コメント → 修正依頼 / 承認（観点は「役割分担とチェック体制」を参照） |
-| 作者 | 指摘対応 → 再依頼 |
-| マージ実行者 | **Squash merge** で main に反映、ブランチは自動削除 |
+| 作者 | PR を出す（`godd-submit`）。**最初からレビュー可能な状態**で作られるため、切り替え操作は不要 |
+| レビュアー | コメント → 修正依頼 / 承認 |
+| 作者 | 指摘対応（`godd-dev` に指摘内容を伝えて修正）→ 再依頼 |
+| マージ実行者 | **Squash merge** で `main` に反映、ブランチは自動削除 |
-PR 本文・コミットメッセージ・ブランチ命名は `git.template.md` のルールに従います。
-> _(Optional / godd 利用時)_ `godd_pr_analyze` で差分のサマリと自動チェックを実施できる。
+PR 本文・コミットメッセージ・ブランチ命名は [git.template.md](./git.template.md) に従います。
 ---
-## 7. デプロイ
+## 担当範囲の外
-各環境のデプロイ手順は `docs/007_guides/` 配下のセットアップガイドを参照します。
+次は**実装担当の担当範囲外**です。手順は覚えなくて構いません。
-| 環境 | 担当 | タイミング |
+| 作業 | 誰が行うか | 自分がすること |
 |---|---|---|
-| ローカル | 開発者個別 | 任意 |
-| クラウド（初回） | チーム 1 名 | プロジェクト初期構築時 |
-| クラウド（更新） | リリース担当 | main マージ後・リリース時 |
+| PR のマージ | レビュアー | 指摘に対応する。マージは待つ |
+| デプロイ | リリース担当 | なし |
+| リリース（タグ付与・リリースノート） | リリース担当 | 完了報告のみ |
+| クラウドインフラの構築 | インフラ担当 | なし |
+| 権限の付与 | 管理者 | 必要になったら依頼する |
+依頼が必要な場面と伝え方は [judgment.template.md](./judgment.template.md) にあります。
-参照先:
+---
-- `docs/007_guides/setup_local_environment.template.md`
-- `docs/007_guides/setup_infra.template.md`
+## うまくいかないとき
-> _(Optional / godd Notes 利用時)_ `godd notes compose` / `godd notes infra` / `godd notes deploy` / `godd notes status` で各環境のデプロイ・状態確認が可能。
+| 状況 | どうするか |
+|---|---|
+| 手が止まった・進めてよいか分からない | [judgment.template.md](./judgment.template.md) |
+| エラーが出た | [../007_guides/troubleshooting.md](../007_guides/troubleshooting.md) |
+| 言葉が分からない | [../007_guides/glossary.md](../007_guides/glossary.md) |
 ---
-## 8. リリース
+## このフローで使うツール
-| ステップ | 担当 |
+| ツール | 用途 |
 |---|---|
-| 1. リリースノート作成 | リリース担当 |
-| 2. Canary リリース | main マージ時の自動タグ付与（`v<X.Y.Z>-canary.<N>`） |
-| 3. 動作確認 | QA + 作者（Canary 環境で疎通・基本シナリオ） |
-| 4. 本番リリース | リリース担当（`v<X.Y.Z>` タグ付与 → 本番デプロイ） |
-| 5. 完了報告 | 作者 |
+| `godd-dev` | 起票と実装。**このフローの入口** |
+| `godd-docs` | ドキュメント・仕様の同期（起票モードのループ内では自動実行） |
+| `godd-submit` | push と PR 作成（起票モードのループ内では自動実行） |
+| `godd-check` | 提出前の品質チェック（任意） |
+| `godd-review` | 自己レビュー（任意） |
+| `godd-sync` | `main` の最新化 |
+| `godd-slack-question` | Issue の不明点を Slack のスレッドで PM に質問（起票直後に自動で走る） |
-> _(Optional / godd 利用時)_ `godd_release_notes` でリリースノート生成、`godd_report` で完了報告を自動化。
+`godd-dev` がブランチ作成もコミットも行うため、`godd-new-branch` や `godd-commit` を本フローで呼ぶ必要はありません。
+**全ツールの一覧**は [../007_guides/godd_tools.md](../007_guides/godd_tools.md) にあります。
 ---
-## (Optional) godd 補助ツール早見表
+## godd を使わない場合
-godd を利用するプロジェクトでは、本ワークフローの各ステップを `godd_*` MCP ツールで自動化できます。godd を利用しないプロジェクトでは本章は読み飛ばして構いません。
+> **GoDD を使っているなら読み飛ばして構いません。** 導入していないプロジェクトのために、同じ考え方を手作業で行う場合の手順を残しています。
-| ツール | フェーズ | 概要 |
-|---|---|---|
-| `godd_spec` | 着手前 | 要求 → 仕様化 |
-| `godd_impact` | 着手前 | 影響範囲分析 |
-| `godd_test_plan` | 着手前 | テスト計画 |
-| `godd_sync` | 着手前 | main 同期 |
-| `godd_new_branch` | 着手前 | ブランチ作成 |
-| `godd_git_workflow` | 着手前 | sync + branch + commit を一括 |
-| `godd_dev` | 実装 | 開発メインエントリ |
-| `godd_adr` | 実装 | 設計判断の記録 |
-| `godd_documentation` / `godd_docs_update` | 実装 | ドキュメント同期 |
-| `godd_check` | 品質 | 提出前チェック |
-| `godd_review` | 品質 | CTO レベル自己レビュー |
-| `godd_commit` | コミット | 責務単位コミット |
-| `godd_push` / `godd_push_execute` / `godd_pr_create` | 提出 | 個別実行 |
-| `godd_submit` | 提出 | 一括実行（推奨） |
-| `godd_pr_analyze` | レビュー | PR 差分の分析 |
-| `godd_release_notes` | リリース | リリースノート生成 |
-| `godd_notes_deploy` | デプロイ | Notes デプロイ案内 |
-| `godd_report` | 完了 | 完了報告 |
-> 完全な一覧（29 件）と詳細は `docs/007_guides/godd_usage.md` を参照。
+| ステップ | 内容 |
+|---|---|
+| 1. 着手前 | Issue と仕様の確定を確認。不足していれば**先に仕様を整備する**。影響範囲と必要なテストを洗い出す |
+| 2. main 同期 | `git checkout main && git pull origin main`。コンフリクトは**仕様書準拠側を優先** |
+| 3. ブランチ作成 | `git checkout -b feat/#<issue>-<topic>-<YYYYMMDD>` |
+| 4. 実装 | 仕様を起点に実装。仕様にない要求が出たら**先に仕様を更新**する。トレードオフは ADR に記録 |
+| 5. 品質ゲート | 上記「品質ゲート」の項目をローカルで通す |
+| 6. コミット | **1 コミット = 1 責務**。schema / backend / frontend / tests / docs を分ける |
+| 7. 提出 | push → PR 作成。PR 本文の「仕様書更新チェック」を必ず埋める |
+| 8. レビュー → マージ | 上記「レビュー → マージ」と同じ |
+| 9. デプロイ・リリース | 「担当範囲の外」のとおり、リリース担当が行う |
+---
+## 関連ドキュメント
+- 毎日の進め方: [daily_flow.template.md](./daily_flow.template.md)
+- 判断に迷ったら: [judgment.template.md](./judgment.template.md)
+- Git 運用ルール: [git.template.md](./git.template.md)
+- 用語が分からない: [../007_guides/glossary.md](../007_guides/glossary.md)
+- 困ったとき: [../007_guides/troubleshooting.md](../007_guides/troubleshooting.md)
+- ツール一覧: [../007_guides/godd_tools.md](../007_guides/godd_tools.md)

package/templates/notes-docs/007_guides/README.md ADDED Viewed

@@ -0,0 +1,85 @@
+# ガイド・セットアップ
+**必要になったときに引くフォルダ**です。全部を読む必要はありません。
+まず、自分がどれに当てはまるかを選んでください。
+---
+## あなたはどれですか
+### A. これから開発に参加する（はじめての人）
+**[getting_started.md](./getting_started.md) だけを読んでください。** 他は不要です。
+受け取るものの確認から最初の PR までが一本道でまとまっています（所要 1〜1.5時間）。
+> **まだプロジェクトを手元に取得（clone）していなくても読めます。** GoDD Notes、または GitHub の Web 画面で開いてください。
+### B. すでにセットアップ済みで、日々開発している
+日常の手順は **[../006_development_workflow/daily_flow.template.md](../006_development_workflow/daily_flow.template.md)** にあります。
+このフォルダからは、必要なときだけ以下を引いてください。
+| 場面 | ドキュメント |
+|---|---|
+| 言葉の意味が分からない | [glossary.md](./glossary.md) |
+| エラーが出た（画面に出た言葉から引く） | [troubleshooting.md](./troubleshooting.md) |
+| 進めてよいか迷った・人に聞くか判断したい | [../006_development_workflow/judgment.template.md](../006_development_workflow/judgment.template.md) |
+| どのツールを使うか探したい | [godd_tools.md](./godd_tools.md) |
+| ツールの使い方・フローを知りたい | [godd_usage.md](./godd_usage.md) |
+| Notes で何ができるか確認したい | [godd_notes_features.md](./godd_notes_features.md) |
+| Notes の操作方法を知りたい | [godd_notes_usage.md](./godd_notes_usage.md) |
+### C. チームに GoDD を導入する（導入担当）
+| # | ドキュメント | 内容 |
+|---|---|---|
+| 1 | [setup_godd.md](./setup_godd.md) | GoDD 本体の導入（ZIP / npm の2経路） |
+| 2 | [setup_godd_notes.md](./setup_godd_notes.md) | GoDD Notes の構築（ローカル 〜 クラウド） |
+| 3 | [bot-token-setup.md](./bot-token-setup.md) | GitHub App の作成と3値の受け渡し |
+| 4 | [setup_local_environment.template.md](./setup_local_environment.template.md) | ローカルに Notes を立てる |
+### D. 本番クラウド環境を構築する（インフラ担当）
+**[infra/](./infra/) フォルダにまとまっています。** → [infra/README.md](./infra/README.md)
+ローカル利用だけなら、このフォルダは**読む必要がありません**。
+---
+## ファイル一覧
+| ドキュメント | 対象 | 内容 |
+|---|---|---|
+| [getting_started.md](./getting_started.md) | **はじめての人** | セットアップ 〜 最初の PR まで |
+| [glossary.md](./glossary.md) | 全員 | 用語集 |
+| [troubleshooting.md](./troubleshooting.md) | 全員 | 症状別の対処・相談の判断基準 |
+| [godd_tools.md](./godd_tools.md) | 全員 | GoDD ツール全31件のリファレンス |
+| [godd_usage.md](./godd_usage.md) | GoDD 利用者 | ツールの使い方・場面ごとの流れ別フロー |
+| [godd_notes_features.md](./godd_notes_features.md) | Notes 利用者 | Notes の機能一覧 |
+| [godd_notes_usage.md](./godd_notes_usage.md) | Notes 利用者 | Notes の操作方法 |
+| [setup_godd.md](./setup_godd.md) | 導入担当 | GoDD の導入手順 |
+| [setup_godd_notes.md](./setup_godd_notes.md) | 導入担当 | Notes の構築手順 |
+| [setup_local_environment.template.md](./setup_local_environment.template.md) | 導入担当 | ローカル Notes の構築 |
+| [bot-token-setup.md](./bot-token-setup.md) | 導入担当 | GitHub App の設定 |
+| [infra/](./infra/) | インフラ担当 | クラウド構築（AWS 構成・GuardDuty・コスト監視・Terraform） |
+---
+## 迷ったときの原則
+| 迷い | 答え |
+|---|---|
+| 全部読むべき？ | **いいえ。** 必要になったときに引く |
+| AWS のガイドは読むべき？ | **本番クラウドを構築する担当者だけ。** ローカル利用なら不要 |
+| 仕様とドキュメントが食い違っている | **仕様書（`docs/003_requirements/`）が正**。食い違いを見つけたら Issue を立てる |
+| このフォルダに書いてあることが実態と違う | Issue を立てて報告する。**放置しない** |
+---
+## 関連フォルダ
+- 開発の進め方: [../006_development_workflow/](../006_development_workflow/)
+- 仕様書: `../003_requirements/`