Claude Code のフックとカスタムコマンドで開発を標準化する

Claude Code のフックで品質ゲートを自動化し、TDD・コードレビュー・ビルド修正をカスタムコマンドとして用意した実装手順です。AI が高速に書くコードの品質を、仕組みで担保する構成を解説します。

5分で読めます Tech
「Hooks(品質ゲート)」「カスタムコマンド」「スキル」の 3 段スラブが積み重なり、TDD / レビュー / Build-Fix のアイコンと結ばれた開発ワークフロー強化スタック図
この記事は AI が下書きを補助し、運営者が内容を確認して公開しています。

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 コマンド(実装中品質確認)

# .claude/commands/checkpoint.md  
# /checkpoint - 実装中品質チェックポイント

## 目的
実装途中で品質・進捗・方向性を確認し、早期に問題を発見する

## チェック項目
1. **コード品質**: 型安全性・可読性・保守性
2. **テストカバレッジ**: 重要な機能のテスト存在確認
3. **セキュリティ**: 脆弱性・機密情報露出の確認
4. **パフォーマンス**: 明らかな性能問題の検出
5. **設計一貫性**: アーキテクチャ方針との整合性

## 実行結果
```
## 🔍 Checkpoint Report

### ✅ 合格項目
- 型安全性: TypeScript エラー 0件
- コードフォーマット: Prettier 準拠
- 基本的なセキュリティ: 機密情報露出なし

### ⚠️  要注意項目  
- テストカバレッジ: 新機能のテスト未実装
- パフォーマンス: N+1 クエリの可能性

### 🚨 改善必須項目
- セキュリティ: 入力値検証が不十分
- 設計: 責務分離原則の違反

### 📋 推奨アクション
1. 新機能のユニットテスト追加
2. バリデーション層の強化  
3. リファクタリング (責務分離)
```

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
   ```

2. **最初に失敗するテストを書く**
   ```typescript
   describe('UserService', () => {
     it('should create user with valid email', () => {
       const userService = new UserService();
       const result = userService.createUser({
         email: '[email protected]',
         name: 'Test User'
       });
       
       expect(result.success).toBe(true);
       expect(result.user.id).toBeDefined();
     });
   });
   ```

3. **テスト実行して失敗確認**
   ```bash
   pnpm test src/features/user/__tests__/user.service.test.ts
   # Expected: FAIL (実装がないため)
   ```

### Phase 2: Green (最小実装)  
1. **テストが通る最小限のコードを実装**
   ```typescript
   // src/features/user/user.service.ts
   export class UserService {
     createUser(userData: { email: string; name: string }) {
       return {
         success: true,
         user: {
           id: crypto.randomUUID(),
           ...userData
         }
       };
     }
   }
   ```

2. **テスト成功確認**
   ```bash
   pnpm test src/features/user/__tests__/user.service.test.ts
   # Expected: PASS
   ```

### Phase 3: Refactor (改善)
1. **コード品質向上**
   - 重複コード除去
   - 命名改善  
   - 型安全性向上

2. **テスト品質向上**
   - エッジケース追加
   - テストデータの整理
   - モックの活用

3. **リファクタリング後のテスト確認**
   ```bash
   pnpm test
   pnpm typecheck
   pnpm lint
   ```

## 成功基準
- 全テストが通る
- 型チェックがクリア
- lint エラーがない
- カバレッジが向上している

## 注意点
- 実装前に必ずテストを書く
- 最小限の実装から始める
- リファクタリング時は既存テストを維持

settings.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 スクリプト・コマンド・スキルを段階的に導入し、チーム内でのコンセンサスを得ながら標準化を進めることが重要です。

関連記事