「Claude Code、毎回同じこと聞いてくるの、ダルくない？」
Claude Code を使い始めて最初の1週間、こんなやり取りを 毎日 していた。
👤「このプロジェクトのコミット規約は日本語で、Conventional Commits で……」
🤖「承知しました！」
👤「ブランチは feat/ で切って、worktree 使って……」
🤖「了解です！」
👤「テスト通ったら PR 作って、タイトルは70文字以内で……」
🤖「わかりました！」
翌日。
👤「このプロジェクトのコミット規約は日本語で
……お前、昨日も聞いたよな？
CLAUDE.md にルールを書けば覚えてくれる。でもそれだけじゃ 「手順」は覚えない。Issue を見て → ブランチ切って → 実装して → テスト通して → PR 作る。この一連の流れを、毎回1ステップずつ指示するのは人間のほうが消耗する。
「手順ごと教え込めないのか？」
調べたら、スキル（.claude/skills/）という仕組みがあった。スラッシュコマンドで呼び出せるカスタム手順書。/solve 42 と打てば Issue #42 を全自動で解く、みたいなことができるらしい。
1個作ったら便利だった。5個作ったら快適になった。10個超えたあたりで、「これ体系化できるのでは」と思い始めた。
そして気づいたら53個になっていた。
さらに、AI が自分自身のスキルを改善し始める という予想外の展開が待っていた。
先に数字を見せます
まず、いま手元の業務 Web アプリのリポジトリがどうなっているか。
プロジェクト規模
| 指標 | 数値 |
|---|---|
| TypeScript 総行数 | 約 65,000行 |
| ファイル数 | 450ファイル |
| git コミット数 | 633 |
| GitHub PR 数 | 273 |
| DB エンティティ数 | 28テーブル |
| API エンドポイント | 25本 |
| フロントエンドページ | 28画面 |
技術スタック: Next.js (App Router) + Hono + Drizzle ORM + TanStack Query v5。monorepo 構成（shared / backend / frontend）。
Claude Code カスタマイズ規模
| 指標 | 数値 |
|---|---|
スキル（.claude/skills/） |
53個 |
専門エージェント（.claude/agents/） |
18体 |
常時適用ルール（.claude/rules/） |
6ファイル |
エージェント永続メモリ（.claude/agent-memory/） |
5体分 |
| CLAUDE.md | 135行 |
53個のスキル、18体の専門エージェント。 これが多いのか少ないのか、ピンとこないかもしれません。
比較のために言うと、Claude Code をインストールした直後に使えるカスタムスキルは 0個 です。.claude/ ディレクトリすら存在しません。ここからどうやって53個まで育てたのか——それがこの記事の本題です。
「Claude Code って何？」という方のために、まず手短に解説します（知っている方は 全体アーキテクチャ へどうぞ）。
Claude Code ってそもそも何？
Claude Code は、Anthropic が提供する ターミナルで動く AI コーディングエージェント です。
npm install -g @anthropic-ai/claude-code
claude # 起動。ターミナルが AI 開発環境になる
Cursor や GitHub Copilot との違いは 「エディタではなくターミナルに住んでいる」 こと。ファイルの読み書き、git 操作、コマンド実行、すべてをターミナル上で AI が自律的にやってくれます。
| 観点 | Cursor / Copilot | Claude Code |
|---|---|---|
| 動作場所 | エディタ内 | ターミナル |
| 操作単位 | ファイル編集 | ファイル + git + コマンド実行 |
| カスタマイズ | 設定ファイル | スキル + エージェント + Hooks |
| 自律性 | 低〜中 | 高（マルチステップ自律実行） |
そしてこの「カスタマイズ」の部分が、今回の主役です。
カスタマイズの3本柱
| 仕組み | 役割 | 例 |
|---|---|---|
| スキル | スラッシュコマンドで呼べるカスタム手順書 |
/solve 42 → Issue #42 を全自動解決 |
| エージェント | 専門分野に特化した AI の分身 | security-reviewer, arch-reviewer |
| ルール | 常時適用される行動制約 | 「聞かずに判断しろ」「トークンを節約しろ」 |
| Hooks | 特定操作で自動発火するトリガー |
git push → 品質チェック強制実行 |
| 永続メモリ | セッションをまたいで記憶を保持 | 「この脆弱性は前回確認済み」 |
これだけだと「ふーん」という感じだと思うので、実際にどう動くのか見せます。
全体アーキテクチャ
53個のスキルは、役割ごとに5つのレイヤーに分かれています。
下のレイヤーほど基礎的で、上のレイヤーが下を組み合わせて動く。 そして最上位の Layer 5 が「スキル自体を改善する」メタレイヤー。
ここからは各レイヤーを掘り下げていきます。
深掘り①：/solve — Issue 番号1つで PR まで全自動
一番使うスキルがこれ。GitHub Issue の番号を渡すだけで、調査→実装→テスト→PR まで全部やってくれる。
👤: /solve 42
これだけ。以降、人間は見守るだけ。
11フェーズの全自動フロー
Phase 2 の「git worktree で隔離」 がポイント。作業中のブランチを汚さずに、完全に独立した環境で開発する。失敗しても元のコードは無傷。
Phase 5 の「テスト失敗 → 自力修正」 は typecheck && test && lint を走らせて、失敗したら自分でコードを直す。最大3回リトライ。人間が介入するのは3回直しても通らなかったときだけ。
Phase 11 が最も異質。 作業が終わった後に「今回の作業手順」と「スキル定義」を突合して、乖離があればスキル自体を自動修正する。これは後で詳しく解説します。
スキル定義の中身
---
name: solve
description: GitHub Issue番号だけで全自動解決する
argument-hint: "[Issue番号(例: 42)]"
---
### Phase 1: Issue 把握
gh issue view <番号> --json title,body,labels
### Phase 2: 隔離環境
git worktree add -b feat/<branch-name> ...
### Phase 5: 品質チェック（並列実行）
pnpm typecheck && pnpm test && pnpm lint
失敗したら自力修正。最大3回リトライ。
### Phase 8: PR 作成
gh pr create --title "..." --body "..."
SKILL.md はただの Markdown。プログラミング不要。日本語で手順を書くだけで、AI がそのとおりに動く。 これがスキルの敷居が低い理由です。
深掘り②：18体の専門エージェントと「最大10体並列レビュー」
1体のAIにすべてを任せると、レビューの観点が浅くなる。人間のチームでも「セキュリティはAさん、パフォーマンスはBさん」と分業するように、AIも 専門分野に特化させた 方が精度が上がる。
18体の専門エージェント一覧
| エージェント | 専門分野 | 使用モデル |
|---|---|---|
| security-reviewer | SQLi, XSS, 認証バイパス | sonnet |
| arch-reviewer | 3層分離、設計パターン違反 | sonnet |
| perf-reviewer | N+1クエリ、re-render | sonnet |
| convention-checker | 命名規約、import順 | haiku |
| error-handler-reviewer | AppError準拠、try-catch配置 | haiku |
| api-contract-checker | フロント/バックの型一致 | haiku |
| test-analyzer | テスト不足の検出 | haiku |
| frontend-optimizer | バンドル肥大、hydrationミスマッチ | sonnet |
| accessibility-checker | a11y、UXパターン | sonnet |
| fullstack-validator | API レスポンス型の整合性 | sonnet |
| 他8体 | ... | ... |
haiku（安い・速い）と sonnet（賢い）の使い分け がコスト最適化のカギ。命名規約チェックに高性能モデルは要らない。
/review-squad — 差分規模で自動スケール
小さい PR に10体のエージェントを投入しても無駄。差分のファイル数に応じて 3体〜10体を自動で増減 させる。
各エージェントは 並列実行 される。10体が順番にレビューしたら時間がかかりすぎるが、同時に動けば1体とほぼ同じ時間で終わる。
深掘り③：エージェントが「記憶」を持つ
ここからが一番面白い部分。
通常、Claude Code のセッションは 会話が終わると記憶がリセット されます。昨日見つけたバグも、先週確認したセキュリティ問題も、全部忘れる。
これを解決するのが 永続メモリ（.claude/agent-memory/）。エージェントが自分で発見したことをファイルに書き込み、次回起動時に読み込む。
セキュリティレビュアーの記憶（実物）
# Security Reviewer Memory
## 認証アーキテクチャ
- Google OAuth -> JWT (jose)
- アクセストークン: インメモリ管理
- リフレッシュトークン: httpOnly Cookie + DB にハッシュ保存
## 既知の脆弱性パターン（発見済み）
### [CRITICAL] ハードコードされたフロントエンドURL
- `backend/src/routes/auth.ts:84`
- 修正: `FRONTEND_URL` 環境変数を追加
### [WARNING] カレンダー year/month に範囲バリデーションなし
- `backend/src/routes/calendar.ts:22-23`
- 異常値でも DB クエリが実行される
- 修正: `.pipe(z.number().int().min(2000).max(2100))` を追加
「前回見つけた脆弱性」を覚えている。 だから次回のレビューで同じ問題を再度報告する無駄がない。そして修正されたかどうかも追跡できる。
アーキテクチャレビュアーの「合法的な例外」
## 既知の違反パターン
### CRITICAL
1. pricing.service.ts:516-588 - service内でtry-catch（規約違反）
## 合法的な例外
- approval-request.service.ts の try-catch: 補償トランザクション
実装のための意図的な例外。コメントで明記済み。
これが地味にすごい。「規約違反だけど、意図的にやっている箇所」を記憶している。 人間のレビュアーが「あ、ここは前にも見たけどわざとだから OK」と判断するのと同じことを、AI がやっている。
毎回「この try-catch は規約違反です！」と指摘されたら鬱陶しいですよね。永続メモリがそれを防ぐ。
深掘り④：AI がスキルを自己改善する——skills-evolve の仕組み
ここが一番予想外だった部分です。
/solve や /swarm が完了するたびに、skills-evolve というスキルが 自動発火 する。何をするかというと——
自己進化の3ステップ
Step 1 が核心。 「SKILL.md に書いてある手順」と「実際に AI が実行した手順」を1:1で突合する。
たとえば：
- SKILL.md には Phase 3 があるのに、実際にはスキップされた → 条件付き実行に変更
- SKILL.md にない手順を AI が自分で追加した → 新 Phase として SKILL.md に追記
- Phase の順序を入れ替えた方が効率的だった → 順序を変更
「自問」ではなく「構造的な差分検出」 と定義されているのがポイント。AI に「うまくいった？」と聞いても「はい、うまくいきました！」と返ってくるだけ。そうではなく、ツール呼び出しの履歴という客観データ と突合させることで、嘘のない自己改善が実現する。
skills-learn — 失敗からも学ぶ
skills-evolve が「成功した作業からの改善」なら、skills-learn は 「失敗やフィードバックからの学習」 を担う。
発火条件：
- ユーザーが AI の出力を修正・やり直しさせた
- 「次からはこうして」「多すぎる」「足りない」等のフィードバック
- Skill 実行中にエラーを自力回避した（手順にないステップを追加）
- 外部レビューで同じ Skill の欠陥が指摘された
つまり 「怒られたら学ぶ」 仕組み。人間のフィードバックがそのまま SKILL.md の改善に反映される。
深掘り⑤：Hooks — 「git push できない」仕組み
53個のスキルを作っても、使い忘れたら意味がない。特に品質チェック（/pre-push）は「急いでるからスキップ」されがち。
そこで Hooks で物理的にブロックする。
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"command": "git push を検知したら exit 2 でブロック"
}],
"PostToolUse": [{
"matcher": "Write|Edit",
"command": "shared/ 編集後に export 漏れチェックを通知"
}],
"UserPromptSubmit": [{
"command": "「実装して」を検知したら auto-context を発火"
}]
}
}
git push のブロック
AI 自身が git push できない。 /pre-push 経由でしか push できない設計。品質ゲートを迂回する方法がない。
編集後の自動通知
shared/validators/ を編集したら「export-sync: index.ts のエクスポート漏れを確認してください」と自動通知。hooks/mutations/ を編集したら「cache-sync: invalidateQueries の漏れを確認してください」と通知。
忘れがちな確認事項を、ファイルパスに紐づけて自動リマインド する仕組みです。
実際のディレクトリ構造
ここまでの話を踏まえて、.claude/ の全体像を見てみましょう。
.claude/
├── settings.json # Hooks（自動発火トリガー）
│
├── rules/ # 常時適用ルール（6ファイル）
│ ├── auto-decide.md # 「聞くな、自分で決めろ」
│ ├── token-guard.md # トークン節約ルール
│ ├── backend-patterns.md # バックエンド規約（backend/** で自動ロード）
│ ├── frontend-patterns.md # フロントエンド規約（frontend/** で自動ロード）
│ ├── shared-patterns.md # 共有層の規約
│ └── test-patterns.md # テスト規約
│
├── skills/ # スラッシュコマンド（53個）
│ ├── solve/SKILL.md # Issue → PR 全自動
│ ├── swarm/SKILL.md # マルチエージェント並列実装
│ ├── review-squad/SKILL.md# 最大10体並列レビュー
│ ├── pre-push/SKILL.md # push前品質ゲート
│ ├── auto-review/SKILL.md # 編集後自動レビュー
│ ├── new-entity/SKILL.md # フルスタック雛形生成
│ ├── skills-evolve/SKILL.md # Skill自己進化
│ ├── skills-learn/SKILL.md # 失敗からの学習
│ └── ... (45個省略)
│
├── agents/ # 専門エージェント（18体）
│ ├── security-reviewer.md
│ ├── arch-reviewer.md
│ ├── perf-reviewer.md
│ ├── convention-checker.md
│ └── ... (14体省略)
│
└── agent-memory/ # 永続メモリ（5体分）
├── security-reviewer/MEMORY.md
├── arch-reviewer/MEMORY.md
├── perf-reviewer/MEMORY.md
├── impact-tracer/MEMORY.md
└── spec-analyzer/MEMORY.md
rules/ のパス条件付き自動ロード が地味に便利。backend-patterns.md は backend/** のファイルを操作するときだけ読み込まれる。フロントエンドを触るときにバックエンドの規約を読み込む必要がない。トークンの節約にもなる。
品質パイプライン：3段階の自動防衛
スキルとエージェントを組み合わせると、こんな品質パイプラインが自動で動く。
| Stage | タイミング | チェック内容 | 所要時間 |
|---|---|---|---|
| 1 | ファイル編集直後 | 即死バグ、セキュリティ穴、型安全性 | 約10秒 |
| 2 | git push 時 | typecheck + test + lint + 自動修正 | 1〜3分 |
| 3 | PR 作成時 | 設計・セキュリティ・パフォーマンス・a11y | 3〜5分 |
Stage 1 が最も費用対効果が高い。 編集するたびに10秒でチェックが走るので、問題の発見が早い。Stage 2 で初めて気づくバグより、Stage 1 で即座に直すバグの方が圧倒的にコストが低い。
育て方：0個から53個までのロードマップ
「53個」と聞くと構えてしまうかもしれませんが、最初から全部作る必要はありません。
Phase 1：基盤（最初の1週間）
作るもの:
├── CLAUDE.md # プロジェクトのルール
├── rules/
│ └── auto-decide.md # 「聞くな、判断しろ」
└── skills/
├── commit/ # コミット自動化
└── pr/ # PR 作成自動化
最初は3ファイルだけ。 CLAUDE.md にプロジェクトの規約を書き、/commit と /pr で最も頻繁な操作を自動化する。これだけで「毎回同じこと聞いてくる」問題が解消される。
Phase 2：開発効率化（2〜3週目）
追加:
├── skills/
│ ├── solve/ # Issue → PR 全自動
│ ├── new-entity/ # フルスタック雛形生成
│ ├── check/ # typecheck + test + lint
│ └── start/ # 作業開始手順
└── rules/
├── backend-patterns.md
└── frontend-patterns.md
/solve を作ると世界が変わる。Issue 番号を渡すだけで PR ができる。雛形生成（/new-entity）も、同じ構造のファイルを何度も手書きするストレスから解放してくれる。
Phase 3：品質自動化（1ヶ月目〜）
追加:
├── skills/
│ ├── pre-push/ # push前品質ゲート
│ ├── auto-review/ # 編集後自動レビュー
│ └── review-squad/ # 並列レビュー
├── agents/
│ ├── security-reviewer.md
│ ├── arch-reviewer.md
│ └── convention-checker.md
└── settings.json # Hooks（git push ブロック）
専門エージェントと Hooks を追加して、品質パイプラインを構築。ここまで来ると「手動レビューで見つかるバグ」がほぼゼロになる。
Phase 4：自己進化（成熟期）
追加:
├── skills/
│ ├── skills-evolve/ # Skill 自動改善
│ ├── skills-learn/ # 失敗からの学習
│ └── skills-watch/ # 構造変化検知
└── agent-memory/ # エージェント永続メモリ
最後に追加するのが自己進化レイヤー。 ここまで来ると、スキルが自分で自分を改善し始める。人間がやることは「たまに進化の結果を確認する」程度。
やってみて気づいたこと
予想通りだったこと
- コミットとPR作成の自動化は即効性がある。 毎日10回以上やる操作だから。
- CLAUDE.md は最重要。 ここがダメだと全スキルの品質が落ちる。
- 専門エージェントは分けた方がいい。 1体にすべてを任せるとレビューが浅くなる。
予想外だったこと
- AI は「忘れる」のが最大の弱点。 永続メモリを入れるまで、同じ脆弱性を毎回指摘してくるのが本当に鬱陶しかった。逆に入れたら劇的に改善した。
- 「聞くな」ルールの効果が想像以上。 AI への返事を打つ時間がゼロになると、体感速度が2倍になる。
- 自己進化は本当に動く。 最初は半信半疑だったが、「SKILL.md に書いてない手順を AI が追加した → 次回から SKILL.md に自動追記される」が実際に起きた。
- Hooks でのブロックは心理的安全性を生む。 「push しちゃったけどテスト通ってなかった」が物理的に起きなくなるので、安心して AI に任せられる。
まとめ
| 観点 | 評価 |
|---|---|
| 初期コスト | CLAUDE.md + 2〜3スキルで 1日で効果が出る |
| スキル定義 | Markdown で手順を書くだけ。プログラミング不要 |
| 専門エージェント | 分業させると精度が上がる。haiku/sonnet の使い分けがコスト最適化のカギ |
| 永続メモリ | 「忘れる」問題を根本解決。セッション横断で知識が蓄積 |
| 自己進化 | ツール呼び出し履歴との突合で 嘘のない自己改善 が実現 |
| Hooks | 品質ゲートを 物理的にバイパス不能 にできる |
| スケール | 53スキル・18エージェントでも 管理コストは低い（自己改善するので） |
次にやりたいこと
- エージェント間の知識共有 — security-reviewer の発見を arch-reviewer が参照できる仕組み
- スキルのバージョン管理 — 自己進化の履歴を git で追跡して、改悪を検知
-
メトリクス可視化 —
/solveの平均所要時間、自動修正の成功率をダッシュボード化 -
他プロジェクトへの横展開 —
.claude/ディレクトリごとテンプレート化して再利用
おわりに
正直、最初は「CLAUDE.md にルール書くだけでいいでしょ」と思っていました。
でも1週間使って気づいた。ルールだけでは「手順」は自動化できない。 Issue を見て、ブランチ切って、実装して、テスト通して、PR 作る。この一連の流れを毎回手動で指示するのは、AI を使っているのに人間が消耗する。
スキルを1個作ったら便利だった。5個作ったら快適になった。10個超えたら「体系化しよう」と思った。そして53個になった頃には AI が自分自身を改善し始めていた。
振り返ると、一番大きかったのは 「聞くな、自分で判断しろ」ルール だったかもしれない。AI が毎回確認してくるのをやめさせたら、初めて「AI と一緒に働いている」感覚になった。確認ダイアログが出るたびにクリックするのは「一緒に働いている」じゃなくて「監視している」だから。
53個のスキルと18体のエージェントは、1日で作ったものじゃない。633コミットの積み重ねの中で、「これ毎回やってるな」と気づくたびに1つずつ追加していった結果です。
最初の一歩は CLAUDE.md と /commit だけでいい。そこから育てていけば、いつの間にか AI が自分で育ち始めます。