💪

Claude Codeの「正しい整備」で品質とスループットはどう変わるか

に公開
Claude
Claude Code
tech

Claude Codeの「正しい整備」で品質とスループットはどう変わるか

はじめに

Claude Codeのベストプラクティスやハッカソン優勝者の設定が公開された。それまでカスタムスラッシュコマンドとサブエージェントしか使っていなかったが、これらにのっとって設定を追加し、コード品質とスループットがどう変化したかを業務の全セッションログ（記録方法）から定量的に検証した。

結論を先に書く。

指標 Before（4日） After（4日） 変化
C評価率 50% 32% 改善
訂正率（実装のみ） 17.3% 3.2% 5.4倍改善
実装完了機能数 6件 16件 2.7倍

※品質スコアは本プロジェクト固有のレビュー基準による評価であり、絶対的な指標ではない。
※比較期間が各4日間と短く、分析自体もAI（Claude）を使って実施しているため、あくまで参考。

前提：プロジェクトと計測方法

  • 技術スタック: Laravel（PHP） + React、Docker環境
  • アーキテクチャ: クリーンアーキテクチャ（レイヤー分離）
  • 比較期間: 1/23〜1/26（整備前4日間）vs 1/27〜1/30（整備後4日間）

Claude Codeの全セッションログを日次で記録し、以下の指標をカウントした。

指標 カウント方法
ユーザー発言数 ユーザー: の出現回数
訂正回数 「修正して」「やり直し」「違う」「戻して」等の出現回数
品質スコア コードレビュー時のA〜D評価（後述の判定基準で付与）
ツール実行回数 PHPStan / Deptrac / mago / テスト の文字列出現回数

なお、Before期間にも整備作業（PHPStanカスタムルール作成、Deptrac導入調査等）が含まれるが、やり取りの70%は実装作業。

Before：ドキュメント参照型の運用

プロジェクトのdocs/ディレクトリに約30のMarkdownファイルを整備し、カスタムコマンドやエージェントに読み込ませていた。

docs/
├── architecture/           # クリーンアーキテクチャ設計
├── development/
│   ├── coding-standards/   # PHP/React/DB/共通の規約
│   ├── code-review/        # レビューチェックリスト
│   └── testing/            # テスト戦略
├── Databases/              # ER図・テーブル定義
└── business/               # ビジネスドメイン知識

この方式には3つの構造的な問題があった。

  1. コンテキスト消費: ドキュメントをReadするとすべてコンテキストウィンドウに載る[1]。ドキュメントが増えるほど本来の作業に使えるコンテキストが減る
  2. 強制力がない: ドキュメントを「読んだ」ことと「従う」ことは別。アーキテクチャ制約は読んでいても逸脱が起きる
  3. 検証手段がない: 出力がルールにしたがっているかをClaude自身が確認できない

After：Rules + ツール統合型の運用

変更点1：ドキュメントをRulesに再構成

docs/から.claude/rules/に再構成した。各ファイルにはpathsフロントマターでファイルパターンを指定しており、該当するファイルを操作するときだけルールが適用される[2]。

.claude/
├── rules/                    # レイヤー別の実装ルール（paths付き）
│   ├── 00-core-principles.md   # 基本原則
│   ├── 10-domain-layer.md      # Entity/VO/Factory
│   ├── 15-aggregates-layer.md  # アグリゲート境界
│   ├── 30-application-layer.md # UseCase/Query/DTO
│   ├── 50-frontend-layer.md    # React
│   └── 70-tests-layer.md       # テスト
├── commands/                 # 開発フローコマンド
├── agents/                   # 専門エージェント（12種）
└── skills/                   # 再利用可能なスキル

変更点2：静的解析ツールの整備

以下のPHPツールを導入し、Claude Codeが自律的に実行できるようにした。

ツール 用途
mago lint（コードフォーマット・構文チェック）
PHPStan 静的解析（型の不一致・未使用コード等の検出）
Deptrac アーキテクチャ規約違反検知（レイヤー依存方向の制約）

これをコードレビュースキル（/code-review）に組み込むことで、レビュー前に自動的に静的解析が走る仕組みにした。

変更点3：エージェント・コマンド体系の構築

開発フロー全体をコマンドとエージェントで統制する体系を作った。

/plan-implementation → 要件定義・既存パターン調査・実装計画
    ↓
/tdd-execute → フェーズ単位でTDD実装
    ↓
/code-review → PHPStan・Deptrac・mago自動実行 → A〜D評価

整備前後でフロー自体は同じだが、各ステップの中身（ツール・エージェント・ルール）が異なる。

定量データと分析

品質スコアの判定基準

Before/Afterでレビューの仕組み自体が異なる。

Before After
レビュー構成 単一エージェント 3つの専門エージェントを並列実行（Agents）
静的解析 レビューフローに含まれない backend-verifierがPHPStan・Deptrac・テストを実行
スコア基準 エージェント裁量で判定 ツール検証結果を統合して判定（基準を明示的に定義）

After版のスコア定義:

スコア 基準
A 全検証Pass、エラー0件。即承認可
B ほぼPass、軽微な警告あり（1〜2件の小修正で承認可）
C 複数検証でFail（PHPStan/Lintエラー複数、APIパラメーター不一致等）
D 重大問題あり（Deptrac依存違反、テスト失敗、アーキテクチャ違反）

レビュー基準が甘くなったのではなく、ベストプラクティスにしたがって実装・レビューの仕組みを改善したことで、レビュー到達時点のコード品質が上がった。

コードレビュー品質スコア → ツールの効果

再レビュー（修正後の再評価）を含む全スコアで比較する。

スコア Before（12件） After（22件） 変化
A/A- 3件 (25%) 7件 (32%) 改善
B 3件 (25%) 8件 (36%) 改善
C 6件 (50%) 7件 (32%) 改善

Before期間は実装時に静的解析がなく、型の不一致やレイヤー依存違反がそのままレビューに流れていた。After期間はPHPStan/Deptracが実装中に問題を事前に検出するため、レビューが設計判断に集中でき、A/B評価が増加した。

具体例:

  • Before: UseCaseでJsonResponseを返す設計 → ユーザーが指摘して修正。
  • After: PHPStanがnullable型不一致を自動検出。Deptracがレイヤー依存違反を検出

訂正率 → Rules/Skillsの効果

指標 Before After 変化
ユーザー発言 107回 431回 4.0倍
訂正回数 14回 14回 同数
訂正率（実装のみ） 13/75 = 17.3% ~11/340 = ~3.2% 5.4倍改善

訂正率はツール（PHPStan/Deptrac）とは独立した指標だ。ツールは自動検出・自動修正であり、ユーザーの訂正指示にはカウントされない。訂正率の改善はRules/Skillsによる初回出力精度の向上に起因する可能性が高い。

ただし交絡因子がある：タスク種類の違い（Before: API新規実装+バグ修正、After: 既存機能改修中心）、Skillsの成熟度差。また、Before期間の訂正14回のうち9回は1/23の特定バグ修正に集中しており、サンプルサイズの限界には留意が必要だ。

作業スループット

指標 Before（4日） After（4日） 変化
実装完了した機能数 6件 16件 2.7倍
作成・編集ファイル数 28件 109件 3.9倍

※「機能数」にはバグ修正（1ファイル修正）から大型機能（10Phase実装）まで含まれており、粒度は均一ではない。

静的解析ツールの実行回数

ツール Before After 備考
PHPStan —（未導入） 117回 After期間で新規導入
Deptrac —（未導入） 176回 After期間で新規導入
mago 27回 101回 3.7倍
テスト 18回 162回 9.0倍

効果の構造

Rulesとツールは独立ではなく連動している。Rulesで初回出力の精度を上げ、ツールで漏れを検出し、Skillsでそのサイクルを自動化する。

残された課題と推奨事項

ツールで防げない問題

問題の種類 対策状況
レイヤー依存違反 Deptracで検出可能
型の不一致・未使用コード PHPStanで検出可能
計画と実装の乖離 未対策（ユーザー介入に依存）
結合バグ（二重APIリクエスト等） テストカバレッジ依存

特に「計画と実装の乖離」は厄介だ。Claudeが計画では「/xxxに配置」と書いたのに、実装では/yyyに配置するようなものはツールでは検出できない。

推奨する導入順序

  1. ツールを整備する: 静的解析ツールとテスト実行環境を整え、Claude Codeが自律的に実行できるツールを用意する。「正しい状態を確認する手段」を与える
  2. Rulesで規約を自動適用する: .claude/rules/にpaths付きで配置し、必要なときに必要なルールだけが適用される仕組みにする
  3. Skillsでワークフローに統合する: /code-reviewの一部としてツールが自動的に走るようにする
  4. 問題→ルール化のサイクルを回す: 問題発見 → ルール追記 → スキル更新を1セッション内で完結させる

おわりに

Claude Codeは「ドキュメントを読ませれば賢くなる」ツールではない。ベストプラクティスに則り、コンテキストを正しく管理し、検証ツールを与えることで、はじめてその性能を引き出せるツールだ。

具体的には、Rulesでコンテキストウィンドウに載せる情報を制御し、静的解析ツールで出力を自律的に検証させ、Skillsでそのサイクルを自動化する。この仕組みを整えたことで、訂正率は17.3%から3.2%に改善した。

まだまだ、ベストプラクティスから取り入れられていないところはあるので、順次取り入れていく

脚注

  1. Best practices - Claude Code Docs — "Claude's context window holds your entire conversation, including every message, every file Claude reads, and every command output." ↩︎

  2. Manage Claude's memory - Claude Code Docs — "Rules can be scoped to specific files using YAML frontmatter with the paths field." ↩︎

Discussion