Claude Code をうまく使う「コンテキストエンジニアリング」実践ガイド｜Anthropic流の運用環境設計8原則

# プロジェクト名

## 概要
- **技術スタック**: Node.js 20 / TypeScript / Drizzle ORM / PostgreSQL
- **テストフレームワーク**: Vitest（`npm test`）
- **コードフォーマット**: Prettier（コミット前に `npm run format` を実行）

## 必ず守るルール
- `main` ブランチへの直接 push は禁止（必ず PR 経由）
- コミットメッセージは Conventional Commits 形式（feat:/fix:/docs: など）
- 環境変数は `.env.example` を更新してから `.env` に追加

## このプロジェクト固有の注意点
- DB マイグレーションは `npm run db:migrate` で実行（本番は手動承認が必要）
- テスト用 DB のリセット: `npm run db:reset`（テスト前に毎回実行）
- E2E テストはローカル Dev サーバーが起動している状態で実行する

## 過去の失敗と教訓
- JWT オプションは `{ expiresIn: "24h" }` 形式で指定（数値指定は無効エラーになる）
- bcrypt は非同期版を使うこと（同期版はテストがタイムアウトする）
- Drizzle の型推論は `$inferSelect` を使う（`InferModel` は deprecated）

## 開発フロー
1. `git checkout -b feat/機能名` でブランチを切る
2. 実装前に `docs/task_plan.md` にタスクを書く
3. テストを書いてから実装する（TDD）
4. `npm test` が通ったら PR を作成する

# まず動くものを素早く作る
Create a rough prototype of the dashboard. Don't worry about code quality.
I want to see how it feels to use it.

# 確認後、本実装に切り替える
/clear

# 新しいセッションで本実装
Now implement the dashboard properly based on what we learned.
Requirements:
- [プロトタイプで確認した仕様を箇条書き]
Success criteria: npm test passes, screenshot matches the design

# Plan Mode を起動（実装は行わない）
claude --plan

# または対話中に切り替え
# Shift+Tab で Plan Mode / Auto-accept を切り替え

# Plan Mode での指示例
Implement user authentication with email/password.
Do NOT write any code yet.
Just create a detailed implementation plan including:
- File structure
- API endpoints
- Database schema
- Test strategy

# 3つの独立した作業ディレクトリを作成
git worktree add ../project-feat-auth feat/auth
git worktree add ../project-feat-search feat/search
git worktree add ../project-bugfix fix/login-bug

# tmux で各 worktree に Claude を起動（並列実行）
tmux new-session -d -s auth    -c ../project-feat-auth    'claude'
tmux new-session -d -s search  -c ../project-feat-search  'claude'
tmux new-session -d -s bugfix  -c ../project-bugfix        'claude'

# セッションを切り替える
tmux switch-client -t auth
tmux switch-client -t search

# 自動命名 worktree で独立セッションを起動
claude --worktree

# 名前を指定して起動
claude --worktree feat/payment-refactor

# tmux と組み合わせて起動
claude --worktree --tmux

# commit-push-pr

現在の変更をコミット・push して PR を作成します。

## 手順

1. lint を実行する: `npm run lint`
   - エラーがあれば自動修正を試みる
2. テストを実行する: `npm test`
   - 失敗したら修正してから続行する
3. 変更内容を確認: `git diff --staged`
4. 変更内容を要約してコミットメッセージを作成する（Conventional Commits 形式）
5. コミットして push する
6. `gh pr create` で PR を作成する
   - タイトル: コミットメッセージの1行目
   - 本文: 変更の概要・テスト方法・レビューポイント

## 注意
- `main` や `master` ブランチに直接 push しない
- PR は draft で作成する（`--draft` フラグ）

# review-checkpoint

実装の中間チェックポイントを実施します。

## 実行内容

1. テストを実行し、すべて通過していることを確認
2. 現在の実装と当初の計画（docs/plan.md）を比較
3. 逸脱している箇所をリスト化
4. 技術的負債になりそうな箇所を指摘
5. 次のステップの提案

セッション開始時に必ずこのコマンドを実行すること。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/test-gate.py"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env python3
import json, sys, subprocess

input_data = json.load(sys.stdin)

# 無限ループ防止（絶対に必要）
# Stop Hook が「ブロック」すると Claude が再実行 → Stop Hook が再発火 → 無限ループ
if input_data.get('stop_hook_active', False):
    sys.exit(0)

# lint → test → build の順でチェック
checks = [
    (['npm', 'run', 'lint'], 'リントエラーが検出されました'),
    (['npm', 'test'],        'テストが失敗しています'),
    (['npm', 'run', 'build'], 'ビルドが失敗しています'),
]

for cmd, message in checks:
    result = subprocess.run(cmd, capture_output=True, timeout=120)
    if result.returncode != 0:
        output = result.stdout.decode('utf-8', errors='replace')
        print(json.dumps({
            "decision": "block",
            "reason": f"{message}。修正してから終了してください。

{output[:2000]}"
        }))
        sys.exit(0)

# すべて通過 → 終了を許可（何も出力しない）
sys.exit(0)

/plugin install tdd-guard@tdd-guard
/tdd-guard:setup

# バグ調査に適用する例
Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses.
Have them talk to each other to try to disprove each other'"'"'s theories,
like a scientific debate.
Update docs/findings.md with whatever consensus emerges.

# 設計議論に適用する例
I'"'"'m designing a new caching strategy. Create an agent team:
- One agent supporting Redis-based caching (make the strongest case)
- One agent supporting in-memory caching (make the strongest case)
- One playing devil'"'"'s advocate for both
Have them debate and summarize the trade-offs in docs/cache-decision.md.

# コードレビューに適用する例
Review the authentication module in src/auth/.
Create three specialized reviewers:
- Security reviewer: focus on vulnerabilities and attack vectors
- Performance reviewer: focus on bottlenecks and scalability
- Test coverage reviewer: focus on edge cases and missing tests
Consolidate findings in docs/auth-review.md.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

# files.txt に変換対象ファイルのリスト
cat files.txt | while read file; do
  claude -p "Migrate $file from React class components to hooks.
Return OK if successful, FAIL with reason if not." \
    --allowedTools "Edit,Bash(git add *,git commit *)" &
done
wait   # すべての並列実行が完了するまで待機

# API 仕様の調査をサブエージェントに委ねる
Spawn a subagent to research the Stripe Webhooks API.
Focus on:
- Event types for payment lifecycle
- Signature verification best practices
- Retry behavior and idempotency
Write findings to docs/stripe-research.md. Return when complete.

# コードベース調査をサブエージェントに委ねる
Spawn a subagent to understand how authentication is currently implemented.
Read all files in src/auth/ and middleware/.
Summarize the architecture and any security concerns in docs/auth-analysis.md.
Do NOT make any changes. Return when complete.

# タスク計画

## 現在のフェーズ: Phase 2 - 認証機能実装

## タスク一覧

### Phase 1: 環境構築（完了）
- [x] TASK-001: DB スキーマ作成
- [x] TASK-002: プロジェクト初期化

### Phase 2: 認証機能（進行中）
- [x] TASK-003: ユーザーモデル実装
- [ ] TASK-004: ログインエンドポイント（⚡ 現在作業中）
- [ ] TASK-005: JWT ミドルウェア

## 判明した制約
- bcrypt のハッシュ化は非同期処理が必要（同期版はテストがタイムアウトする）
- テスト用 DB は毎回 `npm run db:reset` でリセットする必要がある

## セッション 2026-03-20

### 試したこと
- JWT の有効期限を1時間に設定 → ログインテストが断続的に失敗
- 有効期限を24時間に変更 → テスト安定化

### 成功したアプローチ
- `jsonwebtoken` ライブラリのオプション `{ expiresIn: "24h" }` を使う

### 失敗したアプローチ
- `expiry: 3600` を直接渡す → `invalid options` エラーになる（要注意）

### 次回の開始点
- TASK-005 JWT ミドルウェアの実装から再開
- `src/middleware/auth.ts` の `validateToken()` 関数から始める

## 教訓（累積）

### 認証関連
- JWT の有効期限は `{ expiresIn: "24h" }` 形式で指定すること（数値指定は無効）
- bcrypt のハッシュ化は必ず非同期版を使うこと（同期版はタイムアウトする）

### デプロイ関連
- deploy_to_db() は SSH stdin パイプ方式を使う（SCP 方式は Windows パスが文字化けする）
- 内部リンクは post_name ではなく本番 post_id で構成すること

### テスト関連
- テスト用 DB は各テスト前に `npm run db:reset` でリセットが必要
- E2E テストは `playwright.config.ts` で retries: 2 を設定するとフラキーテストが減る

#!/usr/bin/env python3
"""セッション終了時に progress.md を自動更新する"""
import json, sys, datetime, subprocess, os

input_data = json.load(sys.stdin)

if input_data.get('stop_hook_active', False):
    sys.exit(0)

# 本日の日付
today = datetime.date.today().isoformat()

# 直近の git diff を取得（変更サマリ）
diff = subprocess.run(
    ['git', 'diff', '--stat', 'HEAD'],
    capture_output=True, text=True
).stdout.strip()

# progress.md に追記
progress_path = 'docs/progress.md'
os.makedirs('docs', exist_ok=True)

with open(progress_path, 'a', encoding='utf-8') as f:
    f.write(f'
## セッション {today}
')
    f.write('### 変更ファイル
')
    f.write(f'```
{diff or "(変更なし)"}
```
')
    f.write('### 次回の開始点
')
    f.write('（ここに次回開始時の状況を記録する）
')

sys.exit(0)