Claude Code で「自己改善する開発チーム」を作った — WordPress子テーマ移行プロジェクトの実践記録 | GH Media
URLがコピーされました

Claude Code で「自己改善する開発チーム」を作った — WordPress子テーマ移行プロジェクトの実践記録

TECH
# AI# Claude Code# WordPress# 開発効率化
URLがコピーされました
Claude Code で「自己改善する開発チーム」を作った — WordPress子テーマ移行プロジェクトの実践記録

はじめに

エンジニア歴10年。現在は Next.js、Nuxt、NestJS に加え、PHP や Python まで、フルスタックで開発を回している私ですが、2026年2月、WordPress子テーマの移行プロジェクトに Claude Code を本格導入しました。結論から言えば 「最高すぎた」 。

特に、親テーマとの CSS specificity の戦い、レスポンシブ対応の複数ブレークポイント管理、修正のたびに発生する回帰バグ — こうした 「人間ひとりでは見落としが避けられない」タイプの問題 に、Claude Code は劇的に効いた。

本記事では、Claude Code の設定ファイル群（CLAUDE.md、エージェント定義、ナレッジ管理）をどう設計し、5つの専門エージェントが自律的に学習しながら開発を回す体制をどう構築したかを、実際のコードと設定を交えて解説する。

プロジェクトの背景

何を作っていたか

ある HR 系の WordPress メディアサイトの子テーマ開発。ある商用テーマ（以下 ThemeX と表記）を親テーマとして拡張し、独自のレイアウトシステム、バナー管理、カテゴリ重み付けなどを実装している。

技術スタックは意図的にシンプルに保っている：

  • WordPress 6.3.7 / PHP 8.2 / MySQL 8.0
  • ビルドツールなし（webpack/Gulp 不使用）
  • CSS はプリプロセッサなしの素のCSS、filemtime() でキャッシュバスト
  • JS は Vanilla JS + jQuery

なぜ Claude Code が必要だったか

親テーマ ThemeX との CSS specificity の戦い、レスポンシブ対応の複数ブレークポイント管理、そして修正のたびに発生する回帰バグ。これらの問題は「調べて → 直して → テストして → 見落としに気づいてやり直す」のループを延々と繰り返す性質のもので、人間ひとりでは見落としが避けられなかった。

Claude Code 導入の時系列

2/16  CLAUDE.md 初版をリポジトリに追加（86行のシンプルな構成）
2/24  5フェーズ開発フロー体制を確立、エージェント定義ファイルを作成
2/25  テスト班エージェント追加、ナレッジファイル自動蓄積が稼働開始
2/26  振り返り班エージェント追加、自己改善ループが完成

導入からわずか 10日 で、5つの専門エージェントが協調する開発体制が出来上がった。

設定アーキテクチャ：2層の CLAUDE.md

Claude Code のカスタマイズの中核は CLAUDE.md だ。このプロジェクトでは グローバル（全プロジェクト共通） と プロジェクト固有 の2層構成にしている。

グローバル CLAUDE.md（~/.claude/CLAUDE.md）

全プロジェクトで適用される基本ルール。自分の「開発スタイル」を定義する場所だ。

# グローバルルール

## 基本方針

- 全出力を日本語で行う（コードコメント、ドキュメント、コミットメッセージ含む）

## コミット

- 件名のみ: `type: 件名` の1行のみ。本文・箇条書き・トレーラーは一切含めない
- Co-Authored-By は含めない

## 作業フロー

- 3ファイル以上に影響する変更は、実装前に計画を提示してユーザーの承認を得ること
- 同じアプローチで2回失敗した場合は、別のアプローチを検討するか、ユーザーに相談

## スキル作成の提案

- 3ステップ以上 + 月1回以上再発 + 50%以上時間削減 → スキル化を提案

ポイントは Claude Code のデフォルト動作を明示的に上書きしている こと。例えば Co-Authored-By トレーラーは Claude Code がデフォルトで付与するが、「含めない」と明記することで自分のコミットスタイルを維持できる。

プロジェクト CLAUDE.md（リポジトリルート）

プロジェクト固有の情報を集約する。ここが Claude Code の「脳」になる。

## テーマアーキテクチャ

### CSS読み込みアーキテクチャ

- 全ページ共通: global.css → header.css, footer.css, parts.css, pagination.css, mobile-overrides.css
- トップページ: + home.css
- 記事詳細: + single.css
- アーカイブ系: + category.css

### テンプレートタイプシステム

投稿には `_custom_template_type` メタフィールド（informational, transactional, feature）があり、
対応するレイアウトファイルが描画される。

### 親テーマの主な上書き

- parent_posts_loop() — 投稿一覧レイアウト
- redirect_canonical フィルター無効化（CDNプロキシ互換性のため）

アーキテクチャの概要をここに書いておくと、Claude はコードを読む前から構造を把握した状態で作業を始められる。 「このCSSはどこで読み込まれるの？」という探索的な時間を大幅に削減できる。

5フェーズ開発フロー：専門エージェントによる分業

このプロジェクトの最大の特徴は、5つの専門エージェントが順番に作業を回すフローを CLAUDE.md で定義していることだ。

調査班(Opus) → ユーザー承認 → 実装班(メイン) → テスト班(Sonnet) → レビュー班(Sonnet) → 振り返り班(Haiku)

なぜ分業するのか

ひとつの AI に「調べて、直して、テストして、レビューして」を全部やらせると、自分が書いたコードに対して甘い評価をしがちという問題がある。テスト班やレビュー班を別エージェントにすることで、実装時のバイアスなく客観的な検証ができる。

各エージェントの設計

エージェント定義は .claude/agents/ に Markdown ファイルとして配置する。

調査班（investigator.md）— Opus

# 調査・設計班 (Investigator)

## 設定

- **model**: `claude-opus-4-6`（複数ファイルの横断的分析・設計判断が必要なため）

## 初動: 過去の知見を確認

調査を開始する前に、以下のファイルを Read で読み込み、過去の知見を確認すること:

1. `.claude/knowledge/checklist.md` — 「調査・設計班」セクションのチェック項目を確認
2. `.claude/knowledge/learnings.md` — 今回のタスクに関連する過去の発見パターンがないか確認

## 制約

- コードの読み取りと調査のみ行う。ファイルの編集・作成は行わない

ポイント: 調査班は Opus を使う。複数ファイルを横断して「親テーマの clearfix が flex item になるから space-between が狂う」のような深い分析をするには、最も賢いモデルが必要だ。そしてファイル編集は明示的に禁止している。調査と実装を分離することで、方針の承認なしにコードが変わることを防ぐ。

実装班（implementer.md）— メインの Claude が担当

# 実装班 (Implementer)

## 初動

`.claude/knowledge/checklist.md` の「実装班」セクションを確認

## 実装原則

- 既存パターンへの追従（新しいパターンやライブラリは導入しない）
- 最小限の変更（周辺コードのリファクタリングは行わない）
- 調査班の方針から大きく逸脱しない。疑問がある場合は実装せず報告

実装班はサブエージェントではなく、メインの Claude 自身が担当する。全ツール（ファイル編集、Bash実行等）へのアクセスが必要なためだ。

テスト班（tester.md）— Sonnet

# テスト班 (Tester)

## 設定

- **model**: `claude-sonnet-4-6`

## 検証パターン

- レイアウト検証: getBoundingClientRect() で複数ビューポート幅を一括検証
- 表示検証: getComputedStyle() でスタイル適用確認
- 回帰検証: 変更対象外ページの抜き打ちチェック

## 制約

- ファイル編集は行わない。修正方法の提案も行わない（事実のみ報告）

重要な設計判断: テスト班は「事実のみ報告」に制限している。「ここが壊れています。修正するには〜」と提案まで始めると、テストと実装の責務が曖昧になる。テスト班は「何がどう壊れているか」だけを報告し、直すかどうかは人間が判断する。

振り返り班（retrospective.md）— Haiku

# レトロスペクティブ班 (Retrospective)

## 設定

- **model**: `claude-haiku-4-5`（定型フォーマットへのファイル追記のみで十分なため）
- **mode**: `acceptEdits`（ナレッジファイルの書き込みを自動承認）

振り返り班は Haiku（最も安価で高速なモデル）を使う。やることは「今回の開発サイクルで得た知見を所定のフォーマットで追記する」だけで、高度な推論は不要だ。acceptEdits モードにすることでファイル書き込みの権限確認も省略し、完全自動で動く。

モデル選定の考え方

エージェントモデル理由
調査班Opus（最高性能）複数ファイルの横断分析、CSS specificity の推論に高い知性が必要
実装班メインClaude全ツールアクセスが必要なためサブエージェント化できない
テスト班Sonnet（バランス型）Playwright でのブラウザ検証は判断力が必要だがOpusほどではない
レビュー班Sonnetコードレビューには一定の判断力が必要
振り返り班Haiku（最軽量）定型フォーマットへの追記のみ。最も安価

タスクの複雑さに応じてモデルを使い分けることで、品質を維持しながらコストを最適化している。

自己改善する開発チーム：ナレッジ管理システム

このプロジェクトで最も効果を発揮したのが、.claude/knowledge/ ディレクトリによる自己改善ループだ。

仕組み

開発サイクル完了
  ↓
振り返り班が自動起動
  ↓
learnings.md に「今回の知見」を追記
checklist.md に「次回チェックすべき項目」を追記
  ↓
次の開発サイクル開始
  ↓
調査班が learnings.md と checklist.md を読み込み
  ↓
過去の失敗パターンを踏まえた調査・設計

ナレッジの実例

learnings.md に蓄積された実際の知見の一部：

## 2026-02-24: サイドバーレイアウト統一

### 発見パターン

- 親テーマの clearfix `#main-wrap::after` は、display: flex に切り替えた際に
  見えない3番目の flex item として機能し、justify-content: space-between の空間分配を狂わせる
- 親テーマの `#sidebar { float: right }` は ID セレクタのため、
  子テーマのクラスセレクタでは !important なしに上書きできない

### 失敗と学び

- サイドバーの padding 調整で新着記事側を変更 → ユーザーに却下された。
  正しくは「ランキングを新着記事に合わせる」方向だった

これは開発中に実際に踏んだ地雷の記録だ。次回のサイクルでは、調査班がこの知見を読んでから作業を始めるため、同じ失敗を繰り返さない。

チェックリストの実例

checklist.md はチームごとにセクション分けされている：

## 調査・設計班

- [ ] clearfix疑似要素（`::after { clear: both }`）が flex item になっていないか確認
- [ ] ブレークポイント別のギャップ幅・サイドバー幅のマップを作成すること
- [ ] CSS の `cssRules` を走査して specificity 競合を事前に検出

## 実装班

- [ ] ID セレクタの上書きには `!important` が必要
- [ ] hover 状態には `.parent:hover .child` の具体的なセレクタを使用
- [ ] CSS 短縮記法を使う場合は値マップをコメントで記載

## テスト班

- [ ] 隣接帯域の境界値（1024px/1025px、1200px/1201px 等）を必ず検証
- [ ] flex 疑似要素（clearfix）が各レイアウトで無効化されているか確認

このチェックリストは開発サイクルを重ねるごとに成長する。初回は0件だったものが、2週間で 30件以上 のチェック項目に育った。

肥大化への対策

知見が無制限に増えると逆にノイズになる。これを防ぐルールもエージェント定義に組み込んでいる：

## 肥大化防止

- ナレッジ50件超 → 古いエントリを要約セクションに圧縮
- チェックリスト15項目超/チーム → 低頻度マーク付与、ユーザーに整理を提案

Playwright MCP による自動ブラウザ検証

テスト班は Playwright MCP プラグイン を使って実際のブラウザで描画状態を検証する。

// テスト班が実行する検証コードの例
// 複数ビューポート幅で getBoundingClientRect() を一括計測
const viewports = [1440, 1200, 1024, 768, 425];
for (const width of viewports) {
  await page.setViewportSize({ width, height: 900 });
  const sidebar = await page.evaluate(() => {
    const el = document.querySelector('#sidebar');
    return el ? el.getBoundingClientRect() : null;
  });
  console.log(`${width}px: sidebar right = ${sidebar?.right}`);
}

「目視で問題なさそう」ではなく、px単位の数値でレイアウトの正確性を検証できる。レスポンシブ対応で複数ブレークポイントを跨ぐ修正には欠かせない。

権限管理：最小権限の原則

settings.local.json で、各ツールの使用許可をホワイトリスト方式で管理している：

{
  "permissions": {
    "allow": [
      "mcp__plugin_playwright_playwright__browser_navigate",
      "mcp__plugin_playwright_playwright__browser_resize",
      "mcp__plugin_playwright_playwright__browser_take_screenshot",
      "mcp__plugin_playwright_playwright__browser_evaluate",
      "mcp__plugin_playwright_playwright__browser_close",
      "mcp__figma__get_design_context",
      "mcp__figma__get_screenshot"
    ]
  }
}

Playwright と Figma の MCP ツールを事前承認しておくことで、テスト班が毎回「このツール使っていいですか？」と聞いてくる煩わしさを排除している。

フィードバックループ：失敗から自動的に学ぶ

CLAUDE.md にはフィードバックループも定義している：

テストで FAIL → 実装班に戻って修正
レビューで重要度「高」 → 調査班に戻って再調査を提案

これにより、テストで見つかった問題が実装にフィードバックされ、レビューで見つかった設計上の問題が調査からやり直される。そしてサイクル完了時に振り返り班が知見を記録するため、次回のサイクルでは同じ問題が予防される。

                    ┌─── FAIL ───────────────┐
                    │                         ↓
調査班 → 承認 → 実装班 → テスト班 → レビュー班 → 振り返り班
  ↑                                    │
  └──── 重要度「高」 ──────────────────┘
                                               │
                                               ↓
                                    learnings.md / checklist.md 更新
                                               │
                                               ↓
                                    次のサイクルの調査班が参照 ←──┘

導入前後の変化

コミットメッセージの質

導入前（2025年12月）:

chore: docker環境作成
feat: ファイルのアップロード上限引き上げ

導入後（2026年2月）:

fix: カテゴリページのclearfix疑似要素がflex itemになり右余白が広がる問題を修正
fix: 記事詳細1201-1439px帯域のサイドバー右余白欠落を中間MQで修正

コミットメッセージが「何をしたか」から「何がなぜ起きていて、どう直したか」に進化している。

開発速度

2026年2月25日には 52件のコミット が1日で行われている。レスポンシブ対応の細かな修正が連続するタスクで、調査班が問題を特定 → 実装班が修正 → テスト班が複数ビューポートで一括検証、というサイクルが高速に回った結果だ。

品質

ナレッジが蓄積されるほど、同じ失敗の再発率が下がる。「clearfix が flex item になる問題」は初回で1時間かかったが、チェックリストに登録された後は調査段階で即座に検出されるようになった。

これから Claude Code を導入する人へ

1. CLAUDE.md はプロジェクトの「脳」

プロジェクトのアーキテクチャ、ディレクトリ構成、コーディング規約を CLAUDE.md に書いておくと、Claude が「すでに知っている状態」で作業を開始できる。特にレガシーコードや複雑な依存関係があるプロジェクトほど効果が大きい。

2. エージェントの分業は「自分に甘い問題」を解決する

1つの AI に全部やらせると、自分が書いたコードに対して甘くなる。テストとレビューを別エージェントにするだけで、検証の客観性が劇的に向上する。

3. モデルはタスクの複雑さで使い分ける

全部 Opus にする必要はない。定型的な作業には Haiku、判断が必要な検証には Sonnet、深い分析には Opus。適材適所のモデル選定がコスト最適化の鍵。

4. ナレッジの自動蓄積が最大の差別化

初日は何も知らない Claude だが、振り返り班が知見を蓄積し続けることで、使えば使うほど賢くなる開発環境が実現する。これは単なるチャット AI では得られない、Claude Code ならではの価値だ。

5. 小さく始めて育てる

最初は86行のシンプルな CLAUDE.md から始まった。エージェント定義もチェックリストも、必要になったタイミングで追加していった。完璧な設定を最初から作ろうとせず、開発しながら育てていくのが現実的なアプローチだ。

まとめ

Claude Code の真価は、単発の質問応答ではなく、プロジェクト固有の知識を蓄積し、専門エージェントが分業で品質を担保し、失敗から自動的に学ぶ「自己改善する開発チーム」を構築できることにある。

設定ファイルは Markdown で書ける。特別なプログラミングは不要。必要なのは「自分の開発フローをどう構造化するか」という設計思考だけだ。

Claude Code、最高すぎた。

本記事で紹介した設定ファイル群は、WordPress子テーマ開発プロジェクトでの実践に基づいています。プロジェクトの性質に応じてエージェント構成やチェックリストの内容はカスタマイズしてください。

AI を活用した業務効率化に取り組んでいます

グリームハブ合同会社では、本記事で紹介したような AI を活用した開発プロセスの最適化 をはじめ、Claude Code・GitHub Copilot 等の AI ツール導入支援、開発ワークフローの設計、WordPress サイト構築など、幅広くお手伝いしています。

「AI を開発現場にどう取り入れればいいかわからない」「既存の開発フローを効率化したい」といったお悩みがあれば、お気軽にご相談ください。

お問い合わせはこちら → グリームハブ合同会社 お問い合わせ

URLがコピーされました

グリームハブ合同会社は、変化の激しい時代において、アイデアを形にし、人がもっと自由に、もっと創造的に生きられる世界を目指しています。

記事を書いた人
鈴木 翔
鈴木 翔

技術の可能性に魅了され、学生時代からプログラミングとデジタルアートの分野に深い関心を持つ

関連記事