AI 駆動開発における品質ゲートの課題
Claude Code（Anthropic が提供する AI コーディングエージェント CLI）を使った開発では、AI エージェントが高速にコードを生成・修正しますが、品質チェックや標準的なワークフローが自動化されていないと、技術的負債の蓄積やセキュリティリスクが発生します。
この記事では、Anthropic ハッカソン優勝リポジトリ「everything-claude-code」の分析から得た知見を基に、Hooks・カスタムコマンド・スキル化による開発ワークフロー強化の実装方法を解説します。ハーネス（AI エージェントの品質管理フレームワーク）の概念を活用し、品質ゲートを自動化します。
現状分析と改善対象の特定
既存構成の課題
# 現在の analytics_note の構成
.claude/
├── agents.md # エージェント定義あり
├── rules/ # ルールセットあり
├── commands/ # 基本コマンドのみ
└── settings.json # 最小限の deny リスト
# 不足している要素
├── hooks.json # ❌ 品質ゲート未設定
├── skills/ # ❌ TDD ワークフロー未スキル化
└── scripts/ # ❌ Hook スクリプト未実装everything-claude-code からの学び
このリポジトリは Claude Code の設定を徹底的に作り込んだ実例で、以下の優れた実装が参考になります：
- 28 エージェント体制: 役割分離による専門性向上
- 包括的 Hooks: AI 操作への自動品質チェック
- 豊富なコマンド:
/plan,/build-fix,/checkpointなど - スキル体系: TDD・PM2・デプロイが標準化
Hooks による品質ゲート自動化
1. Hooks 設定ファイルの作成
# .claude/hooks.json
{
"hooks": {
"before_edit": [
{
"name": "block-no-verify",
"script": ".claude/scripts/block-no-verify.js",
"description": "危険な操作の実行前確認"
}
],
"after_edit": [
{
"name": "auto-format",
"script": ".claude/scripts/auto-format.js",
"description": "コード編集後の自動フォーマット"
}
],
"before_write": [
{
"name": "doc-file-warning",
"script": ".claude/scripts/doc-file-warning.js",
"description": "ドキュメントファイル作成時の警告"
}
],
"before_bash": [
{
"name": "block-dangerous-deploy",
"script": ".claude/scripts/block-dangerous-deploy.js",
"description": "デプロイ・publish コマンドのブロック"
}
]
}
}2. 危険操作ブロックスクリプト
// .claude/scripts/block-no-verify.js
module.exports = function(context) {
const { file_path, old_string, new_string } = context.params;
// --no-verify フラグを含むコミットをブロック
if (new_string && new_string.includes('--no-verify')) {
return {
allow: false,
message: "⚠️ --no-verify フラグの使用は禁止されています。pre-commit フックを迂回する理由を明確にしてください。"
};
}
// 秘密鍵や API キーのパターンを検出
const sensitivePatterns = [
/sk-[a-zA-Z0-9]{48,}/, // OpenAI API key
/ghp_[a-zA-Z0-9]{36}/, // GitHub personal access token
/-----BEGIN PRIVATE KEY-----/
];
for (const pattern of sensitivePatterns) {
if (new_string && pattern.test(new_string)) {
return {
allow: false,
message: "🔒 機密情報の可能性があるコンテンツを検出しました。環境変数またはシークレット管理サービスを使用してください。"
};
}
}
return { allow: true };
};3. 自動フォーマットスクリプト
// .claude/scripts/auto-format.js
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');
module.exports = function(context) {
const { file_path } = context.params;
try {
// package.json でフォーマッターを確認
const packagePath = path.join(process.cwd(), 'package.json');
if (!fs.existsSync(packagePath)) {
return { allow: true };
}
const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
const hasPrettier = pkg.devDependencies?.prettier || pkg.dependencies?.prettier;
if (!hasPrettier) {
return { allow: true };
}
// ファイル拡張子に基づく自動フォーマット
const ext = path.extname(file_path);
const formatableExts = ['.js', '.ts', '.tsx', '.json', '.md', '.css'];
if (formatableExts.includes(ext)) {
try {
execSync(`npx prettier --write "${file_path}"`, {
stdio: 'pipe',
timeout: 5000
});
console.log(`✨ ${file_path} を自動フォーマットしました`);
} catch (error) {
console.log(`⚠️ ${file_path} のフォーマットに失敗しました: ${error.message}`);
}
}
return { allow: true };
} catch (error) {
console.error('Auto-format hook error:', error.message);
return { allow: true };
}
};カスタムコマンドによる開発効率化
1. /plan コマンド（実装計画作成）
# .claude/commands/plan.md
# /plan - 実装計画作成コマンド
## 目的
複雑な機能実装の前に、段階的な実装計画を作成し、レビューと合意を得る
## 実行内容
1. **要件分析**: ユーザーの要求を技術要件に分解
2. **アーキテクチャ設計**: 変更対象ファイル・依存関係の特定
3. **段階分割**: 実装を段階に分けてリスク軽減
4. **完了条件定義**: 各段階の成功基準を明確化
5. **レビュー依頼**: 計画をユーザーに提示して承認要求
## 使用場面
- 新機能の実装開始前
- 大規模リファクタリングの計画
- 複数ファイルにわたる変更
- API 仕様変更を伴う実装
## 出力形式実装計画: [機能名]
1. 要件分析
- 機能要件: …
- 非機能要件: …
- 制約事項: …
2. アーキテクチャ設計
- 変更対象: …
- 依存関係: …
- データフロー: …
3. 実装段階
Phase 1: [基盤実装]
- 作業内容: …
- 影響範囲: …
- 完了条件: …
Phase 2: [機能実装]
- 作業内容: …
- 影響範囲: …
- 完了条件: …
4. リスク分析
- リスク: …
- 対策: …
5. 承認依頼
この計画で実装を開始してよろしいですか？
2. /build-fix コマンド（ビルドエラー自動修正）
# .claude/commands/build-fix.md
# /build-fix - ビルド・lint・型チェック自動診断修正
## 目的
ビルドエラー・lint エラー・型エラーを自動診断し、段階的に修正する
## 実行手順
1. **現状確認**: build・lint・型チェックを実行
2. **エラー分析**: エラーメッセージを分類・優先度付け
3. **自動修正**: 機械的に修正可能なエラーを処理
4. **手動修正**: 複雑なエラーを段階的に解決
5. **完了確認**: 全チェックが成功するまで反復
## 対応エラー種別
- **TypeScript エラー**: 型不整合・未定義参照
- **ESLint エラー**: コーディング規約違反
- **Prettier エラー**: フォーマット不整合
- **ビルドエラー**: 依存関係・設定ミス
## 実行例
```bash
# 1. 現状診断
pnpm build # ビルドエラー確認
pnpm lint # lint エラー確認
pnpm typecheck # 型チェックエラー確認
# 2. 自動修正実行
pnpm lint --fix # 自動修正可能な lint エラー解決
pnpm format # コードフォーマット統一
# 3. 手動修正 (必要に応じて)
# - 型定義追加
# - import パス修正
# - 非推奨 API 置換
# 4. 再確認
pnpm build && pnpm lint && pnpm typecheck
### 3. /checkpoint コマンド（実装中品質確認）
```markdown
# .claude/commands/checkpoint.md
# /checkpoint - 実装中品質チェックポイント
## 目的
実装途中で品質・進捗・方向性を確認し、早期に問題を発見する
## チェック項目
1. **コード品質**: 型安全性・可読性・保守性
2. **テストカバレッジ**: 重要な機能のテスト存在確認
3. **セキュリティ**: 脆弱性・機密情報露出の確認
4. **パフォーマンス**: 明らかな性能問題の検出
5. **設計一貫性**: アーキテクチャ方針との整合性
## 実行結果🔍 Checkpoint Report
✅ 合格項目
- 型安全性: TypeScript エラー 0件
- コードフォーマット: Prettier 準拠
- 基本的なセキュリティ: 機密情報露出なし
⚠️ 要注意項目
- テストカバレッジ: 新機能のテスト未実装
- パフォーマンス: N+1 クエリの可能性
🚨 改善必須項目
- セキュリティ: 入力値検証が不十分
- 設計: 責務分離原則の違反
📋 推奨アクション
- 新機能のユニットテスト追加
- バリデーション層の強化
- リファクタリング (責務分離)
TDD ワークフローのスキル化
1. TDD スキルの定義
# .claude/skills/tdd-workflow/SKILL.md
# TDD Workflow Skill
## 概要
Test-Driven Development の標準的なサイクル（Red-Green-Refactor）を Claude Code で実践するスキル
## 適用場面
- 新機能の実装開始時
- 既存機能の仕様変更時
- バグ修正でテストが不足している場合
## スキル実行手順
### Phase 1: Red (テスト失敗)
1. **要件をテストコードで表現**
```bash
# 新しいテストファイル作成
touch src/features/user/__tests__/user.service.test.ts-
最初に失敗するテストを書く
describe('UserService', () => { it('should create user with valid email', () => { const userService = new UserService(); const result = userService.createUser({ email: 'test@example.com', name: 'Test User' }); expect(result.success).toBe(true); expect(result.user.id).toBeDefined(); }); }); -
テスト実行して失敗確認
pnpm test src/features/user/__tests__/user.service.test.ts # Expected: FAIL (実装がないため)
Phase 2: Green (最小実装)
-
テストが通る最小限のコードを実装
// src/features/user/user.service.ts export class UserService { createUser(userData: { email: string; name: string }) { return { success: true, user: { id: crypto.randomUUID(), ...userData } }; } } -
テスト成功確認
pnpm test src/features/user/__tests__/user.service.test.ts # Expected: PASS
Phase 3: Refactor (改善)
-
コード品質向上
- 重複コード除去
- 命名改善
- 型安全性向上
-
テスト品質向上
- エッジケース追加
- テストデータの整理
- モックの活用
-
リファクタリング後のテスト確認
pnpm test pnpm typecheck pnpm lint
成功基準
- 全テストが通る
- 型チェックがクリア
- lint エラーがない
- カバレッジが向上している
注意点
- 実装前に必ずテストを書く
- 最小限の実装から始める
- リファクタリング時は既存テストを維持
## settings.json の強化
```json
{
"deny": {
"read": [
".env*",
"**/secrets/**",
"**/private/**",
"**/.aws/**",
"**/.ssh/**"
],
"write": [
"package-lock.json",
"yarn.lock",
"pnpm-lock.yaml",
".git/**",
"**/node_modules/**"
],
"bash": [
"rm -rf",
"sudo",
"chmod 777",
"npm publish",
"yarn publish",
"pnpm publish",
"docker push",
"kubectl apply",
"terraform apply",
"serverless deploy",
"vercel --prod",
"netlify deploy --prod"
]
},
"require_confirmation": [
"database migrations",
"production deployments",
"package.json dependencies",
"security-related changes"
]
}Code Review コマンドの7観点強化
# .claude/commands/review.md (更新版)
# /project:review - 7観点スコアカード型レビュー
## レビュー観点
### 1. 機能要件 (Functionality) [0-10]
- 要求仕様との適合性
- エッジケースの考慮
- エラーハンドリングの充実度
### 2. コード品質 (Quality) [0-10]
- 可読性・保守性
- 設計パターンの適用
- SOLID 原則の遵守
### 3. 型安全性 (Type Safety) [0-10]
- TypeScript の活用度
- null/undefined の適切な扱い
- 型推論の最適化
### 4. テスト (Testing) [0-10]
- ユニットテストの充実度
- テストカバレッジ
- テスト可読性・保守性
### 5. セキュリティ (Security) [0-10]
- 入力値検証
- 認証・認可の実装
- 機密情報の適切な管理
### 6. パフォーマンス (Performance) [0-10]
- アルゴリズムの効率性
- メモリ使用量の最適化
- データベースクエリの効率性
### 7. 保守性 (Maintainability) [0-10]
- モジュール分割の適切性
- 依存関係の管理
- ドキュメント整備
## 総合評価基準
- 70点以上: マージ推奨
- 50-69点: 要改善点あり、再レビュー
- 50点未満: 大幅修正必要導入効果と期待値
品質向上
- Hook による自動品質ゲート
- 危険操作の事前ブロック
- セキュリティリスクの早期検出
開発効率化
/planによる実装前設計/build-fixによる自動修正/checkpointによる進捗確認
技術的負債軽減
- TDD スキルによる品質確保
- 7観点レビューによる多角的評価
- フォーマット・lint の自動化
まとめ
Claude Code の Hooks・コマンド・スキル機能を活用することで、AI 駆動開発における品質ゲートと標準ワークフローを自動化できます。特に、everything-claude-code から学んだベストプラクティスを組み合わせることで、セキュリティと開発効率を両立した開発環境を構築できます。
実装時は、プロジェクトの特性に応じて Hook スクリプト・コマンド・スキルを段階的に導入し、チーム内でのコンセンサスを得ながら標準化を進めることが重要です。
関連記事
- Claude Code カスタムフックで AI エージェントの暴走を防ぐ — PreToolUse / PostToolUse フックの基本構造と設計パターンの全体像
- Claude Code コミット規律フックの実装 — 破壊的操作を検出してブロックするフックの詳細実装と運用ノウハウ
- Claude Code の承認ログを SQLite に保存して AI の行動パターンを分析する — フックで収集したデータを分析し、allowedTools を最適化する方法