# 悪い例: 責任が混在している
def file_manager(action: str, path: str, content: str = ""):
    if action == "read":
        return open(path).read()
    elif action == "write":
        open(path, "w").write(content)
    elif action == "delete":
        os.remove(path)

# 良い例: 責任を分離する
def read_file(path: str) -> str: ...
def write_file(path: str, content: str) -> None: ...
def delete_file(path: str) -> None: ...

# ツール定義の例（Claude の tool_use 形式）
tools = [
    {
        "name": "search_web",
        "description": "Web を検索して情報を取得します（読み取り専用・副作用なし）",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "検索クエリ"}
            }
        }
    },
    {
        "name": "send_email",
        "description": "【副作用あり・不可逆】メールを送信します。実行前に必ずユーザーに確認してください",
        "input_schema": {
            "type": "object",
            "properties": {
                "to": {"type": "string"},
                "subject": {"type": "string"},
                "body": {"type": "string"}
            },
            "required": ["to", "subject", "body"]
        }
    }
]

# 悪い例
raise Exception("Error")

# 良い例: エージェントが回復アクションを判断できる
raise ToolError(
    code="FILE_NOT_FOUND",
    message=f"ファイル '{path}' が見つかりません",
    suggestion="ls コマンドで利用可能なファイル一覧を確認してください",
    recoverable=True
)

# エージェントのテスト構造例
class AgentTestSuite:

    def test_task_completion(self):
        """タスクが正しく完了するか"""
        result = agent.run("src/utils.ts に JSDoc コメントを追加して")
        assert result.status == "completed"
        assert "JSDoc" in read_file("src/utils.ts")

    def test_error_recovery(self):
        """エラー発生時に自己回復できるか"""
        # 存在しないファイルを指定
        result = agent.run("nonexistent.ts を編集して")
        assert result.recovery_attempted == True
        assert result.status in ["recovered", "escalated"]

    def test_boundary_respect(self):
        """スコープ外の操作をしないか"""
        result = agent.run("src/ のコードを改善して")
        touched_files = result.get_modified_files()
        assert all(f.startswith("src/") for f in touched_files)

    def test_efficiency(self):
        """無駄なツール呼び出しがないか"""
        result = agent.run("package.json のバージョンを確認して")
        assert result.tool_call_count <= 3  # 読み込み・確認・返答の 3 回以内

# メインエージェントのプロンプト（CLAUDE.md または直接指示）

以下を並列で実行してください:

Task 1: src/api/ ディレクトリ内の全エンドポイントを解析し、
        認証されていないエンドポイントのリストを作成してください。

Task 2: test/ ディレクトリを確認し、カバレッジが 80% 未満の
        ファイルを特定してください。

Task 3: package.json の依存関係で脆弱性があるものを
        npm audit の結果から抽出してください。

3 つのタスクが完了したら結果を統合して改善提案をまとめてください。

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '実行コマンド: ' $CLAUDE_TOOL_INPUT | tee -a ~/.claude/audit.log"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsc --noEmit 2>&1 | head -20"
          }
        ]
      }
    ]
  }
}

優先度（高）
  ↑ システムプロンプト（Claude 自体の設定）
  │ ~/.claude/CLAUDE.md（グローバル設定）
  │ <project-root>/CLAUDE.md（プロジェクト設定）
  ↓ <subdir>/CLAUDE.md（サブディレクトリ指示）
優先度（低）

# プロジェクト: <名前>

## 1. 技術スタック
- 言語: TypeScript 5.x（strict mode 必須）
- フレームワーク: Next.js 15（App Router）
- DB: PostgreSQL 16 + Prisma ORM
- テスト: Vitest + Testing Library

## 2. コーディング規約
- 関数は純粋関数を優先。副作用は I/O 層に閉じ込める
- エラーは `Result<T, E>` 型で表現（throw 禁止）
- `any` / `unknown` 使用時は型ガードを必ず付ける
- コメントは「なぜ」を書く（「何をするか」はコードが語る）

## 3. ディレクトリ構造
src/
  app/        # Next.js App Router
  domain/     # ビジネスロジック（フレームワーク非依存）
  infra/      # DB・外部API・ストレージ
  shared/     # 共通型・ユーティリティ

## 4. 禁止事項
- `console.log` をコミットしない（`logger` モジュールを使う）
- 環境変数の直書き禁止（`config/env.ts` 経由）
- `any` キャストを PR にコミットしない

## 5. よく使うコマンド
- `npm run dev`   開発サーバー起動
- `npm test`      テスト実行（watch モード）
- `npm run check` 型チェック + lint + format チェック

<!-- コンテキスト圧縮メモ（セッション途中で記録） -->
## 完了済みタスク要約（2025-06-01）

### 認証モジュールのリファクタリング
- 変更ファイル: src/auth/jwt.ts, src/auth/middleware.ts
- 変更内容: RS256 署名方式に移行、リフレッシュトークン追加
- テスト: auth.test.ts 全 12 ケースパス
- 注意点: 既存セッションは移行期間中 HS256 でも有効

# 悪い例（トークン消費大）
以下のファイルを修正してください:
[src/utils.ts の全 200 行を貼り付け]

# 良い例（参照のみ）
src/utils.ts の formatDate 関数（L45-L72）を修正してください。
現在の問題: タイムゾーン非対応

CLAUDE.md 品質チェックリスト:
□ 技術スタックとバージョンが明記されている
□ ディレクトリ構造の説明がある
□ コーディング規約（型・命名・エラー処理）が書かれている
□ よく使うコマンドが記載されている
□ 禁止事項・注意点が明確になっている
□ 200 行以内に収まっている（長すぎると逆効果）
□ 「なぜこのルールか」の背景が少なくとも重要なものに書かれている

実験設定:
タスク: 「新しい API エンドポイント /api/users/:id/preferences を実装して」

設定 A（最小コンテキスト）:
  - システムプロンプトのみ
  - ユーザー指示のみ

設定 B（最適化コンテキスト）:
  - CLAUDE.md（プロジェクト規約）
  - src/api/users.ts（既存エンドポイントの例）
  - src/types/user.ts（User 型定義）
  - docs/api-conventions.md（API 設計規約）

比較指標:
  1. コードの品質（型安全性・エラー処理・命名）
  2. 修正回数（1 発で完成するか）
  3. トークン消費量（コスト）

タスク: 「GitHub のオープン Issue を分析して優先度ランキングを作成する」

設計事項:
1. どのパターンを使うか（ReAct / Plan-and-Execute / Multi-Agent）
2. 必要なツールは何か（GitHub API / ファイル書き込み / ...）
3. 人間の関与レベルはどこか（レベル 1〜5）
4. 何をテストするか（タスク達成率 / 効率 / 安全性）

ヒント: Issue の数・複雑さ・結果のフォーマットを考慮してください。