diff --git a/.claude/AGENT.md b/.claude/AGENT.md
deleted file mode 100644
index ab8dc39b..00000000
--- a/.claude/AGENT.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# DevForge - エージェント行動ガイドライン
-
-## CLAUDE.md との責務分担
-
-| ファイル | 責務 |
-|---|---|
-| `CLAUDE.md` | **何を・どう書くか** — コーディング規約・CI確認・命名・ADR |
-| `AGENT.md` | **どう動くか** — 自律判断の範囲・確認基準・セキュリティ判断 |
-
----
-
-## 自律的に行ってよいこと（確認不要）
-
-- ファイルの読み取り・編集・新規作成
-- ruff / lint / テストの実行（読み取り専用の CI チェック）
-- `git status` / `git diff` / `git log` などの参照系 git コマンド
-- `.gitignore` や `.vscode/settings.json` などの設定ファイルの軽微な修正
-
-## 確認が必要なこと（実行前に必ずユーザーに確認する）
-
-### Git 操作
-- `git commit` — コミットメッセージと対象ファイルを提示してから実行
-- `git push` — 明示的に依頼された場合のみ
-- `git reset --hard` / `git checkout -- .` などの破壊的操作
-- force push（原則禁止。ユーザーが明示的に求めた場合のみ）
-
-### ブランチ操作
-- 新しいブランチの作成（ベースブランチは必ず `origin/dev`）
-- ブランチの削除
-
-### GitHub 操作
-- Issue の作成・編集・クローズ
-- PR の作成・マージ・クローズ
-- コメントの投稿
-
-### インフラ・DB
-- Alembic マイグレーションの実行（`alembic upgrade`）
-- DB データの削除・変更を伴うスクリプトの実行
-- Terraform の `apply` / `destroy`
-
----
-
-## セキュリティに関する判断基準
-
-- `.env` / `.env.*` ファイルは読まない・編集しない
-- 秘密鍵・トークン・パスワードをコードやコメントに埋め込まない
-- 環境変数の値をログや出力に含めない
-- セキュリティ上のリスクを検知した場合は実装前にユーザーに報告する
-
----
-
-## スコープ外の判断
-
-以下は自律的に判断せず、ユーザーに確認する:
-
-- 技術選定・アーキテクチャの変更（ADR が必要な判断）
-- 既存 API の破壊的変更
-- 依存パッケージの追加・削除・バージョン変更
-- CI/CD パイプラインの変更
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index 889ecf7b..eae00197 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -1,46 +1,101 @@
 # DevForge - Claude Code ガイドライン
 
-## コーディング規約
+## このファイルの読み方
 
-### 共通ルール
-- **コメント・ドキュメント**: コード内のコメント、docstring、JSDoc はすべて**日本語**で記述すること。
-- **エラーメッセージ**: HTTPException の `detail` 等、ユーザーに返すエラーメッセージはすべて**日本語**で記述すること。
-- **例外の握りつぶし禁止**: `except SomeException: pass` は禁止。最低でも `logger.debug/warning/error` でログを出すこと。補助的な処理（通知など）で例外を抑制する場合も `logger.warning` でログを残すこと。
+- 本ファイルは全体ルールの索引。AI エージェント（Claude Code 含む）が最初に読むべき内容を集約している。
+- 領域固有ルール（backend / frontend / infra）は `.claude/rules/<scope>/*.md` に分割済み。対象パスを編集する際に自動でロードされる。重複は避け、詳細は各 rule ファイルへ寄せる。
 
-### Python (backend)
-- ruff に準拠すること
-- PEP8を守るな、PEP8を理解した上で抽象化しろ
-- ruff の設定は `backend/pyproject.toml` に定義済み
-- コード変更後は `make lint-backend` を実行し、違反がないことを確認すること
-- 未使用の import を残さないこと（F401）
+## AI エージェント実行方法
 
-### TypeScript/React (frontend)
-- ESLint / Prettier の設定に従うこと
-- `cd frontend && npm run lint` でリントチェック
+**原則: 開発ツールはすべて Nix devshell 経由で実行する。** ホスト側に Python / Node / ruff / tofu / WeasyPrint 用ネイティブライブラリは入っていない前提。
+
+### 第一選択: `make` ターゲット
+
+Makefile は `nix develop --command bash -c "..."` でラップ済み。AI は基本これを使う。
+
+| 用途 | コマンド |
+|---|---|
+| CI 相当一括 | `make ci` （= `lint + test + build-frontend`） |
+| Backend lint | `make lint-backend` |
+| Backend test | `make test-backend` |
+| Frontend lint | `make lint-frontend` |
+| Frontend test | `make test-frontend` |
+| Lint 自動修正 | `make lint-fix` |
+| マイグレーション | `make migrate` / `make migrate-create MSG="..."` |
+| インフラ validate | `make infra-validate` |
+
+### 第二選択: `nix develop --command` ラッパー
+
+make に無い操作（特定ファイルだけ ruff したい等）の場合のみ使う:
+
+```bash
+nix develop --command bash -c "cd backend && .venv/bin/python -m ruff check app/services/tasks/handlers/blog_summarize.py"
+nix develop --command bash -c "cd backend && .venv/bin/python -m pytest tests/test_worker_extended.py -q"
+nix develop --command bash -c "cd frontend && npm run test:e2e"
+```
+
+### 禁止: 生シェルでの直接実行
+
+`cd backend && .venv/bin/python -m pytest ...` を nix の外で叩くと、`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` が未設定で WeasyPrint のインポートが `OSError: cannot load library 'libgobject-2.0-0'` で落ちる。AI は nix wrap を必ず通す。
+
+### Sandbox と nix の競合（重要）
+
+Claude Code の sandbox は `~/.cache/nix/fetcher-locks/*.lock` への書き込みを拒否する。`make lint-backend` / `make test-backend` を sandbox 有効で実行すると次のエラーになる:
+
+```
+error: opening lock file "~/.cache/nix/fetcher-locks/...lock": Operation not permitted
+```
+
+この場合は sandbox を無効化して再実行する（Bash ツールの `dangerouslyDisableSandbox: true`）。nix の lock 書き込みは安全な操作なので例外として許容してよい。
+
+## コーディング規約（共通）
+
+- **コメント・ドキュメント**: コード内コメント・docstring・JSDoc はすべて**日本語**で記述する。
+- **エラーメッセージ**: HTTPException の `detail` 等、ユーザーに返すメッセージはすべて**日本語**。
+- **例外の握りつぶし禁止**: `except SomeException: pass` は禁止。最低でも `logger.debug/warning/error` でログを残す。補助処理（通知生成など）で抑制する場合も `logger.warning` でログを出すこと。
+- **過剰な抽象化を避ける**: PEP8 を守るな、PEP8 を理解した上で抽象化しろ。
+
+言語別の詳細ルールは `.claude/rules/{backend,frontend,infra}/` を参照。
 
 ## CI 確認ルール
 
-アプリケーションの改修を行った場合、以下のコマンドで CI 相当のチェックをローカルで実行し、パスすることを確認すること:
+アプリケーションの改修後は、ローカルで CI 相当を pass させてから完了報告する。
 
 ```bash
-# backend（nix develop 経由でシステムライブラリを解決する。Makefile が自動でラップする）
+# 一括（最速・推奨）
+make ci
+
+# 個別
 make lint-backend && make test-backend
+make lint-frontend && make test-frontend && make build-frontend
+```
 
-# frontend（ユニット・ビルド）
-cd frontend && npm run lint && npm test && npm run build
+### E2E テストのトリガー
 
-# frontend E2E（新機能・ページ追加・ルーティング変更・認証フロー変更を行った場合は必須）
-cd frontend && npm run test:e2e
-```
+以下のいずれかに該当する変更を行った場合、E2E を必ず実行する:
 
-**E2E テスト実行のトリガー**: 以下のいずれかに該当する変更を行った場合、必ず E2E テストを実行すること:
 - 新しいページまたはルートの追加
 - 認証・ナビゲーション・レイアウトの変更
 - 通知ベルなどサイドバーコンポーネントの変更
 - バックエンド API の追加・変更で、フロントエンドの UI フローに影響するもの
 
+```bash
+nix develop --command bash -c "cd frontend && npm run test:e2e"
+```
+
 CI 定義: `.github/workflows/ci.yml`
 
+## 失敗から学んだ知見
+
+過去の手戻り・障害から導いた再発防止ルール。
+
+- **テストで DB をモックしない**: 統合テストは実 DB（テスト用 SQLite セッション）に当てる。モック/本番乖離でマイグレーション失敗を見落とした実績がある。
+- **新規ブランチは `origin/dev` 起点で切る**: `main` 起点だと不要差分が大量に乗る。
+- **契約変更時は既存テストの assert を必ず見直す**: 戻り値・例外仕様を変える時、旧契約を固定化したテスト（例: `test_no_cache_returns_early` のような silent-return アサーション）が残ると修正の意図が後退する。テスト名と本体の両方を更新する。
+- **`IntegrityError` 後の再 SELECT は `None` を判定する**: ユニーク制約衝突後の再取得で他セッションが先に commit したケースを想定し、`None` ならば明示的に `RuntimeError` を上げる。戻り値型が non-Optional な関数で握りつぶさないこと。
+- **タスクハンドラの「黙って return」は禁止**: 失敗パスでは `NonRetryableError` / `RetryableError` を `raise` し、worker に `dead_letter` / `retrying` 遷移と通知発行を任せる。早期 return は呼び出し側に completed として観測される。
+- **lint 失敗時は当該ファイルだけ確認**: `make lint-backend` が他ファイルの I001 等で落ちる場合、自分の変更分は `nix develop --command bash -c "cd backend && .venv/bin/python -m ruff check <touched_file>"` で個別検証してから進める（既存違反を巻き込まない）。
+
 ## 命名規約
 
 | 種別 | 名前 |
@@ -66,6 +121,7 @@ INTERNAL_SECRET      # Cloudflare Pages → Cloud Run 間の秘密ヘッダー
 ```
 
 ### オプション
+
 ```
 GITHUB_CLIENT_ID     # GitHub OAuth Client ID
 GITHUB_CLIENT_SECRET # GitHub OAuth Client Secret
@@ -76,17 +132,11 @@ VERTEX_LOCATION      # 例: asia-northeast1
 VERTEX_MODEL         # 例: gemini-2.5-flash-lite
 ```
 
-## スコープ別ルール
-
-バックエンド・フロントエンド・インフラ固有のルール（アーキテクチャ、DB設計、認証、LLM統合等）は `.claude/rules/` に分割済み。対象パスのファイルを編集する際に自動でロードされる。
-
 ## ADR（Architecture Decision Record）
 
-技術選定・アーキテクチャ判断を行う際は必ず `docs/adr/` を確認し、
-既存の判断と矛盾しない実装を行うこと。
+技術選定・アーキテクチャ判断を行う際は必ず `docs/adr/` を確認し、既存の判断と矛盾しない実装を行うこと。
 
-新たに重要な技術判断を行う場合は `CONTRIBUTING.md` の ADR 運用ルールに従い、
-ADR を作成してから実装を開始すること。
+新たに重要な技術判断を行う場合は `CONTRIBUTING.md` の ADR 運用ルールに従い、ADR を作成してから実装を開始する。
 
 - ADR 一覧: `docs/adr/`
 - テンプレート: `docs/adr/0000-template.md`
diff --git a/.claude/rules/backend/architecture.md b/.claude/rules/backend/architecture.md
index 464ccecb..6aa54e25 100644
--- a/.claude/rules/backend/architecture.md
+++ b/.claude/rules/backend/architecture.md
@@ -7,47 +7,109 @@ paths:
 
 ```
 backend/app/
-├── main.py              # FastAPI アプリ（lifespan で DB bootstrap）
+├── main.py              # FastAPI アプリ（lifespan で DB bootstrap・鍵検証）
+├── messages.json        # ユーザー向けメッセージ・通知文言の定義
 ├── core/                # 設定・メッセージ・認証・暗号化などの横断基盤
 │   ├── settings.py
 │   ├── messages.py
 │   ├── logging_utils.py
 │   ├── date_utils.py
 │   ├── encryption.py
+│   ├── errors.py        # ErrorCode / raise_app_error
+│   ├── context.py       # リクエスト相関 ID 等のコンテキスト
+│   ├── metrics.py
+│   ├── redis_client.py
 │   └── security/
-│       ├── auth.py
+│       ├── auth.py      # JWT（RS256）発行・検証
 │       ├── csrf.py
 │       └── dependencies.py
-├── db/                  # DB接続・bootstrap・backup・seed・migration 補助
+├── middleware/
+│   └── request_id.py    # リクエスト ID 付与
+├── db/                  # DB 接続・bootstrap・migration 補助
 │   ├── database.py
 │   ├── bootstrap.py
-│   ├── backup.py
 │   ├── migrations.py
 │   ├── seed.py
-│   └── sqlite_backup.py
-├── routers/             # エンドポイント（auth, basic_info, resumes, rirekisho, blog, intelligence, admin, health, master_data, notifications）
+│   └── seeds/
+├── routers/             # FastAPI エンドポイント
+│   ├── auth/            # 認証関連（endpoints, github_auth, oauth_flow, token_manager）
+│   ├── blog.py
+│   ├── career_analysis.py
+│   ├── download_utils.py
+│   ├── health.py
+│   ├── intelligence.py
+│   ├── internal.py      # Cloud Tasks → backend 内部 API
+│   ├── master_data.py
+│   ├── notifications.py
+│   └── resumes.py
 ├── models/              # SQLAlchemy 2.0 宣言的マッピング
+│   ├── user.py / blog.py / cache.py / career_analysis.py
+│   ├── master_data.py / notification.py / resume.py
 ├── schemas/             # Pydantic リクエスト/レスポンススキーマ
-├── repositories/        # データアクセス層（UserRepository, NotificationRepository 等）
+│   ├── auth.py / blog.py / career_analysis.py / intelligence.py
+│   ├── master_data.py / resume.py / shared.py
+├── repositories/        # データアクセス層
+│   ├── base.py / user.py / blog.py / career_analysis.py
+│   ├── master_data.py / notification.py / resume.py
 ├── services/
 │   ├── blog/                    # ブログ収集・技術記事判定・スコア算出
+│   │   ├── account_service.py
 │   │   ├── collector.py
 │   │   ├── scorer.py
+│   │   ├── sync_service.py
 │   │   └── tech_keywords.json
-│   ├── intelligence/           # GitHub 分析パイプラインと LLM 連携
+│   ├── career_analysis/         # キャリア分析（プロンプト組み立て・テックスタックマージ）
+│   │   ├── builder.py
+│   │   ├── prompt_builder.py
+│   │   └── tech_stack_merger.py
+│   ├── intelligence/            # GitHub 分析パイプラインと LLM 連携
 │   │   ├── pipeline.py
 │   │   ├── github_collector.py
+│   │   ├── github_analysis_service.py
+│   │   ├── github/              # GitHub API クライアント・リポジトリ解析
+│   │   │   ├── api_client.py
+│   │   │   └── repo_analyzer.py
 │   │   ├── llm_summarizer.py
+│   │   ├── llm_advice_service.py
 │   │   ├── response_mapper.py
 │   │   ├── position_scorer.py
-│   │   ├── skill_*.py
-│   │   └── llm/
+│   │   ├── position_weights.json
+│   │   ├── skill_extractor.py
+│   │   ├── skill_taxonomy/      # スキル分類（言語・トピック・所有権マップ）
+│   │   └── llm/                 # LLM クライアント実装
 │   │       ├── base.py
 │   │       ├── factory.py
 │   │       ├── ollama_client.py
 │   │       └── vertex_client.py
+│   ├── llm/                     # LLM 入出力サニタイザ等（intelligence/llm とは別）
+│   │   └── sanitizer.py
+│   ├── tasks/                   # 非同期タスク基盤（Cloud Tasks / ローカル）
+│   │   ├── base.py              # TaskType 定義
+│   │   ├── exceptions.py        # RetryableError / NonRetryableError
+│   │   ├── worker.py            # execute_task（状態遷移・通知）
+│   │   ├── dispatch_service.py
+│   │   ├── factory.py
+│   │   ├── cloud_tasks.py       # Cloud Tasks エンキュー
+│   │   ├── local.py             # BackgroundTasks 直接実行
+│   │   └── handlers/            # タスク種別ごとのハンドラ
+│   │       ├── base.py          # TaskHandler 抽象基底クラス
+│   │       ├── blog_summarize.py
+│   │       ├── career_analysis.py
+│   │       └── github_analysis.py
 │   ├── markdown/                # Markdown テンプレート生成
 │   ├── pdf/                     # WeasyPrint による PDF 生成
+│   ├── progress_service.py      # 進捗状態管理
 │   └── shared/                  # ドメイン横断の service util
 │       └── sort_utils.py
+├── prompts/             # LLM プロンプトテンプレート
+├── fonts/               # PDF 生成用フォント
+└── utils/
+    └── prompt_loader.py # プロンプトファイルローダ
 ```
+
+## 主要モジュールのポイント
+
+- **routers/auth/**: パッケージ化されており、`endpoints` / `github_auth` / `oauth_flow` / `token_manager` に責務分割
+- **services/tasks/**: Cloud Tasks（本番）と BackgroundTasks（ローカル）を共通の `execute_task` でディスパッチ。状態遷移（`processing` / `completed` / `dead_letter` / `retrying`）は worker が担う
+- **services/intelligence/**: GitHub 分析 → LLM 要約パイプライン。Ollama / Vertex AI を `LLMClient` 抽象で切替
+- **services/llm/ と services/intelligence/llm/**: 別物。前者は入出力サニタイザ等の横断 util、後者は LLM プロバイダクライアントの実装
diff --git a/.claude/rules/backend/auth-security.md b/.claude/rules/backend/auth-security.md
index 22721959..540dac8b 100644
--- a/.claude/rules/backend/auth-security.md
+++ b/.claude/rules/backend/auth-security.md
@@ -7,19 +7,23 @@ paths:
 
 ## 認証
 
-- JWT（`python-jose`）+ bcrypt（`passlib`）、Cookie に 8 時間有効のトークンを格納
-- **`bcrypt==3.2.2` に固定**（passlib 1.7.4 は bcrypt 4.x と非互換）
-- GitHub OAuth ログインに対応（`GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` の設定が必要）
+- **認証方式**: GitHub OAuth のみ。パスワード認証は実装していない（`User.hashed_password` は nullable のまま、OAuth 専用設計）
+- **JWT**: `python-jose[cryptography]`、RS256 署名（`JWT_PRIVATE_KEY` / `JWT_PUBLIC_KEY`）
+- **トークン有効期間**:
+  - アクセストークン: 15 分（Cookie 名 `access_token`）
+  - リフレッシュトークン: 7 日（Cookie 名 `refresh_token`）
+- 起動時に `validate_jwt_key_pair()` で秘密鍵と公開鍵の整合性を検証する
 - GitHub OAuth の `state` は **backend 側 Cookie で検証**する。frontend だけで検証しないこと
-- 認証Cookie属性は `COOKIE_SECURE` / `COOKIE_SAMESITE` で制御する
+- 認証 Cookie 属性は `COOKIE_SECURE` / `COOKIE_SAMESITE` で制御する
 
 ## 暗号化
 
-- 履歴書（Rirekisho）の個人情報フィールド（email / phone / postal_code / address）は `encryption.py` で暗号化保存
-- `FIELD_ENCRYPTION_KEY` 環境変数（Fernet）
+- 履歴書（Rirekisho）の個人情報フィールド（email / phone / postal_code / address）は `app/core/encryption.py` で暗号化保存
+- 鍵は `FIELD_ENCRYPTION_KEY` 環境変数（Fernet）
 
 ## セキュリティ
 
-- 外部API呼び出しや LLM 実行のような**高コスト endpoint**には rate limit を付けること（slowapi）
-- OAuth 開始URLは backend で発行し、許可された `CORS_ORIGINS` のみをリダイレクト先に使うこと
-- cookie 認証を使う変更では `Secure` / `SameSite` / CORS の整合を必ず確認すること
+- 外部 API 呼び出しや LLM 実行のような**高コスト endpoint**には rate limit を付けること（`slowapi`）
+- OAuth 開始 URL は backend で発行し、許可された `CORS_ORIGINS` のみをリダイレクト先に使うこと
+- Cookie 認証を使う変更では `Secure` / `SameSite` / CORS の整合を必ず確認すること
+- Cloudflare Pages → Cloud Run 間は `INTERNAL_SECRET` ヘッダで認証する（local 環境では省略可）
diff --git a/.claude/rules/backend/python.md b/.claude/rules/backend/python.md
index 93aeb31f..aa98b8da 100644
--- a/.claude/rules/backend/python.md
+++ b/.claude/rules/backend/python.md
@@ -7,7 +7,8 @@ paths:
 
 - ruff に準拠すること（設定: `backend/pyproject.toml`）
 - PEP8を守るな、PEP8を理解した上で抽象化しろ
-- コード変更後は `cd backend && .venv/bin/python -m ruff check app tests alembic_migrations` を実行し、違反がないことを確認すること
+- コード変更後は `make lint-backend` を実行し、違反がないことを確認すること（Nix devshell 経由で ruff が解決される）
+- 特定ファイルだけ検証したい場合は `nix develop --command bash -c "cd backend && .venv/bin/python -m ruff check <path>"` を使う。生シェルで `.venv/bin/python` を直接叩くのは禁止（WeasyPrint の動的ライブラリが解決できず import に失敗するため）
 - 未使用の import を残さないこと（F401）
 
 ## 例外処理の必須ルール
@@ -30,5 +31,5 @@ paths:
 
 ## システムパッケージと Dockerfile
 
-- Pythonライブラリがシステムパッケージ（C ライブラリ等）に依存する場合、`backend/Dockerfile` の `apt-get install` にも該当パッケージを追加すること
-- ローカルで `brew install` 等を行った場合は、必ず Dockerfile 側にも対応する Debian パッケージを追加し、Cloud Run デプロイに影響がないことを確認すること
+- Pythonライブラリがシステムパッケージ（C ライブラリ等）に依存する場合、ローカル環境（`flake.nix` の `devShells.default.packages`）と本番イメージ（`backend/Dockerfile` の `apt-get install`）の両方に追加すること
+- `flake.nix` だけ更新して Dockerfile を忘れると Cloud Run デプロイで import エラーになる
diff --git a/.claude/rules/backend/test.md b/.claude/rules/backend/test.md
new file mode 100644
index 00000000..eaea6e06
--- /dev/null
+++ b/.claude/rules/backend/test.md
@@ -0,0 +1,48 @@
+---
+paths:
+  - backend/**
+---
+
+# Backend テスト方針
+
+## いつテストを書く・回すか（トリガー）
+
+以下のいずれかに該当する変更を行った場合、テスト追加・更新と実行が必須:
+
+- **新規エンドポイント追加**: 必ず統合テスト（`tests/test_<router>.py`）を追加し、正常系・認可エラー・バリデーションエラー・404 を最低限カバーする
+- **既存エンドポイントの契約変更**: ステータスコード / レスポンス body / 副作用が変わる場合、既存テストの assert を見直す（旧契約を固定化したテストが残ると意図が後退する）
+- **リポジトリ層・サービス層のロジック変更**: 該当ユニットテスト（`tests/test_<module>.py` / `tests/services/`）を更新
+- **タスクハンドラの追加・変更**: `tests/test_worker_extended.py` または `tests/test_worker_timeout.py` に状態遷移（`processing` → `completed` / `dead_letter` / `retrying`）のテストを追加
+- **マイグレーション追加**: 実 DB に対する upgrade/downgrade が通ることを `make test-backend` で確認
+- **暗号化・認証関連**: `tests/test_auth.py` / `tests/test_encryption.py` / `tests/test_oauth_flow.py` を必ず回す
+
+## 実行コマンド
+
+```bash
+make test-backend                    # 全テスト
+```
+
+特定ファイルだけ回す場合:
+```bash
+nix develop --command bash -c "cd backend && .venv/bin/python -m pytest tests/test_worker_extended.py -q"
+```
+
+## OK 基準（達成条件）
+
+以下をすべて満たして初めて「テスト OK」と判定する:
+
+1. **全テスト pass**: `make test-backend` が exit 0
+2. **新規・変更コードに対応するテストが存在する**:
+   - 新規エンドポイント → ハッピーパス + 認可失敗 + 不正入力（最低 3 ケース）
+   - 新規サービス関数 → 主要分岐ごとに 1 ケース
+   - タスクハンドラ → 成功 / `NonRetryableError` / `RetryableError` の 3 パス
+3. **失敗パスを明示的に検証している**: 例外を `pytest.raises(ExpectedError)` で必ず assert する。silent return を許容するテスト（過去の `test_no_cache_returns_early` のようなもの）は書かない
+4. **モックは最小限**: DB はモックしない（実 SQLite セッションを使う）。外部サービス（GitHub API / LLM / Cloud Tasks / Redis）はモックする
+5. **lint が pass**: `make lint-backend` も同時に通ること
+
+## アンチパターン
+
+- `assert result is not None` だけで満足する（中身を検証していない）
+- `try / except Exception: pass` をテストコード内で使う（失敗を隠す）
+- `time.sleep` での同期待ち（フレーキーになる。`AsyncMock` / `monkeypatch` を使う）
+- 過剰モック: SQLAlchemy セッション全体をモックする等。実 DB セッションを使うこと
diff --git a/.claude/rules/frontend/architecture.md b/.claude/rules/frontend/architecture.md
index 7e44b692..113d09e0 100644
--- a/.claude/rules/frontend/architecture.md
+++ b/.claude/rules/frontend/architecture.md
@@ -7,31 +7,66 @@ paths:
 
 ```
 frontend/src/
+├── main.tsx              # BrowserRouter + Redux Provider ラップ
+├── App.tsx               # 認証ステート管理 + <AppRoutes />
+├── App.module.css
+├── styles.css / styles/  # グローバルスタイル
 ├── router/
-│   ├── routes.tsx       # 全ルート定義（パス↔ページ対応表）
-│   └── guards.tsx       # PrivateRoute / PublicRoute（Outlet パターン）
-├── pages/               # ルートのエントリーポイント（薄いラッパー）
+│   ├── routes.tsx        # 全ルート定義（パス↔ページ対応表）
+│   ├── guards.tsx        # PrivateRoute / PublicRoute（Outlet パターン）
+│   └── index.ts
+├── pages/                # ルートのエントリーポイント（薄いラッパー）
+│   ├── LoginPage.tsx / GitHubCallbackPage.tsx
+│   ├── CareerPage.tsx / CareerAnalysisPage.tsx
+│   ├── BlogPage.tsx / GitHubIntelligencePage.tsx
+│   └── NotFoundPage.tsx
 ├── components/
 │   ├── AuthenticatedLayout.tsx  # サイドバー + <Outlet />（フッターに NotificationBell を配置）
 │   ├── LoadingOverlay.tsx       # 共通ローディング UI（position:fixed; z-index:100 でビューポート全体を覆う）
 │   ├── NotificationBell.tsx     # 通知ベル（未読バッジ・ドロップダウンパネル）
-│   ├── NotificationBell.module.css
-│   ├── forms/           # BasicInfoForm, CareerResumeForm, ResumeForm
-│   ├── analysis/        # GitHubAnalysisPage, LanguageBar
-│   ├── auth/            # LoginForm, RegisterForm
-│   └── blog/            # BlogPage
+│   ├── ConfirmDialog.tsx        # 確認モーダル
+│   ├── ErrorBoundary.tsx        # 例外境界
+│   ├── TaskProgressStepper.tsx  # 非同期タスク進捗ステッパー
+│   ├── UserMenu.tsx
+│   ├── forms/                   # BasicInfoForm, CareerResumeForm, ResumeForm 等
+│   ├── analysis/                # GitHubAnalysisPage, LanguageBar 等
+│   ├── career-analysis/         # CareerAnalysisPage + 結果表示
+│   ├── auth/                    # LoginForm, RegisterForm
+│   ├── blog/                    # BlogPage
+│   ├── icons/                   # アイコンコンポーネント（Bell, Eye, Qiita, Zenn 等）
+│   └── ui/                      # 汎用 UI（ErrorToast, InlineSpinner, Skeleton）
 ├── hooks/
-│   ├── useDocumentForm.ts    # フォーム CRUD の共通フック（loading / saving / error 管理）
-│   ├── useMasterData.ts      # マスタデータのモジュールレベルキャッシュ
-│   ├── useNotifications.ts   # 通知ベル用フック（30秒ポーリング・パネル開閉・既読処理）
-│   └── usePdfActions.ts      # PDF ダウンロード/プレビュー
+│   ├── useDocumentForm.ts       # フォーム CRUD の共通フック（loading / saving / error 管理）
+│   ├── useMasterData.ts         # マスタデータのモジュールレベルキャッシュ
+│   ├── useNotifications.ts      # 通知ベル用フック（30秒ポーリング・パネル開閉・既読処理）
+│   ├── usePdfActions.ts         # PDF ダウンロード/プレビュー
+│   ├── useTaskPolling.ts        # 非同期タスクの進捗ポーリング
+│   ├── useBlogAccountManager.ts / useBlogSummaryPolling.ts
+│   ├── useCareerAnalysisPage.ts / useCareerExperienceMutators.ts
+│   ├── usePhotoUpload.ts / useProjectModalState.ts
+│   ├── useTheme.ts
+│   └── analysis/                # useAsyncAnalysisPage（非同期分析共通）
 ├── api/
-│   ├── client.ts        # fetch ラッパー（Cookie 認証、401 ハンドリング）
-│   └── *.ts             # ドメイン別 API モジュール
-├── App.tsx              # 認証ステート管理 + <AppRoutes /> 呼び出し
-└── main.tsx             # BrowserRouter ラップ
+│   ├── client.ts                # fetch ラッパー（Cookie 認証、401 ハンドリング）
+│   └── *.ts                     # ドメイン別 API モジュール（auth, blog, resumes, career-analysis, intelligence, master-data, notifications, download, ai-resume）
+├── store/                       # Redux Toolkit + redux-persist
+│   ├── index.ts                 # store 構成
+│   ├── persistConfig.ts
+│   └── formCacheSlice.ts        # フォームキャッシュ
+├── utils/
+│   ├── appError.ts
+│   └── errorId.ts
+├── constants/ + constants.ts    # 定数定義
+├── types.ts                     # 共通型
+├── formTypes.ts / formMappers.ts / payloadBuilders.ts  # フォーム入出力変換
+├── test/ + test-setup.ts        # vitest セットアップ
+└── styles/
 ```
 
-**ルーティング**: react-router-dom v7。ガードは Outlet パターン（レイアウトルート）で実装。`/login`, `/signin` は PublicRoute、他は PrivateRoute でガード。
+**ルーティング**: react-router-dom v7。ガードは Outlet パターン（レイアウトルート）で実装。`/login` 系は PublicRoute、他は PrivateRoute でガード。
 
 **フォームパターン**: `useDocumentForm` フックが load/create/update/loading/saving を一元管理。各フォームはこのフックを使い、`LoadingOverlay` でデータ取得中の操作をブロックする。
+
+**状態管理**: Redux Toolkit + redux-persist。`store/formCacheSlice` でフォームの一時保持を行う。サーバ状態は各 API モジュール経由で取得し、コンポーネントローカルもしくはフックでキャッシュする方針。
+
+**非同期タスクの進捗**: `useTaskPolling` / `useAsyncAnalysisPage` でバックエンドの `dead_letter` / `processing` / `completed` 状態をポーリングし、`TaskProgressStepper` で可視化する。
diff --git a/.claude/rules/frontend/test.md b/.claude/rules/frontend/test.md
new file mode 100644
index 00000000..aa9bcdd8
--- /dev/null
+++ b/.claude/rules/frontend/test.md
@@ -0,0 +1,63 @@
+---
+paths:
+  - frontend/**
+---
+
+# Frontend テスト方針
+
+## いつテストを書く・回すか（トリガー）
+
+### ユニット / コンポーネントテスト（vitest + node:test）
+
+- **新規フック追加**: 必ず `*.test.ts` を作成（loading / success / error の 3 パス最低限）
+- **既存フックの契約変更**: 戻り値・副作用が変わる場合、既存 `*.test.ts` の assert を見直す
+- **payloadBuilders / formMappers の変更**: `payloadBuilders.test.ts` を更新（node:test 経由）
+- **api/client.ts の変更**: `api/client.test.ts` を更新（401 リダイレクト、Cookie 認証の挙動）
+- **コンポーネント追加**: ロジックを含むものはテストを追加。表示のみのものは省略可
+
+### E2E テスト（Playwright）
+
+以下のいずれかに該当する変更を行った場合、E2E を必ず実行:
+
+- 新しいページまたはルートの追加
+- 認証・ナビゲーション・レイアウトコンポーネントの変更
+- 通知ベル / サイドバー / `AuthenticatedLayout` の変更
+- バックエンド API の追加・変更で、frontend の UI フローに影響するもの
+
+## 実行コマンド
+
+```bash
+make test-frontend                                              # unit + vitest
+nix develop --command bash -c "cd frontend && npm run test:e2e" # E2E（Playwright）
+```
+
+特定の vitest スイートだけ回す場合:
+```bash
+nix develop --command bash -c "cd frontend && npx vitest run src/hooks/useDocumentForm.test.ts"
+```
+
+## OK 基準（達成条件）
+
+以下をすべて満たして初めて「テスト OK」と判定する:
+
+1. **全 unit / vitest pass**: `make test-frontend` が exit 0
+2. **lint が pass**: `make lint-frontend` も同時に通ること
+3. **build が通る**: `make build-frontend`（tsc + vite build）が通ること。TypeScript の型エラーが残っていないこと
+4. **E2E トリガーに該当する場合は E2E pass**: 上記トリガーリストに該当する変更では `npm run test:e2e` を必ず実行し、全シナリオが green
+5. **新規・変更コードに対応するテストが存在する**:
+   - 新規フック → 主要分岐ごとに 1 ケース（最低 3 ケース）
+   - 新規 API モジュール → 成功 / 4xx / 5xx の 3 パス
+   - E2E は authenticated layout 経由でゴールデンパスを 1 本通す
+
+## E2E の注意点（重要 — 過去にハマった）
+
+- **ルートモックは LIFO 登録**: キャッチオールを先、具体的モックを後（`.claude/rules/frontend/typescript.md` 参照）
+- **`LoadingOverlay` 対策**: `waitForAuthenticatedLayout(page)` を必ず呼び出す。`position: fixed; z-index: 100` が要素クリックを邪魔する
+- **キャッチオールパターン**: `http://localhost:8000/**` を使う。`**/api/**` は Vite dev server のソースファイルにもマッチして壊れる
+
+## アンチパターン
+
+- `await new Promise(r => setTimeout(r, ms))` での同期待ち（フレーキー）
+- `data-testid` 過剰依存（ユーザー視点のセレクタを優先: role / name / placeholder）
+- E2E でテスト用バックエンドを起動せずモックだけで済ませる（API 統合バグを取り逃す）
+- snapshot testing で大きな DOM 全体をスナップショットする（差分の意味が不明瞭になる）
diff --git a/.claude/rules/frontend/typescript.md b/.claude/rules/frontend/typescript.md
index 926db803..50896228 100644
--- a/.claude/rules/frontend/typescript.md
+++ b/.claude/rules/frontend/typescript.md
@@ -6,16 +6,17 @@ paths:
 # TypeScript/React コーディング規約
 
 - ESLint / Prettier の設定に従うこと
-- `cd frontend && npm run lint` でリントチェック
+- リントは `make lint-frontend`、テストは `make test-frontend` を使う（Nix devshell 経由で解決される）
+- 個別スクリプトを叩きたい場合は `nix develop --command bash -c "cd frontend && npm run <script>"` を使う。生シェルでの `cd frontend && npm ...` は AI エージェントでは禁止
 
 ## E2E テスト（Playwright）
 
 E2E テストは `frontend/e2e/` に配置する。
 
 ### 実行タイミング
-新しいページ・ルート・認証フロー・ナビゲーション・レイアウトコンポーネントを追加・変更した場合は必ず実行すること:
+新しいページ・ルート・認証フロー・ナビゲーション・レイアウトコンポーネントを追加・変更した場合は必ず実行すること（Makefile に E2E ターゲットは無いため nix wrap で叩く）:
 ```bash
-cd frontend && npm run test:e2e
+nix develop --command bash -c "cd frontend && npm run test:e2e"
 ```
 
 ### ルートモックの注意点（重要）
diff --git a/.claude/rules/github.md b/.claude/rules/github.md
deleted file mode 100644
index 1188852e..00000000
--- a/.claude/rules/github.md
+++ /dev/null
@@ -1,151 +0,0 @@
-## GitHub 運用ルール
-
-### Issue 作成
-
-Issue は `gh` CLI で作成する。テンプレートファイルは使用しない。
-
-#### 機能追加 (feature)
-
-```bash
-gh issue create \
-  --title "feat: タイトル" \
-  --label "feature" \
-  --body "$(cat <<'EOF'
-## 🧩 Problem
-
-## 🎯 Goal
-
-## 💡 Solution
-
-## 🛠 Scope
-
-- [ ]
-
-## 🚫 Out of Scope
-
--
-
-## 📊 Impact
-
-- [ ] Frontend
-- [ ] Backend
-- [ ] Data
-EOF
-)"
-```
-
-#### 改善 (improvement)
-
-```bash
-gh issue create \
-  --title "improve: タイトル" \
-  --label "improvement" \
-  --body "$(cat <<'EOF'
-## 現状の課題
-
-## 改善内容
-
-## 対応範囲
-
-- [ ]
-
-## 影響範囲
-
-- [ ] Frontend
-- [ ] Backend
-- [ ] Infra
-EOF
-)"
-```
-
-#### リファクタリング (refactor)
-
-```bash
-gh issue create \
-  --title "refactor: タイトル" \
-  --label "refactor" \
-  --body "$(cat <<'EOF'
-## リファクタリング対象
-
-## 現状の問題点
-
-## 改善方針
-
-## 対応範囲
-
-- [ ]
-
-## 影響範囲
-
-- [ ] Frontend
-- [ ] Backend
-- [ ] Infra
-EOF
-)"
-```
-
-#### バグ修正 (bug)
-
-```bash
-gh issue create \
-  --title "fix: タイトル" \
-  --label "bug" \
-  --body "$(cat <<'EOF'
-## 発生している問題
-
-## 再現手順
-
-## 期待する動作
-
-## 原因（わかれば）
-
-## 影響範囲
-
-- [ ] Frontend
-- [ ] Backend
-- [ ] Infra
-EOF
-)"
-```
-
-### Pull Request 作成
-
-PR は `gh` CLI で作成する。現在のブランチから自動検出する。
-
-```bash
-gh pr create \
-  --title "タイトル" \
-  --body "$(cat <<'EOF'
-## 概要
-
-## 変更内容
-
--
-
-## 関連 Issue
-
-closes #
-
-## 確認事項
-
-- [ ] CI が通ること
-- [ ] 動作確認済み
-EOF
-)" \
-  --base dev
-```
-
-- `--base` は原則 `dev` ブランチ
-- 関連 Issue がある場合は body 内に `closes #番号` を含める
-- label はIssueの種別に合わせて `--label` で付与する
-
-### ラベル管理
-
-リポジトリに以下のラベルが存在しない場合は作成する:
-
-```bash
-gh label create feature --color 0E8A16 --description "新機能" --force
-gh label create improvement --color 1D76DB --description "改善" --force
-gh label create refactor --color D93F0B --description "リファクタリング" --force
-gh label create bug --color B60205 --description "バグ修正" --force
-```
diff --git a/.claude/rules/infra/opentofu.md b/.claude/rules/infra/opentofu.md
index c3ce8418..d4794798 100644
--- a/.claude/rules/infra/opentofu.md
+++ b/.claude/rules/infra/opentofu.md
@@ -14,4 +14,4 @@ infra/
 CLI: OpenTofu (`tofu`) を使用する。Nix で管理されており `nix develop` シェル内で利用可能。`.tf` の構文は Terraform と同一。
 デプロイ: GitHub Actions で `dev` ブランチ push 時に frontend → Cloudflare Pages、backend → Docker → Artifact Registry → Cloud Run。
 
-DB は Turso (libSQL) を使用。Terraform 対象外で `turso CLI` 手動管理。詳細は `infra/README.md` の「Turso のセットアップ」参照。
+DB は Turso (libSQL) を使用。Terraform 対象外で `turso CLI` 手動管理。詳細は `docs/data-model.md` の「Turso CLI セットアップ」参照。
diff --git a/.claude/rules/infra/terraform.md b/.claude/rules/infra/terraform.md
deleted file mode 100644
index 1b1746d9..00000000
--- a/.claude/rules/infra/terraform.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-paths:
-  - infra/**
----
-
-# Infrastructure (Terraform)
-
-```text
-infra/
-├── modules/             # cloud_run, artifact_registry, cloud_tasks, cloudflare, monitoring, service_account
-└── environments/        # dev, stg, prod（各環境で tfvars 管理）
-```
-
-デプロイ: GitHub Actions で `dev` ブランチ push 時に frontend → Cloudflare Pages、backend → Docker → Artifact Registry → Cloud Run。
-
-DB は Turso (libSQL) を使用。Terraform 対象外で `turso CLI` 手動管理。詳細は `infra/README.md` の「Turso のセットアップ」参照。
diff --git a/.claude/rules/infra/test.md b/.claude/rules/infra/test.md
new file mode 100644
index 00000000..52130b25
--- /dev/null
+++ b/.claude/rules/infra/test.md
@@ -0,0 +1,68 @@
+---
+paths:
+  - infra/**
+---
+
+# Infra 検証方針（OpenTofu）
+
+Infra 層には実テストフレームワークは存在しない。代わりに **fmt / validate / plan** をテスト相当とみなし、変更時に必ず走らせる。
+
+## いつ検証を回すか（トリガー）
+
+以下のいずれかに該当する変更を行った場合、対応する検証を必ず実行:
+
+- **`infra/modules/**` の変更**: 全環境（dev / stg / prod）の validate が必要（モジュールは全環境から参照される）
+- **`infra/environments/<env>/**` の変更**: 当該環境の validate
+- **`*.tf` のフォーマット崩れ**: `make infra-fmt-check` が落ちないことを確認
+- **新規変数 / outputs 追加**: tfvars との対応関係を確認し、未指定変数で plan が落ちないこと
+
+## 実行コマンド
+
+```bash
+make infra-fmt-check       # フォーマットチェック
+make infra-validate        # dev / stg / prod を順に validate
+make infra-validate-dev    # 個別: dev 環境
+make infra-validate-stg    # 個別: stg 環境
+make infra-validate-prod   # 個別: prod 環境
+```
+
+自動整形:
+```bash
+make infra-fmt
+```
+
+`plan` を手元で確認したい場合（state にアクセスするため認証必要）:
+```bash
+nix develop --command bash -c "tofu -chdir=infra/environments/dev plan"
+```
+
+## OK 基準（達成条件）
+
+以下をすべて満たして初めて「Infra 検証 OK」と判定する:
+
+1. **`make infra-fmt-check` が pass**: 整形済み
+2. **`make infra-validate` が pass**: 影響範囲の環境すべてで validate が通る（modules を触ったら 3 環境全て）
+3. **plan で意図しないリソース差分が出ない**: 削除・置換（`-/+`）が発生する変更は、本当に意図したものかコミット前に必ず確認する
+4. **変数追加時**: 該当環境の `terraform.tfvars` または `*.auto.tfvars` に値を追記したか確認
+5. **state を破壊するような変更を避けている**: `lifecycle { prevent_destroy = true }` のリソースに対する破壊的変更が無いこと
+
+## DB（Turso）の扱い
+
+- Turso (libSQL) は OpenTofu 管理対象外で `turso CLI` で手動運用
+- スキーマ変更は backend 側の Alembic マイグレーション（`backend/alembic_migrations/versions/`）で行う
+- 詳細は `docs/data-model.md` の「Turso CLI セットアップ」参照
+
+## デプロイフロー
+
+GitHub Actions が `dev` ブランチ push 時に自動実行:
+
+1. frontend → Cloudflare Pages
+2. backend → Docker → Artifact Registry → Cloud Run
+
+インフラ変更（`infra/**`）は別の GitHub Actions ワークフローまたは手動 `tofu apply` で適用する。
+
+## アンチパターン
+
+- `tofu apply -auto-approve` をローカルから本番に流す
+- `lifecycle.prevent_destroy` 付きリソースに対し `terraform_remote_state` 切替で実質再作成する
+- modules を変更したのに dev 環境だけで validate して済ます（stg / prod で同じモジュール参照が壊れる）
diff --git a/.claude/skills/backend_refacter/SKILL.md b/.claude/skills/backend_refacter/SKILL.md
index bb77f14b..91649338 100644
--- a/.claude/skills/backend_refacter/SKILL.md
+++ b/.claude/skills/backend_refacter/SKILL.md
@@ -162,7 +162,9 @@ backend/app/
 
 ## 最低限の検証コマンド
 
-- `cd backend && PYTHONPATH=. .venv/bin/python -m ruff check app tests alembic_migrations`
-- `cd backend && PYTHONPATH=. .venv/bin/python -m pytest -q tests`
+- `make lint-backend`
+- `make test-backend`
+
+特定ファイルだけ検証したい場合は `nix develop --command bash -c "cd backend && .venv/bin/python -m ruff check <path>"` を使う。生シェルで `.venv/bin/python` を直接叩くのは禁止（WeasyPrint の動的ライブラリが解決できず import に失敗する）。
 
 コード変更を含む場合は、少なくとも影響範囲のテストを回し、必要なら全件を回してください。
diff --git a/.claude/skills/frontend_refacter/SKILL.md b/.claude/skills/frontend_refacter/SKILL.md
index e9a75ee6..2a002061 100644
--- a/.claude/skills/frontend_refacter/SKILL.md
+++ b/.claude/skills/frontend_refacter/SKILL.md
@@ -161,8 +161,10 @@ frontend/src/
 
 ## 最低限の検証コマンド
 
-- `cd frontend && npm run lint`
-- `cd frontend && npm test`
-- `cd frontend && npm run build`
+- `make lint-frontend`
+- `make test-frontend`
+- `make build-frontend`
+
+個別スクリプトを叩きたい場合は `nix develop --command bash -c "cd frontend && npm run <script>"` を使う。生シェルでの `cd frontend && npm ...` は AI エージェントでは禁止。
 
 コード変更を含む場合は、少なくとも影響範囲の画面とテストを確認し、最後に build まで通してください。
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 244fe4e4..ee4c631d 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -175,7 +175,8 @@
         "DYLD",
         "turso",
         "libsql",
-        "Qiita"
+        "Qiita",
+        "pyproject"
     ],
     "flake8.args": [
         "--max-line-length=100"
diff --git a/AGENT.md b/AGENT.md
new file mode 100644
index 00000000..f614a0d2
--- /dev/null
+++ b/AGENT.md
@@ -0,0 +1 @@
+プロジェクトのガイドラインは [.claude/CLAUDE.md](./.claude/CLAUDE.md) を参照してください。
diff --git a/README.md b/README.md
index c72bdf39..4a3dedf4 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,17 @@
 GitHub活動分析、ブログ連携による発信力を集計
 キャリアインテリジェンスを提供するWebアプリケーションです。
 
+## ドキュメント
+
+| ドキュメント | 内容 |
+|---|---|
+| [docs/development.md](./docs/development.md) | Nix devshell・初回セットアップ・ローカル開発・テスト/リント |
+| [docs/deployment.md](./docs/deployment.md) | 本番デプロイ（GCP）・OpenTofu インフラ構成・CI/CD・ブランチ保護 |
+| [docs/api.md](./docs/api.md) | REST API 一覧・環境変数リファレンス |
+| [docs/data-model.md](./docs/data-model.md) | Turso (libSQL) 運用・Alembic マイグレーション・データ設計 |
+| [docs/adr/](./docs/adr/) | アーキテクチャ判断記録（ADR） |
+| [docs/runbooks/](./docs/runbooks/) | 運用 Runbook |
+
 ## 主な機能
 
 ### ドキュメント管理
@@ -45,277 +56,28 @@ GitHub活動分析、ブログ連携による発信力を集計
 | PDF出力 | WeasyPrint（職務経歴書）, ReportLab（分析レポート補助） |
 | LLM | Ollama / Vertex AI（設定で切替、任意） |
 | インフラ | GCP (Cloud Run, Artifact Registry, Secret Manager), Turso, Cloudflare Pages |
-| IaC | Terraform（モジュール構成、マルチ環境） |
+| IaC | OpenTofu（モジュール構成、マルチ環境） |
 | CI/CD | GitHub Actions |
 
-## セットアップ
-
-### Nix を使ったセットアップ（推奨）
-
-[Nix](https://nixos.org/download/) がインストール済みの場合、`nix develop` 一発で Python 3.13・Node.js 22・Redis・WeasyPrint ネイティブライブラリが揃った開発環境が起動します。
-
-```bash
-# フレーク機能を有効化（初回のみ）
-# ~/.config/nix/nix.conf または /etc/nix/nix.conf に以下を追加
-# experimental-features = nix-command flakes
-
-nix develop
-```
-
-シェルに入ったら、通常どおり `make setup` でセットアップできます。
-
-```bash
-make setup
-```
-
-#### direnv を使った自動起動
-
-[direnv](https://direnv.net/) がインストール済みであれば、`.envrc` が同梱されているためディレクトリに移動するだけで自動的に Nix 開発シェルが起動します。
-
-```bash
-direnv allow   # 初回のみ許可が必要
-```
-
----
-
-### ローカル開発
-
-#### バックエンド起動
-
-```bash
-cd backend
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-cp .env.example .env
-uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
-```
-
-DB は Turso (libSQL) を使います。先に別ターミナルで `turso dev --db-file ./backend/local.sqlite` を起動し、`backend/.env` の `TURSO_DATABASE_URL=http://127.0.0.1:8080` を設定してください（詳細は後述の「Turso (libSQL) ローカル起動」参照）。
-
-#### フロントエンド起動
-
-別ターミナルで:
-
-```bash
-cd frontend
-npm install
-make dev-proxy
-```
-
-ブラウザで `http://localhost:8788` を開きます。
+## クイックスタート
 
-#### Docker起動（FastAPI + Ollama + libSQL）
+詳細手順は [docs/development.md](./docs/development.md) を参照。
 
 ```bash
-docker compose up --build
-```
-
-`docker-compose.yml` で以下のサービスをまとめて起動します:
-
-- `api`: FastAPI
-- `ollama`: LLM
-- `redis`: rate limit 等
-- `libsql`: libSQL サーバー（`ghcr.io/tursodatabase/libsql-server`）。`/var/lib/sqld` を `libsql_data` ボリュームに永続化
-
-DB 接続先は compose 内で `TURSO_DATABASE_URL=http://libsql:8080` に固定されています。
-
-##### マスタデータ変更時の再起動
-
-シードデータ（`backend/app/seed.py`）を変更した場合は、libSQL ボリュームを破棄して再起動します。
-
-```bash
-docker compose down
-docker volume rm devforge_libsql_data
-docker compose up
-```
-
-#### ローカル uvicorn で動かす場合の libSQL 起動
+nix develop          # devshell に入る（direnv 利用時は自動）
+make setup           # git hooks + backend (.venv + uv) + frontend (npm ci)
+make generate-keys   # JWT RS256 鍵ペアを生成
+cp backend/.env.example backend/.env
 
-`docker compose up libsql` だけ起動すれば、ホストの `127.0.0.1:8080` に libSQL サーバーが公開されます。
-`backend/.env` で以下を設定すれば、ホストの uvicorn から接続できます。
-
-```env
-TURSO_DATABASE_URL=http://127.0.0.1:8080
-TURSO_AUTH_TOKEN=
+make dev             # docker compose up（FastAPI + Ollama + Redis + libSQL）
 ```
 
-##### TablePlus からローカル libSQL に接続する
-
-1. TablePlus で **新規接続** → **libSQL** を選択
-2. **URL** に `http://127.0.0.1:8080` を指定（`docker compose up libsql` 経由）
-3. **Token** は空のままで OK
-4. **テスト** → **接続**
-
-> **注意**: 旧 SQLite ファイル方式（`data/devforge.sqlite` の bind mount, DBeaver の SQLite 直接接続）は廃止しました。
-
----
-
-### 本番デプロイ（GCP）
-
-#### 1. 事前準備
+CI 相当を一括で走らせる:
 
 ```bash
-export PROJECT_ID=<your-gcp-project-id>   # 例: devforge-prod-xxxxxxxx
-export ENV=<dev|stg|prod>
-export REGION=asia-northeast1
-
-# gcloud 認証
-gcloud auth login
-gcloud config set project ${PROJECT_ID}
-
-# 必要な GCP API を有効化
-gcloud services enable artifactregistry.googleapis.com
-gcloud services enable run.googleapis.com
-gcloud services enable secretmanager.googleapis.com
-```
-
-#### 2. OpenTofu でインフラを構築する
-
-CLI は Nix 管理。`nix develop` シェル内で `tofu` を利用する（または `make infra-*` ターゲットを使う）。
-
-```bash
-# GCS tfstate バケットを作成（初回のみ）
-gcloud storage buckets create gs://devforge-tfstate-${ENV} \
-  --location=${REGION} --uniform-bucket-level-access
-
-# インフラ構築
-nix develop --command bash -c "cd infra/environments/${ENV} && tofu init && tofu plan && tofu apply"
-```
-
-構成: `infra/environments/{dev|stg|prod}`, `infra/modules/`
-モジュール: `service_account`, `artifact_registry`, `storage`, `cloud_run`
-
-#### 3. Docker イメージをビルドして push する
-
-> **注意**: Apple Silicon Mac（M1/M2/M3）は必ず `--platform linux/amd64` を付けること。
-> 省略すると Cloud Run で `exec format error` が発生する。
-
-```bash
-# Docker → Artifact Registry の認証設定（初回のみ）
-gcloud auth configure-docker ${REGION}-docker.pkg.dev
-
-# ビルド → タグ付け → push
-docker build --platform linux/amd64 -t devforge-${ENV} ./backend
-docker tag devforge-${ENV} ${REGION}-docker.pkg.dev/${PROJECT_ID}/devforge-${ENV}/devforge-${ENV}:latest
-docker push ${REGION}-docker.pkg.dev/${PROJECT_ID}/devforge-${ENV}/devforge-${ENV}:latest
+make ci              # lint + test + build-frontend
 ```
 
-#### 4. Cloud Run にデプロイする
-
-```bash
-gcloud run deploy devforge-${ENV} \
-  --image ${REGION}-docker.pkg.dev/${PROJECT_ID}/devforge-${ENV}/devforge-${ENV}:latest \
-  --region ${REGION} \
-  --platform managed
-
-# デプロイ確認（URL取得）
-gcloud run services describe devforge-${ENV} --region ${REGION} \
-  --format "value(status.url)"
-```
-
-秘密情報（`ADMIN_TOKEN` 等）は Secret Manager 経由の環境変数注入を推奨。
-GitHub OAuth の `state` は backend 側 Cookie で検証されるため、`CORS_ORIGINS` と Cookie 設定を環境に合わせて揃えること。
-
-#### 5. トラブルシューティング
-
-| エラー | 原因 | 対処 |
-|---|---|---|
-| `Error 403: ... is disabled` | GCP API が未有効 | `gcloud services enable <API名>` |
-| `exec format error` | Apple Silicon で `--platform linux/amd64` が未指定 | 上記手順3でビルドし直す |
-| `deletion protection is enabled` | Terraform destroy 時 | リソースの `deletion_protection = false` に変更 → `apply` → `destroy` |
-
----
-
-## API概要
-
-### 認証
-- `POST /auth/register`: 新規ユーザー登録（username, email, password）
-- `POST /auth/login`: ログイン
-- `GET /auth/me`: 現在のログインユーザー取得
-- `POST /auth/logout`: ログアウト
-- `POST /auth/refresh`: リフレッシュトークンでアクセストークンを更新
-- `GET /auth/github/login-url`: GitHub OAuth 開始URL取得
-- `GET /auth/github/login`: GitHub OAuth 認可URLへリダイレクト
-- `GET /auth/github/callback`: GitHub OAuth コールバック（GitHub→backend）
-- `POST /auth/github/callback`: 互換用コールバック
-
-### 職務経歴書
-- `POST /api/resumes`: 作成（1ユーザー1件。既存時は `409`）
-- `PUT /api/resumes/{id}`: 更新
-- `DELETE /api/resumes`: 削除
-- `GET /api/resumes/latest`: 現在データ取得
-- `GET /api/resumes/{id}`: 取得
-- `GET /api/resumes/{id}/pdf`: PDFダウンロード
-- `GET /api/resumes/{id}/markdown`: Markdownダウンロード
-
-### GitHub分析
-- `POST /api/intelligence/analyze`: GitHub活動の全パイプライン分析（GitHub OAuth必須、202 非同期、レート: 5/分）
-- `GET /api/intelligence/cache`: キャッシュされた分析結果を取得
-- `GET /api/intelligence/cache/status`: 分析タスクのステータスをポーリング（軽量）
-- `POST /api/intelligence/position-advice`: 分析結果をもとにポジション別学習アドバイスを生成（レート: 10/分）
-
-### ブログ連携
-- `GET /api/blog/accounts`: 連携アカウント一覧
-- `POST /api/blog/accounts`: アカウント追加（Zenn / note、レート: 10/分）
-- `DELETE /api/blog/accounts/{id}`: アカウント削除
-- `GET /api/blog/articles`: 記事一覧（プラットフォームでフィルタ可）
-- `POST /api/blog/accounts/{id}/sync`: 外部プラットフォームから記事同期（レート: 10/分）
-- `GET /api/blog/score`: ブログスコア（投稿頻度・反応数・技術記事比率等）を算出
-- `GET /api/blog/summary-cache`: キャッシュされたAI要約を取得
-- `GET /api/blog/summary-cache/status`: AI要約タスクのステータスをポーリング（軽量）
-- `POST /api/blog/summarize`: ブログAI要約を生成（202 非同期、レート: 5/分）
-
-### AIキャリアパス分析
-- `POST /api/career-analysis/generate`: キャリアパス分析を開始（職務経歴書必須、202 非同期、レート: 5/分）
-- `GET /api/career-analysis/`: 分析履歴一覧
-- `GET /api/career-analysis/{id}`: 分析結果詳細
-- `GET /api/career-analysis/{id}/status`: ステータスをポーリング（軽量）
-- `DELETE /api/career-analysis/{id}`: 分析結果削除
-
-### マスタデータ管理
-- `GET /api/master-data/qualification`: 資格一覧
-- `POST /api/master-data/qualification`: 資格追加（管理者）
-- `PUT /api/master-data/qualification/{id}`: 資格更新（管理者）
-- `DELETE /api/master-data/qualification/{id}`: 資格削除（管理者）
-- `GET /api/master-data/technology-stack`: 技術スタック一覧
-- `POST /api/master-data/technology-stack`: 技術スタック追加（管理者）
-- `PUT /api/master-data/technology-stack/{id}`: 技術スタック更新（管理者）
-- `DELETE /api/master-data/technology-stack/{id}`: 技術スタック削除（管理者）
-
-### 通知
-- `GET /api/notifications`: 通知一覧（直近30件）
-- `GET /api/notifications/unread-count`: 未読件数
-- `PATCH /api/notifications/{id}/read`: 個別既読
-- `POST /api/notifications/read-all`: 全て既読
-
-### その他
-- `GET /health`: ヘルスチェック
-
-## 環境変数
-
-各 `.env.example` を参照。主要な設定:
-
-| 変数 | 用途 |
-|---|---|
-| `TURSO_DATABASE_URL` | Turso (libSQL) 接続 URL（ローカル: `http://127.0.0.1:8080` / 本番: `libsql://<db>.turso.io`） |
-| `TURSO_AUTH_TOKEN` | Turso 認証トークン（本番は Secret Manager から注入。`turso dev` では空） |
-| `JWT_PRIVATE_KEY` | RS256署名用秘密鍵（PEM形式） |
-| `JWT_PUBLIC_KEY` | RS256検証用公開鍵（PEM形式） |
-| `FIELD_ENCRYPTION_KEY` | Fernet暗号化キー |
-| `ADMIN_TOKEN` | 管理者操作用トークン |
-| `CORS_ORIGINS` | 許可するオリジン（カンマ区切り） |
-| `COOKIE_SECURE` | 認証Cookieに `Secure` を付与するか（本番: `true`） |
-| `COOKIE_SAMESITE` | 認証Cookieの SameSite（`lax` / `strict` / `none`） |
-| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | GitHub OAuth（任意） |
-| `LLM_PROVIDER` | `ollama` または `vertex` |
-| `OLLAMA_BASE_URL` | Ollama エンドポイント（`LLM_PROVIDER=ollama` 時必須） |
-| `OLLAMA_MODEL` | Ollama 利用時のモデル名（デフォルト: `gemma3:4b`） |
-| `OLLAMA_TIMEOUT` | Ollama 生成タイムアウト秒数（デフォルト: `1200`） |
-| `VERTEX_PROJECT_ID` / `VERTEX_LOCATION` | Vertex AI 利用時の設定 |
-| `VERTEX_MODEL` | Vertex AI 利用時のモデル名（デフォルト: `gemini-2.5-flash-lite`） |
-| `VITE_API_BASE_URL` | フロントエンド→バックエンドURL |
-
 ## システム構成図
 
 ```mermaid
@@ -345,7 +107,7 @@ graph TB
 
     subgraph "GCP Project: <PROJECT_ID>"
         subgraph "Cloud Storage"
-            TfstateBucket["GCS: devforge-tfstate-{env}<br/>Terraform State"]
+            TfstateBucket["GCS: devforge-tfstate-{env}<br/>OpenTofu State"]
         end
 
         subgraph "Cloud Run"
@@ -382,114 +144,3 @@ graph TB
     SA -->|"実行権限"| CloudRun
     SA -->|"secretAccessor"| Secrets
 ```
-
-## データベース・マイグレーション
-
-### Turso (libSQL)
-
-- **本番**: Turso Cloud（東京リージョン `nrt`）。`turso CLI` で DB と auth token を発行し、URL は Cloud Run 環境変数、トークンは Secret Manager に登録
-- **ローカル**: `turso dev --db-file ./backend/local.sqlite` で libSQL HTTP サーバーを起動
-- **接続**: `app.core.settings.build_sqlalchemy_database_url()` が `TURSO_DATABASE_URL` を SQLAlchemy URL（HTTP/HTTPS は `sqlite+libsql://`、ローカルファイルは `sqlite:///`）に変換
-- **ローカル DB**: `backend/local.sqlite` はコミットしない。必要時に自動生成/再作成する
-
-### Alembicマイグレーション
-
-本番環境では Cloud Run 起動時に自動実行される（`alembic upgrade head`）。
-手動実行が必要な場合:
-
-```bash
-cd backend && alembic upgrade head
-```
-
-設定: `backend/alembic.ini` / `backend/alembic_migrations/versions`
-libSQL は SQLite 互換で ALTER COLUMN 非対応のため、複雑なスキーマ変更は `batch_alter_table` を使う。
-
-## データ設計メモ
-
-- `basic_info` / `resumes` は **1ユーザー1件**
-- `career_analyses` は **複数バージョン保持可能**（分析履歴として蓄積）
-- `intelligence_cache` / `blog_summary_cache` は **1ユーザー1件**（最新結果のみ保持）
-- 可変長データは JSON ではなく子テーブルに正規化
-  - `basic_info_qualifications`
-  - `resume_experiences` / `resume_clients` / `resume_projects` / `resume_project_*`
-  - `blog_article_tags`
-- 日付は DB では `DATE` として保持
-  - 日単位: `record_date` / `birthday` / `blog_articles.published_at`
-  - 月単位: 職務経歴・学歴・職歴は月初日に正規化して保存し、API では `YYYY-MM` で返却
-- `blog_articles` は `account_id` 起点で管理し、`platform` は `blog_accounts` から解決
-- 非同期タスクはステータスフィールド（`pending` / `running` / `completed` / `failed`）で管理し、フロントエンドはポーリングで結果を取得する
-
-## テスト
-
-### フロントエンド（ユニット・ビルド）
-```bash
-cd frontend
-npm run lint
-npm run test
-npm run build
-```
-
-### フロントエンド E2E（Playwright）
-```bash
-cd frontend
-npm run test:e2e        # ヘッドレス実行
-npm run test:e2e:ui     # UI モードで実行（デバッグ用）
-```
-
-E2E テストは `frontend/e2e/` に配置。新しいページ・ルート・認証フロー・レイアウト変更時は必ず実行すること。
-
-### バックエンド
-```bash
-cd backend
-.venv/bin/python -m ruff check app tests alembic_migrations
-.venv/bin/python -m pytest -q tests
-```
-
-## CI/CD（GitHub Actions）
-
-### アプリケーション CI（`.github/workflows/ci.yml`）
-
-- **実行タイミング**: `pull_request` / `push`（target: `dev` / `stg` / `main`、`frontend/**` or `backend/**` 変更時）
-- **テスト内容**:
-  - frontend: `npm run lint`, `npm run test`, `npm run build`, E2E（Playwright / Chromium）
-  - backend: `ruff check`, `pytest`
-- **自動デプロイ**（`dev` ブランチ push 時のみ）:
-  - フロントエンド → Cloudflare Pages へデプロイ
-  - バックエンド → Artifact Registry へイメージ push → Cloud Run デプロイ
-  - GitHub Actions 実行用サービスアカウントには、Cloud Run runtime SA に対する `roles/iam.serviceAccountUser` が必要
-- **低コスト運用**: Linuxランナー、依存キャッシュ、`concurrency` で古い実行を自動キャンセル、アプリ差分がない場合は重い処理をスキップ
-
-### OpenTofu 検証 CI（`.github/workflows/opentofu-ci.yml`）
-
-- **実行タイミング**: `pull_request` / `push`（target: `dev` / `stg` / `main`、`infra/**` 変更時）
-- **実行内容**:
-  - `tofu fmt -check -recursive`
-  - `tofu init -backend=false`
-  - `tofu validate`
-
-## ブランチ保護
-
-### ローカル（ターミナル）での直コミット/直push防止
-
-```bash
-./scripts/setup-git-hooks.sh
-```
-
-- `.githooks/pre-commit`: `dev` / `stg` / `main` への直接コミットを拒否
-- `.githooks/pre-push`: `dev` / `stg` / `main` への直接pushを拒否
-
-### GitHub 側での強制保護（推奨）
-
-1. GitHub リポジトリの `Settings` -> `Branches` -> `Add branch protection rule`
-2. `Branch name pattern` に `dev` を設定
-3. 以下を有効化
-   - `Require a pull request before merging`
-   - `Require status checks to pass before merging`
-     - `test`
-     - `opentofu-fmt`
-     - `opentofu-validate-dev`
-     - `opentofu-validate-stg`
-     - `opentofu-validate-prod`
-4. `stg` と `main` についても同じ設定を追加
-5. `Do not allow bypassing the above settings`（利用可能な場合）を有効化
-6. 保存
diff --git a/backend/app/repositories/blog.py b/backend/app/repositories/blog.py
index b8a7c284..e8d4bf47 100644
--- a/backend/app/repositories/blog.py
+++ b/backend/app/repositories/blog.py
@@ -218,7 +218,8 @@ def get(self) -> BlogSummaryCache | None:
         statement = select(BlogSummaryCache).where(BlogSummaryCache.user_id == self.user_id)
         cache = self.db.scalar(statement)
         # SQLite は timezone を保持しないため naive UTC と比較する
-        if cache and cache.expires_at and cache.expires_at <= datetime.now(timezone.utc).replace(tzinfo=None):
+        now_utc = datetime.now(timezone.utc).replace(tzinfo=None)
+        if cache and cache.expires_at and cache.expires_at <= now_utc:
             self.db.delete(cache)
             self.db.commit()
             return None
@@ -240,9 +241,14 @@ def get_or_create(self) -> BlogSummaryCache:
             return cache
         except IntegrityError:
             self.db.rollback()
-            return self.db.scalar(
+            cache = self.db.scalar(
                 select(BlogSummaryCache).where(BlogSummaryCache.user_id == self.user_id)
             )
+            if cache is None:
+                raise RuntimeError(
+                    "BlogSummaryCache の再取得に失敗しました（IntegrityError 後）"
+                )
+            return cache
 
     def invalidate(self, *, commit: bool = True) -> bool:
         cache = self.get()
diff --git a/backend/app/services/tasks/handlers/blog_summarize.py b/backend/app/services/tasks/handlers/blog_summarize.py
index ac099bb3..b4d056c1 100644
--- a/backend/app/services/tasks/handlers/blog_summarize.py
+++ b/backend/app/services/tasks/handlers/blog_summarize.py
@@ -7,6 +7,7 @@
 from ....core.logging_utils import get_logger
 from ....models import BlogSummaryCache
 from ....repositories import BlogArticleRepository
+from ..exceptions import NonRetryableError
 from .base import TaskHandler
 
 logger = get_logger(__name__)
@@ -39,8 +40,9 @@ async def run(self, db: Session, payload: dict) -> None:
             return
         cache = self.get_record(db, payload)
         if not cache:
-            logger.error("ブログサマリキャッシュが見つかりません", extra={"user_id": user_id})
-            return
+            message = "ブログサマリキャッシュが見つかりません"
+            logger.error(message, extra={"user_id": user_id})
+            raise NonRetryableError(f"{message} (user_id={user_id})")
 
         cache.status = "processing"
         cache.started_at = _now()
diff --git a/backend/app/services/tasks/worker.py b/backend/app/services/tasks/worker.py
index 3c8dec0d..7ccc7826 100644
--- a/backend/app/services/tasks/worker.py
+++ b/backend/app/services/tasks/worker.py
@@ -8,6 +8,7 @@
 リトライ・dead_letter・通知などのタスク横断ロジックのみを担う。
 """
 
+import time
 from datetime import datetime, timezone
 
 from sqlalchemy.orm import Session
@@ -19,7 +20,6 @@
 from .base import TaskType
 from .exceptions import NonRetryableError
 from .handlers import get_handler
-import time
 
 logger = get_logger(__name__)
 
diff --git a/backend/tests/test_worker_extended.py b/backend/tests/test_worker_extended.py
index 295dbd0c..9c525883 100644
--- a/backend/tests/test_worker_extended.py
+++ b/backend/tests/test_worker_extended.py
@@ -45,7 +45,11 @@ def _run(coro):
 
 class TestRunGithubAnalysis:
     def _make_user_and_cache(self, db: Session, username="github:gh-user"):
-        user = UserRepository(db).create(username, hashed_password=None, email=f"{username}@test.com")
+        user = UserRepository(db).create(
+            username,
+            hashed_password=None,
+            email=f"{username}@test.com",
+        )
         cache = GitHubAnalysisCache(user_id=user.id, status="pending")
         db.add(cache)
         db.commit()
@@ -93,7 +97,10 @@ def test_status_transitions_to_completed(self, db_session: Session):
                 "app.services.intelligence.github_analysis_service.get_llm_client",
                 return_value=MagicMock(check_available=AsyncMock(return_value=False)),
             ),
-            patch("app.services.intelligence.github_analysis_service.decrypt_field", return_value="token123"),
+            patch(
+                "app.services.intelligence.github_analysis_service.decrypt_field",
+                return_value="token123",
+            ),
         ):
             _run(
                 _run_github_analysis(
@@ -134,7 +141,10 @@ async def _fake_collect(**kwargs):
                 "app.services.intelligence.github_analysis_service.get_llm_client",
                 return_value=MagicMock(check_available=AsyncMock(return_value=False)),
             ),
-            patch("app.services.intelligence.github_analysis_service.decrypt_field", return_value=None),
+            patch(
+                "app.services.intelligence.github_analysis_service.decrypt_field",
+                return_value=None,
+            ),
         ):
             _run(
                 _run_github_analysis(
@@ -163,7 +173,10 @@ def test_github_user_not_found_sets_dead_letter(self, db_session: Session):
                 side_effect=GitHubUserNotFoundError("notfound"),
             ),
             patch("app.services.progress_service.set_progress", new_callable=AsyncMock),
-            patch("app.services.intelligence.github_analysis_service.decrypt_field", return_value=None),
+            patch(
+                "app.services.intelligence.github_analysis_service.decrypt_field",
+                return_value=None,
+            ),
         ):
             with pytest.raises(GitHubUserNotFoundError):
                 _run(
@@ -202,7 +215,11 @@ def test_no_cache_raises_runtime_error(self, db_session: Session):
 
 class TestRunBlogSummarize:
     def _make_user_and_cache(self, db: Session, username="blog-worker-user"):
-        user = UserRepository(db).create(username, hashed_password=None, email=f"{username}@test.com")
+        user = UserRepository(db).create(
+            username,
+            hashed_password=None,
+            email=f"{username}@test.com",
+        )
         cache = BlogSummaryCache(user_id=user.id, status="pending")
         db.add(cache)
         db.commit()
@@ -324,14 +341,17 @@ def test_no_articles_sets_dead_letter(self, db_session: Session):
         assert cache.status == "dead_letter"
         assert cache.error_message == "分析対象の記事がありません"
 
-    def test_no_cache_returns_early(self, db_session: Session):
-        """キャッシュが見つからない場合、例外なく早期リターンすること。"""
-        _run(
-            _run_blog_summarize(
-                db_session,
-                {"user_id": "ghost-user"},
+    def test_no_cache_raises_non_retryable(self, db_session: Session):
+        """キャッシュが見つからない場合、NonRetryableError を送出すること。"""
+        from app.services.tasks.exceptions import NonRetryableError
+
+        with pytest.raises(NonRetryableError):
+            _run(
+                _run_blog_summarize(
+                    db_session,
+                    {"user_id": "ghost-user"},
+                )
             )
-        )
 
     def test_status_set_to_processing_before_llm_call(self, db_session: Session):
         """LLM 呼び出し前に status が processing に更新されること。"""
@@ -368,7 +388,11 @@ async def _fake_check_available():
 
 class TestRunCareerAnalysis:
     def _make_user_and_analysis(self, db: Session, username="career-worker-user"):
-        user = UserRepository(db).create(username, hashed_password=None, email=f"{username}@test.com")
+        user = UserRepository(db).create(
+            username,
+            hashed_password=None,
+            email=f"{username}@test.com",
+        )
         analysis = CareerAnalysis(
             user_id=user.id,
             version=1,
@@ -436,6 +460,7 @@ def test_value_error_sets_dead_letter(self, db_session: Session):
 
         db_session.refresh(analysis)
         assert analysis.status == "dead_letter"
+        assert analysis.error_message is not None
         assert "不足" in analysis.error_message
 
     def test_no_record_returns_early(self, db_session: Session):
diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 00000000..882de04f
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,153 @@
+# API・環境変数リファレンス
+
+REST API エンドポイント一覧と、バックエンド／フロントエンドで使用する環境変数を扱います。
+
+## API概要
+
+### 認証
+
+認証方式は **GitHub OAuth のみ**（パスワード認証は未実装）。
+
+- `GET /auth/me`: 現在のログインユーザー取得
+- `POST /auth/logout`: ログアウト
+- `POST /auth/refresh`: リフレッシュトークンでアクセストークンを更新
+- `GET /auth/github/login-url`: GitHub OAuth 開始URL取得
+- `GET /auth/github/login`: GitHub OAuth 認可URLへリダイレクト
+- `GET /auth/github/callback`: GitHub OAuth コールバック（GitHub→backend）
+- `POST /auth/github/callback`: 互換用コールバック
+
+### 職務経歴書
+- `POST /api/resumes`: 作成（1ユーザー1件。既存時は `409`）
+- `PUT /api/resumes/{id}`: 更新
+- `DELETE /api/resumes`: 削除
+- `GET /api/resumes/latest`: 現在データ取得
+- `GET /api/resumes/{id}`: 取得
+- `GET /api/resumes/{id}/pdf`: PDFダウンロード
+- `GET /api/resumes/{id}/markdown`: Markdownダウンロード
+
+### GitHub分析
+- `POST /api/intelligence/analyze`: GitHub活動の全パイプライン分析（GitHub OAuth必須、202 非同期、レート: 5/分）
+- `POST /api/intelligence/analyze/retry`: 失敗した分析タスクの再実行（202 非同期）
+- `GET /api/intelligence/cache`: キャッシュされた分析結果を取得
+- `GET /api/intelligence/cache/status`: 分析タスクのステータスをポーリング（軽量）
+- `GET /api/intelligence/progress`: 分析中の進捗ステップ取得
+- `POST /api/intelligence/position-advice`: 分析結果をもとにポジション別学習アドバイスを生成（レート: 10/分）
+
+### ブログ連携
+- `GET /api/blog/accounts`: 連携アカウント一覧
+- `POST /api/blog/accounts`: アカウント追加（Zenn / note、レート: 10/分）
+- `PATCH /api/blog/accounts/{platform}`: 連携アカウントの username 更新(同期状態リセット、レート: 10/分)
+- `DELETE /api/blog/accounts/{account_id}`: アカウント削除
+- `GET /api/blog/articles`: 記事一覧（プラットフォームでフィルタ可）
+- `POST /api/blog/accounts/{account_id}/sync`: 外部プラットフォームから記事同期（レート: 10/分）
+- `GET /api/blog/score`: ブログスコア（投稿頻度・反応数・技術記事比率等）を算出
+- `GET /api/blog/summary-cache`: キャッシュされたAI要約を取得
+- `GET /api/blog/summary-cache/status`: AI要約タスクのステータスをポーリング（軽量）
+- `POST /api/blog/summarize`: ブログAI要約を生成（202 非同期、レート: 5/分）
+- `POST /api/blog/summarize/retry`: 失敗した要約タスクの再実行（202 非同期）
+
+### AIキャリアパス分析
+- `POST /api/career-analysis/generate`: キャリアパス分析を開始（職務経歴書必須、202 非同期、レート: 5/分）
+- `POST /api/career-analysis/{id}/retry`: 失敗した分析の再実行（202 非同期）
+- `GET /api/career-analysis/`: 分析履歴一覧
+- `GET /api/career-analysis/{id}`: 分析結果詳細
+- `GET /api/career-analysis/{id}/status`: ステータスをポーリング（軽量）
+- `DELETE /api/career-analysis/{id}`: 分析結果削除
+
+### マスタデータ管理
+- `GET /api/master-data/qualification`: 資格一覧
+- `POST /api/master-data/qualification`: 資格追加（管理者）
+- `PUT /api/master-data/qualification/{id}`: 資格更新（管理者）
+- `DELETE /api/master-data/qualification/{id}`: 資格削除（管理者）
+- `GET /api/master-data/technology-stack`: 技術スタック一覧
+- `POST /api/master-data/technology-stack`: 技術スタック追加（管理者）
+- `PUT /api/master-data/technology-stack/{id}`: 技術スタック更新（管理者）
+- `DELETE /api/master-data/technology-stack/{id}`: 技術スタック削除（管理者）
+
+### 通知
+- `GET /api/notifications`: 通知一覧（直近30件）
+- `GET /api/notifications/unread-count`: 未読件数
+- `PATCH /api/notifications/{id}/read`: 個別既読
+- `POST /api/notifications/read-all`: 全て既読
+
+### 内部 API（Cloud Tasks コールバック専用）
+- `POST /internal/tasks/{task_type}`: Cloud Tasks からのタスク実行リクエストを受け付ける。`TASK_RUNNER=cloud_tasks` の場合は `X-CloudTasks-QueueName` ヘッダで検証
+
+### その他
+- `GET /health`: ヘルスチェック
+
+## 環境変数
+
+各 `.env.example` を参照。主要な設定:
+
+### DB・暗号化・認証
+
+| 変数 | 用途 |
+|---|---|
+| `TURSO_DATABASE_URL` | Turso (libSQL) 接続 URL（ローカル: `http://127.0.0.1:8080` / 本番: `libsql://<db>.turso.io`） |
+| `TURSO_AUTH_TOKEN` | Turso 認証トークン（本番は Secret Manager から注入。`turso dev` では空） |
+| `JWT_PRIVATE_KEY` | RS256署名用秘密鍵（PEM形式） |
+| `JWT_PUBLIC_KEY` | RS256検証用公開鍵（PEM形式） |
+| `FIELD_ENCRYPTION_KEY` | Fernet暗号化キー（履歴書の個人情報フィールド用） |
+| `ADMIN_TOKEN` | 管理者操作用トークン |
+
+### HTTP・Cookie・CORS
+
+| 変数 | 用途 |
+|---|---|
+| `CORS_ORIGINS` | 許可するオリジン（カンマ区切り） |
+| `COOKIE_SECURE` | 認証Cookieに `Secure` を付与するか（本番: `true`） |
+| `COOKIE_SAMESITE` | 認証Cookieの SameSite（`lax` / `strict` / `none`） |
+| `INTERNAL_SECRET` | Cloudflare Pages → Cloud Run 間の秘密ヘッダー値（local 環境では省略可） |
+| `CALLBACK_BASE_URL` | GitHub OAuth `redirect_uri` のベース URL。未設定時は `x-forwarded-host` から自動検出 |
+
+### GitHub OAuth
+
+| 変数 | 用途 |
+|---|---|
+| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | GitHub OAuth クライアント情報 |
+
+### LLM（Ollama / Vertex AI）
+
+| 変数 | 用途 |
+|---|---|
+| `LLM_PROVIDER` | `ollama` または `vertex` |
+| `OLLAMA_BASE_URL` | Ollama エンドポイント（`LLM_PROVIDER=ollama` 時必須） |
+| `OLLAMA_MODEL` | Ollama 利用時のモデル名（デフォルト: `gemma3:4b`） |
+| `OLLAMA_TIMEOUT` | Ollama 生成タイムアウト秒数（デフォルト: `1200`） |
+| `VERTEX_PROJECT_ID` / `VERTEX_LOCATION` | Vertex AI 利用時の設定 |
+| `VERTEX_MODEL` | Vertex AI 利用時のモデル名（デフォルト: `gemini-2.5-flash-lite`） |
+
+### 非同期タスク（Cloud Tasks）
+
+| 変数 | 用途 |
+|---|---|
+| `TASK_RUNNER` | `cloud_tasks`（本番）/ 未設定（ローカル: BackgroundTasks 直接実行） |
+| `GCP_PROJECT_ID` | Cloud Tasks の GCP プロジェクト ID |
+| `CLOUD_TASKS_QUEUE` | Cloud Tasks のキュー名 |
+| `CLOUD_TASKS_LOCATION` | Cloud Tasks のロケーション（例: `asia-northeast1`） |
+| `CLOUD_TASKS_SERVICE_URL` | Cloud Tasks → Cloud Run コールバック先 URL |
+| `CLOUD_TASKS_SERVICE_ACCOUNT` | Cloud Tasks 実行用サービスアカウント |
+| `TASK_MAX_ATTEMPTS` | タスク最大試行回数（リトライ判定で参照） |
+
+### Redis（レートリミット等）
+
+| 変数 | 用途 |
+|---|---|
+| `UPSTASH_REDIS_URL` | Upstash Redis REST URL（本番） |
+| `UPSTASH_REDIS_TOKEN` | Upstash Redis REST トークン |
+
+### 運用・ロギング
+
+| 変数 | 用途 |
+|---|---|
+| `ENVIRONMENT` | 環境名（`local` / `dev` / `stg` / `prod`） |
+| `APP_VERSION` | アプリケーションバージョン（ログ・メトリクス用） |
+| `LOG_LEVEL` | ログレベル（`DEBUG` / `INFO` / `WARNING` / `ERROR`） |
+| `LOG_FORMAT` | ログフォーマット（`json` / `text`） |
+
+### フロントエンド
+
+| 変数 | 用途 |
+|---|---|
+| `VITE_API_BASE_URL` | フロントエンド→バックエンドURL |
diff --git a/docs/data-model.md b/docs/data-model.md
new file mode 100644
index 00000000..a04b251a
--- /dev/null
+++ b/docs/data-model.md
@@ -0,0 +1,71 @@
+# データベース・データモデル
+
+Turso (libSQL) の運用、Alembic マイグレーション、テーブル設計方針を扱います。
+
+## データベース・マイグレーション
+
+### Turso (libSQL)
+
+- **本番**: Turso Cloud（東京リージョン `nrt`）。`turso CLI` で DB と auth token を発行し、URL は Cloud Run 環境変数、トークンは Secret Manager に登録
+- **ローカル**: `turso dev --db-file ./backend/local.sqlite` で libSQL HTTP サーバーを起動
+- **接続**: `app.core.settings.build_sqlalchemy_database_url()` が `TURSO_DATABASE_URL` を SQLAlchemy URL（HTTP/HTTPS は `sqlite+libsql://`、ローカルファイルは `sqlite:///`）に変換
+- **ローカル DB**: `backend/local.sqlite` はコミットしない。必要時に自動生成/再作成する
+
+### Turso CLI セットアップ（本番）
+
+DB は Turso (libSQL) を使用します。OpenTofu の対象外なので、`turso CLI` で各環境のリソースを手動作成します。
+
+```bash
+# 認証
+turso auth login
+
+# dev / stg / prod それぞれの DB を東京リージョン (nrt) で作成
+turso db create devforge-dev --location nrt
+turso db create devforge-stg --location nrt
+turso db create devforge-prod --location nrt
+
+# 接続 URL を確認（libsql://devforge-<env>-<username>.turso.io）
+turso db show devforge-dev --url
+
+# 認証トークンを発行（環境ごとに分ける）
+turso db tokens create devforge-dev
+turso db tokens create devforge-stg
+turso db tokens create devforge-prod
+```
+
+発行した URL とトークンは次のように設定します。
+
+| 値 | 配置先 |
+|---|---|
+| `TURSO_DATABASE_URL` | Cloud Run 環境変数（OpenTofu `terraform.tfvars` の `turso_database_url`） |
+| `TURSO_AUTH_TOKEN` | Secret Manager `devforge-<env>-turso-auth-token`（OpenTofu で secret 本体は作成済み、version は手動で追加） |
+
+GitHub Actions の OpenTofu CI でも `TF_VAR_turso_database_url` を GitHub Secrets 経由で渡してください。
+
+### Alembic マイグレーション
+
+本番環境では Cloud Run 起動時に自動実行される（`alembic upgrade head`）。
+手動実行は `make` 経由（Nix devshell ラップ）で行う:
+
+```bash
+make migrate                                 # alembic upgrade head
+make migrate-create MSG="add user table"     # 新規マイグレーション生成
+```
+
+設定: `backend/alembic.ini` / `backend/alembic_migrations/versions`
+libSQL は SQLite 互換で ALTER COLUMN 非対応のため、複雑なスキーマ変更は `batch_alter_table` を使う。
+
+## データ設計メモ
+
+- `basic_info` / `resumes` は **1ユーザー1件**
+- `career_analyses` は **複数バージョン保持可能**（分析履歴として蓄積）
+- `intelligence_cache` / `blog_summary_cache` は **1ユーザー1件**（最新結果のみ保持）
+- 可変長データは JSON ではなく子テーブルに正規化
+  - `basic_info_qualifications`
+  - `resume_experiences` / `resume_clients` / `resume_projects` / `resume_project_*`
+  - `blog_article_tags`
+- 日付は DB では `DATE` として保持
+  - 日単位: `record_date` / `birthday` / `blog_articles.published_at`
+  - 月単位: 職務経歴・学歴・職歴は月初日に正規化して保存し、API では `YYYY-MM` で返却
+- `blog_articles` は `account_id` 起点で管理し、`platform` は `blog_accounts` から解決
+- 非同期タスクはステータスフィールド（`pending` / `running` / `completed` / `failed`）で管理し、フロントエンドはポーリングで結果を取得する
diff --git a/docs/deployment.md b/docs/deployment.md
new file mode 100644
index 00000000..f7147a55
--- /dev/null
+++ b/docs/deployment.md
@@ -0,0 +1,221 @@
+# デプロイ・インフラガイド
+
+GCP への本番デプロイ手順、OpenTofu によるインフラ構成、CI/CD、ブランチ保護を扱います。
+
+## 本番デプロイ（GCP）
+
+### 1. 事前準備
+
+```bash
+export PROJECT_ID=<your-gcp-project-id>   # 例: devforge-prod-xxxxxxxx
+export ENV=<dev|stg|prod>
+export REGION=asia-northeast1
+
+# gcloud 認証
+gcloud auth login
+gcloud config set project ${PROJECT_ID}
+
+# 必要な GCP API を有効化
+gcloud services enable artifactregistry.googleapis.com
+gcloud services enable run.googleapis.com
+gcloud services enable secretmanager.googleapis.com
+```
+
+### 2. OpenTofu でインフラを構築する
+
+CLI は Nix 管理。`nix develop` シェル内で `tofu` を利用する（または `make infra-*` ターゲットを使う）。
+
+```bash
+# GCS tfstate バケットを作成（初回のみ）
+gcloud storage buckets create gs://devforge-tfstate-${ENV} \
+  --location=${REGION} --uniform-bucket-level-access
+
+# インフラ構築
+nix develop --command bash -c "cd infra/environments/${ENV} && tofu init && tofu plan && tofu apply"
+```
+
+構成: `infra/environments/{dev|stg|prod}`, `infra/modules/`
+モジュールの詳細・運用ルール・state 移行については下記「インフラ構成（OpenTofu）」を参照。
+
+### 3. Docker イメージをビルドして push する
+
+> **注意**: Apple Silicon Mac（M1/M2/M3）は必ず `--platform linux/amd64` を付けること。
+> 省略すると Cloud Run で `exec format error` が発生する。
+
+```bash
+# Docker → Artifact Registry の認証設定（初回のみ）
+gcloud auth configure-docker ${REGION}-docker.pkg.dev
+
+# ビルド → タグ付け → push
+docker build --platform linux/amd64 -t devforge-${ENV} ./backend
+docker tag devforge-${ENV} ${REGION}-docker.pkg.dev/${PROJECT_ID}/devforge-${ENV}/devforge-${ENV}:latest
+docker push ${REGION}-docker.pkg.dev/${PROJECT_ID}/devforge-${ENV}/devforge-${ENV}:latest
+```
+
+### 4. Cloud Run にデプロイする
+
+```bash
+gcloud run deploy devforge-${ENV} \
+  --image ${REGION}-docker.pkg.dev/${PROJECT_ID}/devforge-${ENV}/devforge-${ENV}:latest \
+  --region ${REGION} \
+  --platform managed
+
+# デプロイ確認（URL取得）
+gcloud run services describe devforge-${ENV} --region ${REGION} \
+  --format "value(status.url)"
+```
+
+秘密情報（`ADMIN_TOKEN` 等）は Secret Manager 経由の環境変数注入を推奨。
+GitHub OAuth の `state` は backend 側 Cookie で検証されるため、`CORS_ORIGINS` と Cookie 設定を環境に合わせて揃えること。
+
+### 5. トラブルシューティング
+
+| エラー | 原因 | 対処 |
+|---|---|---|
+| `Error 403: ... is disabled` | GCP API が未有効 | `gcloud services enable <API名>` |
+| `exec format error` | Apple Silicon で `--platform linux/amd64` が未指定 | 上記手順3でビルドし直す |
+| `deletion protection is enabled` | OpenTofu destroy 時 | リソースの `deletion_protection = false` に変更 → `apply` → `destroy` |
+
+## インフラ構成（OpenTofu）
+
+GCP インフラストラクチャを OpenTofu で管理しています。CLI は Nix 管理（`nix develop` シェル内で `tofu` が利用可能）。
+
+### ディレクトリ構成
+
+```
+infra/
+├── environments/
+│   ├── dev/          # 開発環境
+│   ├── stg/          # ステージング環境
+│   └── prod/         # 本番環境
+└── modules/
+    ├── artifact_registry/   # Docker イメージリポジトリ
+    ├── cloud_run/           # Cloud Run サービス + Secret Manager
+    ├── cloud_tasks/         # Cloud Tasks キュー
+    ├── cloudflare/          # Cloudflare Pages + DNS
+    ├── monitoring/          # Cloud Monitoring アラート
+    └── service_account/     # Cloud Run 用サービスアカウント
+```
+
+### モジュール
+
+| モジュール | 概要 |
+|---|---|
+| `service_account` | Cloud Run ランタイム用のサービスアカウント |
+| `artifact_registry` | Docker イメージの Artifact Registry リポジトリ |
+| `cloud_run` | Cloud Run サービス、Secret Manager シークレット、IAM |
+| `cloud_tasks` | バックグラウンドタスク用 Cloud Tasks キュー |
+| `cloudflare` | Cloudflare Pages プロジェクトと DNS レコード |
+| `monitoring` | Cloud Run エラーレート等のアラート設定 |
+
+> **DB は Turso (libSQL) に移行済み**。GCS の SQLite バックアップ用バケット (`storage` モジュール) は廃止済み。Turso のリソースは OpenTofu 外（`turso CLI` 手動）で管理（[data-model.md](./data-model.md) の「Turso CLI セットアップ」参照）。
+
+### バージョン管理
+
+- OpenTofu 本体: 各環境の `versions.tf` で `required_version` を固定（~> 1.8）
+- インフラテンプレート: 各環境の `terraform.tfvars` で `template_version` を管理
+
+### ローカル検証コマンド
+
+```bash
+# Makefile 経由（nix develop ラップ済み）
+make infra-fmt-check
+make infra-validate          # dev / stg / prod をすべて
+make infra-validate-dev      # 個別: dev 環境
+make infra-validate-stg      # 個別: stg 環境
+make infra-validate-prod     # 個別: prod 環境
+
+# 直接実行する場合
+nix develop --command tofu -chdir=infra/environments/dev init -backend=false
+nix develop --command tofu -chdir=infra/environments/dev validate
+```
+
+### plan/apply 実行時の注意
+
+GCS backend を使用しているため、`tofu init` 時にバックエンドの認証が必要です。ローカルで `plan` する場合は `gcloud auth application-default login` を実施してください。
+
+```bash
+nix develop --command bash -c "cd infra/environments/dev && tofu init && tofu plan"
+```
+
+Cloud Run サービスを OpenTofu で初回作成する場合は、`modules/cloud_run/main.tf` の `local.bootstrap_image` に定義された公開 hello イメージで起動します。Artifact Registry にアプリイメージが push されていなくても初回 apply が成立します。
+
+GitHub Actions はその後 `gcloud run deploy` で新しいリビジョンを配備します。OpenTofu では Cloud Run の `image` 差分を無視するため、後続の `apply` で CI 配備済みイメージへ巻き戻しません。
+
+Secret Manager は secret 本体だけでなく secret version が必要です。Cloud Run 起動前に最低でも以下 4 つの version を追加してください。
+
+- `devforge-<env>-secret-key`
+- `devforge-<env>-field-encryption-key`
+- `devforge-<env>-admin-token`
+- `devforge-<env>-turso-auth-token`
+
+GitHub OAuth を使う場合だけ `enable_github_oauth = true` を設定し、さらに以下 2 つの version も追加してください。
+
+- `devforge-<env>-github-client-id`
+- `devforge-<env>-github-client-secret`
+
+### 運用ルール
+
+- `dev` → `stg` → `prod` の順で `template_version` を更新
+- `main` マージ前に GitHub Actions の `OpenTofu CI` が成功していることを確認
+
+### State 移行（resume_stack からの移行）
+
+各 environment には `moved` ブロックを定義してあり、`module.resume_stack.*` から新しい module address への state 移行は `tofu plan/apply` 時に自動で処理されます。
+
+既に旧構成に対して `apply` を途中まで実行してしまった場合は、最新の設定を反映してから再度 `plan` を実行してください。`resume_stack` 配下の既存 state が残っているリソースは自動で移動され、実際に削除済みのリソースだけが再作成対象として残ります。
+
+### Terraform からの移行メモ
+
+- 本リポジトリは Terraform から OpenTofu に切り替え済み。`.tf` ファイル本体の構文は互換のためそのまま使用可能。
+- 旧 `.terraform.lock.hcl` は削除済み。初回 `tofu init` で `registry.opentofu.org` のプロバイダ向けに再生成されます。
+- GCS バックエンドの state はそのまま流用できます（破壊的な変換は不要）。
+
+## CI/CD（GitHub Actions）
+
+### アプリケーション CI（`.github/workflows/ci.yml`）
+
+- **実行タイミング**: `pull_request` / `push`（target: `dev` / `stg` / `main`、`frontend/**` or `backend/**` 変更時）
+- **テスト内容**:
+  - frontend: `npm run lint`, `npm run test`, `npm run build`, E2E（Playwright / Chromium）
+  - backend: `ruff check`, `pytest`
+- **自動デプロイ**（`dev` ブランチ push 時のみ）:
+  - フロントエンド → Cloudflare Pages へデプロイ
+  - バックエンド → Artifact Registry へイメージ push → Cloud Run デプロイ
+  - GitHub Actions 実行用サービスアカウントには、Cloud Run runtime SA に対する `roles/iam.serviceAccountUser` が必要
+- **低コスト運用**: Linuxランナー、依存キャッシュ、`concurrency` で古い実行を自動キャンセル、アプリ差分がない場合は重い処理をスキップ
+
+### OpenTofu 検証 CI（`.github/workflows/opentofu-ci.yml`）
+
+- **実行タイミング**: `pull_request` / `push`（target: `dev` / `stg` / `main`、`infra/**` 変更時）
+- **実行内容**:
+  - `tofu fmt -check -recursive`
+  - `tofu init -backend=false`
+  - `tofu validate`
+
+## ブランチ保護
+
+### ローカル（ターミナル）での直コミット/直push防止
+
+```bash
+./scripts/setup-git-hooks.sh
+```
+
+- `.githooks/pre-commit`: `dev` / `stg` / `main` への直接コミットを拒否
+- `.githooks/pre-push`: `dev` / `stg` / `main` への直接pushを拒否
+
+### GitHub 側での強制保護（推奨）
+
+1. GitHub リポジトリの `Settings` -> `Branches` -> `Add branch protection rule`
+2. `Branch name pattern` に `dev` を設定
+3. 以下を有効化
+   - `Require a pull request before merging`
+   - `Require status checks to pass before merging`
+     - `test`
+     - `opentofu-fmt`
+     - `opentofu-validate-dev`
+     - `opentofu-validate-stg`
+     - `opentofu-validate-prod`
+4. `stg` と `main` についても同じ設定を追加
+5. `Do not allow bypassing the above settings`（利用可能な場合）を有効化
+6. 保存
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 00000000..e20c28a6
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,150 @@
+# 開発ガイド
+
+ローカル環境のセットアップ、開発サーバー起動、テスト・リント実行までを扱います。
+
+## セットアップ
+
+### Nix devshell（必須）
+
+開発ツール（Python 3.13 / Node.js 22 / ruff / tofu / WeasyPrint ネイティブライブラリ等）はすべて [Nix](https://nixos.org/download/) devshell で提供する。ホスト OS への直接インストールは想定していない。
+
+```bash
+# フレーク機能を有効化（初回のみ）
+# ~/.config/nix/nix.conf または /etc/nix/nix.conf に以下を追加
+# experimental-features = nix-command flakes
+
+nix develop
+```
+
+#### direnv で自動起動
+
+[direnv](https://direnv.net/) がインストール済みであれば、`.envrc` が同梱されているためディレクトリに移動するだけで Nix devshell が自動起動する。
+
+```bash
+direnv allow   # 初回のみ許可が必要
+```
+
+### ローカル開発
+
+> **前提**: 開発ツール（Python / Node / ruff / tofu / WeasyPrint 用ネイティブライブラリ）はすべて Nix devshell で提供する。ホスト側に直接インストールしない方針のため、コマンドは `make` 経由（内部で `nix develop --command` ラップ）で実行する。
+
+#### 初回セットアップ
+
+```bash
+nix develop          # devshell に入る（または direnv で自動）
+make setup           # git hooks + backend (.venv + uv) + frontend (npm ci)
+make generate-keys   # JWT RS256 鍵ペアを生成
+cp backend/.env.example backend/.env  # 環境変数を埋める
+```
+
+#### Docker 起動（推奨: FastAPI + Ollama + Redis + libSQL）
+
+```bash
+make dev             # docker compose up
+make dev-build       # 再ビルドして起動
+make dev-down        # 停止
+```
+
+`docker-compose.yml` で以下のサービスをまとめて起動する:
+
+- `api`: FastAPI（`backend/Dockerfile` をビルド）
+- `ollama`: LLM ランタイム（`ollama/ollama:latest`、`gemma3:4b` を自動 pull）
+- `redis`: レート制限・キャッシュ
+- `libsql`: libSQL サーバー（`ghcr.io/tursodatabase/libsql-server`）。`/var/lib/sqld` を `libsql_data` ボリュームに永続化
+
+DB 接続先は compose 内で `TURSO_DATABASE_URL=http://libsql:8080` に固定されている。
+
+> **方針**: Ollama はコンテナまたは Nix 環境内で動かす想定。ホスト OS に直接 `ollama serve` する運用はサポート外。
+
+#### フロントエンド単体起動（バックエンドは docker / 別途）
+
+```bash
+make dev-frontend    # Vite 開発サーバー（http://localhost:5173）
+make dev-proxy       # Vite + Cloudflare Pages dev proxy（http://localhost:8788）
+```
+
+#### バックエンドだけ uvicorn で動かしたい場合
+
+```bash
+# libSQL だけ compose で起動（ホストの 127.0.0.1:8080 に公開）
+docker compose up libsql
+
+# 別ターミナルで uvicorn 起動（nix devshell 内で実行）
+nix develop --command bash -c "cd backend && .venv/bin/uvicorn app.main:app --reload --host 0.0.0.0 --port 8000"
+```
+
+`backend/.env`:
+
+```env
+TURSO_DATABASE_URL=http://127.0.0.1:8080
+TURSO_AUTH_TOKEN=
+```
+
+#### マスタデータ変更時の再起動
+
+シードデータ（`backend/app/db/seed.py`）を変更した場合は、libSQL ボリュームを破棄して再起動する。
+
+```bash
+make dev-down
+docker volume rm devforge_libsql_data
+make dev
+```
+
+#### TablePlus からローカル libSQL に接続する
+
+1. TablePlus で **新規接続** → **libSQL** を選択
+2. **URL** に `http://127.0.0.1:8080` を指定（`docker compose up libsql` 経由）
+3. **Token** は空のままで OK
+4. **テスト** → **接続**
+
+> **注意**: 旧 SQLite ファイル方式（`data/devforge.sqlite` の bind mount, DBeaver の SQLite 直接接続）は廃止しました。
+
+## テスト・リント
+
+> すべて Nix devshell 経由で実行する（`make` が `nix develop --command` をラップしている）。
+
+### CI 相当を一括実行
+
+```bash
+make ci          # lint + test + build-frontend
+```
+
+### バックエンド
+
+```bash
+make lint-backend    # ruff check（app / tests / alembic_migrations）
+make test-backend    # pytest -q tests
+make lint-fix        # ruff --fix（自動修正）
+```
+
+特定ファイルだけ ruff したい場合:
+
+```bash
+nix develop --command bash -c "cd backend && .venv/bin/python -m ruff check <path>"
+```
+
+### フロントエンド（ユニット・ビルド）
+
+```bash
+make lint-frontend       # eslint
+make test-frontend       # vitest
+make build-frontend      # Vite ビルド
+```
+
+### フロントエンド E2E（Playwright）
+
+```bash
+nix develop --command bash -c "cd frontend && npm run test:e2e"        # ヘッドレス
+nix develop --command bash -c "cd frontend && npm run test:e2e:ui"     # UI モード（デバッグ用）
+```
+
+E2E テストは `frontend/e2e/` に配置。新しいページ・ルート・認証/ナビゲーション/レイアウト変更時は必ず実行すること。
+
+### インフラ（OpenTofu）
+
+```bash
+make infra-fmt-check        # tofu fmt -check
+make infra-validate         # dev / stg / prod を順に validate
+```
+
+詳細は [deployment.md](./deployment.md) の「インフラ構成（OpenTofu）」を参照。
diff --git a/docs/ollama-setup.md b/docs/ollama-setup.md
deleted file mode 100644
index 304b8bb9..00000000
--- a/docs/ollama-setup.md
+++ /dev/null
@@ -1,105 +0,0 @@
-# Ollama + Gemma 3 セットアップガイド
-
-DevForge の GitHub 分析・キャリアパス分析機能では、分析結果の自然言語要約に Ollama（ローカル LLM ランタイム）と Gemma 3 モデルを使用します。
-Ollama はオプション機能であり、起動していなくても分析自体は正常に動作します。
-
-## Ollama とは
-
-[Ollama](https://ollama.com/) はローカルマシン上で大規模言語モデル（LLM）を実行するためのツールです。
-API サーバーとして動作し、DevForge のバックエンドから HTTP 経由で呼び出します。
-
-## インストール（macOS）
-
-```bash
-# Homebrew
-brew install ollama
-
-# または公式サイトからダウンロード
-# https://ollama.com/download
-```
-
-## Gemma 3 モデルのダウンロード
-
-```bash
-# 4B パラメータモデル（推奨、RAM 8GB 以上で動作）
-ollama pull gemma3:4b
-```
-
-> **モデル選択について**
-> - `gemma3:4b`（デフォルト）: RAM ~4 GiB。Docker 環境でも快適に動作。
-> - `gemma3:9b`: RAM ~6 GiB。品質向上、やや遅い。
-> - `gemma3:27b`: RAM ~18 GiB。高品質だが、ホスト上で Ollama を直接起動する必要あり。
-
-## Ollama サーバーの起動
-
-```bash
-ollama serve
-```
-
-デフォルトで `http://localhost:11434` でリッスンします。
-
-## 動作確認
-
-```bash
-# サーバーの応答確認
-curl http://localhost:11434/api/tags
-
-# モデルの動作確認
-curl -s http://localhost:11434/api/generate -d '{
-  "model": "gemma3:4b",
-  "prompt": "Hello",
-  "stream": false
-}' | python3 -m json.tool
-```
-
-## DevForge との連携設定
-
-以下の環境変数で設定をカスタマイズできます（いずれもオプション）:
-
-| 環境変数 | デフォルト値 | 説明 |
-|---|---|---|
-| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama サーバーの URL |
-| `OLLAMA_MODEL` | `gemma3:4b` | 使用するモデル名 |
-| `OLLAMA_TIMEOUT` | `1200.0` | 生成リクエストのタイムアウト秒数 |
-
-## Docker で実行する場合
-
-`docker-compose.yml` に Ollama サービスが含まれており、`gemma3:4b` を自動的に pull・起動します。
-
-```bash
-docker compose up
-```
-
-コンテナ起動時にモデルの pull が完了してから API サーバーが起動します（初回のみ時間がかかります）。
-
-### メモリ要件
-
-| モデル | 必要メモリ | Docker Desktop 推奨設定 |
-|---|---|---|
-| `gemma3:4b` | ~4 GiB | 8 GiB 以上 |
-| `gemma3:9b` | ~6 GiB | 10 GiB 以上 |
-
-## トラブルシューティング
-
-### Ollama が起動しない
-
-```bash
-# ポートが使用中の場合
-lsof -i :11434
-
-# ログを確認
-ollama serve 2>&1
-```
-
-### モデルのダウンロードが遅い
-
-初回 pull 時のみ時間がかかります。`gemma3:4b` は約 2.5 GB のダウンロードです。
-
-### DevForge で AI 要約が表示されない
-
-1. `ollama serve` が起動しているか確認
-2. `curl http://localhost:11434/api/tags` で応答があるか確認
-3. 指定したモデルがダウンロード済みか確認（`models` 配列に表示されること）
-4. バックエンドのログにタイムアウトや接続失敗が出ていないか確認
-
-AI 要約は Ollama が利用できない場合、自動的にスキップされます（エラーにはなりません）。
diff --git a/infra/README.md b/infra/README.md
deleted file mode 100644
index 377ac1a3..00000000
--- a/infra/README.md
+++ /dev/null
@@ -1,123 +0,0 @@
-# OpenTofu Infrastructure
-
-GCP インフラストラクチャを OpenTofu で管理するディレクトリです。CLI は Nix 管理（`nix develop` シェル内で `tofu` が利用可能）。
-
-## 構成
-
-```
-infra/
-├── environments/
-│   ├── dev/          # 開発環境
-│   ├── stg/          # ステージング環境
-│   └── prod/         # 本番環境
-└── modules/
-    ├── artifact_registry/   # Docker イメージリポジトリ
-    ├── cloud_run/           # Cloud Run サービス + Secret Manager
-    ├── cloud_tasks/         # Cloud Tasks キュー
-    ├── cloudflare/          # Cloudflare Pages + DNS
-    ├── monitoring/          # Cloud Monitoring アラート
-    └── service_account/     # Cloud Run 用サービスアカウント
-```
-
-## モジュール
-
-| モジュール | 概要 |
-|---|---|
-| `service_account` | Cloud Run ランタイム用のサービスアカウント |
-| `artifact_registry` | Docker イメージの Artifact Registry リポジトリ |
-| `cloud_run` | Cloud Run サービス、Secret Manager シークレット、IAM |
-| `cloud_tasks` | バックグラウンドタスク用 Cloud Tasks キュー |
-| `cloudflare` | Cloudflare Pages プロジェクトと DNS レコード |
-| `monitoring` | Cloud Run エラーレート等のアラート設定 |
-
-> **DB は Turso (libSQL) に移行済み**。GCS の SQLite バックアップ用バケット (`storage` モジュール) は廃止済みです。Turso のリソースは Terraform 外（`turso CLI` 手動）で管理します。詳細は下記「Turso のセットアップ」を参照してください。
-
-## バージョン管理
-
-- OpenTofu 本体: 各環境の `versions.tf` で `required_version` を固定（~> 1.8）
-- インフラテンプレート: 各環境の `terraform.tfvars` で `template_version` を管理
-
-## ローカル検証コマンド
-
-```bash
-# Makefile 経由（nix develop ラップ済み）
-make infra-fmt-check
-make infra-validate-dev    # / -stg / -prod / make infra-validate ですべて
-
-# 直接実行する場合
-nix develop --command tofu -chdir=infra/environments/dev init -backend=false
-nix develop --command tofu -chdir=infra/environments/dev validate
-```
-
-## plan/apply 実行
-
-GCS backend を使用しているため、`tofu init` 時にバックエンドの認証が必要です。
-ローカルで `plan` する場合は `gcloud auth application-default login` を実施してください。
-
-```bash
-nix develop --command bash -c "cd infra/environments/dev && tofu init && tofu plan"
-```
-
-Cloud Run サービスを OpenTofu で初回作成する場合は、`modules/cloud_run/main.tf` の `local.bootstrap_image` に定義された公開 hello イメージで起動します。Artifact Registry にアプリイメージが push されていなくても初回 apply が成立します。
-
-GitHub Actions はその後 `gcloud run deploy` で新しいリビジョンを配備します。OpenTofu では Cloud Run の `image` 差分を無視するため、後続の `apply` で CI 配備済みイメージへ巻き戻しません。
-
-Secret Manager は secret 本体だけでなく secret version が必要です。Cloud Run 起動前に最低でも以下 4 つの version を追加してください。
-
-- `devforge-<env>-secret-key`
-- `devforge-<env>-field-encryption-key`
-- `devforge-<env>-admin-token`
-- `devforge-<env>-turso-auth-token`
-
-GitHub OAuth を使う場合だけ `enable_github_oauth = true` を設定し、さらに以下 2 つの version も追加してください。
-
-- `devforge-<env>-github-client-id`
-- `devforge-<env>-github-client-secret`
-
-## Turso のセットアップ
-
-DB は Turso (libSQL) を使用します。Terraform の対象外なので、`turso CLI` で各環境のリソースを手動作成します。
-
-```bash
-# 認証
-turso auth login
-
-# dev / stg / prod それぞれの DB を東京リージョン (nrt) で作成
-turso db create devforge-dev --location nrt
-turso db create devforge-stg --location nrt
-turso db create devforge-prod --location nrt
-
-# 接続 URL を確認（libsql://devforge-<env>-<username>.turso.io）
-turso db show devforge-dev --url
-
-# 認証トークンを発行（環境ごとに分ける）
-turso db tokens create devforge-dev
-turso db tokens create devforge-stg
-turso db tokens create devforge-prod
-```
-
-発行した URL とトークンは次のように設定します。
-
-| 値 | 配置先 |
-|---|---|
-| `TURSO_DATABASE_URL` | Cloud Run 環境変数（Terraform `terraform.tfvars` の `turso_database_url`）|
-| `TURSO_AUTH_TOKEN` | Secret Manager `devforge-<env>-turso-auth-token`（Terraform で secret 本体は作成済み、version は手動で追加）|
-
-GitHub Actions の Terraform CI でも `TF_VAR_turso_database_url` を GitHub Secrets 経由で渡してください。
-
-## 運用ルール
-
-- `dev` -> `stg` -> `prod` の順で `template_version` を更新
-- `main` マージ前に GitHub Actions の `OpenTofu CI` が成功していることを確認
-
-## State 移行 (resume_stack からの移行)
-
-各 environment には `moved` ブロックを定義してあり、`module.resume_stack.*` から新しい module address への state 移行は `tofu plan/apply` 時に自動で処理されます。
-
-既に旧構成に対して `apply` を途中まで実行してしまった場合は、最新の設定を反映してから再度 `plan` を実行してください。`resume_stack` 配下の既存 state が残っているリソースは自動で移動され、実際に削除済みのリソースだけが再作成対象として残ります。
-
-## Terraform からの移行メモ
-
-- 本リポジトリは Terraform から OpenTofu に切り替え済みです。`.tf` ファイル本体の構文は互換のためそのまま使用可能。
-- 旧 `.terraform.lock.hcl` は削除済み。初回 `tofu init` で `registry.opentofu.org` のプロバイダ向けに再生成されます。
-- GCS バックエンドの state はそのまま流用できます（破壊的な変換は不要）。