1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@masakai(坂井 正徳)

Claude Codeを「開発チーム」として運用する — エージェント・スキル・フック構成の全体像

1
Posted at

Claude Codeを単なるコード補完ツールとして使うのはもったいないです。ここでは、実際の受託開発プロジェクトで「Claude Codeを開発チームとして運用する」構成を紹介します。
他の方々の構成に比べれば整理がまだまだですが、まずはいったんまとめておこうかなと思い、備忘録のつもりで書いています。

全体アーキテクチャ

1. ディレクトリ構成

Claude Codeの設定はグローバルとプロジェクトローカルの2層構造になっています。

~/.claude/                      # グローバル設定
├── CLAUDE.md                   # 全プロジェクト共通の行動ルール
├── settings.json               # パーミッション・環境変数・Hooks定義
├── settings.local.json         # ローカル専用の追加パーミッション
├── agents/                     # カスタムエージェント定義
│   ├── architect.md
│   ├── developer.md
│   ├── reviewer.md
│   ├── release-manager.md
│   ├── ci-engineer.md
│   ├── unit-test-writer.md
│   └── risk-assessor.md
├── skills/                     # スキル（スラッシュコマンド）
│   ├── codex-skill/
│   ├── humanizer-ja.md
│   ├── dashboard-design/
│   └── sme-security/
├── memory/                     # 永続記憶
│   ├── MEMORY.md               # 記憶インデックス
│   └── feedback_*.md           # 各記憶ファイル
├── hooks/                      # フックスクリプト
│   └── speak-output.sh
└── repo_switcher.py            # リポジトリ自動切り替えスクリプト

<project>/
└── .claude/
    ├── CLAUDE.md               # プロジェクト固有ルール
    └── agent-memory/           # プロジェクト固有の学習データ
        ├── architect/
        ├── developer/
        └── reviewer/

2. エージェントチームの設計

フェーズ分離型ワークフロー

開発フローをフェーズごとに専門エージェントに分担させます。これにより「設計しながらコードも書く」という混乱を防げます。

エージェント定義の構造（Markdownファイル）

各エージェントは ~/.claude/agents/<name>.md というファイルで定義します。

---
name: developer
description: "実装フェーズを担うエージェント。..."
model: inherit          # 親から継承（sonnet/opus/haiku も指定可）
color: green            # UIでの表示色
memory: project         # プロジェクトスコープの記憶を使用
tools:                  # 使用可能なツールを制限
  - Read
  - Write
  - Edit
  - Bash
  - WebSearch
  - WebFetch
  - Agent
---

# システムプロンプト
あなたはこのプロジェクトの実装を担う開発者です...

ポイント：toolsでツールを制限することで役割を強制できます。
たとえば reviewer には Edit と Write を与えない → コードを修正できない → 「指摘のみ」を強制できます。

各エージェントの責務

エージェント ツール制限 主な責務
architect Edit/Write禁止 要件整理・設計・documents/更新計画
developer 全ツール使用可 コーディング・テスト実行
unit-test-writer 全ツール使用可 Djangoテスト作成
reviewer Edit/Write禁止 コードレビュー・セキュリティ検査
ci-engineer 全ツール使用可 GitHub Actions・Docker CI設定
release-manager 限定ツール バージョン更新・git push・タグ付け
risk-assessor 全ツール使用可 CVE評価・ISO27005リスク台帳更新

risk-assessor は少し特別な存在

他のエージェントが「開発フロー（設計 → 実装 → レビュー → リリース）」に属するのに対し、risk-assessor はセキュリティ監査フローに属します。ユーザーの指示ではなく、CIパイプラインで新規CVEが検出されたときに自動発火するのが想定の使い方です。

成果物も独自で、docs/iso27005/risks/ 配下に CVEごとの個別リスクファイル（status: proposed）を作成し、ISO27005に基づくリスク台帳（ISO27005_risk_register.md）のTOCを更新します。変化がなければ何も出力しない、という静かな設計になっています。

開発チームの他メンバーが「人間の依頼に応える」エージェントであるのに対し、risk-assessor は外部の脅威情報に自律的に反応するセンサーに近い役割を担っています。

3. CLAUDE.md — チーム全員の行動規範

グローバルの CLAUDE.md には、エージェント全員が従う共通ルールを書きます。

# Global Developer Instructions

- Use 4-space indentation for all code.

## 実装・修正の作業ルール

**1. スコープを守る**
- タスクで変更が必要なファイルを事前にリストアップし、それ以外は触れない
- 「整合性のため」「ついでに」という理由でのスコープ外変更は禁止

**2. 変更前に現状を読む**
- 変更対象のコードを実際に読んでから手を入れる（記憶や推測で変更しない）

## 商用アプリのセキュリティ基準（触る前に確認する3点）
- SECRET_KEY がハードコードされていないか
- DEBUG=True が本番設定ファイルに混入していないか
- 管理系ビューにアクセス制御があるか

プロジェクト固有のルールは <repo>/CLAUDE.md に書き、グローバルルールを上書き・補足します。

4. Hooks — Claude Codeのライフサイクルに割り込む

Hooksは settings.json に定義し、Claudeの動作ライフサイクルの各イベントで任意のシェルコマンドを実行できます。

実装例：claude_mascotとの連携

// settings.json の hooks セクション
{
  "hooks": {
    "SessionStart": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "python3 /path/to/send_status.py IDLE --with-usage"
      }]
    }],
    "UserPromptSubmit": [{
      "matcher": ".*",
      "hooks": [
        {
          "type": "command",
          "command": "python3 /path/to/send_status.py THINKING"
        },
        {
          "type": "command",
          "command": "python3 ~/.claude/repo_switcher.py"
        }
      ]
    }],
    "Stop": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "python3 /path/to/send_status.py SUCCESS --with-usage"
      }]
    }]
  }
}

repo_switcher — プロンプトからリポジトリを自動検出

UserPromptSubmit フックで呼ばれ、プロンプトに含まれるキーワードから対象リポジトリのパスを特定して Claude に additionalContext として渡します。

# repo_switcher.py（概念コード）
REPOS = {
    "FOD_Project": "/Users/.../FOD_Project",
    "GenbaFlow":   "/Users/.../GenbaFlow",
    "myoffice":    "/Users/.../myoffice",
    # ...
}

# プロンプト内のキーワードを検出してパスを返す

「FOD_Projectのバグを直して」と言うだけで、Claudeが自動的に正しいリポジトリのコンテキストを取得できます。

5. Permissions — パーミッション制御

settings.json の permissions で、どのコマンドを自動実行するか・ブロックするかを細かく制御できます。

{
  "permissions": {
    "allow": [
      "Bash(git log *)",
      "Bash(git diff *)",
      "Bash(gh *)",
      "Bash(docker ps *)",
      "Bash(grep *)",
      "Bash(find *)"
    ],
    "deny": [
      "Read(**/.env)",
      "Read(**/.env.*)",
      "Read(**/*.key)",
      "Write(**/.env*)",
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(docker system prune *)"
    ]
  }
}

設計思想：

  • allow = 毎回確認不要な読み取り系・git操作
  • deny = .envファイルの読み取り・破壊的操作を完全にブロック

ローカル固有の設定（サーバーSSH先など）は settings.local.json に分離することで、チーム共有の settings.json をリポジトリにコミットしやすくなります。

6. Skills — スラッシュコマンドで呼び出せるカスタム機能

スキルはユーザーが /codex、/humanizer-ja のようにスラッシュコマンドで呼び出せるカスタム機能です。

~/.claude/skills/
├── codex-skill/
│   └── SKILL.md        # codex CLIとの統合
├── humanizer-ja.md     # AIらしい日本語を人間らしくする
├── dashboard-design/   # デジタル庁ガイドラインベースの設計
└── sme-security/       # 中小企業セキュリティ対策ガイド

---
name: codex
description: OpenAI Codex CLIを使ったコードレビュー
---

# Codex スキル

codex exec --full-auto --sandbox read-only --cd <project_directory> "<request>"

コードレビュー・バグ調査・リファクタリング提案を
CodexCLIに委任する。

7. 記憶システム — 会話をまたいで学習する

Claude Codeにはファイルベースの記憶システムがあります。

~/.claude/memory/
├── MEMORY.md                    # インデックス（常に読み込まれる）
└── feedback_license_policy.md  # 個別の記憶ファイル

記憶の種類は4つです：

種類 用途 例
user ユーザーのプロフィール・スキル 「Go歴10年、Reactは初心者」
feedback 過去の指摘・確認済みのアプローチ 「テストDBはモックを使わない」
project 進行中の作業・決定事項 「2026-06-01にリリースフリーズ」
reference 外部リソースの場所 「バグはLinear INGESTプロジェクトで管理」

8. 運用して分かったポイント

✅ うまくいったこと

エージェントのツール制限は効果的
reviewer に Edit を与えないことで「指摘するだけで直さない」が確実に守られます。エージェントへの指示ではなく、構造で強制できます。

CLAUDE.md の2層構造
グローバルに「絶対に守るルール」、プロジェクトに「このリポジトリ特有のルール」を書くことで、複数プロジェクトを管理しやすくなります。

フックによる状態可視化
claude_mascot との連携により、Claudeが今「考えているか」「ツールを使っているか」「エラーか」が一目でわかります。長時間タスクでの精神的な安心感が高いです。

repo_switcher による文脈の自動注入
「FOD_Projectの〇〇を直して」と言うだけで、Claudeが自動的に正しいコンテキストを掴みます。毎回リポジトリパスを言わなくてよいです。

/security-review と risk-assessor の連携
risk-assessor の主戦場はGitHub ActionsのCI実行時で、pip-audit などが検出した既知脆弱性（CVE）をISO27005リスク台帳に記録するのが中心的な使い方です。一方、/security-review はコードの変更差分に対して設計上の問題や実装ミスを発見する組み込みスキルです。

この2つを連動させることで、外部脅威（CVE）と内部起因（コード変更）の両方をリスク台帳でカバーでき、ISO27001が求める包括的な脆弱性管理（A.8.8）により準拠した体制になります。

【外部脅威】CI（pip-audit等）→ CVE検出 → risk-assessor → ISO27005リスク台帳
【内部起因】/security-review → 重大度判定 → Critical/High のみ risk-assessor → ISO27005リスク台帳

⚠️ 注意点

  • 簡単な作業であればオーケストレータ（Claude Code本体）が全部やってくれますが、定義したサブエージェントに与えたツール制限をオーケストレータ自身は簡単に超えてしまいます。「え、そんなとこまで直しちゃったの？！」という事態が多々起きます。スコープを厳密に守りたい場合は、明示的にサブエージェントを指名して作業を委任しましょう
  • エージェントを多用するとトークン消費が増えます。軽いタスクはメインループで直接やる方が効率的です
  • CLAUDE.md に書きすぎると毎回全部読まれてコストが増えるので、本当に重要なルールだけに絞りましょう
  • settings.json の deny リストに機密ファイルを書いておくことはセーフティネットであり、ソースコードの除外（.gitignore）とは別に管理しましょう

まとめ

Claude Codeは「チャットでコードを書く」ツールではなく、設定次第で本物の開発チームとして機能するプラットフォームになりえます。

  • CLAUDE.md = チームの行動規範
  • Agents = 役割分担された専門家チーム
  • Hooks = CI/CDのように動作を自動化するパイプライン
  • Skills = 再利用可能なカスタムコマンド
  • Permissions = セキュリティポリシー
  • Memory = 会話をまたいで成長する知識ベース

これらを組み合わせることで、「ユーザーが要件を伝えると、設計・実装・テスト・レビュー・リリースまでチームが自律的に動く」開発体制が作れます。

検証環境: Claude Code (claude-sonnet-4-6)、macOS、2026年5月時点の設定

1
0
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
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?