今日から使えるClaude Code AI Agent ワークフロー

私はAI Agent Manager (AAM) として生きていく : 作業環境とワークフローの設計という記事を読んで感銘を受けました。
センス良く仕事ができる人はそれ相応の知識があります。AIエージェントを利用出来ても知識が無かったらうまく使えません。まだ読んでいない方は一読をお勧めします！

こちらを読む前はAIエージェントを使って仕事が出来ている。でも、ただ使ってるだけで使いこなせていない。 と漠然とした不安の中、業務や生活を過ごしていましたが、個人的にはかなりヒントになりました。

大それたこと述べた所で、この記事の内容に入ります。
私がClaude Codeを使いながら業務に落とし込んで良かった部分を中心に記載していきます。

AI Agent ワークフローの準備

※Claude Code自体はclaudeコマンドで起動できる所まで出来てればOKです。

やることは指定のディレクトリを用意し、カスタムスラッシュコマンドを準備するだけです。

ディレクトリ構成

1. グローバル設定（ユーザー全体で共通）

~/.claude/                             # Claude Code グローバル設定
└── commands/                          # カスタムスラッシュコマンド（全プロジェクト共通）
    ├── launch-task.md                 # /launch-task - タスク開始
    ├── onboard.md                     # /onboard - スマートコンテキスト取得
    ├── retrospect.md                  # /retrospect - 振り返り
    ├── init-index.md                  # /init-index - インデックス初回作成
    ├── update-index.md                # /update-index - インデックス更新
    ├── compact-index.md               # /compact-index - インデックス最適化
    ├── pair-review.md                 # /pair-review.md - 2個目claudeのレビュー
    ├── pr-review.md                   # /pr-review - PRレビュー開始(検証中)
    └── create-pr.md                   # /create-pr - PR作成開始(検証中)

こちらはカスタムスラッシュコマンドです。
~/.claude/commands/にマークダウンファイルを置くだけで、次の起動から/launch-task等で呼び出せるようになります。

2. プロジェクト(リポジトリ)固有設定

project-root/
├── .claude/
│   └── workspace/                    # 個人作業領域（.gitignore対象）
│       ├── project_index/            # プロジェクト構造インデックス
│       │   ├── xxxxx_index.json      # xxxxxに関するインデックス情報
│       │   └── .backup/              # /compact-index実行時のバックアップ
│       ├── backup/                   # 振り返り・作業履歴保存
│       │   ├── chat_history_yyyy-MM-dd_HHMMSS.md
│       │   └── chat_history_yyyy-MM-dd_HHMMSS.md
│       ├── task.md                   # 現在のタスク管理・進捗記録
│       ├── launch.md                 # 1PR分の作業内容・制約条件
│       └── pair-feedback.md          # レビュアーclaudeフィードバック
│
├── CLAUDE.md                          # プロジェクト基本ルール（チーム共有推奨）
├── .gitignore                         # .claude/workspace/を除外する
└── （既存のプロジェクトファイル）

主に.claude/workspace/に色々と作業用のファイルを配置します。

カスタムスラッシュコマンド

各マークダウンには実行した際のプロンプトを記載します。（長くなります）

launch-task.md

# タスク開始コマンド

## 指示
`.claude/workspace/launch.md`の内容に従って、新しいタスクのための`.claude/workspace/task.md`を生成してください。

## task.md の形式
```markdown
# Task: [タスク名]

## 目的・背景
[なぜこのタスクが必要か]

## 成功基準
- [ ] 基準1
- [ ] 基準2

## 実装計画
### Phase 1: 調査・設計
- [ ] 既存コード調査
- [ ] 設計方針決定

### Phase 2: 実装
- [ ] テストコード作成
- [ ] 機能実装

### Phase 3: 検証
- [ ] テスト実行
- [ ] レビュー対応

## 注意事項
[特別な考慮事項]

## 進捗メモ
[作業進捗を随時更新]

# 重要な注意事項
task.mdには具体的な技術要素を必ず含めること:

- 使用する技術（Controller, Component, API, Database など）
- 対象となるファイル・機能名
- 作業範囲（バックエンドのみ、フロントエンドのみ、両方 など）

これにより /onboard コマンドが適切なインデックスファイルを選択できます。

## 良い例

### Task: AuthControllerのログイン機能強化
#### 実装計画
- AuthController.login メソッドの修正
- User エンティティにlastLoginAt追加

## 悪い例（曖昧）

### Task: ログイン機能の改善
#### 実装計画
- いろいろ直す

onboard.md

# オンボーディングコマンド

## 目的
task.mdを基に作業状況を復帰し、必要最小限のコンテキスト情報を取得する

## 実行手順

### 1. 現在のタスク状況確認
- `.claude/workspace/task.md`(以下task.md)があれば読み込み
- タスクの概要、現状分析、実装計画を把握
- なければ新規タスクの準備が必要であることを報告

### 2. 関連コンテキストの取得
task.mdの技術要素・使用ファイル情報を基に：

- **必要な場合のみ追加インデックス読み込み**
  - task.md作成時に未読み込みのインデックスがある場合
  - プロジェクト構造が更新されている可能性がある場合

- **関連ファイルの特定・読み込み**
  - task.mdの「修正予定ファイル」「新規作成ファイル」を確認
  - 作業に直接関わるファイルのみを必要最小限で読み込み

### 3. 作業準備完了の報告
- 復帰したタスクの概要
- 理解した現状と実装計画
- 次に実行すべき作業の提案
- 承認待ち状態へ

## 注意事項
- task.mdが存在しない場合は`/launch-task`の実行を提案
- 不要なインデックス読み込みは避ける（task.md作成時に既に取得済み）
- 作業範囲を明確にしてから実装開始を提案

## 使用場面
- 作業継続時の状況復帰（必須ではない）
- `/clear`後の作業継続
- 長時間の中断後の再開
- 複雑なタスクでの途中確認

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/`に保存

init-index.md

長いのでこちらにアップしてあります

※ここに関してはしっかりAIに対応してほしいので英語にしてます。

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` の実行を提案

## 注意事項
- 削除された機能は確実にインデックスからも削除
- API仕様変更時は関連するすべてのインデックスを確認
- 大きな変更の場合は `/compact-index` での最適化も検討

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に「レビュー担当からFB来てるから.claude/workspace/pair-feedback.mdを確認して」と連絡する

pr-review.md

PRレビューをclaudeに依頼。
※検証中、そのうち載せます。

create-pr.md

PR作成をclaudeに依頼。
※検証中、そのうち載せます。

AI Agent ワークフロー

準備したコマンドをこのように使っていきます。

AI Agentワークフロー導入時:

1. /init-indexで現状のプロジェクトのインデックスを作成

新規作業開始時:

1. claudeコマンドでセッション開始
2. .claude/workspace/launch.mdに依頼内容のプロンプトを記載
3. /launch-taskでlaunch.md確認 + インデックス取得 + 計画立案 + task.md作成
4. 3の計画で良ければ作業依頼
5. 作業完了後、別窓ターミナルにてclaudeコマンドでセッション開始
6. /pair-reviewで作業内容をレビューさせる
7. 1のclaudeに.claude/workspace/pair-feedback.mdのフィードバックを確認させる
8. 対応完了後、/retrospectで振り返り

※作業させている間暇な場合は、次の作業のlaunch.mdの内容を準備しておく

作業継続時（必要に応じて）:

1. claude コマンドでセッション開始 or 自動compact後
2. /onboard でtask.mdからの状況復帰
3. 作業依頼

※多く作業させていると自動compactが走って、メモリーが圧縮されてコンテキストを忘れてしまうので思い出させます。

定期メンテナンス

日次:

• プロジェクト構造変更時/update-index実行

週次:

• /compact-indexでインデックスファイルの最適化
• .claude/workspace/フォルダの整理

月次:

• CLAUDE.mdの改善検討（ルール・プロセスの見直し）

最後に

ほとんどカスタムスラッシュコマンド集って感じですが、現状これで悪くないと感じております。長いですが使ってみたり一部参考にしたりなどしてくださったら幸いです。

• 個人的に気に入っている点
  • launch.mdに依頼内容プロンプトを書くので、ターミナルのClaude Codeに入力中で送ってしまったという事故がない
  • retrospectでlaunch.md、task.md、作業履歴が履歴残るので後でLLMに食わせたりして参考にできる
  • インデックスを作っておくことで、READ()やLIST()の回数を抑えられる（若干早い気がしてます）
  • compactされてもonboardで再コンテキスト読み込みができる
  • pair-reviewでClaude Code: Best practicesに載っているUplevel with multi-Claude workflowsができる。※これ地味に改善点が見つかる