メインコンテンツへスキップ

私の Claude Code 品質管理ワークフロー

手書き

Claude Code を使用する際の品質管理プラクティスを共有します：Hooks 自動化、テスト戦略、AI Review、Pre-commit、GitHub 連携の5つの防衛ライン

·8 分で読める

なぜ AI プログラミングの品質管理に注目すべきなのか？

Claude Code を使って AI プログラミングを行う中で、重要な現象に気づきました。Claude Code は開発速度を 2〜3 倍に向上させることができますが、この AI 支援プログラミングによる効率向上は新たな課題ももたらします――AI が生成したコードには、より厳格な品質チェックと品質管理が必要です。

適切な品質チェックフローがなければ、Claude Code の作業効率はむしろ頻繁なデバッグやリファクタリングによって低下してしまいます。

これにより、ひとつの核心原則に気づきました：AI の出力は検証が必要であり、盲目的に信頼してはいけない。

半年間の実践と最適化を経て、包括的な品質保証体制を構築しました。これから私の品質チェックフローを共有します。これは自動化チェックから手動レビューまでの階層的な品質管理フローです。このフローは段階的なものです――最も基本的な部分から始めて、必要に応じて徐々に強化することができます。

Claude Code の基本的な使い方にまだ慣れていない方は、まず《Claude Code 10大ベストプラクティス》を読んで基本的なワークフローを理解してください。

始める前に：チェックをスムーズにする2つの準備

具体的なチェックフローに入る前に、2つの準備作業を行うことで、その後の品質チェックが格段に効率的になります。

機能別にコードを整理する

プロジェクトコードの整理方法には通常2つの選択肢があります：技術レイヤーで分類する方法（レイヤードアーキテクチャ）と、ビジネス機能で分類する方法（機能別整理）です。AI 支援プログラミングのシナリオでは、私は後者を選びました：

機能別整理 vs 技術レイヤー別整理
2つのコード整理方式の比較：レイヤードアーキテクチャ vs 機能別整理

レイヤードアーキテクチャ

src/
├── routers/        # 所有路由/API 端点
├── services/       # 所有业务逻辑
├── repositories/   # 所有数据访问
└── models/         # 所有数据模型

機能別整理アーキテクチャ

src/
├── user/
│   ├── __init__.py        # Python 包标识
│   ├── router.py          # FastAPI 路由定义
│   ├── service.py         # 业务逻辑
│   ├── models.py          # 数据库模型（SQLAlchemy）
│   ├── schemas.py         # Pydantic 数据验证
│   └── CLAUDE.md          # 模块特定规范
└── order/
    ├── __init__.py
    ├── router.py
    ├── service.py
    ├── models.py
    └── schemas.py

なぜ機能別整理が AI にとってより親和性が高いのか？

例を挙げましょう：Claude にレビュー機能を修正させる場合、レイヤードアーキテクチャでは routers/review.py、services/review_service.py、models/review_model.py、さらに schemas/review_schema.py と、少なくとも4つの異なるディレクトリのファイルを読み取る必要があります。一方、機能別整理では関連ファイルがすべて src/review/ ディレクトリに集まっているため、AI はモジュール全体のコンテキストを一度に把握できます。

さらに、各モジュールに独自の CLAUDE.md を持たせることができ、そのモジュール固有のルールや制約を定義できます。これにより、AI が異なるモジュール間を切り替える際に、自動的に異なる開発規範に適応できるようになります。

Make コマンドで統一エントリーポイントを作る

新しいプロジェクトを始める際、最初にやることは Makefile の作成です。なぜでしょうか？

AI がコードを書く際、プロジェクトの「ルール」を知る必要があります。毎回 Claude に「ruff check && mypy . && pytest を実行してください」と伝えるよりも、単に「make check を実行して」と言う方がはるかに効率的です。

これが私の基本 Makefile テンプレートです：

.PHONY: help setup dev run stop format check test clean

help: ## 显示帮助信息
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'

setup: ## 初始化开发环境（安装依赖 + git hooks）
	@echo "📦 Installing dependencies..."
	uv sync
	@echo "🔧 Installing pre-commit hooks..."
	uv run pre-commit install

dev: ## 本地开发模式（支持热重载）
	@echo "🚀 Starting dev server with hot reload..."
	uvicorn main:app --reload --host 0.0.0.0 --port 8000

run: ## 生产模式（多 worker）
	@echo "🚀 Starting production server..."
	uvicorn main:app --workers 4 --host 0.0.0.0 --port 8000

stop: ## 停止后台运行的服务
	@echo "🛑 Stopping server..."
	# 停止服务的逻辑

format: ## 格式化代码
	@echo "🎨 Formatting code..."
	black .
	ruff check --fix .

check: ## 代码检查 + 类型检查 + 测试
	@echo "🔍 Checking code..."
	ruff check .
	mypy .
	pytest

test: ## 运行测试
	@echo "🧪 Running tests..."
	pytest

clean: ## 清理缓存文件
	@echo "🧹 Cleaning up..."
	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
	find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true

なぜこれが効果的なのか？

  1. 統一されたコマンドインターフェース：プロジェクトがどの技術スタックを使用していても、make format、make test は常に有効です
  2. AI フレンドリー：Claude はこれらの簡潔なコマンドをより覚えやすく、使いやすくなります
  3. 規範の強制：チームメンバー（または将来の自分）が何を実行すべきか明確になります

このシンプルな標準化により繰り返しのコミュニケーションが減り、AI 支援開発において特に効果的です。

完全な AI プログラミング品質チェックフロー

第1の防衛ライン：Hooks 自動チェック

Claude Code の品質チェックフローにおいて、最も基本的な要素は自動化チェックです。

Claude がコーディングを完了するたびに、設定した Hook が自動的にフォーマットを実行します：

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "make format",
        "timeout": 60
      }]
    }]
  }
}

これにより、手動の介入なしにコードスタイルの一貫性が確保されます。

第2の防衛ライン：テスト戦略

Mock について、私のやり方は多くの方とは異なるかもしれません：Mock を使わなくて済むなら使わない、というスタンスです。

理由はシンプルです。Mock テストが通っても、本番環境で動くとは限りません。こんな経験が何度もありました：ユニットテストはすべてグリーンなのに、デプロイしたら問題が発生する。Mock が実際の境界条件を隠してしまっていたのです。AI が生成するコードでは、この問題がより顕著になります：AI はテストを書く際、自分のコードに「合わせて」しまいがちで、テストを通すために書くのであって、本当に境界条件を検証しているわけではありません。インテグレーションテストの方が、この種の問題をより効果的に発見できます。

もちろん、Mock が必要なシーンもあります：有料 API の呼び出し、時間に関連するロジック、不安定なサードパーティサービスなどです。しかしそれ以外では、インテグレーションテストを書くことを優先しています。

カバレッジについては、80% を目標にしています――コアロジックをカバーできれば十分で、100% を追求する必要はありません。あるモジュールを修正した際は、pytest tests/user/ を実行すれば素早く検証でき、全テストの完了を待つ必要がありません。

Claude にこのテスト戦略を守らせるために、CLAUDE.md に要件を明確に記載しています：

## 测试规范

- 实现新功能时，先写测试，确认测试失败，再写实现代码
- 每次修改后运行 `make test` 确保没有破坏现有功能
- 不要为了让测试通过而修改测试本身
- 外部 API、时间相关逻辑使用 Mock，其他场景优先使用真实依赖

第3の防衛ライン：ローカル AI Review

ローカル AI Review
Claude Code Commands を使用したコードレビュー

大きな変更に対しては、Claude Code の Commands を使用してコードレビューを行います。通常、特定のディレクトリの変更をレビューするよう Claude に依頼します。例えば「src/order/ の今回の修正をレビューして」というように、コンテキストをより集中させます。

# 使用专门的审查 Commands
/code-review:code-review

いつ使うべきか？

  • 必須：アーキテクチャの変更、新機能、セキュリティ関連
  • 推奨：重要なビジネスロジックの修正
  • 任意：小さなバグ修正、シンプルな文言修正

個人開発者として、定期的に Claude にモジュール全体のレビューを依頼することもあります。これはチーム開発ではあまり現実的ではありません――コードは異なるメンバーが書いているため、自由にリファクタリングすると他の人の領域を侵してしまう可能性があります。しかし個人開発ではその心配がなく、問題を発見したらすぐに調整できます。

第4の防衛ライン：Pre-commit Hook

これが最も重要な環節です――チェックが通らなければ、コードはそもそもコミットできません。

私のやり方は pre-commit フレームワークと make check を組み合わせることで、設定は非常にシンプルです：

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: make-check
        name: Run make check
        entry: make check
        language: system
        pass_filenames: false

すべてのチェックロジックは Makefile で統一管理し、pre-commit はコミット時のトリガーのみを担当します。

次に Makefile に setup コマンドを追加します：

setup: ## 初始化开发环境
    @uv sync
    @uv run pre-commit install

make setup を実行すると、毎回の git commit で自動的に make check がトリガーされるようになります。

個人開発であれば、この手順は手動で行うこともできます。しかし、setup コマンドの設定をお勧めします。別のパソコンに切り替えたり、プロジェクトを再クローンした際に、make setup を一度実行するだけで開発環境を復元でき、多くの手順を覚えたり、再設定したりする必要がなくなります。

これらの設定作業自体も Claude Code に任せることができます――「pre-commit を設定して、コミット時に make check を実行するようにして」と伝えれば、設定ファイルを生成してインストールまで行ってくれます。

第5の防衛ライン：GitHub 連携

Claude Code は GitHub 連携機能を提供しており、Pull Request のたびに自動的に AI コードレビューをトリガーできます。

GitHub 連携のインストール
/install-github-app を実行して GitHub 連携を完了

Claude Code で /install-github-app を実行し、プロンプトに従って認証フローを完了するだけです。

インストール完了後、プロジェクトに .github/workflows ディレクトリが追加されており、Claude のレビューワークフロー設定が含まれています。

GitHub workflows の設定
自動生成された Claude レビューワークフロー設定

以降、PR を提出するたびに Claude が自動的にコードをレビューし、PR にコメントを残します。レビューのスタイルや着目点を調整したい場合は、workflows 内の prompt 設定を直接編集できます。

これが最後の品質ゲートです――コードはマージ前にもう一度 AI レビューを受け、見落とした問題がないことを確認します。

品質チェック体制の全体像

この5つの防衛ラインが、包括的な品質保証体制を構成しています：

防衛ラインチェック方式トリガータイミング役割
Hooks自動化コーディング完了後コードスタイルの一貫性を確保
テスト手動 + 自動機能実装後ロジックの問題を発見
AI ReviewAI レビュー大きな変更時即時フィードバックを取得
Pre-commit自動化コミット前低品質なコードのリポジトリ混入を防止
GitHub 連携AI レビューPR 時最終レビューの関門

この品質チェックフローは自動化から手動まで、ローカルからクラウドまで、Claude Code が生成するコードの品質を確保します。

まとめ：AI 時代の品質管理体制

AI プログラミングの時代はすでに到来していますが、品質管理が時代遅れになることはありません。

この包括的な Claude Code 品質チェックフローは、5つの品質管理プロセスを連携させ、堅牢な品質保証体制を形成しています。どの AI プログラミングツールを使用していても、この品質チェックの考え方は普遍的に適用できます。

AI プログラミングにおける品質管理の詳細な経験共有が、皆さん自身に合った品質保証体制の構築に役立てば幸いです。ご質問やご自身の実践経験の共有がありましたら、ぜひコメントでお知らせください！

関連記事

関連記事

私の Claude Code ベストプラクティス

Claude Code でコードを書く際の知見を共有します。10の核心テクニック、スラッシュコマンド詳解、カスタムコマンド設定で、AIプログラミングの効率を向上させましょう

Eclipse から Zed へ：ある開発者のエディタ進化史

バックエンド開発からフルスタック開発へ、200以上のプラグインを持つ VS Code からターミナルファーストのワークフローへ。AI時代とともに変わってきた私のエディタ選びの記録

コメント

前の記事
Eclipse から Zed へ：ある開発者のエディタ進化史
次の記事
私の Claude Code ベストプラクティス