gcp-agile-template
CLAUDE.md0 starsChanged 7 months agoMITView on GitHub
スモークテストで以下を確認済み: - backend は uv 管理(pyproject.toml + uv.lock)。uv sync で 3.12.x の Python と全依存が入る。 - frontend は Svelte 5 + SvelteKit 2 + Tailwind v4 + adapter-static。npm install → npm run check がエラー 0 件で通り、npm run build で frontend/build/ に静的ファイル出力可能。 - backend は GOOGLE_CLOUD_PROJECT / PROJECT_ID 未設定でも起動可能(/health は 200・Firestore 依存エンドポイントは 503)。 - テスト雛形済み:backend pytest(18 件パス:core 4 + module_loader 8 + profile module 6・httpx.AsyncClient ベース)、frontend vitest(6 件パス・@testing-library/svelte + SvelteKit ランタイムモック)。 - モジュールシステム稼働中:modules/profile/ がリファレンス実装、backend/module_loader.py が lifespan で自動ロード、scripts/sync-modules.mjs がフロントを同期、scripts/install_module.py で外部から取り込み可能。 未整備項目: - frontend/static/icon-192.png…
- Reads credentials
- Deletes or force-pushes
- Installs packages
In this repository8 other files it gives its agents.
- daily-standupSkill
- deploy-gcpSkill
- mobile-checkSkill
- plan-architectureSkill
- plan-featureSkill
- plan-sprintSkill
- sprint-planningSkill
- sprint-reviewSkill
The file
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
[PROJECT_NAME] — スマホファースト × GCPファースト
プロジェクト概要
<!-- 一言:何を・誰に・なぜ -->Repository State(重要:未来の Claude へ)
スモークテストで以下を確認済み:
- backend は uv 管理(
pyproject.toml+uv.lock)。uv syncで 3.12.x の Python と全依存が入る。 - frontend は Svelte 5 + SvelteKit 2 + Tailwind v4 + adapter-static。
npm install→npm run checkがエラー 0 件で通り、npm run buildでfrontend/build/に静的ファイル出力可能。 - backend は
GOOGLE_CLOUD_PROJECT/PROJECT_ID未設定でも起動可能(/healthは 200・Firestore 依存エンドポイントは 503)。 - テスト雛形済み:backend
pytest(18 件パス:core 4 + module_loader 8 + profile module 6・httpx.AsyncClient ベース)、frontendvitest(6 件パス・@testing-library/svelte + SvelteKit ランタイムモック)。 - モジュールシステム稼働中:
modules/profile/がリファレンス実装、backend/module_loader.pyが lifespan で自動ロード、scripts/sync-modules.mjsがフロントを同期、scripts/install_module.pyで外部から取り込み可能。
未整備項目:
frontend/static/icon-192.png/icon-512.pngは未配置(manifest.json は参照のみ。実プロジェクトで PNG を配置すること)。MakefileのPROJECT_ID/APP_NAME、本ファイルの「GCPプロジェクト設定」、frontend/.env.example/backend/.env.exampleの値は未設定プレースホルダ。firebaseCLI は別途npm install -g firebase-toolsが必要。- ADR は
docs/adr/ADR-001-template.mdのテンプレートのみ、docs/sprints/backlog.mdも雛形のみ。
モジュールシステム(外部から機能を取り込む)
このリポジトリはフィーチャーモジュール方式で、検証済みの機能スライスを modules/<name>/ に
配置します。1 機能 = backend ルーター + frontend コンポーネント/ルート + テスト が同居します。
ディレクトリ規約
modules/<name>/
├── module.toml # マニフェスト([module].name は必須)
├── README.md
├── backend/
│ ├── __init__.py
│ ├── router.py # 必須: APIRouter を `router` 名でエクスポート
│ ├── models.py # 任意(相対 import 可: from .models import X)
│ └── tests/
│ └── test_*.py # ルートの conftest.py の fixture(client / mock_firestore_db)を共有
└── frontend/
├── lib/ # → frontend/src/lib/modules/<name>/ に同期される
└── routes/ # → frontend/src/routes/<route>/ に同期されるロードの仕組み
- backend:
backend/main.pyの lifespan でmodule_loader.load_modules(app, modules/)がアルファベット順に走査し、router.pyを動的 import →app.include_router(router, prefix=...)。プレフィックス既定値は/api/v1/<name>、module.tomlの[backend].prefixで上書き可。1 つが壊れても他はロードされる。 - frontend:
npm run modules:syncがscripts/sync-modules.mjsを実行し、modules/*/frontend/libをfrontend/src/lib/modules/<name>/に、modules/*/frontend/routes/*をfrontend/src/routes/*にコピー。同期先は.gitignore対象で、各ファイル先頭にAUTO-GENERATEDマーカーが入る。dev/build/check/testの前段で自動実行される。
取り込みコマンド
# ローカルパス
python scripts/install_module.py /path/to/external/module
# Git URL(branch 指定・モノレポの subdir 指定可)
python scripts/install_module.py https://github.com/user/repo.git --ref main --subdir packages/billing
# .zip
python scripts/install_module.py ./module.zip
# 既存上書き
python scripts/install_module.py <source> --forceサンプルモジュール
modules/profile/ がリファレンス実装。/api/v1/profile の GET / PUT を提供し、Pydantic バリデーション + Firestore 更新 + 認証ガード + テスト 6 件を含む。新しいモジュールを書くときはこれをコピー元にする。
仕様書の取り込みシステム(specs/)
外部から仕様書バンドル(ユーザーストーリー・受入条件・ADR・スプリント計画書)を取り込むための仕組み。コードのモジュールシステムと対称的に動作。
バンドル構造
specs/<name>/
├── spec.toml # マニフェスト([spec].name は必須)
├── README.md # バンドルの説明
└── docs/ # プロジェクトの docs/ にミラーされる構造
├── adr/ADR-NNN-*.md
└── sprints/sprint-N/specs/<story>.md役割の分担
specs/<name>/— 取り込み時の凍結アーカイブ(編集しない・再取り込みで上書きされる)docs/...— 実際の作業領域(spec-agent / 人間が編集する)
scripts/install_spec.py は両方に配置する:(1) 元バンドル全体を specs/<name>/ に凍結、(2) docs/** 部分を プロジェクトの docs/** にマージ。
取り込みコマンド
# ローカルパス
python scripts/install_spec.py /path/to/bundle
# Git URL(branch・モノレポ subdir 指定可)
python scripts/install_spec.py https://github.com/po/specs.git --ref main --subdir bundles/onboarding
# .zip
python scripts/install_spec.py ./onboarding-spec.zip
# 既存 docs/ ファイルを上書き
python scripts/install_spec.py <source> --forceコンフリクト方針
- 同一内容なら静かにスキップ(idempotent)
- 内容が異なる既存ファイルがあると exit 2 で警告し、コピーをスキップ
--forceで上書きspecs/<name>/自体は --force なしでも上書きされる(凍結アーカイブの再取り込み)
サンプルバンドル
specs/user-onboarding-mvp/ がリファレンス。Google ログイン仕様 + 表示名編集仕様 + ADR-002 の 3 ファイルが入っており、docs/adr/ADR-002-auth-split.md 等にコピー済み。新規バンドルを作るときの構造の参考にする。
Architecture(複数ファイルを読まないと分からない big picture)
認証フロー(フロント → バック)
frontend/src/lib/firebase/client.ts:signInWithGoogleがブラウザ UA を見て分岐:- スマホ →
signInWithRedirect(ポップアップは iOS Safari で動作不安定なため) - PC →
signInWithPopup - リダイレクト後の結果は
handleRedirectResultで取得。
- スマホ →
frontend/src/lib/stores/auth.ts:initAuth(+layout.svelteのonMountから呼ばれる)がonAuthStateChangedでuserストアを更新し、ID トークンをidTokenストアに保存。55 分ごとにgetIdToken(true)で自動リフレッシュ。frontend/src/lib/firebase/api.ts:authFetchがすべての API 呼び出しの基底。idTokenをAuthorization: Bearer ...で付与し、VITE_API_BASE_URL(Cloud Run URL)に投げる。backend/middleware/auth.py:verify_tokenが FastAPI のDependsで受け、Firebase Admin SDK のverify_id_tokenで検証。Cloud Run では Application Default Credentials を使う(GOOGLE_APPLICATION_CREDENTIALS不要)。backend/main.py:get_profileのように、ハンドラはtoken: dict = Depends(verify_token)を受け取り →require_db()で Firestore クライアント取得(未初期化なら 503)→get_current_user_id(token)→ Firestoreusers/{uid}を read/upsert。
新規エンドポイントを追加するときも必ず Depends(verify_token) を経由させ、Firestore を使うなら require_db() でガードすること。
Svelte 5 規約(重要)
このリポジトリは Svelte 5 構文で書く。Svelte 4 構文は使わない:
- ✅
let foo = $state(0)/let { children } = $props() - ✅
$derived(...)/$effect(() => {...}) - ✅
{@render children()}(旧<slot />) - ✅
onclick={fn}(旧on:click={fn}) - ✅
import { page } from '$app/state'(旧$app/storesの$page)
ポート規約
| 環境 | ポート | 設定箇所 |
ローカル uvicorn --reload | 8000 | Makefile, CLAUDE.md |
| Dockerfile / Cloud Run | 8080 | backend/Dockerfile |
| SvelteKit dev | 5173 | Vite デフォルト(CORS 許可済み) |
main.py の CORS allowlist は PROJECT_ID 環境変数から https://{PROJECT_ID}.web.app / .firebaseapp.com / http://localhost:5173 を許可する。
Firestore 起動パターン
backend/main.py の lifespan は GOOGLE_CLOUD_PROJECT / PROJECT_ID を見て firestore.AsyncClient(project=...) を 1 回だけ初期化する。env 未設定時は db = None のまま起動し、Firestore 依存エンドポイントは require_db() で 503 を返す(/health は 200 のまま)。
スマホ専用レイアウトシェル
frontend/src/routes/+layout.svelte が以下を強制:
max-width: 430px(PC でも中央 430px に固定 = スマホ UI 前提)min-height: 100dvh(dynamic viewport で iOS のアドレスバー伸縮に追従)padding-bottom: calc(64px + env(safe-area-inset-bottom))(ボトムナビ + ノッチ対応)protectedRoutes = ['/home', '/profile', '/settings']に未認証アクセスすると/loginへ強制リダイレクト
新ページを protected にしたい場合は +layout.svelte の配列に追加。
ビルド・デプロイ経路
- frontend:
vite build→@sveltejs/adapter-staticがfrontend/build/に SPA 出力(fallback: 'index.html')→firebase.jsonのpublic: "frontend/build"で Hosting にアップロード。 - backend:
gcloud run deploy --source backend/で Dockerfile(uv ベース)をビルド → Artifact Registry 経由で Cloud Run。
技術スタック
フロントエンド
- Svelte 5 + SvelteKit 2(
adapter-staticで SPA 化) - Tailwind CSS v4(Vite plugin・
src/app.cssで@import "tailwindcss") - Vitest(単体)+ Playwright(E2E / mobile-check)
- デプロイ先:Firebase Hosting(CDN・無料枠)
バックエンド
- Python 3.12 + uv(
pyproject.toml+uv.lock) - FastAPI 0.115(非同期・型安全)
- Cloud Run(コンテナ・ゼロスケール・asia-northeast1)
- Pub/Sub(非同期イベント処理)
データ
- Firestore(NoSQL・リアルタイム・スマホ同期)
- Cloud Storage(ファイル・動画・モデル)
- BigQuery(分析・ML学習データ蓄積)
AI / ML
- Vertex AI(モデル管理・推論)
- MediaPipe(オンデバイスML)
- Cloud Run MCP Server(Claude Codeからデプロイ直結)
DevOps
- Cloud Build(CI/CD)
- Artifact Registry(コンテナ管理)
- Secret Manager(APIキー管理)
GCPプロジェクト設定
PROJECT_ID=
APP_NAME=
REGION=asia-northeast1Makefile・本ファイル・backend/.env・frontend/.env.local の 4 箇所を埋めること。
コマンド集
初期セットアップ(プロジェクト ID 設定後に 1 回)
make setup # gcloud で必要な GCP API を一括有効化
make install # backend (uv sync) + frontend (npm install)make が無い環境(Windows ネイティブ等)では下記の生コマンドを直接叩く。
ローカル開発(ターミナル 2 枚)
# ターミナル 1: バックエンド(:8000)
cd backend && uv run uvicorn main:app --reload --port 8000
# ターミナル 2: フロントエンド(:5173)
cd frontend && npm run devmake が使える環境なら make dev-backend / make dev-frontend。
テスト(TDD 中心の開発フロー)
重要: pytest はプロジェクトルートから実行する(pytest.ini で testpaths = backend/tests modules を集中管理しているため)。backend/.venv/Scripts/pytest.exe を直接呼ぶか、make test-backend を使う。
# バックエンド全件(backend/tests + modules/*/backend/tests を一括収集)
backend/.venv/Scripts/pytest.exe --tb=short
backend/.venv/Scripts/pytest.exe -x --ff # 失敗最優先・即停止(TDD ループ向け)
# 特定モジュールだけ
backend/.venv/Scripts/pytest.exe modules/profile
# 単体テスト指定
backend/.venv/Scripts/pytest.exe modules/profile/backend/tests/test_router.py::test_put_profile_rejects_empty_display_name -v
# Make 経由(POSIX シェル環境)
make test-backend
# フロントエンド単体(Vitest・watch がデフォルト・modules:sync が前段で走る)
cd frontend && npm test # 1 回実行
cd frontend && npm run test:watch # ファイル変更で再実行
# フロントエンド型チェック
cd frontend && npm run check
# モバイルチェック(Playwright・mobile-chrome プロジェクト)
cd frontend && npm run mobile-checkデプロイ
make deploy-backend # gcloud run deploy --source backend/
make deploy-frontend # npm run build → firebase deploy --only hosting
make deploy # test → backend → frontend を順次Claude Code 環境(このリポジトリ固有)
MCP サーバー(.mcp.json)
HTTP 型で 3 つ有効:
- cloud-run — Cloud Run のデプロイ・サービス管理を自然言語で
- bigquery — クエリ・テーブル操作
- firestore — ドキュメント read/write
permissions(.claude/settings.json)
- allow:
gcloud:*,firebase:*,uv:*,uvx:*,pytest:*,npm:*,npx:*,git:* - deny:
gcloud secrets:*(Claude は Secret Manager の値を直接読み書きできない。シークレット登録は人間が手動で行う)、rm -rf /*
フック(クロスプラットフォーム・Python ベース)
PostToolUse(Edit|Write): 編集ファイル名と時刻を.claude/session.logに追記Stop: セッション境界を.claude/session.logに記録
旧 bash 構文($(date +%H:%M) / basename)は Windows で動かなかったため、Python ワンライナーに置換済み。
実験フラグ
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が有効。/sprint-planning で agent team が起動できる前提。
スプリント開発ルール
エージェント構成(.claude/agents/)
- orchestrator : タスク分解・進捗管理・ブロッカー解消(コードは書かない)
- spec-agent : ユーザーストーリー・受入条件の生成
- backend-agent : FastAPI・Cloud Run実装
- mobile-agent : スマホUX・PWA・レスポンシブ実装
- infra-agent : GCPリソース・IaC・デプロイ管理
注: 旧版 CLAUDE.md では architect / test-agent / review-agent も列挙されていたが、現状
.claude/agents/には未配置。必要になったら作成すること。
TDD ルール(必須・最優先)
このプロジェクトは TDD(Red-Green-Refactor)が基本ワークフロー です。
- Red — まず失敗するテストを書く。テストは契約(API シグネチャ・期待される挙動)を定義する。
- Green — そのテストを通す最小限の実装を書く。
- Refactor — テストが緑のまま、実装をきれいにする。
具体ルール:
- 実装コミットの前にテストコミットを置く(
git logで順序が確認できるようにする)。 - バックエンド:
backend/tests/test_*.pyにpytest+httpx.AsyncClientでテストを書く。backend/tests/conftest.pyのclient/override_verify_tokenフィクスチャを再利用する。 - フロントエンド:
*.test.tsをテスト対象と同じディレクトリに同居させる。vitest+@testing-library/svelte。SvelteKit ランタイム依存($app/stateなど)はfrontend/vitest.setup.tsで既にモック済み。 - E2E &スマホチェックは
cd frontend && npm run mobile-check(Playwright)。 /plan-featureの計画書では「テスト計画」を最優先項目として書く。実装ファイルを変更するより前に、書くべきテストを列挙する。- 例外:純粋なドキュメント・設定・型のリネームのみのコミットはテスト不要(PR 説明で「ノーテストで OK な理由」を明記)。
スマホファーストルール(必須)
- モバイル幅(375px)で先に実装・確認
- タッチターゲット最小44×44px
- LCP 2.5秒以内・CLS 0.1以下
- オフライン対応(Service Worker)
- /mobile-check を実装ごとに実行
GCPファーストルール(必須)
- ローカルDBは使わない → Firestore / BigQuery
- 環境変数は Secret Manager から取得(
gcloud secrets:*は deny されているので登録は人間に依頼) - ログは Cloud Logging に統一
- コスト確認:/deploy-gcp 実行前に見積もり表示
スプリントサイクル(1週間)
計画フェーズ(/plan モード:コードを書かない・人間承認必須)
/plan-architecture → 大きな設計変更時のみ。ADR作成。人間承認。
↓
/plan-sprint → バックログ全体計画・Wave設計・コスト見積もり。人間承認。
↓
/plan-feature × N → ストーリーごとの詳細計画・影響ファイル・API契約。人間承認。実装フェーズ(承認後に開始)
/sprint-planning → エージェント起動・worktree作成
実装(Wave並列) → mobile / backend / infra が独立作業
/daily-standup → 毎日の進捗確認・スマホ品質・コスト確認
/mobile-check → LCP・CLS・PWA・375px確認
/deploy-gcp → Cloud Run・Firebase Hosting デプロイ振り返りフェーズ
/sprint-review → DoD確認・CLAUDE.md更新・レトロ記録/plan モードの原則
- 計画フェーズではコードを一行も書かない
- 計画書を人間が承認してから実装開始
- バグ修正・軽微な変更は /plan-feature を省略可
- 計画変更は計画書を先に修正してから実装に反映
Definition of Done
- /plan-feature の計画書が承認済み(テスト計画を含む)
- テストを実装より先に書いた(コミット順序で確認可能)
- 新機能には新テストが追加されている(実装のみのコミットは差し戻し)
- backend
uv run pytest/ frontendnpm testが全件グリーン - フロントエンド変更は
npm run checkで型エラー 0 - /mobile-check 通過(375px・LCP・タッチ・PWA)
- review-agent 承認
- Cloud Run・Firebase Hosting にデプロイ確認
- 受入条件すべて満たす
- CLAUDE.md に知見を追記
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

