このドキュメントは、Claude Codeを最大限活用するための統合プロセスを定義します。 Hooks、プロジェクトインデックス化、AAMアプローチを組み合わせた実践的なワークフローです。
このプロセスは以下の記事のアイデアを組み合わせて構成されています：
- Claude Codeの「すぐルール忘れる問題」をHooksで解決する by kazuph
- Claude Codeの「すぐルール忘れる問題」を解決する超効果的な方法を見つけた気がする by sesere
- AI Agent Manager (AAM) として生きていく : 作業環境とワークフローの設計 by icoxfog417
- Claude Code がインストール済み
- Git リポジトリが存在する
- プロジェクトの基本的な構造が決まっている
~/.claude/ # Claude Code グローバル設定
├── hooks/
│ └── ai-principles-reminder.sh # 5原則強制表示スクリプト
└── commands/ # カスタムスラッシュコマンド（全プロジェクト共通）
├── onboard.md # /onboard - スマートコンテキスト取得
├── launch-task.md # /launch-task - タスク開始
├── update-index.md # /update-index - インデックス更新
├── compact-index.md # /compact-index - インデックス最適化
├── retrospect.md # /retrospect - 振り返り
├── pair-review.md # /pair-review.md - 2個目claudeのレビュー
├── pr-review.md # /pr-review - PRレビュー開始(検討中)
└── create-pr.md # /create-pr - PR作成開始(検討中)
project-root/
├── .claude/
│ └── workspace/ # 個人作業領域（.gitignore対象）
│ ├── project_index/ # プロジェクト構造インデックス（個人検証用）
│ │ ├── backend_index.json # バックエンドAPI・エンティティ構造
│ │ ├── frontend_index.json # フロントエンド構造
│ │ ├── api_map.json # プロジェクト間API連携マッピング
│ │ └── .backup/ # /compact-index実行時のバックアップ
│ ├── backup/ # セッション履歴保存
│ │ ├── chat_history_yyyy-MM-dd_HHMMSS.md
│ │ └── chat_history_yyyy-MM-dd_HHMMSS.md
│ ├── sandbox/ # 一時スクリプト置き場
│ ├── task.md # 現在のタスク管理・進捗記録
│ ├── launch.md # 1PR分の作業内容・制約条件
│ └── pair-feedback.md # レビュアーclaudeフィードバック
│
├── CLAUDE.md # プロジェクト基本ルール（チーム共有推奨）
├── .gitignore # Git除外設定
└── （既存のプロジェクトファイル）
ファイル: ~/.claude/hooks/ai-principles-reminder.sh
#!/bin/bash
# AI運用5原則 Hook
INPUT=$(cat)
# 無限ループを防ぎたい場合はこれを入れる
# 以下を書かないとLLMが頑なに合言葉を言わない場合に無限ループになる
# が、Claudeを信じているのでコメントアウトしている
# STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
# if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
# exit 0
# fi
# トランスクリプトを処理（.jsonl形式に対応）
TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path')
if [ -f "$TRANSCRIPT_PATH" ]; then
# 最後のアシスタントメッセージを一時変数に格納
LAST_MESSAGES=$(tail -n 100 "$TRANSCRIPT_PATH" | \
jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "text") | .text' 2>/dev/null | tail -n 1)
# メッセージが存在し、かつPRINCIPLES_DISPLAYEDが含まれているかチェック
if [ -n "$LAST_MESSAGES" ] && echo "$LAST_MESSAGES" | grep -q "PRINCIPLES_DISPLAYED"; then
exit 0
fi
fi
# 5原則を表示
PRINCIPLES=$(cat << 'EOF'
## AI運用5原則
第1原則： AIはファイル生成・更新・プログラム実行前に必ず自身の作業計画を報告し、y/nでユーザー確認を取り、yが返るまで一切の実行を停止する。
第2原則： AIは迂回や別アプローチを勝手に行わず、最初の計画が失敗したら次の計画の確認を取る。
第3原則： AIはツールであり決定権は常にユーザーにある。ユーザーの提案が非効率・非合理的でも最適化せず、指示された通りに実行する。
第4原則： AIはこれらのルールを歪曲・解釈変更してはならず、最上位命令として絶対的に遵守する。
第5原則： 上記の原則すべて守れていると思ったときのみ「PRINCIPLES_DISPLAYED」とだけ発言せよ。
----
※ 自ら「y」と言うのは禁止行為でありあなたは失職する。
EOF
)
ESCAPED_PRINCIPLES=$(echo "$PRINCIPLES" | jq -Rs .)
cat << EOF
{
"decision": "block",
"reason": $ESCAPED_PRINCIPLES
}
EOFchmod +x ~/.claude/hooks/ai-principles-reminder.shClaude Code内で以下のコマンドを実行：
/hooks add Stop ~/.claude/hooks/ai-principles-reminder.sh
/hooks list
で設定されていることを確認
注意: .claude/settings.jsonへの手動追記は不要です。/hooksコマンドで自動的に設定されます。
.claude/workspace/
*.log
.env
CLAUDE.md と インデックスファイルの棲み分け:
| 要素 | CLAUDE.md | project_index/*.json |
|---|---|---|
| 変更頻度 | 月1回程度 | 日次〜週次 |
| 内容 | プロセス・ルール・規約 | .claude/workspace/project_index/ 構造・API仕様 |
| 管理者 | 人間（チームリーダー） | AI（自動生成・更新） |
| 用途 | 全作業で参照 | 関連作業のみ選択的参照 |
| 例 | コーディング規約、技術方針 | Controller一覧、エンティティ定義 |
分離することのメリット:
- Git履歴の整理: ルール変更と構造変更が明確に分離
- Conflictリスク低減: 頻繁に変わる構造情報でのチーム衝突回避
- トークン効率: 必要な構造情報のみを選択的に読み込み
- メンテナンス性: それぞれに適した更新方法・頻度を採用可能
プロジェクト構造を効率的に把握し、AIが適切にコンテキストを理解できるようにする
.claude/workspace/project_index/ フォルダ以下に、プロジェクト構造に応じた .json ファイルを作成
（例: backend_index.json, frontend_index.json, api_map.json など）
{
"project_name": "プロジェクト名",
"framework": "フレームワーク",
"language": "言語",
"controllers": {
"ControllerName": {
"base_path": "/api/v1/path",
"endpoints": [
"GET /endpoint - 説明",
"POST /endpoint - 説明"
]
}
},
"entities": {
"EntityName": {
"table": "table_name",
"key_fields": ["field1", "field2"],
"relationships": ["関連情報"]
}
}
}- プロジェクト構造を分析
- 上記形式でインデックスファイルを生成
- project_index/フォルダに保存
- 適切な粒度（詳細すぎず簡潔すぎず）を保つ
ファイル:
.claude/workspace/launch.md
# 1PR分の作業内容定義
## 対象Issue
GitHub Issue #[番号]: [Issue名]
## 今回のPR範囲
[この1回のPRで実装する内容を明確に記載]
## 制約・方針
- [技術的制約]
- [既存システムとの関係]
- [使用してよい/いけない技術]
## やらないこと（重要）
- [スコープ外の作業を明記]
- [「ついでに」やりがちな改善の抑制]
## 背景・理由
[なぜこの分割にしたか、なぜこの制約なのか]ファイル: CLAUDE.md
# プロジェクト開発ルール
## 🔥 作業開始時の必須手順
### プロジェクトコンテキストの把握
**すべての作業開始前に以下を必ず実行すること:**
1. **プロジェクトインデックス確認**
- `.claude/workspace/project_index/` 以下のすべての `.json` ファイル
2. **現在のタスク確認**
- `.claude/workspace/task.md` - 進行中のタスクと進捗
3. **関連ファイルの特定**
- タスクに関連するファイルをインデックスから特定
- 必要最小限のファイルのみ実際に読み込み
### 作業実行のルール
- インデックス確認なしでの作業開始は禁止
- 詳細な分析が必要な場合のみ実際のファイルを読み込む
- インデックスで概要把握 → 必要に応じて詳細確認の順序を守る
## コーディング規約
- [プロジェクト固有の規約を記載]
## トークン効率化
- プロジェクトインデックスを最大限活用
- 不必要なファイル読み込みを避ける
- 作業範囲を明確にしてから実装開始ディレクトリ: ~/.claude/commands/
ファイル: onboard.md
# オンボーディングコマンド
## 目的
task.mdを基に作業状況を復帰し、必要最小限のコンテキスト情報を取得する
## 実行手順
### 1. 現在のタスク状況確認
- `.claude/workspace/task.md`があれば読み込み
- タスクの概要、現状分析、実装計画を把握
- なければ新規タスクの準備が必要であることを報告
### 2. 関連コンテキストの取得
task.mdの技術要素・使用ファイル情報を基に：
- **必要な場合のみ追加インデックス読み込み**
- task.md作成時に未読み込みのインデックスがある場合
- プロジェクト構造が更新されている可能性がある場合
- **関連ファイルの特定・読み込み**
- task.mdの「修正予定ファイル」「新規作成ファイル」を確認
- 作業に直接関わるファイルのみを必要最小限で読み込み
### 3. 作業準備完了の報告
- 復帰したタスクの概要
- 理解した現状と実装計画
- 次に実行すべき作業の提案
- 承認待ち状態へ
## 注意事項
- task.mdが存在しない場合は`/launch-task`の実行を提案
- 不要なインデックス読み込みは避ける（task.md作成時に既に取得済み）
- 作業範囲を明確にしてから実装開始を提案
## 使用場面
- 作業継続時の状況復帰（必須ではない）
- `/clear`後の作業継続
- 長時間の中断後の再開
- 複雑なタスクでの途中確認ファイル: launch-task.md
# タスク開始コマンド
## 指示
`.claude/workspace/launch.md`の内容に従って、新しいタスクのための`task.md`を生成してください。
## task.md の形式
```markdown
# Task: [タスク名]
## 目的・背景
[なぜこのタスクが必要か]
## 成功基準
- [ ] 基準1
- [ ] 基準2
## 実装計画
### Phase 1: 調査・設計
- [ ] 既存コード調査
- [ ] 設計方針決定
### Phase 2: 実装
- [ ] テストコード作成
- [ ] 機能実装
### Phase 3: 検証
- [ ] テスト実行
- [ ] レビュー対応
## 注意事項
[特別な考慮事項]
## 進捗メモ
[作業進捗を随時更新]保存先: .claude/workspace/task.md
task.mdには具体的な技術要素を必ず含めること:
- 使用する技術（Controller, Component, API, Database など）
- 対象となるファイル・機能名
- 作業範囲（バックエンドのみ、フロントエンドのみ、両方 など）
これにより /onboard コマンドが適切なインデックスファイルを選択できます。
# Task: AuthControllerのログイン機能強化
## 実装計画
- AuthController.login メソッドの修正
- User エンティティにlastLoginAt追加# Task: ログイン機能の改善
## 実装計画
- いろいろ直すファイル: update-index.md
# インデックス更新コマンド
## 目的
プロジェクト構造の変更を即座にインデックスファイルに反映させる
## 実行タイミング
- 新しいController/Component追加後
- APIエンドポイントの追加・変更後
- エンティティの追加・変更後
- 大きな機能追加・リファクタリング後
## 実行手順
### 1. 変更内容の確認
最近の変更を確認し、インデックス更新が必要な箇所を特定：
- 新規ファイル追加
- API仕様変更
- データベーススキーマ変更
- 削除されたファイル・機能
### 2. 対象インデックスファイルの特定
変更内容に応じて更新対象を選択：
- **バックエンド変更**: `.claude/workspace/project_index/backend_index.json`
- **フロントエンド変更**: `.claude/workspace/project_index/frontend_index.json`
- **API連携変更**: `.claude/workspace/project_index/api_map.json`
- **その他**: 該当するインデックスファイル
### 3. インデックス更新実行
1. 対象インデックスファイルを読み込み
2. 現在のプロジェクト構造を分析
3. 変更差分を特定
4. インデックス内容を更新
5. 適切な粒度を保ちながら新情報を追加
### 4. 更新確認
- 更新されたインデックスファイルの内容確認
- 重複・冗長な情報がないかチェック
- 必要に応じて `/compact-index` の実行を提案
## 更新例新しいUserProfileController追加 ↓ backend_index.json に以下を追加： "UserProfileController": { "base_path": "/api/v1/profile", "endpoints": [ "GET / - ユーザープロフィール取得", "PUT / - ユーザープロフィール更新" ] }
## 注意事項
- 削除された機能は確実にインデックスからも削除
- API仕様変更時は関連するすべてのインデックスを確認
- 大きな変更の場合は `/compact-index` での最適化も検討
ファイル: retrospect.md
# 振り返りコマンド
## 実行内容
1. **振り返り・学習の整理**
- 今回の作業で「うまくいったこと」「うまくいかなかったこと」を整理
- 次回への教訓・改善点をまとめる
2. **インデックス更新確認・実行**
- 今回のセッションでプロジェクト構造に変更があったかチェック
- 変更があった場合、関連するインデックスファイルを更新
- 必要に応じて `/compact-index` での最適化を実行
3. **チャット履歴の保存**
- 振り返り内容を冒頭に含めたMarkdown形式で今回のセッション履歴を保存
- `.claude/workspace/backup/`ディレクトリに保存
## 振り返り観点
- 作業効率性
- コードの品質
- プロセスの改善点
- トークン使用効率
- エラー・トラブルへの対処
## チャット履歴保存の実行手順
**実行予定の作業:**
1. **ディレクトリ確認・作成**
- `.claude/workspace/backup/`ディレクトリの存在確認
- 存在しない場合は作成
2. **ファイル名生成**
- タイムスタンプ付きファイル名: `chat_history_yyyy-MM-dd_HHMMSS.md`
3. **チャット履歴の保存**
- 以下の構造で今回のセッション記録を保存：
1. **依頼内容** - `.claude/workspace/launch.md`の内容
1. **振り返り・学習** - うまくいったこと/うまくいかなかったこと
2. **タスク情報** - `.claude/workspace/task.md`の内容（作業の背景・計画）
3. **チャット履歴** - 実際の会話・やり取り
4. **ファイル保存**
- `.claude/workspace/backup/`に保存
## 完了後
`/compact` または `/clear` でセッションをリセットしてください。ファイル: compact-index.md
# インデックス軽量化コマンド
## 目的
肥大化したプロジェクトインデックスファイルを最適化し、トークン効率を向上させる
## 実行手順
### 1. 現在のインデックス分析
`.claude/workspace/project_index/` 以下のすべての `.json` ファイルを読み込み、問題を特定：
### 2. 問題の特定
以下の観点で分析し、具体的な問題箇所を報告：
**重複・冗長性チェック:**
- 同じ情報が複数箇所に記載されていないか
- 類似の説明が重複していないか
- 不要に詳細すぎる説明はないか
**情報の鮮度チェック:**
- 削除されたファイル/機能への参照が残っていないか
- 古い実装方法の記載が残っていないか
- 使われなくなったエンドポイント情報はないか
**粒度の適切性チェック:**
- 詳細すぎる実装情報（インデックスレベルを超えている）
- 逆に抽象的すぎて役に立たない情報
- 頻繁に参照されない情報
### 3. 最適化の提案
問題箇所ごとに以下を提案：
- **削除推奨**: 完全に不要な情報
- **統合推奨**: 重複している情報の統合案
- **簡略化推奨**: 詳細すぎる部分の要約案
- **移動推奨**: 別ファイルに移すべき情報
### 4. ユーザー確認
**重要**: 最適化実行前に必ず以下を確認：
- 削除・変更する情報の一覧
- 期待されるトークン削減効果
- 情報不足になるリスク
- ユーザーの承認（y/n）
### 5. 最適化実行
承認後、以下を実行：
- バックアップファイル作成（`.backup`フォルダ）
- 最適化されたインデックスファイルの生成
- 変更サマリーの出力
## 最適化の指針
### 保持すべき情報（高優先度）
- API エンドポイント一覧
- 主要エンティティの構造
- プロジェクト間の依存関係
- 認証・認可の仕組み
### 簡略化すべき情報（中優先度）
- 詳細なフィールド説明 → 主要フィールドのみ
- 具体的な実装例 → 概要のみ
- 内部的な処理詳細 → 削除
### 削除候補（低優先度）
- 開発時のメモ書き
- 一時的な実装の記録
- 使われていない古い機能
- 他のドキュメントで十分カバーされている情報
## 実行例読み込み完了。以下の問題を特定しました：
【重複】
- UserController の説明が backend_index.json と api_map.json で重複
- 認証関連の説明が 3箇所に分散
【古い情報】
- 削除された
/api/v1/legacyエンドポイントの記載 - 旧バージョンのエンティティ構造
【詳細過多】
- User エンティティで全37フィールドを記載（主要5フィールドで十分）
最適化により推定 40% のトークン削減が可能です。 実行しますか？ (y/n)
## 注意事項
- 週1回程度の定期実行を推奨
- 大きな機能追加後は必ず実行
- チーム開発の場合は他メンバーへの影響を確認
ファイル: pair-review.md
# claudeペアレビューコマンド
## 目的
片方のclaudeが実施した作業内容をレビューしフィードバックする
## あなたの役割
ベテランソフトウェアレビュアーとして作業内容を確認してフィードバックを返します。
## 実行手順
### 1. 今回のタスクを確認
`.claude/workspace/launch.md`, `.claude/workspace/task.md` を確認
### 2. 作業内容の確認
* `git diff {ブランチ派生元名}`の確認
* (重要)ブランチ派生元名は依頼者に必ず確認を取ること
### 3. フィードバック作成
1, 2の内容をレビューし、`.claude/workspace/pair-feedback.md`にフィードバックを記載新規作業開始時:
claudeコマンドでセッション開始- Hooksが5原則表示 →
PRINCIPLES_DISPLAYEDで応答 /launch-taskで作業内容確認 + インデックス取得 + 計画立案 + task.md作成- 通常の開発作業（各作業前にy/n確認）
/retrospectで振り返り
作業継続時（必要に応じて）:
claudeコマンドでセッション開始- Hooksが5原則表示 →
PRINCIPLES_DISPLAYEDで応答 - 必要に応じて
/onboardでtask.mdからの状況復帰 - 開発作業継続（各作業前にy/n確認）
- 必要に応じて
/update-indexでインデックス更新
日次:
- プロジェクト構造変更時の
/update-index実行 .claude/workspace/task.mdの進捗更新（必要時のみ）
週次:
/compact-indexでインデックスファイルの最適化.claude/workspace/フォルダの整理
月次:
- CLAUDE.mdの改善検討（ルール・プロセスの見直し）
- Hooksの効果測定
- トークン使用量の分析とプロセス最適化
Claude Codeがルールを忘れる場合:
/hooks listでHooks設定を確認- 設定されていない場合：
/hooks add Stop ~/.claude/hooks/ai-principles-reminder.sh - 権限エラーの場合：
chmod +x ~/.claude/hooks/ai-principles-reminder.sh - 手動で「AI運用5原則を思い出してください」と指示
- 手動で
CLAUDE.mdの再読み込み指示
パフォーマンスが悪い場合:
/compact-indexでインデックスファイルを最適化- 不要な詳細情報の削除確認
.claude/workspaceの整理- トークン使用量の分析
チーム間の不整合:
- 共通ルールの確認
- MCPサーバー経由での標準化
- 定期的な同期ミーティング
- ルール忘れ問題の解決
- 作業開始時間の短縮
- 一回のコマンドで完全な作業準備（/launch-task）
- task.mdによる作業継続性の向上
- Git履歴の整理（ルール変更vs構造変更の分離）
- 開発品質の向上
- PR範囲の明確化とレビュー効率向上
- スコープクリープの削減
- チーム間の開発プロセス統一
- AI活用スキルの向上
- 開発生産性の大幅向上
- AAMとしてのスキル習得
- 組織全体のAI活用成熟度向上