Stg

.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 有効で実行すると次のエラーになる:
+
+```text
+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`

.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 プロバイダクライアントの実装