3
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@ennagara128

Claude Code の CLAUDE.md / Skills / Agents を3層で整備する設計パターン

3
Posted at

はじめに

Claude Code を実務で使い込むほど、設定ファイルが肥大化していきます。

  • CLAUDE.md にあらゆる規約を書く
  • Skills を作るが、責務が曖昧で重複する
  • Agents を増やすが、Skills との使い分けが分からない

「全部 CLAUDE.md に書いて済ませる」運用は最初は楽ですが、半年後に 誰も読まない（読めない）巨大ファイル になりがちです。

本記事では、私が実務で採用している 3層分離の設計パターン を共有します。

全体像：3層モデル

層 何を書くか 例
CLAUDE.md（基盤層） プロジェクトの「常に効くルール」「変わらない規約」 コーディング規約・禁止事項・命名規則
Skills（手順層） 「特定のトリガーで呼び出す手順書」 デプロイ手順・調査手順・記事投稿手順
Agents（タスク層） 「独立したタスクとして並列実行できる単位」 コードレビュー専用・ドキュメント生成専用

ポイントは 「変化頻度・呼び出し方・粒度」が違うものを混ぜない こと。

CLAUDE.md：基盤層の設計

CLAUDE.md は 「全タスクで常に効くべきルール」 だけに絞ります。

# プロジェクト規約

## 必ず守ること
- 任意のファイルを編集前に必ず Read する
- TypeScript の `any` は使わない
- データベース変更（マイグレーション）は別PRに分ける
- セキュリティ関連の変更は人間レビュー必須

## 命名規則
- コンポーネント: PascalCase
- ユーティリティ関数: camelCase
- 定数: SCREAMING_SNAKE_CASE
- ファイル名: ケバブケース

## 禁止事項
- console.log の本番コード残し
- ハードコードされたAPIキー
- `as` での強制型キャスト

## 関連
- 詳細手順は `.claude/skills/` を参照
- 並列実行可能なタスクは `.claude/agents/` を参照

ポイント:

  • 200行以下に抑える（超えると読まれない）
  • 個別のタスク手順は書かない（Skills へ）
  • 「変わらないこと」だけ

Skills：手順層の設計

Skills は 「特定のキーワードで呼び出される手順書」 として整備します。

ディレクトリ構造例：

.claude/skills/
├── deploy/
│   └── SKILL.md          # トリガー: 「デプロイして」
├── investigate-bug/
│   └── SKILL.md          # トリガー: 「このバグ調査して」
├── post-blog/
│   └── SKILL.md          # トリガー: 「記事投稿して」
└── review-pr/
    └── SKILL.md          # トリガー: 「PR レビューして」

各 SKILL.md の構造：

---
name: deploy
description: 本番環境へのデプロイ手順を実行する。「デプロイして」で呼び出す
---

# デプロイ手順

## トリガー
- 「デプロイして」「本番デプロイ」「リリース」

## 前提条件
- 全テスト緑
- 人間レビュー承認済みPR

## 手順

### 1. デプロイ前チェック
- npm run test:all
- npm run lint
- git status でコミット漏れ確認

### 2. ステージング先行
- staging ブランチへマージ
- ステージング環境で動作確認

### 3. 本番デプロイ
- main ブランチへマージ
- vercel コマンドで本番反映
- ヘルスチェック実行

## 完了条件
- ヘルスチェック緑
- Slackに完了通知

ポイント:

  • 各 Skill は単一目的（複数の責務を混ぜない）
  • トリガー文言を明示
  • 前提条件・完了条件を書く
  • 200〜300行が目安

Agents：タスク層の設計

Agents は 「独立したタスクとして並列実行できる単位」 に絞ります。

ディレクトリ構造例：

.claude/agents/
├── code-reviewer/
│   └── AGENT.md          # PRごとに自動レビュー
├── doc-generator/
│   └── AGENT.md          # 関数ごとにdocstring生成
└── security-auditor/
    └── AGENT.md          # 月1のセキュリティ監査

各 AGENT.md の構造：

---
name: code-reviewer
description: PRに対してコードレビュー観点をAIで自動判定する。並列実行可能。
parallel: true
---

# コードレビュー Agent

## 用途
- PR作成時に Skills から呼ばれる
- 並列実行され、複数PRを同時にレビュー可能

## 観点
1. 命名規則違反
2. TypeScript の any 濫用
3. デバッグコード残し
4. セキュリティ穴

## 出力
- 各問題に対して file:line + 問題内容 + 修正案
- 機械的観点のみ。設計判断は人間に委ねる

ポイント:

  • 状態を持たない（並列実行可能にするため）
  • Skills より粒度が細かく、独立性が高い
  • 1つの責務に絞る

3層の使い分け：判断フロー

何を CLAUDE.md / Skills / Agents どれに置くべきか迷ったら：

そのルール・手順は…

「全タスクで常に効くべき」？
  YES → CLAUDE.md（基盤層）
  NO  → ↓

特定のキーワードで呼び出す手順書？
  YES → Skills（手順層）
  NO  → ↓

並列実行できる独立タスク？
  YES → Agents（タスク層）
  NO  → CLAUDE.md or Skills のどちらかに統合

この判定フローを CLAUDE.md の冒頭に書いておくと、メンバー全員が迷わず追加できます。

アンチパターン

1. CLAUDE.md にすべて書く

→ 500行を超えた瞬間、誰も読まなくなる。
→ Skills / Agents へ責務を分割する。

2. Skills の中に Agents を呼ぶ手順を直接書く

→ Skills が肥大化し、独立性が下がる。
→ Agents は Skills から「タスク委譲」で呼ぶ設計に。

3. Agents が状態を持つ

→ 並列実行できなくなる。
→ Agent は ステートレス が原則。

効果測定

私のチームでこの3層モデルを導入して、

指標 導入前 導入後
CLAUDE.md 行数 800行 180行
「これどこに書く？」迷う頻度 週3〜4回 月1〜2回
Skills 数 8個 22個（責務明確化で増えた）
Skills 重複率 30% 5%

CLAUDE.md は 80%減 にスリム化しつつ、Skills は 責務が明確になって増えた。
これは健全な変化です。

まとめ

  • Claude Code の設定は「変化頻度・呼び出し方・粒度」で3層に分離する
  • CLAUDE.md（基盤層）: 常に効くルール、200行以内
  • Skills（手順層）: トリガーで呼ぶ手順書、単一目的
  • Agents（タスク層）: 並列実行可能な独立タスク
  • 判定フローを CLAUDE.md 冒頭に置く

「Skills 増えすぎて分からない」「CLAUDE.md が肥大化した」という方は、ぜひ試してみてください。

関連: 教材で手を動かして学ぶ

3
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
3
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?