Claude Codeエージェント実践 Day 1｜自分専用エージェントを払い出す仕組みを作った
TL;DR
- Claude Code を8ヶ月使い込んで、「自分専用のエージェントを量産する仕組み」 を作った
-
/new-agent データ分析エージェント ~/projects/data-analystで払い出せる - 28日間かけて、データ分析・ワークフロー・レポーティングの専門エージェントを育てていく
作ったもの
GitHub: akira-cloudjob-public/agent-scaffold-factory
agent-scaffold-factory/
├── CLAUDE.md ← エージェント管理者定義
├── .claude/commands/
│ └── new-agent.md ← 払い出しコマンド
└── src/
├── agent-framework/ ← 汎用エージェントテンプレート
│ ├── CLAUDE.md
│ ├── .claude/commands/
│ ├── templates/
│ └── knowledge/
└── agent-management/
└── エージェント管理簿.md
「とりあえず動かしたい」という方は、上のリポジトリをフォークして /new-agent を試してみてください。以下、8ヶ月の試行錯誤で得た設計思想を共有します。
はじめに：なぜこのシリーズを書くのか
「また同じ説明してる...」
Claude Code を業務で使い始めて数ヶ月。ふと気づくと、同じ説明を何度も繰り返していました。
「このプロジェクトではTypeScriptを使っていて、テストはJestで、デプロイはVercelで...」
新しいセッションを開くたびに、この説明から始まる。
そこで CLAUDE.md を書き始めました。プロジェクトのルールを書いておけば、Claude Code が読んでくれる。これで毎回の説明が不要になる。
最初は「これで解決した！」と思いました。確かに、毎回の説明は不要になった。
でも1ヶ月使って気づいたんです。新しい問題が生まれていることに。
正直なところ、自分一人で使うだけなら、フォルダを作って思うがままに作業すれば十分です。CLAUDE.md を書いて、あとは好きにやればいい。
でも、チームメンバーに展開することを考えたとき、話が変わりました。
「独立したエージェント」として渡せる形にしておくと、メンバーが迷わない。セットアップの説明も、使い方の説明も、シンプルになる。
これが「エージェントを払い出す仕組み」を作った理由です。
8ヶ月で学んだこと
第1段階：CLAUDE.md を書けばいい？
最初は「CLAUDE.md に全部書けばいい」と思っていました。
# CLAUDE.md
- TypeScriptを使う
- テストはJest
- コミットメッセージは Conventional Commits
- ...
しかし、すぐに問題が出てきます。
問題1: どこまで書けばいいかわからない
書き始めると際限がない。結果、1000行を超える CLAUDE.md ができあがりました。
問題2: プロジェクトごとに書き直し
新しいプロジェクトを始めるたびに、CLAUDE.md を一から書く。前のプロジェクトからコピペしても、微妙に合わない部分がある。
問題3: 成長しない
Claude Code と対話して「ああ、こう伝えればよかったのか」と気づいても、それが次のセッションに活かされない。毎回同じ失敗を繰り返す。
第2段階：テンプレート化の試み
「じゃあテンプレートを作ろう」と考えました。
- 汎用的な部分をテンプレートに
- プロジェクト固有の部分だけ追記
これでコピペの手間は減りました。でも、まだ問題がありました。
問題4: テンプレートがどんどん増える
「データ分析用」「フロントエンド用」「バックエンド用」...
気づけばテンプレートが10個以上。どれを使えばいいかわからなくなる。
問題5: 学んだことが散らばる
あるプロジェクトで「こう書くとうまくいく」と発見しても、他のテンプレートに反映されない。知識が散らばって、活用できない。
第3段階：エージェントという考え方
ここで発想を転換しました。
「CLAUDE.md」を書くのではなく、「エージェント」を育てる。
エージェントとは：
- 特定の仕事ができる「専門家」
- 自分の行動ルールを持っている
- 経験から学んで成長する
つまり、CLAUDE.md は「設定値を並べるファイル」ではなく「AIの振る舞いを定義するファイル」なのです。
この考え方に切り替えてから、いろいろなことがうまくいくようになりました。
agent-scaffold-factory の設計思想
8ヶ月の試行錯誤で、4つの設計思想にたどり着きました。
| # | 思想 |
|---|---|
| 1 | 人間が指揮者である |
| 2 | エージェントは「優秀な部下」である |
| 3 | 段階的承認で手戻りを防ぐ |
| 4 | コンポジションでスキルを組み合わせる |
順に解説します。
思想1：人間が指揮者である
世の中には「AIエージェントのオーケストレーション」を自動化するフレームワークがたくさんあります。
- LangGraph
- AutoGen
- CrewAI
でも、私はあえてこれらを使いませんでした。
理由：人間が判断するべきことがある
「このデータを分析して」と頼んだとき、どこまで深掘りするかは人間が決めるべきです。自動でエージェント間を連携させると、予期しない方向に進んでしまうことがある。
私の業務では、こういう判断が頻繁に発生します：
- 「この異常値、無視していい？」→ 業務知識がないと判断できない
- 「顧客名を出していい？」→ セキュリティポリシーの判断
- 「このデータ、どこまで公開していい？」→ ビジネス判断
これらは人間が判断すべきです。だから、エージェント間の連携は「人間が指揮する」設計にしました。
人間（あなた）= 指揮者
│
├─ データ分析エージェント
│ 「売上を地域×月で見たい」→ 要件確認→分析→納品
│
├─ ワークフローエージェント
│ 「毎週自動で更新して」→ ワークフロー化
│
├─ パイプラインエージェント
│ 「重いから速くして」→ スケール処理
│
└─ レポーティングエージェント
「ダッシュボードに載せて」→ ツールを作る
思想2：エージェントは「優秀な部下」である
CLAUDE.md の冒頭にこう書いています：
## 基本理念
エージェントは「優秀な部下」である。
・上司の曖昧な意図を汲み取り、明確化する
・勝手に進めず、要所で確認を取る
・成果物は必ずドキュメントとして残す
・人間との役割分担を明確にして協働する
・案件から得た知識を蓄積し、継続的に成長する
これ、実は最初から書いていたわけではありません。
12月に使い始めたとき、Claude Code は「なんでも言うことを聞いてくれる便利なツール」だと思っていました。
でも使っているうちに気づきました。
Claude Code は「ツール」ではなく「チームメンバー」として接したほうがうまくいく。
例えば、こんな会話がありました：
私: このCSVを分析して
Claude: 「分析」とのことですが、具体的にどのような観点で分析しましょうか？
売上の推移、地域別比較、異常値検出など、いくつかの切り口が考えられます。
これ、優秀な部下の反応そのものです。
曖昧な指示を受けたとき、勝手に進めずに確認を取る。
この「確認を取る」という行動を CLAUDE.md で明示的に定義したところ、さらに安定しました。
思想3：段階的承認で手戻りを防ぐ
もう一つ、3ヶ月で学んだことがあります。
「一気にやらせる」と失敗する。
最初のころ、こんな依頼をしていました：
私: 売上データを分析して、レポートを作って、ダッシュボードも作って
結果：
- 分析の切り口が意図と違う
- レポートのフォーマットが想定外
- ダッシュボードは...もう手遅れ
全部作り直し。
そこで、標準ワークフローを導入しました：
各フェーズの終わりに「これで合ってる？」と確認を取る。
承認してから次に進む。
これで手戻りが劇的に減りました。
思想4：コンポジションでスキルを組み合わせる
専門エージェントをどう作るか？
最初は「データ分析エージェント」「ワークフローエージェント」を別々に作っていました。
data-analyst/
├── CLAUDE.md ← データ分析用に一から書く
└── ...
workflow-agent/
├── CLAUDE.md ← ワークフロー用に一から書く
└── ...
問題：共通部分のメンテナンスが大変。
そこで、「コンポジション」という考え方を導入しました。
汎用エージェント（ベース）＋ 専門スキル = 専門エージェント
| エージェント | ベース | 追加スキル |
|---|---|---|
| データ分析 | 汎用 | BigQuery |
| ワークフロー | 汎用 | BigQuery + n8n |
| パイプライン | 汎用 | BigQuery + Dataflow |
| レポーティング | 汎用 | BigQuery + Python出力 |
共通部分（汎用エージェント）を一箇所で管理して、専門スキルだけを追加する。
これで、汎用部分のメンテナンスが一箇所で済むようになりました。
スキルの追加方法は Day 9 以降で詳しく解説します。
フォルダ構成の解説
agent-scaffold-factory の中身を詳しく見ていきます。
全体構成
agent-scaffold-factory/
├── CLAUDE.md ← エージェント管理者定義
├── README.md
├── CONTRIBUTING.md
├── .claude/commands/
│ └── new-agent.md ← 払い出しコマンド
└── src/
├── agent-framework/ ← 汎用エージェントテンプレート
│ ├── CLAUDE.md ← 汎用エージェント定義
│ ├── .claude/commands/ ← Phase管理コマンド
│ │ ├── start-req.md
│ │ ├── next-phase.md
│ │ ├── status.md
│ │ └── approve-phase.md
│ ├── templates/ ← ドキュメントテンプレート
│ │ ├── 00_ヒアリング記録.md
│ │ ├── 01_要求定義書.md
│ │ ├── 02_設計書.md
│ │ ├── 03_WBS.md
│ │ └── 04_完了報告.md
│ ├── knowledge/ ← ナレッジ構造
│ │ ├── business/ ← 業務ルール（必須読み込み）
│ │ ├── technical/ ← 技術知識
│ │ ├── people/ ← 関係者情報
│ │ └── lessons/ ← 過去の教訓
│ └── Issue/ ← 課題管理
└── agent-management/
└── エージェント管理簿.md ← 払い出し履歴
Note:
documents/,inputs/,outputs/は払い出し後に作成されるフォルダです。テンプレートには含まれていません。
.claude/commands/ : スラッシュコマンド
Claude Code には「スラッシュコマンド」という機能があります。
.claude/commands/ にMarkdownファイルを置くと、/コマンド名 で呼び出せるようになります。
agent-scaffold-factory では4つのコマンドを用意しました：
| コマンド | 説明 |
|---|---|
/start-req REQ-2026-001 |
新しい依頼を開始 |
/next-phase REQ-2026-001 |
次のフェーズへ進む |
/status |
進捗状況を確認 |
/approve-phase 1 |
フェーズを承認 |
/start-req の中身
# /start-req コマンド
新規REQを開始し、Phase 0を実行します。
## 使用方法
/start-req REQ-YYYY-NNN [Issue番号]
## 実行内容
### 1. フォルダ作成
- inputs/REQ-YYYY-NNN/
- documents/REQ-YYYY-NNN/
### 2. 進捗管理ファイル作成
documents/REQ-YYYY-NNN/00_進捗管理.md を作成
### 3. ヒアリング開始
以下の質問を行う:
1. 何を実現したいですか？
2. なぜそれが必要ですか？
3. 誰が使いますか？
4. いつまでに必要ですか？
5. 制約や前提条件はありますか？
6. 成功の基準は何ですか？
コマンドファイルに「何をするか」を書いておくと、Claude Code がその通りに実行してくれます。
templates/ : ドキュメントテンプレート
各フェーズで作成するドキュメントのテンプレートです。
templates/
├── 00_ヒアリング記録.md
├── 01_要求定義書.md
├── 02_設計書.md
├── 03_WBS.md
└── 04_完了報告.md
なぜテンプレートが必要か？
理由1: 品質の安定
毎回ゼロから書くと、書く内容にばらつきが出ます。テンプレートがあれば、最低限必要な項目が漏れません。
理由2: レビューしやすい
フォーマットが揃っていると、レビュアー（私）が見るべきポイントがわかりやすい。
理由3: 教育効果
新しいエージェントを払い出したとき、テンプレートが「こう書けばいい」という手本になります。
要求定義書テンプレートの例
# 要求定義書 - REQ-YYYY-NNN
## 1. 概要
### 1.1 目的
（何を実現するか）
### 1.2 背景
（なぜ必要か、現状の課題）
### 1.3 スコープ
#### やること
-
#### やらないこと
-
## 2. 要求事項
### 2.1 機能要求
| # | 要求 | 優先度 | 備考 |
|---|------|--------|------|
| F-001 | | 必須/希望 | |
### 2.2 非機能要求
| # | 要求 | 基準 | 備考 |
|---|------|------|------|
| NF-001 | 性能 | | |
| NF-002 | セキュリティ | | |
## 3. 承認
| 役割 | 名前 | 日付 | 承認 |
|------|------|------|------|
| 依頼者 | | | ☐ |
「やること」と「やらないこと」を明示的に書くのがポイントです。
スコープを曖昧にすると、後で「これも入れてほしかった」「これは要らなかった」が発生します。
knowledge/ : ナレッジ管理
ここが agent-scaffold-factory の肝です。
knowledge/
├── business/ ← 業務ルール（起動時に必ず読む）
├── technical/ ← 技術知識（必要時に参照）
├── people/ ← 関係者情報（必要時に参照）
└── lessons/ ← 過去の教訓（問題発生時に参照）
なぜ4つに分けるのか
最初は全部一箇所に置いていました。
knowledge/
├── プロジェクト概要.md
├── 技術スタック.md
├── チームメンバー.md
├── 過去の失敗.md
├── BigQueryの使い方.md
├── n8nの設定.md
├── ...
問題：ファイルが増えすぎて、どれを読めばいいかわからなくなる。
そこで、「いつ読むか」で分類しました：
| カテゴリ | いつ読むか | 例 |
|---|---|---|
| business/ | 起動時に必ず | 承認ルール、命名規約 |
| technical/ | 必要なときだけ | BigQueryの接続情報 |
| people/ | 必要なときだけ | チームメンバー一覧 |
| lessons/ | 問題が起きたとき | 過去のトラブル事例 |
これで、コンテキストの使用量を抑えつつ、必要な情報にアクセスできるようになりました。
lessons/ から business/ への昇格
lessons/ に蓄積された教訓のうち、繰り返し参照されるものは business/ に昇格させます。
lessons/ で教訓を蓄積
↓
3回以上同じ教訓が出てきた
↓
business/ にルールとして昇格
例：
# lessons/REQ-2026-001_lesson.md
## 問題
CSVファイルがShift-JISで、UTF-8として読み込んで文字化け
## 解決策
ファイル読み込み前に文字コードを判定するステップを追加
## 教訓
> インポート処理では、必ず文字コードの確認ステップを入れる
これが3回続いたら：
# business/import_rules.md
## インポート処理チェックリスト
- [ ] 文字コードを確認した
- [ ] ヘッダー行の有無を確認した
- [ ] 区切り文字を確認した
こうやって、エージェントが経験から学んで成長していきます。
2層のPDCAサイクル
agent-scaffold-factory には、2つのPDCAサイクルが回っています。
1層目：個別案件のPDCA
普通のプロジェクト管理です。ヒアリング → 設計 → 実装 → レビュー → 修正。
これは /start-req → /next-phase → /approve-phase で回します。
2層目：エージェント育成のPDCA
もう一つ、メタレベルのPDCAがあります。
- Plan: 「こう指示すればうまくいくはず」というルールを仮説として置く
- Do: 実際の案件でそのルールを試す
- Check: うまくいったか？意図と違う動きがなかったか？
- Action: ルールを更新する（lessons/ → business/）
この2層目のPDCAが回ることで、エージェントが「成長」していきます。
Week 2 の Day 11-13 では、この2層目のPDCAを実際に回す様子をお見せします。
28日間の全体像
なぜ28日間か？
週1本ペースで4週間。仕事をしながらでも無理なく追えるペースです。
そして、この順番にも意味があります。
| Week | テーマ | 狙い |
|---|---|---|
| 1 | 汎用エージェント | 土台を作る |
| 2 | データ分析 | 育て方を学ぶ |
| 3 | パイプライン | 複数エージェントの使い分け |
| 4 | レポーティング | 道具を作らせる |
Week 1 は誰でも使える汎用的な話。Week 2 以降は私の業務（経営企画系）に寄せた内容です。
Week 1: 汎用エージェントの仕組み（Day 1-7）
まずは基礎を固めます。
- CLAUDE.md の書き方
- スラッシュコマンドの作り方
- ナレッジ管理の方法
- 標準ワークフローの設計
この Week 1 の内容は、Claude Code を使っている人なら誰でも参考にできる汎用的な内容です。
Week 2: データ分析エージェントを育てる（Day 8-14）
ここからが「育てる」フェーズです。
汎用エージェントに BigQuery スキルを追加して、データ分析エージェントを作ります。
そして重要なのが Day 11-13。
「意図と違う動きをした」→「ルールを作らせる」
AIエージェントを使っていると、必ず「そうじゃない」という場面があります。
そのときに：
- 止める
- 「なぜそうした？」を確認する
- 「やりたいことは〇〇」と伝える
- 「勘違いしないためには？」と聞いてルールを作らせる
この対話プロセスを丁寧に追っていきます。
Week 3: パイプラインを作るエージェントたち（Day 15-21）
複数のエージェントを使い分ける方法を解説します。
- n8n ワークフローエージェント
- Dataflow パイプラインエージェント
「このタスクはどのエージェントに頼むべきか？」
その判断基準を整理します。
補足: Dataflow は GCP 固有ですが、考え方は AWS Glue や Azure Data Factory でも同じです。「大量データ処理パターン」として抽象化して解説します。
Week 4: 道具を作るエージェント（Day 22-28）
最後のテーマは「ツールがなければ作る」。
既存ツールを使うのも大事ですが、エージェントには「道具を作る」能力もあります。
具体的には、ダッシュボード生成プログラムを作らせます。
BigQuery からデータ取得
↓
Python プログラムで加工
↓
HTML ダッシュボードを出力
↓
Chrome で開いて確認
このプログラムをエージェントに作らせる過程を追います。
なぜこう作ったか
選択肢1: オーケストレーションフレームワークを使う
| 案 | 採用 | 理由 |
|---|---|---|
| LangGraph 等を使う | ✗ | 業務判断は人間がすべき |
| 人間が指揮する | ✓ | 判断ポイントが多い業務に適している |
業務によっては自動オーケストレーションが向いているケースもあると思います。
私の業務（経営企画系のデータ分析）では、判断ポイントが多いので、人間が指揮する設計にしました。
選択肢2: ナレッジの分類方法
| 案 | 採用 | 理由 |
|---|---|---|
| 全部一箇所 | ✗ | コンテキスト効率が悪い |
| 4カテゴリに分類 | ✓ | 「いつ読むか」で分けると効率的 |
最初は全部一箇所に置いていましたが、ファイルが増えすぎて破綻しました。
「いつ読むか」で分類することで、起動時の読み込み量を抑えつつ、必要なときに参照できるようになりました。
選択肢3: テンプレートの粒度
| 案 | 採用 | 理由 |
|---|---|---|
| 細かく分ける | ✗ | 管理が大変 |
| 5ファイルに集約 | ✓ | Phase に対応させると分かりやすい |
テンプレートは Phase に対応させました。
Phase 1 → ヒアリング記録
Phase 2 → 要求定義書
Phase 3 → 設計書
Phase 4 → WBS
Phase 6 → 完了報告
こうすると「今どのテンプレートを使えばいいか」が迷いません。
ハマったところ
問題1: CLAUDE.md が長すぎてコンテキストを圧迫
症状: CLAUDE.md に全部書いたら、実際の作業に使えるコンテキストが少なくなった
原因: CLAUDE.md は毎回読み込まれるので、長いとコンテキストを圧迫する
解決:
- CLAUDE.md は行動原則だけ（短く）
- 詳細は knowledge/ に分離
- 必要なときだけ参照
問題2: スラッシュコマンドが認識されない
症状: .claude/commands/my-command.md を作っても /my-command が動かない
原因: ファイル名にスペースや特殊文字が入っていた
解決: ファイル名は英数字とハイフンのみにする
問題3: エージェントが勝手に進めてしまう
症状: 承認を求めずに実装まで進んでしまう
原因: CLAUDE.md に「承認を取る」というルールが明示されていなかった
解決: 行動原則に「段階的承認」を追加
### 3. 段階的承認
- 各フェーズ完了時にレビューを依頼する
- 承認なしに次フェーズに進まない
- 手戻りを最小化する
まとめ
- Claude Code を8ヶ月使い込んで「自分専用エージェントを量産する仕組み」を作った
- 設計思想は「人間が指揮者」「エージェントは優秀な部下」「段階的承認」
- knowledge/ を4カテゴリに分けることでコンテキスト効率を上げた
- 28日間かけて、データ分析・ワークフロー・レポーティングの専門エージェントを育てていく
このシリーズは試行錯誤の記録です。
「こうしたほうがいい」「うちではこうやってる」という知見があれば、ぜひコメントで教えてください。
次回予告
Day 2: /new-agent でエージェントを払い出す
明日は、実際に /new-agent コマンドを使ってエージェントを払い出す様子をお見せします。
- コマンドの実行
- 払い出されたエージェントの中身
- 最初の
/start-reqまで
シリーズを追いかける
Discussion