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

package/templates/feedback/frontend/config.ts

@@ -0,0 +1,14 @@
+// フィードバック機能の環境出し分け設定。
+//
+// 有効化ルール:
+//   - ローカル開発(vite dev)では常に ON（import.meta.env.DEV）。開発中に必ず試せるように。
+//   - デプロイ環境では VITE_FEEDBACK_ENABLED=true でビルドしたときだけ ON。
+//     → dev 配信用ビルドではフラグを立て、本番ビルドでは立てない、で出し分ける。
+export const FEEDBACK_ENABLED =
+  import.meta.env.VITE_FEEDBACK_ENABLED === "true" || import.meta.env.DEV;
+
+// 送信先エンドポイント。未指定なら同一オリジンの /api/feedback を叩く。
+export const FEEDBACK_API_URL =
+  import.meta.env.VITE_FEEDBACK_API_URL ?? "/api/feedback";
+
+export const FEEDBACK_TOKEN = import.meta.env.VITE_FEEDBACK_TOKEN ?? "";

package/templates/feedback/frontend/types.ts

@@ -0,0 +1,41 @@
+// フィードバック(指摘)1件のデータ構造。フロント→バックエンドで送受信する。
+
+/** スクリーンショット画像上でのピン位置（画像に対する相対%。0〜100） */
+export interface FeedbackPin {
+  x: number;
+  y: number;
+}
+
+/** どの画面で撮られたかのコンテキスト */
+export interface FeedbackPage {
+  /** 完全な URL（クエリ・ハッシュ込み） */
+  url: string;
+  /** パス + ハッシュ（ルート識別用） */
+  path: string;
+  /** document.title */
+  title: string;
+}
+
+/** 環境メタ情報（再現・切り分け用） */
+export interface FeedbackMeta {
+  viewport: { width: number; height: number };
+  userAgent: string;
+  /** 撮影時刻（ISO 8601） */
+  capturedAt: string;
+}
+
+/** 送信ペイロード */
+export interface FeedbackPayload {
+  /** クライアントが書いた指摘コメント */
+  comment: string;
+  /** 起票者名（任意・フリーテキスト） */
+  reporter?: string;
+  /** 画面名（任意・フリーテキスト） */
+  screenName?: string;
+  /** ピン合成済みスクリーンショット（PNG の data URL）。原画はペイロードサイズ削減のため送らない */
+  annotatedScreenshot: string;
+  /** 指摘位置のピン */
+  pin: FeedbackPin;
+  page: FeedbackPage;
+  meta: FeedbackMeta;
+}

package/templates/feedback/terraform/Makefile

@@ -0,0 +1,43 @@
+# Terraform 便利ターゲット（フィードバック基盤）
+#
+# 任意のショートカット。make が無い環境（Windows 等）では
+# terraform init / plan / apply を直接実行すればよい。
+#
+# 認証プロファイルを使う場合は AWS_PROFILE を設定してから実行する。
+#   例: make plan AWS_PROFILE=my-profile
+
+ifdef AWS_PROFILE
+export AWS_PROFILE
+endif
+
+.PHONY: default init fmt validate plan apply apply-auto-approve destroy
+
+default:
+	@echo "make init                - terraform init"
+	@echo "make fmt                 - terraform fmt"
+	@echo "make validate            - terraform fmt(check) + validate"
+	@echo "make plan                - terraform plan"
+	@echo "make apply               - terraform apply"
+	@echo "make apply-auto-approve  - terraform apply -auto-approve"
+	@echo "make destroy             - terraform apply -destroy"
+
+init:
+	terraform init
+
+fmt:
+	terraform fmt
+
+validate:
+	terraform fmt -check && terraform validate
+
+plan: fmt
+	terraform plan
+
+apply: fmt
+	terraform apply
+
+apply-auto-approve: fmt
+	terraform apply -auto-approve
+
+destroy:
+	terraform apply -destroy

package/templates/feedback/terraform/backend.tf

@@ -0,0 +1,10 @@
+terraform {
+  backend "s3" {
+    # GoDD Notes インフラ導入時に作成される tfstate バケットを共用する
+    bucket       = "godd-notes-tfstate-{{ACCOUNT_ID}}"
+    key          = "feedback/{{ENV}}/terraform.tfstate"
+    region       = "{{AWS_REGION}}"
+    encrypt      = true
+    use_lockfile = true
+  }
+}

package/templates/feedback/terraform/lambda.tf

@@ -0,0 +1,95 @@
+# ---------- Secrets Manager ----------
+# godd-notes Terraform が作成済みのシークレットを参照。
+# SystemAdministrator ロールに DescribeSecret 権限がないため data source は使わず、
+# 名前と ARN パターンを直接指定する。
+
+locals {
+  secret_prefix = "godd-notes/${local.env}"
+  github_app_secrets = {
+    app_id          = "${local.secret_prefix}/github-app-id"
+    private_key     = "${local.secret_prefix}/github-app-private-key"
+    installation_id = "${local.secret_prefix}/github-app-installation-id"
+  }
+  secrets_arn_prefix = "arn:aws:secretsmanager:${local.aws_region}:${local.account_id}:secret:${local.secret_prefix}/github-app-"
+}
+
+# ---------- IAM ----------
+
+resource "aws_iam_role" "lambda" {
+  name = "${local.function_name}-role"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect    = "Allow"
+      Principal = { Service = "lambda.amazonaws.com" }
+      Action    = "sts:AssumeRole"
+    }]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "lambda_basic" {
+  role       = aws_iam_role.lambda.name
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
+}
+
+resource "aws_iam_role_policy" "lambda_secrets" {
+  name = "${local.function_name}-secrets"
+  role = aws_iam_role.lambda.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = "secretsmanager:GetSecretValue"
+      Resource = ["${local.secrets_arn_prefix}*"]
+    }]
+  })
+}
+
+# ---------- Lambda ----------
+
+data "archive_file" "lambda" {
+  type        = "zip"
+  source_dir  = local.lambda_src
+  excludes    = ["node_modules", ".git"]
+  output_path = "${path.module}/.build/lambda.zip"
+}
+
+resource "aws_lambda_function" "feedback" {
+  function_name    = local.function_name
+  role             = aws_iam_role.lambda.arn
+  handler          = "index.handler"
+  runtime          = "nodejs22.x"
+  timeout          = 30
+  memory_size      = 256
+  # 連打スパムの天井（GitHub App のレートリミットは GoDD Notes と共有のため巻き添え防止）
+  reserved_concurrent_executions = 5
+  filename         = data.archive_file.lambda.output_path
+  source_code_hash = data.archive_file.lambda.output_base64sha256
+
+  environment {
+    variables = {
+      GITHUB_APP_ID_SECRET              = local.github_app_secrets.app_id
+      GITHUB_APP_PRIVATE_KEY_SECRET     = local.github_app_secrets.private_key
+      GITHUB_APP_INSTALLATION_ID_SECRET = local.github_app_secrets.installation_id
+      GITHUB_REPO                       = var.github_repo
+      GITHUB_BRANCH                     = "feedback-assets"
+      FEEDBACK_TOKEN                    = var.feedback_token
+    }
+  }
+}
+
+# ---------- Function URL ----------
+
+resource "aws_lambda_function_url" "feedback" {
+  function_name      = aws_lambda_function.feedback.function_name
+  authorization_type = "NONE"
+
+  cors {
+    allow_origins = var.allowed_origins
+    allow_methods = ["POST"]
+    allow_headers = ["content-type", "x-feedback-token"]
+    max_age       = 86400
+  }
+}

package/templates/feedback/terraform/local.tf

@@ -0,0 +1,12 @@
+locals {
+  # 1 AWS アカウント = 1 プロダクト前提（GitHub App シークレットも godd-notes/<env>/* のアカウント単位）。
+  # そのためリソース名にプロダクト名は含めない。
+  project_name = "feedback"
+  env          = "{{ENV}}"
+  aws_region   = "{{AWS_REGION}}"
+  account_id   = "{{ACCOUNT_ID}}"
+
+  function_name = "feedback-${local.env}"
+  # 標準配置: リポジトリ直下の feedback-lambda/ を terraform/feedback/<env>/ から参照する
+  lambda_src = "../../../feedback-lambda"
+}

package/templates/feedback/terraform/output.tf

@@ -0,0 +1,9 @@
+output "function_url" {
+  description = "Lambda Function URL（フロントの VITE_FEEDBACK_API_URL に設定する）"
+  value       = aws_lambda_function_url.feedback.function_url
+}
+
+output "function_name" {
+  description = "Lambda 関数名"
+  value       = aws_lambda_function.feedback.function_name
+}

package/templates/feedback/terraform/provider.tf

@@ -0,0 +1,24 @@
+terraform {
+  required_version = ">= 1.14.3"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 6.0"
+    }
+  }
+}
+
+provider "aws" {
+  region = local.aws_region
+
+  allowed_account_ids = [local.account_id]
+
+  default_tags {
+    tags = {
+      Project     = local.project_name
+      Environment = local.env
+      ManagedBy   = "Terraform"
+    }
+  }
+}

package/templates/feedback/terraform/variables.tf

@@ -0,0 +1,25 @@
+variable "github_repo" {
+  description = "Issue を作成する GitHub リポジトリ（owner/repo）"
+  type        = string
+}
+
+variable "allowed_origins" {
+  description = "CORS で許可するオリジン（フロントエンドの配信 URL）。ローカル開発と dev 配信の両方を列挙する"
+  type        = list(string)
+
+  validation {
+    condition     = length(var.allowed_origins) > 0 && !contains(var.allowed_origins, "*")
+    error_message = "allowed_origins には具体的なオリジンを 1 つ以上指定してください（\"*\" は不可）。"
+  }
+}
+
+variable "feedback_token" {
+  description = "フロントエンドからのリクエストを検証するトークン。init 時に自動生成し、gitignore された terraform.tfvars で渡す（コミット禁止）"
+  type        = string
+  sensitive   = true
+
+  validation {
+    condition     = length(var.feedback_token) >= 32
+    error_message = "feedback_token は 32 文字以上のランダム文字列にしてください（openssl rand -base64 32 で生成）。"
+  }
+}

package/templates/github-actions/aws/deploy-notes.yml.hbs

@@ -6,6 +6,11 @@ on:
     paths:
       - 'notes-api/**'
       - 'notes-app/**'
+      - 'terraform/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'terraform/**'
   workflow_dispatch:
 
 permissions:
@@ -27,6 +32,8 @@ jobs:
     outputs:
       api: $\{{ steps.filter.outputs.api }}
       app: $\{{ steps.filter.outputs.app }}
+      terraform: $\{{ steps.filter.outputs.terraform }}
+      terraform-iam: $\{{ steps.filter.outputs.terraform-iam }}
     steps:
       - uses: actions/checkout@v7
       - uses: dorny/paths-filter@v3
@@ -37,10 +44,188 @@ jobs:
               - 'notes-api/**'
             app:
               - 'notes-app/**'
+            terraform:
+              - 'terraform/godd-notes/{{env}}/**'
+            terraform-iam:
+              - 'terraform/godd-notes/{{env}}-iam/**'
 
-  deploy-api:
+  terraform-plan:
     needs: changes
-    if: needs.changes.outputs.api == 'true'
+    if: github.event_name == 'pull_request' && needs.changes.outputs.terraform == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v6
+        with:
+          role-to-assume: arn:aws:iam::{{accountId}}:role/github-actions-{{env}}-plan
+          aws-region: {{region}}
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_wrapper: false
+
+      - name: Terraform Plan
+        id: plan
+        working-directory: terraform/godd-notes/{{env}}
+        continue-on-error: true
+        shell: bash
+        run: |
+          set -o pipefail
+          terraform init -input=false -no-color
+          terraform plan -input=false -no-color 2>&1 | tee "$GITHUB_WORKSPACE/plan.txt"
+
+      - name: Comment PR with Plan
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+
+            let plan = '';
+            try { plan = fs.readFileSync('plan.txt', 'utf8'); } catch { plan = 'Plan failed to execute'; }
+
+            const maxLen = 60000;
+            const truncate = (s) => s.length > maxLen ? s.substring(0, maxLen) + '\n... (truncated)' : s;
+
+            const body = `## Terraform Plan Results (\`{{env}}\`)
+            <details><summary>Show Plan</summary>
+
+            \`\`\`
+            ${truncate(plan)}
+            \`\`\`
+
+            </details>`;
+
+            const comments = await github.rest.issues.listComments({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+            });
+
+            const botComment = comments.data.find(c =>
+              c.user.type === 'Bot' && c.body.includes('## Terraform Plan Results')
+            );
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: body,
+              });
+            }
+
+      - name: Check Plan Status
+        if: steps.plan.outcome == 'failure'
+        run: exit 1
+
+  terraform-iam-notice:
+    needs: changes
+    if: |
+      github.event_name == 'pull_request' &&
+      needs.changes.outputs.terraform-iam == 'true' &&
+      needs.changes.outputs.terraform != 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Comment IAM notice
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const body = '## Terraform IAM Notice (`{{env}}-iam`)\n\n' +
+              '`{{env}}-iam` ディレクトリに変更が検出されました。' +
+              'IAM 変更は自動 plan/apply の対象外です。手動で適用してください。\n\n' +
+              '```bash\ncd terraform/godd-notes/{{env}}-iam\nterraform init\nterraform plan\nterraform apply\n```';
+
+            await github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: body,
+            });
+
+  terraform-apply:
+    needs: changes
+    if: |
+      github.event_name == 'push' &&
+      needs.changes.outputs.terraform == 'true'
+    runs-on: ubuntu-latest
+    environment: {{env}}
+    concurrency:
+      group: terraform-{{env}}
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v6
+        with:
+          role-to-assume: arn:aws:iam::{{accountId}}:role/github-actions-{{env}}
+          aws-region: {{region}}
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_wrapper: false
+
+      - name: Terraform init
+        working-directory: terraform/godd-notes/{{env}}
+        run: terraform init -input=false
+
+      - name: Verify Terraform state is present
+        working-directory: terraform/godd-notes/{{env}}
+        shell: bash
+        run: |
+          set -euo pipefail
+          state_file=$(mktemp)
+          trap 'rm -f "$state_file"' EXIT
+
+          # 初回構築（空 state からの apply）は手動セットアップ手順で行う。
+          # この workflow は既存環境の更新だけを扱い、state 欠落時は fail-closed にする。
+          # A missing/empty state is dangerous for an existing stack: Terraform
+          # would plan already-managed resources as new and may fail or replace
+          # them.  Stop before apply and recover the backend with the documented
+          # `terraform init -migrate-state` procedure instead.
+          if ! terraform state pull >"$state_file"; then
+            echo "::error::Terraform state を取得できません。backend の bucket/key を確認し、移行時は terraform init -migrate-state を使用してください。"
+            exit 1
+          fi
+          if ! jq -e '
+            type == "object" and
+            (.version | type == "number") and
+            (.serial | type == "number") and
+            (.lineage | type == "string" and length > 0) and
+            (.resources | type == "array" and length > 0)
+          ' "$state_file" >/dev/null; then
+            echo "::error::Terraform state が空または不正です。apply を中止しました。バックアップを確認し、terraform init -migrate-state で正しい state を再接続してください。"
+            exit 1
+          fi
+
+      - name: Terraform Apply
+        working-directory: terraform/godd-notes/{{env}}
+        run: terraform apply -input=false -auto-approve -lock-timeout=5m
+
+  deploy-api:
+    needs: [changes, terraform-apply]
+    if: |
+      always() &&
+      github.event_name != 'pull_request' &&
+      needs.changes.outputs.api == 'true' &&
+      (needs.terraform-apply.result == 'success' || needs.terraform-apply.result == 'skipped')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
@@ -55,9 +240,6 @@ jobs:
         id: ecr-login
         uses: aws-actions/amazon-ecr-login@v2
 
-      # ECS タスクは ARM64（Graviton）。x86_64 ランナー上で arm64 イメージを
-      # クロスビルドするため buildx + QEMU を用いる（QEMU 無しだと最初の RUN で
-      # `exec /bin/sh: exec format error` になる）。
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 
@@ -121,8 +303,12 @@ jobs:
             --services $ECS_SERVICE
 
   deploy-app:
-    needs: changes
-    if: needs.changes.outputs.app == 'true'
+    needs: [changes, terraform-apply]
+    if: |
+      always() &&
+      github.event_name != 'pull_request' &&
+      needs.changes.outputs.app == 'true' &&
+      (needs.terraform-apply.result == 'success' || needs.terraform-apply.result == 'skipped')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
@@ -153,9 +339,6 @@ jobs:
         working-directory: notes-app
         run: aws s3 sync dist/ s3://$S3_BUCKET --delete
 
-      # CLOUDFRONT_DISTRIBUTION_ID secret 未登録だと空文字が --distribution-id に渡り
-      # exit 252 でジョブ全体が失敗する（#1097）。未登録時は warning を出してスキップし、
-      # S3 デプロイ自体は成功扱いにする（CDN キャッシュは TTL 失効まで旧コンテンツが残る）。
       - name: Invalidate CloudFront
         run: |
           if [ -z "$CLOUDFRONT_DISTRIBUTION_ID" ]; then

package/templates/notes-docs/001_project/README.md

@@ -2,7 +2,6 @@
 
 > 本ドキュメントは `docs/001_project/README.md` の **テンプレート（プレースホルダー版）** です。
 > `[ ]` で囲まれたプレースホルダーを自プロジェクトの内容に置き換えて利用してください。
-> 書き起こし例として [`ripla-inc/saas-box-manage`](https://github.com/ripla-inc/saas-box-manage) の `saas-box-docs/001_project/` も併せて参照してください。
 
 ---
 
@@ -54,7 +53,6 @@ graph LR
 | RDB | [MySQL / PostgreSQL 等] | [Amazon RDS / Aurora 等] |
 | _(任意)_ LLM/AI 基盤 | [Python / FastAPI + ベクトル DB 等] | [ECS Fargate + EFS 等] |
 
-> 技術スタックの埋め方は [`saas-box-manage` の `saas-box-docs/007_development/stacks.md`](https://github.com/ripla-inc/saas-box-manage/blob/main/saas-box-docs/007_development/stacks.md) を参照してください。
 
 ---
 

package/templates/notes-docs/002_business_flow/README.md

@@ -0,0 +1,19 @@
+# 002_business_flow — ビジネスフロー
+
+> 本ドキュメントは `docs/002_business_flow/README.md` の **テンプレート（プレースホルダー版）** です。
+> `[ ]` で囲まれたプレースホルダーを自プロジェクトの内容に置き換えて利用してください。
+
+本ディレクトリは、プロダクトが対象とする **業務（ビジネス）フロー** を業務単位で整理する場所です。1 業務 = 1 ファイル（`<business_flow_name>.md`、必要に応じて同名の `.drawio`）で管理します。
+
+## ファイル構成
+
+| ファイル | 内容 |
+|---|---|
+| `<business_flow_name>.md` | 特定業務のビジネスフローの解説（登場ロール・手順・分岐・例外） |
+| `<business_flow_name>.drawio` | 同業務のフロー図（GoDD Notes で閲覧・編集可能） |
+
+## ビジネスフロー一覧
+
+| # | 業務名 | ファイル | 概要 |
+|---|---|---|---|
+| 1 | [業務名] | [business_flow_name].md | [3〜5 行で業務の概要] |

package/templates/notes-docs/003_requirements/README.md

@@ -0,0 +1,20 @@
+# 003_requirements — 機能要件
+
+> 本ドキュメントは `docs/003_requirements/README.md` の **テンプレート（プレースホルダー版）** です。
+> `[ ]` で囲まれたプレースホルダーを自プロジェクトの内容に置き換えて利用してください。
+
+本ディレクトリは、**機能要件（Feature 単位の要件定義）** を整理する場所です。画面・機能の一覧は `docs/001_project/pages.csv` / `features.csv` が SSOT で、本ディレクトリはその各機能を詳細化します。
+
+## 構成ルール
+
+| パス | 内容 |
+|---|---|
+| `<Product Name>/<feature_name>.md` | 機能別の要件定義（管理画面・ユーザー向け画面などプロダクトごとにフォルダを分ける） |
+| `spec/` | 仕様 SSOT（API 仕様・インフラ仕様・言語仕様等）。実装と常に同期させる |
+| `questions.csv` | 未回答の質問リスト（`unanswered → answered → spec_reflected` のライフサイクルで管理） |
+
+## requirements 一覧
+
+| # | プロダクト | 機能 | ファイル | ステータス |
+|---|---|---|---|---|
+| 1 | [プロダクト名] | [機能名] | [Product Name]/[feature_name].md | [draft / fixed] |

package/templates/notes-docs/003_requirements/questions.csv

@@ -0,0 +1 @@
+id,status,question,context,answer,owner,created_at,resolved_at,spec_ref,related_job_id,category

package/templates/notes-docs/003_requirements/spec/README.md

@@ -0,0 +1,11 @@
+# spec — 仕様 SSOT
+
+> 本ドキュメントは `docs/003_requirements/spec/README.md` の **テンプレート** です。
+
+本ディレクトリは、プロダクトの **仕様 SSOT（Single Source of Truth）** です。API 仕様・インフラ仕様・言語仕様など、実装の根拠となる仕様書をここに置きます。
+
+## 運用ルール
+
+- 挙動を変更したら、**同じ PR で** 本ディレクトリの該当仕様書を更新する（仕様書の更新漏れは不具合として扱う）
+- 仕様と実装が矛盾したときは、どちらが正か確認してから両方を揃える（推測で実装しない）
+- 1 仕様領域 = 1 ファイルを基本とし、肥大化したら分割する

package/templates/notes-docs/004_pages/README.md

@@ -0,0 +1,22 @@
+# 004_pages — 画面設計
+
+> 本ドキュメントは `docs/004_pages/README.md` の **テンプレート** です。
+
+本ディレクトリは、**画面ごとの画面要件** を URL パス単位で整理する場所です。画面の URL 構造がそのままフォルダ構造になるよう、フロントエンドの `app/` ディレクトリ構成を模したフォルダを配置します。
+
+## 構成ルール
+
+- `app/` 配下に、画面の URL パスに対応するフォルダを作成する（例: `/admin/corporations` → `app/admin/corporations/`）
+- 各フォルダに `requirements.md`（その画面の画面要件）を置く
+- 画面一覧・画面 ID は `docs/001_project/pages.csv` が SSOT。本ディレクトリの各ファイルは画面 ID と対応させる
+
+## 例
+
+```text
+docs/004_pages/
+└── app/
+    ├── admin/
+    │   └── corporations/
+    │       └── requirements.md   # 管理画面: 法人管理の画面要件
+    └── users/
+```

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

@@ -0,0 +1,20 @@
+# 005_architecture — 設計
+
+> 本ドキュメントは `docs/005_architecture/README.md` の **テンプレート** です。
+
+本ディレクトリは、開発をするにあたっての **実際の設計**（インフラ・DB・API・各機能の設計）を整理する場所です。要件（`003_requirements/`）が「何を作るか」を定めるのに対し、ここは「どう作るか」を定めます。
+
+## フォルダ構成
+
+| フォルダ | 内容 |
+|---|---|
+| `stacks/` | 技術スタック（言語・フレームワーク・ライブラリとバージョン） |
+| `api/` | API 設計（Swagger / OpenAPI 等） |
+| `db/` | DB 設計（ER 図・テーブル定義等） |
+| `infra/` | インフラアーキテクチャの設計 |
+| `features/` | 各機能の設計（機能設計書・データフロー・DB 設計） |
+
+## 記述ルール
+
+- 1 機能 = 1 ファイル（`features/<feature_name>.md`）で管理する
+- 実装と設計が乖離したら、設計書側を必ず更新する（設計書は SSOT の一部）