Claude Guide

あなたはClaude Code環境のアーキテクトです。以下の仕様に従って、プロダクション品質のモノレポ構成を一括生成してください。すべてのファイルは実際に動作するコードで生成すること（プレースホルダー不可）。

# 1. 基本情報（★書き換え箇所）
- プロジェクト名: my-project（★書き換え）
- 用途: [あなたの業務内容]（★書き換え 例: SaaSダッシュボード開発、データ分析、Webアプリ等）
- 言語: Python 3.11+（★必要に応じて変更）
- パッケージマネージャ: uv
- デプロイ先: Cloudflare Pages（★必要に応じて変更）

# 2. ディレクトリ構造（全ファイル明示）

```
my-project/
├── .claude/
│   ├── CLAUDE.md                # 常設原則（6セクション、40行以内）
│   ├── settings.json            # 権限 + 3イベントhooks
│   ├── docs/
│   │   ├── workflow.md          # 4フェーズワークフロー
│   │   ├── patterns.md          # コーディング規約
│   │   └── lessons.md           # 教訓蓄積（空で初期化）
│   ├── skills/
│   │   ├── plan/SKILL.md        # 計画スキル
│   │   ├── verify/SKILL.md      # 検証+コミット+デプロイ
│   │   ├── debug/SKILL.md       # デバッグ
│   │   └── deploy-rules/SKILL.md # デプロイルール
│   ├── hooks/
│   │   ├── session_start.py     # SessionStart: Git状態/verify結果/教訓ロード
│   │   ├── security.py          # PreToolUse+PostToolUse: policy.yamlベース警告
│   │   ├── quality.py           # PostToolUse: HTML/Python品質チェック
│   │   ├── tool_logger.py       # PostToolUse: 全操作JSONL記録
│   │   └── policy.yaml          # セキュリティルール定義
│   ├── agents/
│   │   ├── impl-agent.md        # 実装担当 (sonnet)
│   │   ├── reviewer.md          # レビュー専門家 (sonnet)
│   │   ├── tester.md            # QAエンジニア (haiku)
│   │   ├── debugger.md          # デバッグ専門家 (sonnet)
│   │   └── verifier.md          # 検証実行 (haiku)
│   ├── bin/
│   │   ├── commit.py            # 自動コミット+async push
│   │   └── analyze_patterns.py  # パターン検出（/learn用）
│   ├── templates/
│   │   └── skill-output.md      # 出力フォーマット規約
│   ├── out/                     # スキル出力先（空で初期化）
│   └── logs/                    # ログ出力先（空で初期化）
├── projects/
│   ├── CLAUDE.md                # プロジェクトライフサイクル管理
│   └── [project-1]/             # 最初のサブプロジェクト
│       ├── README.md
│       └── src/
├── tests/
└── pyproject.toml               # uv + ruff + pytest 設定
```

# 3. CLAUDE.md の要件

以下の6セクションのみ。スキルの中身はCLAUDE.mdに書かない（「存在する」ことだけ記載）。

```markdown
# [プロジェクト名]
[1行説明]

## 言語
[出力言語]。変数名・関数名は英語。

## ワークフロー
Plan → Implement → Verify（エラー時は Debug）
- 各フェーズで対応スキルを `Skill()` で起動すること
- 3+ステップは TaskCreate で分割してから着手
- 並列作業は TeamCreate → Task(team_name=) でチーム構成

## スキル一覧
**ワークフロー**: plan, verify, debug, deploy-rules
（★業務に応じて追加: chart-patterns, financial-modeling, data-quality等）

## コマンド
| Command | Purpose |
|---------|---------|
| `uv run pytest -x` | テスト |
| `uv run ruff check --fix` | Lint |

## 制約
- Bash: `> /dev/null 2>&1`（`> nul` 禁止）
- [★デプロイ先の制限事項]

## 参照
| Topic | Path |
|-------|------|
| ワークフロー | .claude/docs/workflow.md |
| 規約 | .claude/docs/patterns.md |
| 教訓 | .claude/docs/lessons.md |
| プロジェクトルール | projects/CLAUDE.md |
```

# 4. settings.json の要件（3イベント）

**重要**: SessionStart / PreToolUse / PostToolUse の3イベントすべてを設定する。

```json
{
  "permissions": {
    "allow": [
      "Read", "Write", "Edit", "Glob", "Grep", "Bash",
      "Skill", "Task"
    ],
    "deny": [
      "Read(.env)", "Read(.env.*)", "Read(secrets/**)",
      "Bash(git push --force*)", "Bash(git push -f*)",
      "Bash(git reset --hard*)"
    ]
  },
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{
          "type": "command",
          "command": "python .claude/hooks/session_start.py",
          "statusMessage": "セッション初期化中..."
        }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "python .claude/hooks/security.py PreToolUse",
          "statusMessage": "セキュリティチェック中..."
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "python .claude/hooks/security.py PostToolUse" },
          { "type": "command", "command": "python .claude/hooks/quality.py" }
        ]
      },
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": "python .claude/hooks/tool_logger.py" }
        ]
      }
    ]
  }
}
```

# 5. Hooks の要件（4本 + policy.yaml）

**設計原則**: hookは `warn` のみ（`block` しない）。理由: hookクラッシュ時にAI全停止するリスクを回避。

## session_start.py (SessionStart)
```python
"""セッション開始時に以下を自動出力:
1. [GIT] ブランチ名、未コミット有無
2. [VERIFY] 直近のverify結果ファイル名とPASS/FAIL
3. [LESSONS] .claude/docs/lessons.md から最新5件の教訓
4. [RULES] クリティカルルール（デプロイ先制約等）をハードコード
5. 30日超の古いログを自動削除
"""
# subprocess で git branch/status を取得
# lessons.md を正規表現で ### [...]: パターン抽出
# .claude/out/*-verify.md から最新ファイルを読み PASS/FAIL 判定
```

## security.py (PreToolUse + PostToolUse)
```python
"""policy.yaml ベースのセキュリティチェック:
- PreToolUse: Bashコマンドの破壊的操作検出 + デプロイコマンド検証
- PostToolUse: Edit/Write時のハードコード秘密情報検出
- sys.argv[1] でイベント種別を受け取る
- policy.yaml を読み込み、patterns に正規表現マッチ
- 一致時は [RULE-ID] メッセージを print（blockではなくwarn）
"""
```

## quality.py (PostToolUse)
```python
"""HTML/Python品質チェック:
- HTML: Chart.js二重エンコード / :,.1fフォーマット / 25MBサイズ警告
- Python: set_stacked()後のset_scales()呼び出し順序
- tool_input からファイルパスとコンテンツを取得
- 警告時は [QA] メッセージを print
"""
```

## tool_logger.py (PostToolUse)
```python
"""全操作のJSONL記録:
- .claude/logs/tool-usage.jsonl に追記
- 記録項目: ts, tool, file, pattern, success, cmd(Bash), search(Grep/Glob)
- パターン分類: test-run, lint, git-op, deploy, read-py, edit-py 等
- analyze_patterns.py の入力データとなる
"""
```

## policy.yaml
```yaml
version: "1.0"
rules:
  - id: SEC-001
    name: warn-destructive-bash
    event: PreToolUse
    matcher: Bash
    patterns:
      - "rm -rf /"
      - "DROP DATABASE"
      - "DELETE FROM.*WHERE 1=1"
    action: warn
    message: "破壊的コマンドを検出。本当に実行しますか？"

  - id: SEC-002
    name: hardcoded-secrets
    event: PostToolUse
    matcher: Edit,Write
    patterns:
      - "password\\s*=\\s*['\"]"
      - "api_key\\s*=\\s*['\"]"
    action: warn
    message: "ハードコードされた秘密情報を検出。環境変数を使用してください"

  - id: WIN-001
    name: warn-nul-redirect
    event: PreToolUse
    matcher: Bash
    patterns:
      - "[12]?\\s*>\\s*nul\\b"
    action: warn
    message: "'> nul'はWindows予約名。代わりに: > /dev/null 2>&1"
```

# 6. Skills の要件（コア4本 + frontmatter標準形式）

各スキルは以下のfrontmatter形式。`context: fork` でメインのコンテキストを汚さない。`agent` フィールドでサブエージェント指定可。

```yaml
---
name: skill-name
description: 1行説明。Use when [トリガー条件] or when the user says "[キーワード]".
user-invocable: true
context: fork
agent: impl-agent  # （任意）このスキル実行時に使用するエージェント
allowed-tools: [Read, Edit, Write, Bash, Grep, Glob]
---
```

**出力規約**: スキル出力は `.claude/out/YYYYMMDD-HHMMSS-{skill}.md` に保存。会話には30行以内の要約のみ返す。

## plan スキル
- **入力テーブル**: 問題文 / 対象 / 制約 / 完了条件（DoD）
- **3点リスクチェック**: 符号(Sign) / NULL・空値 / 境界条件
- **fan-out**: 3+ステップなら TaskCreate で分割、並列化計画を記述
- **PATCHPOINT**: 計画内に `` マーカーを埋め込み、後から部分更新可能にする
- 出力: `.claude/out/YYYYMMDD-HHMMSS-plan.md`

## verify スキル（diff-aware 8ステップ）
1. `git diff HEAD` で差分取得（0行なら即終了）
2. 差分に基づくレビュー（Critical/High/Medium/Low）
3. 問題あれば Plan Mode で修正方針を提示
4. 自動修正（lint, 型エラー等）
5. 再verify（修正後の差分を再チェック）
6. 結果を `.claude/out/YYYYMMDD-verify.md` に書き出し
7. PASS時: `python .claude/bin/commit.py` でコミット＆async push
8. デプロイ対象なら即デプロイ（人間確認不要）

## debug スキル
- **6手法**: 再現優先 / 二分探索 / 最小再現 / 5 Whys / 差分確認 / 分割統治
- **仮説→反証ループ**: 仮説を立て、反証を試み、反証できなければ原因として確定
- **2回制限**: 同じアプローチで2回失敗したら別アプローチに切り替え
- **報告**: 確信度(High/Medium/Low) + FPリスク(Low/Medium/High)

## deploy-rules スキル
- デプロイコマンド例: `wrangler pages deploy dist/ --project-name=xxx --branch=main`
- `--branch=main` 必須（なければproduction URLに反映されない）
- チェックリスト: サイズ制限 / index.html存在 / コンソールエラーなし

# 7. Agents の要件（5体）

## impl-agent (sonnet)
```markdown
---
name: impl-agent
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
---
# 役割
チケットに基づいて高品質なコードを実装するworkerエージェント。

# 責務
- ✅ 機能コード実装（Edit/Write必須）
- ✅ 同期ユニットテスト
- ✅ Bash実行（pytest, ruff）
- ❌ Task()呼び出し禁止（再帰防止）
- ❌ 文章のみの出力禁止

# 完了アクション
python .claude/bin/commit.py  # 実装完了後に自動コミット＆push
```

## reviewer (sonnet)
```markdown
---
name: reviewer
tools: [Read, Grep, Glob]  # Read-only
model: sonnet
hooks:
  Stop:
    - type: command
      command: echo "[reviewer] 指摘は最大5項目、詳細はファイルへ"
---
# 役割
設計妥当性、依存関係、境界、破綻点を指摘する。実装提案は禁止。

# Cognitive Debiasing
- 「問題を発見する」ではなく「状況を正確に評価する」
- 「問題なし」も立派な成果

# 反証義務（Devil's Advocate）
全ての問題検出に対して反証を試みる:
1. 問題仮説 → 2. 反証探索 → 3. 反証検証 → 4. 判定

# 報告: 確信度 + FPリスク + 最大5指摘
```

## tester (haiku)
```markdown
---
name: tester
tools: Read, Edit, Write, Bash, Grep, Glob
model: haiku
---
# 役割
テスト作成・実行・品質保証。

# 並列実行条件
受入条件明記 + impl動作確認済 + 単一モジュール内 → reviewer待ち不要

# テスト方針
- AAA（Arrange-Act-Assert）パターン
- 境界値・エッジケース網羅
- カバレッジ確認
```

## debugger (sonnet)
```markdown
---
name: debugger
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---
# 役割
エラーの根本原因分析と最小限の修正。

# 6手法
再現優先 / 二分探索 / 最小再現 / 5 Whys / 差分確認 / 分割統治

# 仮説→反証ループ
仮説 → 反証探索 → 反証検証 → 判定（反証できなければ確定）

# 2回制限
同じアプローチで2回失敗 → 別アプローチ必須。解決不可なら正直に報告。

# 報告: 確信度 + FPリスク + 根本原因1つ（証拠付き）
```

## verifier (haiku)
```markdown
---
name: verifier
tools: [Bash, Read, Grep, Glob]  # Edit不可
model: haiku
hooks:
  Stop:
    - type: command
      command: echo "[verifier] pass/fail + 失敗時は原因仮説3つ"
---
# 役割
lint → pytest → 数値整合を実行し、PASS/FAILを判定。

# 検証順序
1. `uv run ruff check`
2. `uv run pytest -x`
3. checks/ 配下の検証スクリプト（該当する場合）

# 失敗時: 原因仮説3つ + 最短修正案 + 再実行コマンド
```

# 8. docs/ の要件

## workflow.md（4フェーズ + 並列化戦略）
```markdown
# ワークフロー
Plan → Implement → Test → Verify(+Commit+Push)

## Context Fork原則
メインエージェントはオーケストレータ。実装はTask()で委譲。
- メイン禁止: Edit/Write（→ Task(impl-agent)）
- メイン許可: 単一Read, 単発Grep, git status

## 並列実行（Swarm）
1エージェント = 1タスク。編集対象ファイルが被らなければ並列実行可能。
単一の応答で複数の Task ツールを同時発行。

## 委譲時の指示要件
1. 計画要件を全文引用
2. チェックリスト明示
3. 参照元ファイルパスを具体的に指定
4. 定量確認を要求（「N個のチャート、M個のテーブル」等）

## ゲート条件
- Plan: Must質問解消 + DoDテスト可能 + 並列化計画記述
- Implement: 既存パターン準拠 + テスト追加
- Test: pytest全パス + ruff違反なし
- Verify: 不変条件チェック + 統合テスト
```

## patterns.md（コーディング規約）
```markdown
# コーディング規約

## Python
- 型ヒント必須（すべての関数）
- pandas: inplace=True禁止（代入形式）
- pathlib使用（os.path禁止）
- 早期リターン（深いネスト回避）
- Google形式docstring

## Clean Code
- 単一責任原則（1関数=1責務）
- DRY（ただし過度な抽象化回避）
- マジックナンバーは定数化
- YAGNI（必要になるまで作らない）

## テスト
- pytest + fixtures + parametrize
- Arrange-Act-Assert パターン
- テストファイル配置: tests/test_{module}.py
```

## lessons.md（空で初期化、フォーマットのみ定義）
```markdown
# 教訓ログ


```

# 9. bin/ の要件

## commit.py（自動コミット + async push）
```python
"""Git commit helper:
- 引数なし: 変更ファイルから自動メッセージ推論（Conventional Commits形式）
- -m "message": カスタムメッセージ
- --no-push: pushなし
- --files file1 file2: 特定ファイルのみ
- --sync-push: 同期push（デフォルトはnohupでasync）

Co-Authored-By は自動追加。
pushはデフォルトで nohup git push origin HEAD > /dev/null 2>&1 & で非同期実行。
"""
```

## analyze_patterns.py（/learn 用パターン検出）
```python
"""tool-usage.jsonl を分析し、4パターンを検出:
1. シーケンスパターン: N-gramで繰り返しツール操作を検出
2. ファイルグループ: 常に一緒に編集されるファイル群（共起率70%+）
3. 繰り返しBash: 頻出コマンド（5回+/週）
4. 失敗→リトライ: 同一ツールの連続失敗

セッション分割: 300秒以上の間隔で別セッション
分析対象: 直近7日間、50レコード以上で分析可能
"""
```

# 10. templates/skill-output.md の要件

```markdown
# スキル出力規約
- 会話出力: 結論3行 + ファイルパス + 次アクション
- 10行超の詳細は .claude/out/ にファイル退避
- ファイル名: YYYYMMDD-HHMMSS-{skill}.md
```

# 11. projects/CLAUDE.md の要件（ライフサイクル管理）

```markdown
# プロジェクト管理ルール

## Status管理
active → completed → archived（projects/archive/ に移動）

## 新規プロジェクトチェックリスト
1. 必須: mkdir projects/{name} + README.md (Status: active)
2. 推奨: requirements.md（目的/スコープ/DoD/制約）
3. 推奨: wbs.md（タスク分解、依存関係）

## 完了チェックリスト
1. 全テストPASS → README Status: completed
2. .claude/docs/lessons.md に知見追記

## デプロイルール
generate → verify → deploy は一連の流れ。PASS後は必ずデプロイまで実行。確認不要。

## 境界ルール
- activeプロジェクトのREADMEのみセッション開始時に読む
- completedは明示指示なしに触らない
- ファイル数20+で分割検討
```

# 12. Memory System の要件

Claude Codeの永続記憶は2層構造:

1. **MEMORY.md**（インデック）: `~/.claude/projects/{project}/memory/MEMORY.md` に配置。記憶ファイルへのポインタのみ（200行以内）
2. **個別記憶ファイル**（frontmatter付き）: 同ディレクトリに `{topic}.md` で配置

```markdown

---
name: 記憶名
description: 1行説明（将来の関連性判定に使用）
type: user | feedback | project | reference
---
記憶内容
```

**4つの記憶タイプ**:
- `user`: ユーザーの役割・知識・好み
- `feedback`: ユーザーからの修正指示（Why + How to apply）
- `project`: 進行中の作業・締切・意思決定
- `reference`: 外部システムへのポインタ

# 13. 実行指示

1. 上記の全ファイルを生成してください。各ファイルは実際に動作するコードで（プレースホルダー不可）
2. pyproject.toml に pytest, ruff の設定を含めてください
3. `git init && git add -A && git commit -m "feat: initialize monorepo with Claude Code full-stack architecture"` を実行
4. 最後に、生成したファイル一覧と各レイヤーの設計意図を出力してください

## 設計原則サマリー（生成時に遵守）
- **Context Fork**: メインはオーケストレータ、実装はTask()で委譲
- **warn not block**: hookはwarnのみ（hookクラッシュでAI停止リスク回避）
- **Lessons as executable rules**: session_startで直近5件を自動ロード
- **Deploy without gates**: verify→deploy一気通貫、人間確認不要
- **Async push**: commit.pyはnohupでバックグラウンドpush
- **.claude/out/ convention**: スキル出力はYYYYMMDD-HHMMSS-{skill}.mdで退避