@ripla/godd-mcp 1.0.8-canary.2 → 1.0.8-canary.21

package/notes/api/docker/Dockerfile

@@ -6,9 +6,18 @@ RUN apt-get update && apt-get install -y --no-install-recommends libpq-dev gcc &
 
 RUN pip install uv
 
-COPY . .
+# Dependencies are installed from uv.lock, never re-resolved from pyproject.toml:
+# resolving at build time installs whatever is newest that day, so the same
+# source built on two days produced different images (#1384 — SQLAlchemy 2.1
+# arrived unannounced and broke Alembic). --locked fails the build when uv.lock
+# no longer matches pyproject.toml, rather than quietly resolving afresh.
+COPY pyproject.toml uv.lock ./
+RUN uv export --locked --no-dev --no-emit-project -o /tmp/requirements.txt \
+    && uv pip install --system -r /tmp/requirements.txt
 
-RUN uv pip install --system .
+# The project itself, without letting it pull in anything the lock did not pin.
+COPY . .
+RUN uv pip install --system --no-deps .
 
 EXPOSE 3100
 CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-3100}"]

package/notes/api/docker/Dockerfile.test

@@ -8,8 +8,12 @@ RUN apt-get update && apt-get install -y --no-install-recommends libpq-dev gcc &
 
 RUN pip install --no-cache-dir uv
 
-COPY pyproject.toml uv.lock* ./
-RUN uv pip install --system ".[dev]"
+# Same lock as the production image (docker/Dockerfile), plus the dev extra, so
+# tests run against the versions that ship (#1384). The source is used in place
+# from /app, so the project itself is not installed.
+COPY pyproject.toml uv.lock ./
+RUN uv export --locked --extra dev --no-emit-project -o /tmp/requirements.txt \
+    && uv pip install --system -r /tmp/requirements.txt
 
 COPY . .
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ripla/godd-mcp",
-  "version": "1.0.8-canary.2",
+  "version": "1.0.8-canary.21",
   "type": "module",
   "description": "GoDD MCP Server - AI-powered development workflow tools via Model Context Protocol (slash commands support)",
   "main": "dist/index.js",

package/templates/feedback/feedback-lambda/index.mjs

@@ -1,11 +1,9 @@
 // Lambda Function URL handler — フィードバック受付 → GitHub Issue 起票
 // 認証: GoDD Notes Bot (GitHub App) のインストールトークンを都度生成
+// Slack への通知はここでは行わない。feedback ラベルの Issue を GoDD の registry が
+// GitHub の Webhook で受けて投稿する（案件ごとに Slack の認証情報を持たないため）
 
 import crypto from "node:crypto";
-import {
-  SecretsManagerClient,
-  GetSecretValueCommand,
-} from "@aws-sdk/client-secrets-manager";
 
 const GITHUB_API = "https://api.github.com";
 const TOKEN_BUFFER_SECONDS = 300;
@@ -13,15 +11,30 @@ const JWT_EXPIRY_SECONDS = 600;
 // Function URL のリクエスト上限は 6MB。原画は送らない設計のため 3MB で十分
 const MAX_IMAGE_BYTES = 3 * 1024 * 1024;
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-
-const sm = new SecretsManagerClient();
+const FEEDBACK_LABEL = "feedback";
+// 「すぐ直してほしい」の希望。Slack の通知にスタンプが付いて Issue を移すときに引き継がれる
+const FIX_REQUESTED_LABEL = "godd:fix-requested";
+
+// SDK は Lambda ランタイムに同梱されている。読み込みを使う時まで遅らせ、
+// SDK の無い環境（テスト）でも本文の組み立てを検証できるようにする
+let sm = null;
+
+async function secretsManager() {
+  if (sm) return sm;
+  const { SecretsManagerClient, GetSecretValueCommand } = await import(
+    "@aws-sdk/client-secrets-manager"
+  );
+  sm = { client: new SecretsManagerClient(), GetSecretValueCommand };
+  return sm;
+}
 
 // シークレットのキャッシュ（コールドスタートごとにリセット）
 const secretCache = {};
 
 async function getSecret(secretName) {
   if (secretCache[secretName]) return secretCache[secretName];
-  const res = await sm.send(
+  const { client, GetSecretValueCommand } = await secretsManager();
+  const res = await client.send(
     new GetSecretValueCommand({ SecretId: secretName }),
   );
   const value = res.SecretString;
@@ -153,20 +166,28 @@ async function ensureBranch(repo, branch, token) {
   });
 }
 
-async function ensureLabel(repo, token) {
-  const label = await ghFetch(`/repos/${repo}/labels/feedback`, token).catch(
-    () => null,
-  );
+const LABELS = {
+  [FEEDBACK_LABEL]: {
+    color: "D93F0B",
+    description: "フィードバックウィジェットからの自動起票",
+  },
+  [FIX_REQUESTED_LABEL]: {
+    color: "FBCA04",
+    description: "GoDD Comment で「すぐ直してほしい」が選ばれた（承認前の希望）",
+  },
+};
+
+async function ensureLabel(repo, name, token) {
+  const label = await ghFetch(
+    `/repos/${repo}/labels/${encodeURIComponent(name)}`,
+    token,
+  ).catch(() => null);
   if (label) return;
 
   // 既存ラベルは触らず、無い場合のみ作成する（同時作成の競合は無視して続行）
   await ghFetch(`/repos/${repo}/labels`, token, {
     method: "POST",
-    body: JSON.stringify({
-      name: "feedback",
-      color: "D93F0B",
-      description: "フィードバックウィジェットからの自動起票",
-    }),
+    body: JSON.stringify({ name, ...LABELS[name] }),
   }).catch(() => {});
 }
 
@@ -185,10 +206,22 @@ async function commitImage(repo, branch, filePath, imageBuffer, token) {
 // Markdown テーブルのセルに利用者入力を埋め込むためのエスケープ。
 // パイプ・改行を無害化しないと表の構造ごと壊せてしまう（偽の指示文の埋め込みも含む）
 function cell(value) {
-  return String(value).replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+  return inert(String(value)).replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
 }
 
-function buildIssueBody(comment, imageUrl, page, meta, pin, extra = {}) {
+// 利用者入力に HTML コメントを開かせない。末尾の機械向けの印（metaLine）を
+// 偽装されると、Slack 通知のリンクや「すぐ直す」の判定を書き換えられてしまう
+function inert(text) {
+  return text.replace(/<!--/g, "&lt;!--");
+}
+
+// 機械向けの印。registry の Slack 通知と、修正ワークフロー（スクショを
+// git show で取り出す）がこの 1 行を読む。人が読む本文の書式とは独立させる
+function metaLine({ branch, screenshotPath, fixRequested }) {
+  return `<!-- godd-comment: branch=${branch} screenshot=${screenshotPath} fix-requested=${fixRequested} -->`;
+}
+
+export function buildIssueBody(comment, imageUrl, page, meta, pin, extra = {}) {
   const lines = [
     "## フィードバック",
     "",
@@ -197,8 +230,12 @@ function buildIssueBody(comment, imageUrl, page, meta, pin, extra = {}) {
     ...(extra.screenName ? ["### 画面名", "", cell(extra.screenName), ""] : []),
     "### 指摘・要望コメント",
     "",
-    `> ${comment.replace(/\n/g, "\n> ")}`,
+    `> ${inert(comment).replace(/\n/g, "\n> ")}`,
     "",
+    // 希望の記録だけ。修正は Slack の通知にスタンプが付いてから始まる
+    ...(extra.fixRequested
+      ? ["### すぐ直してほしい", "", "希望あり（Slack の通知にスタンプが付いてから修正を始める）", ""]
+      : []),
     "### スクリーンショット（指摘箇所）",
     `[スクリーンショットを開く](${imageUrl})`,
     "",
@@ -214,16 +251,30 @@ function buildIssueBody(comment, imageUrl, page, meta, pin, extra = {}) {
     `| UA | ${cell(meta.userAgent)} |`,
     `| 撮影日時 | ${cell(meta.capturedAt)} |`,
     `| ピン位置 | (${pin.x.toFixed(1)}%, ${pin.y.toFixed(1)}%) |`,
+    "",
+    metaLine({
+      branch: extra.branch,
+      screenshotPath: extra.screenshotPath,
+      fixRequested: extra.fixRequested === true,
+    }),
   ];
   return lines.join("\n");
 }
 
 // ペイロードの形状検証。未検証のまま参照すると TypeError → 500 になり、
 // 内部エラーメッセージが送信者へ漏れるため、先に固定文言の 400 で弾く
-function validatePayload(payload) {
+export function validatePayload(payload) {
   if (typeof payload !== "object" || payload === null) return "不正なペイロードです";
-  const { comment, annotatedScreenshot, pin, page, meta, reporter, screenName } =
-    payload;
+  const {
+    comment,
+    annotatedScreenshot,
+    pin,
+    page,
+    meta,
+    reporter,
+    screenName,
+    fixRequested,
+  } = payload;
   if (typeof comment !== "string" || !comment.trim()) return "comment は必須です";
   if (typeof annotatedScreenshot !== "string")
     return "annotatedScreenshot は必須です";
@@ -248,6 +299,8 @@ function validatePayload(payload) {
     return "reporter が不正です";
   if (screenName !== undefined && typeof screenName !== "string")
     return "screenName が不正です";
+  if (fixRequested !== undefined && typeof fixRequested !== "boolean")
+    return "fixRequested が不正です";
   return null;
 }
 
@@ -284,8 +337,16 @@ export async function handler(event) {
     }
     const validationError = validatePayload(payload);
     if (validationError) return respond(400, { error: validationError });
-    const { comment, annotatedScreenshot, pin, page, meta, reporter, screenName } =
-      payload;
+    const {
+      comment,
+      annotatedScreenshot,
+      pin,
+      page,
+      meta,
+      reporter,
+      screenName,
+      fixRequested,
+    } = payload;
 
     let imageBuffer;
     try {
@@ -307,8 +368,11 @@ export async function handler(event) {
     const rand = Math.random().toString(36).slice(2, 8);
     const filePath = `feedback/${ts}_${rand}.png`;
 
+    const labels = fixRequested
+      ? [FEEDBACK_LABEL, FIX_REQUESTED_LABEL]
+      : [FEEDBACK_LABEL];
     await ensureBranch(repo, branch, token);
-    await ensureLabel(repo, token);
+    for (const label of labels) await ensureLabel(repo, label, token);
     const imageUrl = await commitImage(
       repo,
       branch,
@@ -320,13 +384,16 @@ export async function handler(event) {
     const issueBody = buildIssueBody(comment.trim(), imageUrl, page, meta, pin, {
       reporter: reporter?.trim(),
       screenName: screenName?.trim(),
+      fixRequested: fixRequested === true,
+      branch,
+      screenshotPath: filePath,
     });
     const issue = await ghFetch(`/repos/${repo}/issues`, token, {
       method: "POST",
       body: JSON.stringify({
         title: `[フィードバック] ${comment.trim().replace(/\r?\n/g, " ").slice(0, 60)}`,
         body: issueBody,
-        labels: ["feedback"],
+        labels,
       }),
     });
 

package/templates/feedback/frontend/FeedbackWidget.tsx

@@ -53,6 +53,7 @@ export function FeedbackWidget() {
   const [comment, setComment] = useState("");
   const [reporter, setReporter] = useState(loadSavedReporter);
   const [screenName, setScreenName] = useState("");
+  const [fixRequested, setFixRequested] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [result, setResult] = useState<FeedbackResult | null>(null);
 
@@ -62,6 +63,7 @@ export function FeedbackWidget() {
     setPin(null);
     setComment("");
     setScreenName("");
+    setFixRequested(false);
     setError(null);
     setResult(null);
   }, []);
@@ -169,6 +171,7 @@ export function FeedbackWidget() {
         comment: comment.trim(),
         reporter: reporter.trim() || undefined,
         screenName: screenName.trim() || undefined,
+        fixRequested,
         annotatedScreenshot: annotated,
         pin,
         page: {
@@ -416,6 +419,30 @@ export function FeedbackWidget() {
                     background: "#fbf9f4",
                   }}
                 />
+                <label
+                  htmlFor="feedback-fix-requested"
+                  style={{
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 6,
+                    marginTop: 10,
+                    fontSize: 13,
+                    color: INK,
+                    cursor: phase === "submitting" ? "default" : "pointer",
+                  }}
+                >
+                  <input
+                    id="feedback-fix-requested"
+                    type="checkbox"
+                    checked={fixRequested}
+                    onChange={(e) => setFixRequested(e.target.checked)}
+                    disabled={phase === "submitting"}
+                  />
+                  すぐ直してほしい
+                  <span style={{ fontSize: 12, color: SUB }}>
+                    （担当者が確認してから修正を始めます）
+                  </span>
+                </label>
                 <div
                   style={{
                     display: "flex",

package/templates/feedback/frontend/api.ts

@@ -11,7 +11,8 @@ export interface FeedbackResult {
 
 /**
  * フィードバックをバックエンドへ送信する。
- * バックエンド側でスクショの S3 保存・GitHub Issue 作成・Slack 通知を行う想定。
+ * バックエンド（feedback Lambda）がスクショのコミットと GitHub Issue の作成を行う。
+ * Slack への通知は、作られた Issue をもとに GoDD の registry が行う。
  */
 export async function submitFeedback(
   payload: FeedbackPayload,

package/templates/feedback/frontend/types.ts

@@ -32,6 +32,11 @@ export interface FeedbackPayload {
   reporter?: string;
   /** 画面名（任意・フリーテキスト） */
   screenName?: string;
+  /**
+   * 「すぐ直してほしい」の希望。希望の記録だけで、これだけでは修正は始まらない
+   * （送信者をサーバー側で確認できないため、開発チームの Slack でのスタンプを挟む）
+   */
+  fixRequested?: boolean;
   /** ピン合成済みスクリーンショット（PNG の data URL）。原画はペイロードサイズ削減のため送らない */
   annotatedScreenshot: string;
   /** 指摘位置のピン */

package/templates/notes-docs/005_architecture/api/README.md

@@ -0,0 +1,17 @@
+# 005_architecture/api — API 設計
+
+> 本ドキュメントは `docs/005_architecture/api/README.md` の **テンプレート** です。
+
+本ディレクトリは、**API のインターフェース設計**（エンドポイント・リクエスト/レスポンス・エラー）を整理する場所です。Swagger / OpenAPI の定義ファイルもここに置きます。
+
+## 記述ルール
+
+- エンドポイントを追加・変更したら、ここと関連する要件定義の両方を更新する
+- エラーレスポンスの形式とステータスコードの使い分けを明記する（実装者が推測で決めないため）
+- 認証・認可の前提を明記する
+
+## エンドポイント一覧
+
+| メソッド | パス | 概要 | 認証 |
+|---|---|---|---|
+| [GET] | [/api/v1/xxx] | [概要] | [要 / 不要] |

package/templates/notes-docs/005_architecture/db/README.md

@@ -0,0 +1,17 @@
+# 005_architecture/db — DB 設計
+
+> 本ドキュメントは `docs/005_architecture/db/README.md` の **テンプレート** です。
+
+本ディレクトリは、**テーブル定義・ER 図・インデックス設計・マイグレーション方針**を整理する場所です。
+
+## 記述ルール
+
+- スキーマを変更したら、マイグレーションと同じ PR でここを更新する
+- 論理削除・監査列・命名規約など、全テーブルに共通する規約を先に定める
+- ER 図は Mermaid か drawio で置き、実装とずれたら差し替える
+
+## テーブル一覧
+
+| テーブル名 | 概要 | 主キー | 備考 |
+|---|---|---|---|
+| [table_name] | [概要] | [id] | [備考] |

package/templates/notes-docs/005_architecture/features/README.md

@@ -0,0 +1,18 @@
+# 005_architecture/features — 機能設計書
+
+> 本ドキュメントは `docs/005_architecture/features/README.md` の **テンプレート** です。
+
+本ディレクトリは、**機能ごとの設計書**（どう作るか）を置く場所です。要件（`003_requirements/`）が「何を作るか」を定めるのに対し、ここは実装方針・データフロー・DB 設計を定めます。
+
+## 記述ルール
+
+- **1 機能 = 1 ファイル**（`<feature_name>.md`）で管理する
+- ファイル名は `docs/001_project/features.csv` の機能名と対応させる
+- 実装と設計が乖離したら、設計書側を必ず更新する（設計書は SSOT の一部）
+- 雛形は `docs/003_requirements/【仕様書】フォーマット①（ビジネスサイド向け）.md` を使う。技術的な記述が主になる機能ではフォーマット②を使ってよい
+
+## 設計書一覧
+
+| # | 機能 | ファイル | ステータス |
+|---|---|---|---|
+| 1 | [機能名] | [feature_name].md | [draft / fixed] |

package/templates/notes-docs/005_architecture/infra/README.md

@@ -0,0 +1,19 @@
+# 005_architecture/infra — インフラ設計
+
+> 本ドキュメントは `docs/005_architecture/infra/README.md` の **テンプレート** です。
+
+本ディレクトリは、**インフラのアーキテクチャ設計**（構成図・ネットワーク・環境ごとの差異・監視）を整理する場所です。
+
+構築の**手順**は `docs/007_guides/infra/` に置きます。ここは「どうなっているか」、あちらは「どう作るか」です。
+
+## 記述ルール
+
+- 環境（本番 / ステージング / 開発）ごとの差異を明記する
+- 構成を変更したら構成図も差し替える（図と文章がずれると、図のほうが信じられてしまう）
+- コスト・可用性・セキュリティ上のトレードオフは ADR に残す
+
+## 構成一覧
+
+| 環境 | リージョン | 主要サービス | 備考 |
+|---|---|---|---|
+| [本番] | [ap-northeast-1] | [サービス名] | [備考] |

package/templates/notes-docs/005_architecture/stacks/README.md

@@ -0,0 +1,20 @@
+# 005_architecture/stacks — 技術スタック
+
+> 本ドキュメントは `docs/005_architecture/stacks/README.md` の **テンプレート** です。
+
+本ディレクトリは、**採用している言語・フレームワーク・ライブラリとそのバージョン**、および選定理由を整理する場所です。
+
+## 記述ルール
+
+- 依存を追加・更新したら、ここも併せて更新する（`godd-docs` の同期対象）
+- 「なぜそれを選んだか」を残す。選定理由が無いと、後から入れ替えてよいのか判断できない
+- 設計上の意思決定を伴う変更は ADR にも残す
+
+## スタック一覧
+
+| 層 | 技術 | バージョン | 選定理由 |
+|---|---|---|---|
+| フロントエンド | [技術名] | [x.y.z] | [理由] |
+| バックエンド | [技術名] | [x.y.z] | [理由] |
+| データベース | [技術名] | [x.y.z] | [理由] |
+| インフラ | [技術名] | [x.y.z] | [理由] |

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

@@ -1,4 +1,4 @@
-# GoDD ツール一覧（34 件）
+# GoDD ツール一覧（39 件）
 
 **「こういうことをしたいが、何と言えばいいか」を探すページ**です。上から読む必要はありません。
 
@@ -41,7 +41,7 @@
 |---|---|---|
 | 1 | `godd-dev` | **開発の入口。2つの使い方があります。** 受領資料（zip・議事録・文字起こし）やチャットの要望を渡すと**起票モード**（作業に分ける → 起票〔単一なら実装Issue 1件のみ / 複数なら親Issue + 子Issue〕→ 質問投稿 → 実ファイル受領時のみ資料保管 → Issue を番号昇順に1件ずつ実装）、`#<Issue番号>` を渡すと**実装モード**（回答記録 → ATDD 実装 → 品質ゲート → 責務別コミット） |
 | 2 | `godd-check` | 提出する前のチェック。仕様書との食い違い・影響範囲・テスト・今動いているものを壊していないか・秘密情報の混入をまとめて調べる |
-| 3 | `godd-review` | コードのレビュー。指摘を重大度（CRITICAL / MAJOR / MINOR / SUGGESTION）で分けて返す |
+| 3 | `godd-review` | コードのレビュー。指摘を重大度（CRITICAL / MAJOR / MINOR / SUGGESTION）で分けて返す。コードは直さない。Codex CLI か Claude Code がログイン済みで入っていれば、実装したのとは別の会社の AI にも見てもらう |
 | 4 | `godd-commit` | 変更を意味のまとまりごとに分けて記録し、説明文も作る |
 | 20 | `godd-dev-workflow` | 開発ワークフロー全体（環境構築 → 実装 → テスト → コミット → PR） |
 
@@ -99,7 +99,12 @@
 | 31 | `godd-config` | `config.godd` の表示・更新（`GODD_CONFIG` 環境変数でパス指定可）。**リポジトリガード対象外**の唯一のツール |
 | 32 | `godd-comment` | フィードバック機構（画面のスクリーンショット + ピン + コメント → GitHub Issue を自動で起票）の導入。**GoDD Notes を導入済みのプロジェクト向け** |
 | 33 | `godd-slack-question` | Issue の不明点を Slack のスレッドで PM に質問し、スレッドの URL を Issue に記録する |
-| 34 | `godd-knowledge-save` | 作業中に得た知見を保存する。**自分から頼んだときだけ動きます** |
+| 34 | `godd-knowledge-save` | 作業中に得た知見を保存する。**自分から頼んだときだけ動きます**。保存先は自分に付与された project のどれか |
+| 35 | `godd-knowledge-projects` | 知見の保存先にできる project（自分に付与されたもの）の一覧を見る。保存か検索が使えるなら自動で使えます |
+| 36 | `godd-knowledge-search` | 蓄積された知見を検索する（意味の近さとキーワードの両方で探します）。頼んだときに加え、`godd-dev` が判断に迷う場面などで自分から引きます。探せるのは自分に付与された project の知見だけ |
+| 37 | `godd-knowledge-attachment` | 検索結果に出た添付ファイルのダウンロード URL を取得する（**約 1 時間で使えなくなります**） |
+| 38 | `godd-knowledge-search-general` | 他の案件の知見を、会社名・人名を外した形（一般層）で検索する。頼んだときに加え、`godd-dev` が判断に迷う場面などで自分から引きます。どの案件の知見かは分かりません |
+| 39 | `godd-dev-actions` | GitHub Actions での無人実行用の `godd-dev`（GoDD Maintenance の修正 Actions が使う）。**人が手元で使うときは `godd-dev` を使います** |
 
 ---
 

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

@@ -65,8 +65,6 @@ GoDD は **2 系統のインターフェース** を提供します。
 | `godd-sync` | `main` ブランチを最新化（コンフリクトは SSOT 準拠側を優先） |
 
 > **残りは [godd_tools.md](./godd_tools.md) にまとめています。** 全ツールの網羅一覧はそちらが正で、本ガイドは使い方に絞ります。
-| `godd-slack-question` | Issue の不明点（「# 質問内容」コメント）を Slack スレッドとして投稿し、スレッド URL を Issue に記録（事前レビュー済みの `config.godd.slack` を読み取り専用で参照） |
-| `godd-comment` | フィードバック機構（画面スクショ + ピン + コメント → Issue 起票）の導入 |
 
 ---
 

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

@@ -158,6 +158,12 @@ Step 3 まで完了したら、利用する IDE に応じて MCP を登録しま
 
 **初回承認（必須）**: プロジェクトスコープの `.mcp.json` は、ファイルがあるだけでは有効化されません。対象プロジェクトで `claude` を起動すると承認ダイアログが表示されるので、`godd` サーバーを**承認**してください。承認状態は `claude mcp list` で確認できます（承認前は `⏸ Pending approval`、承認後は接続済みになります）。
 
+### Google 連携（ripla-google）
+
+ライセンスに Google 連携の案件が割り当てられている場合だけ、`godd init` が `.cursor/mcp.json` / `.mcp.json` に `ripla-google` も自動で設定します（完了時に「ripla-google（Google 連携 MCP）を設定しました（割当案件 N 件、…）」と表示されます）。割り当てが無いライセンスでは何も追加されません。
+
+設定されたら IDE / Claude Code を再起動し、`/mcp` で `ripla-google` が connected になっていることを確認してください。Claude Code では `godd` と同じく初回の承認が必要です。
+
 以下の手動登録は、`.mcp.json` の自動生成を使わない場合（生成前のバージョン、またはプロジェクト外スコープで登録したい場合）のフォールバック手順です。
 
 Claude Code では `claude mcp` コマンドで MCP サーバーを登録します。  

package/templates/notes-docs/README.md

@@ -9,9 +9,15 @@
 
 | 用途 | 参照先 |
 |---|---|
-| 埋め方のサンプル | **（プロジェクトで参照できる実例があれば、ここに書き足してください）** |
+| 埋め方のサンプル | `003_requirements/【仕様書サンプル】*.md`（ユーザー管理・権限管理機能 / 通知機能 / 受注・出荷一覧） |
 
-本テンプレートで提示する章立て (`001_project/` 〜 `007_guides/`) は上記2リポジトリと共通です。両者を見比べると「godd 利用 / 非利用」「最小スケルトン / 詳細記述」のバリエーションを把握しやすくなっています。
+## このファイルの役割（重要）
+
+本ファイルの「ディレクトリ構成」は、**コピー先プロジェクトの `docs/README.md` になります**。そして `godd-docs` は実行のたびにコピー先の `docs/README.md` を読み、**そこに書かれた構造を正として実リポジトリと突き合わせ、不足しているドキュメントを作成します**。
+
+したがって、ここに書かれていないものは作られません。構成を変えたときは、このツリーと実ファイルの両方を更新してください。
+
+ツリー中の `<...>` は**可変部分のプレースホルダー**であり、ファイル名ではありません。`<feature_name>.md` という名前の実ファイルを作らないでください。
 
 ---
 
@@ -30,24 +36,30 @@ docs/
 │   └── <business_flow_name>.drawio          # 特定業務のビジネスフローを図示
 ├── 003_requirements/
 │   ├── README.md                            ## フォルダの説明・requirements 一覧
+│   ├── 【仕様書】フォーマット①（ビジネスサイド向け）.md  ## 仕様書の雛形（既定）
+│   ├── 【仕様書】フォーマット②（エンジニア向け）.md      ## 仕様書の雛形（技術寄りの記述が必要な場合）
+│   ├── 【仕様書サンプル】<機能名>.md          ## 雛形の埋め方サンプル（3 本を同梱）
 │   ├── spec/
 │   │   └── README.md                        ## 仕様 SSOT（API 仕様・インフラ仕様等）の説明
 │   └── <Product Name>/
-│       └── <feature_name>.template.md       ## 概要/背景/ユーザーストーリー/画面要件/機能要件/機能詳細/非機能要件/備考
+│       └── <feature_name>.md                # 機能別の要件定義（フォーマット①から作成）
 ├── 004_pages/
 │   ├── README.md                            ## フォルダの説明
 │   └── app/
-│       ├── admin/
-│       │   └── corporations/
-│       │       └── <page_name>.template.md  ## 画面ごとの画面要件を記載
-│       └── users/
+│       └── <url path>/                      # 画面の URL パスをそのままフォルダ構造にする
+│           └── requirements.md              # 画面ごとの画面要件を記載
 ├── 005_architecture/
 │   ├── README.md                            ## フォルダの説明
-│   ├── stacks/                              # 技術スタック
-│   ├── api/                                 # API 設計（Swagger 等）
-│   ├── db/                                  # DB 設計（ER 図等）
-│   ├── infra/                               # インフラ設計
+│   ├── stacks/
+│   │   └── README.md                        ## 技術スタック（言語・FW・ライブラリとバージョン）
+│   ├── api/
+│   │   └── README.md                        ## API 設計（Swagger / OpenAPI 等）
+│   ├── db/
+│   │   └── README.md                        ## DB 設計（ER 図・テーブル定義）
+│   ├── infra/
+│   │   └── README.md                        ## インフラアーキテクチャの設計
 │   └── features/
+│       ├── README.md                        ## 機能設計書の置き場（1 機能 = 1 ファイル）
 │       └── <feature_name>.md                # 機能設計書（データフロー / DB 設計）
 ├── 006_development_workflow/
 │   ├── README.md                            ## フォルダの入口・読む順
@@ -68,7 +80,7 @@ docs/
 │   ├── setup_godd_notes.md                  ## GoDD Notes の構築手順
 │   ├── setup_local_environment.template.md  ## ローカル環境構築
 │   ├── bot-token-setup.md                   ## GitHub App の設定
-│   └── infra/                               ── インフラ担当向け
+│   └── infra/                               ## インフラ担当向け
 │       ├── README.md                        ## 入口・読む順
 │       ├── setup_infra.template.md          ## インフラ CI/CD 構築
 │       ├── setup_aws_accounts.md            ## AWS アカウント構成
@@ -126,10 +138,11 @@ godd init                # config.godd / .cursor/mcp.json を生成
 |---|---|
 | `001_project/README.md` | プロジェクト立ち上げ時に PM が記入 |
 | `001_project/pages.csv` / `features.csv` | 立ち上げ〜キックオフまでに PM が記入。以降は変更を Issue で管理 |
-| `003_requirements/<Product>/<feature>.template.md` | 機能追加時に PM が新規作成 |
-| `004_pages/.../<page>.template.md` | 画面追加時に PM / デザイナーが新規作成 |
-| `006_development_workflow/*.template.md` | プロジェクト立ち上げ時に **チーム方針に合わせて書き換え** |
-| `007_guides/setup_*.template.md` | インフラ・ローカル環境の構成変更時に更新 |
+| `003_requirements/<Product Name>/<feature_name>.md` | 機能追加時に PM が新規作成（雛形は `【仕様書】フォーマット①`） |
+| `004_pages/app/<url path>/requirements.md` | 画面追加時に PM / デザイナーが新規作成 |
+| `005_architecture/features/<feature_name>.md` | 機能の設計が決まった時点で作成・更新 |
+| `006_development_workflow/` のテンプレート | プロジェクト立ち上げ時に **チーム方針に合わせて書き換え** |
+| `007_guides/setup_local_environment.template.md` / `007_guides/infra/setup_infra.template.md` | ローカル環境・インフラの構成変更時に更新 |
 
 ---
 
@@ -172,7 +185,7 @@ flowchart LR
 
 - 「特定プロジェクトの事情」ではなく、**他プロジェクトでも有用な汎用化された改善** を反映する（プロジェクト固有の内容は持ち込まない）
 - 構成・章立てを変える場合は、既に godd init 済みのプロジェクトへの影響（差分の取り込み方法）も PR 本文に書く
-- 変更は本テンプレ群（`docs/003_requirements/Notes/templates/`）にまとめて反映する
+- 変更は GoDD リポジトリ側のテンプレート群にまとめて反映する（配布元の SSOT。本ファイルのコピー先プロジェクトには存在しない）
 
 ---