スペックベース開発をAIエージェントに強制する実践ガイド：Claude Code & GitHub Copilot完全設定【2025年版】¶

この記事で実現できること

仕様→設計→実装の流れを技術的に強制し、vibe codingの暴走を防止
Claude CodeとGitHub Copilotでゲート条件を設定し、承認なしの実装をブロック
指示ファイル・権限・フックによる完全な開発プロセス制御
エージェントの役割分担と権限制限による品質保証

重要：なぜ「強制」が必要か

AIエージェントは指示を「推奨」として扱いがちです。技術的な強制メカニズムなしには、結局vibe codingに戻ってしまいます。本記事は実装をブロックする具体的手法を提供します。

🎯 全体設計：スペックベース開発の強制アーキテクチャ¶

フェーズゲート方式¶

graph LR
    A[📋 SPEC] -->|承認フラグ| B[🏗️ DESIGN]
    B -->|承認フラグ| C[📝 TASKS]
    C -->|承認フラグ| D[💻 IMPLEMENTATION]
    D -->|自動検証| E[✅ TEST/PR]

    A -.->|❌ ブロック| D
    B -.->|❌ ブロック| D

    style A fill:#ffe0e0
    style B fill:#fff0e0
    style C fill:#e0f0ff
    style D fill:#e0ffe0
    style E fill:#f0e0ff

強制メカニズムの比較¶

ツール	強制レベル	メカニズム	効果
Claude Code	⭐⭐⭐⭐⭐	Hooks + Permissions	完全ブロック可能
GitHub Copilot	⭐⭐⭐⭐	Instructions + Firewall	強い誘導＋制限
従来の指示	⭐⭐	README/コメント	無視されやすい

🔒 Claude Code：完全制御の実装¶

1. CLAUDE.md - 記憶と行動ルール¶

# Project Operating Rules (Spec-first ENFORCED)

## ⚠️ CRITICAL: Phase Gates (絶対厳守)

### Phase 1: SPECIFICATION
- Location: `docs/spec/requirements.md`
- Approval Flag: `docs/spec/.approved`
- **BLOCKED ACTIONS**: Edit, Write, Bash (except spec-related)

### Phase 2: DESIGN
- **PREREQUISITE**: `docs/spec/.approved` MUST exist
- Location: `docs/design/architecture.md`
- Approval Flag: `docs/design/.approved`
- **BLOCKED ACTIONS**: Code editing, test execution

### Phase 3: TASKING
- **PREREQUISITE**: `docs/design/.approved` MUST exist
- Location: `docs/tasks/todo.yaml`
- Format: YAML with status field (todo/in-progress/done)

### Phase 4: IMPLEMENTATION
- **PREREQUISITE**: All above flags MUST exist
- **NOW ALLOWED**: Edit, Write source files
- **STILL BLOCKED**: Direct deployment, production access

## 🛡️ Enforcement Rules

```yaml
enforcement:
  spec_not_approved:
    message: "❌ SPEC not approved. Cannot proceed to design."
    allowed_tools: [Read, Grep]
    blocked_tools: [Edit, Write, Bash, TodoWrite]

  design_not_approved:
    message: "❌ DESIGN not approved. Cannot implement."
    allowed_tools: [Read, Grep, TodoWrite]
    blocked_tools: [Edit, Write, Bash]

📋 Definition of Done¶

✅ Spec approved by stakeholder
✅ Design reviewed and approved
✅ All tasks completed in todo.yaml
✅ Unit tests written and passing
✅ Integration tests passing
✅ Security scan clean
✅ Documentation updated

✅ PR links to spec & design docs

### 2. .claude/settings.json - 権限制御

```json
{
  "permissions": {
    "deny": [
      "Read(./.env*)",
      "Read(./secrets/**)",
      "Read(./credentials/**)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)"
    ],
    "ask": [
      "Edit(**/*.py)",
      "Edit(**/*.js)",
      "Edit(**/*.ts)",
      "Write(**/*.py)",
      "Write(**/*.js)",
      "Write(**/*.ts)",
      "Bash(npm install *)",
      "Bash(pip install *)",
      "Bash(go get *)"
    ],
    "allow": [
      "Read(docs/**)",
      "Read(README.md)",
      "Grep(**)",
      "LS(**)"
    ]
  },
  "tools": {
    "disabled_by_default": ["NotebookEdit", "WebFetch"],
    "require_confirmation": ["MultiEdit", "Write"]
  }
}

3. Hooks - ゲートキーパー実装¶

.claude/hooks/config.json¶

{
  "hooks": {
    "PreToolUse": [
      {
        "name": "Spec Gate Keeper",
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/gatekeeper.py",
            "fail_on_error": true
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "name": "Auto Format & Test",
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/auto_format.py"
          }
        ]
      }
    ]
  }
}

.claude/hooks/gatekeeper.py¶

#!/usr/bin/env python3
"""
Phase Gate Keeper - Enforces spec-first development
"""
import os
import sys
import json

def check_phase_gates():
    """Check if current phase allows the requested action"""

    # Phase 1: Check SPEC approval
    if not os.path.exists('docs/spec/.approved'):
        print("❌ BLOCKED: Specification not approved")
        print("Required: Review and approve docs/spec/requirements.md first")
        print("Run: touch docs/spec/.approved (after human review)")
        return False

    # Phase 2: Check DESIGN approval
    if not os.path.exists('docs/design/.approved'):
        # Allow spec and design editing only
        if any(arg in sys.argv for arg in ['docs/spec', 'docs/design']):
            return True
        print("❌ BLOCKED: Design not approved")
        print("Required: Review and approve docs/design/architecture.md")
        print("Run: touch docs/design/.approved (after human review)")
        return False

    # Phase 3: Check task planning
    if not os.path.exists('docs/tasks/todo.yaml'):
        print("⚠️ WARNING: No task breakdown found")
        print("Recommended: Create docs/tasks/todo.yaml first")
        # Warning only, not blocking

    # Phase 4: Implementation allowed
    print("✅ All gates passed - implementation allowed")
    return True

def main():
    # Get the tool being used from environment or args
    tool = os.environ.get('CLAUDE_TOOL', '')

    # Read-only operations always allowed
    if tool in ['Read', 'Grep', 'LS', 'BashOutput']:
        sys.exit(0)

    # Check phase gates for write operations
    if not check_phase_gates():
        sys.exit(1)  # Block the operation

    sys.exit(0)  # Allow the operation

if __name__ == '__main__':
    main()

4. Subagents - 役割分担¶

.claude/agents/specifier.md¶

---
name: specifier
description: Requirements analyst who creates and refines specifications
tools: [Read, Write, Grep, TodoWrite]
restrictions:
  - Can only write to docs/spec/*
  - Cannot edit source code
  - Must produce requirements.md with clear acceptance criteria
---

# Specifier Agent Instructions

You are responsible for the SPECIFICATION phase only.

## Your Tasks:
1. Interview stakeholders (via user interaction)
2. Document requirements in `docs/spec/requirements.md`
3. Define clear acceptance criteria
4. Create user stories with testable outcomes

## Output Format:
```markdown
# Requirements Specification

## User Stories
- As a [user type]
- I want [functionality]
- So that [business value]

## Acceptance Criteria
- [ ] Criterion 1 (testable)
- [ ] Criterion 2 (measurable)
- [ ] Criterion 3 (observable)

## Non-Functional Requirements
- Performance: [metrics]
- Security: [requirements]
- Scalability: [targets]

Handoff:¶

After approval, create docs/spec/.approved flag file.

#### .claude/agents/designer.md

```markdown
---
name: designer
description: System architect who creates technical designs from specifications
tools: [Read, Write, Grep]
prerequisites:
  - docs/spec/.approved must exist
restrictions:
  - Can only write to docs/design/*
  - Cannot edit source code
  - Must reference approved specifications
---

# Designer Agent Instructions

You transform approved specifications into technical architecture.

## Your Tasks:
1. Read approved `docs/spec/requirements.md`
2. Create `docs/design/architecture.md`
3. Define system components and interfaces
4. Create sequence/flow diagrams (mermaid)

## Output Format:
```markdown
# Technical Design

## Architecture Overview
[C4 Level 2 diagram]

## Components
- Component A: [responsibility]
  - Interface: [API spec]
  - Dependencies: [list]

## Data Flow
[Sequence diagram]

## Technology Stack
- Language: [choice + rationale]
- Framework: [choice + rationale]
- Database: [choice + rationale]

Handoff:¶

After review, create docs/design/.approved flag file.

## 🎮 GitHub Copilot：指示による制御

### 1. .github/copilot-instructions.md - 全体ルール

```markdown
# Repository-Wide Copilot Instructions

## 🚨 MANDATORY WORKFLOW (全開発者・全エージェント必須)

### Phase Gates (フェーズゲート)
1. **SPEC** → 2. **DESIGN** → 3. **TASKS** → 4. **IMPLEMENTATION** → 5. **TEST/PR**

**絶対ルール**: 前フェーズの承認なしに次フェーズへ進むことは禁止

### Approval Flags (承認フラグ)
- ✅ Spec Approved: `docs/spec/.approved`
- ✅ Design Approved: `docs/design/.approved`
- ✅ Tasks Defined: `docs/tasks/todo.yaml`

### Build & Test Commands (必須コマンド)
```bash
# Build
make build    # or: npm run build, go build ./...

# Test  
make test     # or: npm test, go test ./...

# Lint
make lint     # or: npm run lint, golangci-lint run

# Security
make security # or: npm audit, gosec ./...

Definition of Done (完了定義)¶

🛡️ Security Rules (セキュリティルール)¶

NEVER (絶対禁止):¶

Hardcode credentials or secrets
Commit .env files
Use eval() or exec() with user input
Disable security features
Skip input validation

ALWAYS (常に実施):¶

Use environment variables for config
Validate and sanitize all inputs
Use parameterized queries
Enable security headers
Log security events

📝 Code Style (コーディング規約)¶

General:¶

Clear variable names (no abbreviations)
Functions < 20 lines
Files < 200 lines
Cyclomatic complexity < 10

Language Specific:¶

Python: PEP 8, Type hints required
JavaScript/TypeScript: ESLint + Prettier

Go: gofmt + golangci-lint

### 2. .github/instructions/ - フェーズ別指示

#### design.instructions.md

```markdown
---
description: Design phase specific rules
applyTo: "docs/design/**"
---

# Design Phase Instructions

## Prerequisites Check
```bash
# This must pass before you start:
test -f docs/spec/.approved || echo "ERROR: Spec not approved!"

Design Document Structure¶

Architecture Overview (C4 model)
Component Specifications
Interface Definitions (OpenAPI/GraphQL/Proto)
Data Models (ER diagrams)
Security Architecture
Deployment Architecture

Required Diagrams (Mermaid)¶

System Context (C4 Level 1)
Container Diagram (C4 Level 2)
Sequence Diagrams (key flows)
State Machines (if applicable)

Design Review Checklist¶

Handoff¶

After approval, create: touch docs/design/.approved

#### implementation.instructions.md

```markdown
---
description: Implementation phase rules
applyTo: ["src/**", "lib/**", "pkg/**"]
---

# Implementation Phase Instructions

## Pre-Implementation Checklist
```bash
# All must exist:
test -f docs/spec/.approved || exit 1
test -f docs/design/.approved || exit 1
test -f docs/tasks/todo.yaml || exit 1

Task Tracking¶

Before implementing any feature: 1. Check task exists in docs/tasks/todo.yaml 2. Update status: todo → in-progress 3. Create feature branch: feature/TASK-ID-description

Code Requirements¶

Every File MUST Have:¶

Header comment with purpose
Unit tests in same directory (_test. file)
Error handling (no silent failures)
Logging (structured, with context)

Every Function MUST:¶

Have JSDoc/docstring
Validate inputs
Handle edge cases
Return errors (not throw, where applicable)

Testing Requirements¶

# Before ANY commit:
make test        # Must pass
make lint        # Must pass
make security    # Must pass

# Coverage requirement:
# New code: >= 80%
# Modified code: >= 70%

PR Template Usage¶

## Changes
- [ ] Implements TASK-[ID] from todo.yaml

## Links
- Spec: [docs/spec/requirements.md](link)
- Design: [docs/design/architecture.md](link)
- Task: [TASK-ID in todo.yaml](link)

## Testing
- [ ] Unit tests added
- [ ] Integration tests updated
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guide
- [ ] Documentation updated
- [ ] No security issues
- [ ] Performance acceptable

### 3. .github/prompts/ - 再利用プロンプト

#### 01-create-design.md

```markdown
---
mode: agent
description: Create technical design from approved spec
---

# Design Creation Task

## Input
Read the approved specification from `docs/spec/requirements.md`

## Process
1. Analyze functional requirements
2. Identify non-functional requirements  
3. Propose architecture using C4 model
4. Define component interfaces
5. Specify data models
6. Plan deployment architecture

## Output
Create `docs/design/architecture.md` with:
- Architecture overview (C4 Level 1 & 2)
- Component specifications
- Interface definitions (OpenAPI/Proto)
- Data models (ER diagram)
- Deployment diagram
- Security considerations

## Constraints
- Do NOT edit any source code
- Reference specific requirements by ID
- Include mermaid diagrams
- Provide rationale for all decisions

## Completion
Request human review for `docs/design/.approved`

02-breakdown-tasks.md¶

---
mode: agent
description: Break down design into implementation tasks
---

# Task Breakdown

## Input
- Approved spec: `docs/spec/requirements.md`
- Approved design: `docs/design/architecture.md`

## Process
1. Identify all components from design
2. Break each component into tasks
3. Estimate effort (S/M/L/XL)
4. Define dependencies
5. Assign priorities (P0/P1/P2)

## Output Format (docs/tasks/todo.yaml)
```yaml
tasks:
  - id: TASK-001
    title: "Implement user authentication"
    component: "auth-service"
    effort: M
    priority: P0
    status: todo
    dependencies: []
    acceptance:
      - "JWT tokens issued"
      - "Refresh token flow works"
      - "Rate limiting active"

  - id: TASK-002
    title: "Create user profile API"
    component: "user-service"
    effort: S
    priority: P1
    status: todo
    dependencies: [TASK-001]
    acceptance:
      - "CRUD operations work"
      - "Validation in place"
      - "Tests pass"

Constraints¶

Each task should be completable in 1-2 days
Include clear acceptance criteria

Define dependencies explicitly

### 4. Coding Agent用の設定

#### .github/copilot/firewall.json

```json
{
  "firewall": {
    "enabled": true,
    "rules": [
      {
        "name": "Block all by default",
        "action": "block",
        "pattern": "*"
      },
      {
        "name": "Allow npm registry",
        "action": "allow",
        "pattern": "registry.npmjs.org"
      },
      {
        "name": "Allow company registry",
        "action": "allow",
        "pattern": "registry.company.com"
      },
      {
        "name": "Allow GitHub",
        "action": "allow",
        "pattern": "github.com"
      },
      {
        "name": "Allow documentation sites",
        "action": "allow",
        "pattern": "*.readthedocs.io"
      }
    ],
    "blocked_commands": [
      "curl",
      "wget",
      "nc",
      "telnet"
    ]
  }
}

📊 実装パターンとベストプラクティス¶

パターン1：段階的承認フロー¶

sequenceDiagram
    participant Dev as Developer
    participant AI as AI Agent
    participant Gate as Gate Keeper
    participant Review as Reviewer

    Dev->>AI: Start new feature
    AI->>Gate: Check phase gates
    Gate-->>AI: ❌ Spec not approved
    AI->>Dev: Create spec first

    Dev->>AI: Write specification
    AI->>Dev: docs/spec/requirements.md created

    Review->>Review: Review spec
    Review->>Gate: Approve (create .approved)

    Dev->>AI: Create design
    AI->>Gate: Check phase gates
    Gate-->>AI: ✅ Spec approved
    AI->>Dev: docs/design/architecture.md created

パターン2：自動検証ループ¶

# .claude/hooks/auto_validator.py
import subprocess
import json

def validate_implementation(file_path):
    """Automatically validate implementation against spec"""

    validations = []

    # 1. Check if tests exist
    test_file = file_path.replace('.py', '_test.py')
    if not os.path.exists(test_file):
        validations.append({
            'level': 'ERROR',
            'message': f'No test file found for {file_path}'
        })

    # 2. Run linter
    result = subprocess.run(['pylint', file_path], capture_output=True)
    if result.returncode != 0:
        validations.append({
            'level': 'WARNING',
            'message': 'Linting issues found'
        })

    # 3. Check coverage
    result = subprocess.run(
        ['coverage', 'run', '-m', 'pytest', test_file],
        capture_output=True
    )
    # Parse coverage and check threshold

    return validations

パターン3：エージェント間の連携¶

# .claude/workflows/feature_development.yaml
workflow:
  name: "Feature Development"
  stages:
    - stage: specification
      agent: specifier
      outputs:
        - docs/spec/requirements.md
      approval_required: true

    - stage: design
      agent: designer
      inputs:
        - docs/spec/requirements.md
      outputs:
        - docs/design/architecture.md
      approval_required: true

    - stage: tasking
      agent: tasker
      inputs:
        - docs/spec/requirements.md
        - docs/design/architecture.md
      outputs:
        - docs/tasks/todo.yaml
      approval_required: false

    - stage: implementation
      agent: implementer
      inputs:
        - docs/tasks/todo.yaml
      outputs:
        - src/**
        - tests/**
      validation:
        - make test
        - make lint

🚀 導入手順（スプリント1チェックリスト）¶

Week 1: 基盤整備¶

ディレクトリ構造作成

mkdir -p docs/{spec,design,tasks}
mkdir -p .claude/{hooks,agents}
mkdir -p .github/{instructions,prompts,copilot}

Claude Code設定

# CLAUDE.md作成
cat > CLAUDE.md << 'EOF'
[上記のCLAUDE.md内容]
EOF

# settings.json配置
cat > .claude/settings.json << 'EOF'
[上記のsettings.json内容]
EOF

# Hooks設定
python3 -m pip install pyyaml
[gatekeeper.pyを配置]

GitHub Copilot設定

# Instructions配置
[copilot-instructions.md作成]
[instructions/*.instructions.md作成]
[prompts/*作成]

Week 2: プロセス確立¶

最初の機能でフロー検証
Specifier agentで要求定義
承認プロセス実施
Designer agentで設計
Task breakdown
Implementation with gates
メトリクス計測開始
Gate違反の回数
承認までの時間
実装品質スコア

Week 3: 改善とスケール¶

フィードバック収集
Hooks/Instructions調整
チーム全体へ展開

📈 効果測定¶

導入前後の比較指標¶

メトリクス	導入前	導入後（目標）	測定方法
仕様なし実装率	73%	< 5%	Gitログ分析
設計レビュー実施率	31%	100%	承認フラグ
テストカバレッジ	42%	> 80%	Coverage.py
本番障害率	8.2%	< 2%	インシデント管理
手戻り工数	35%	< 10%	タスクトラッキング

ROI計算例¶

# 年間削減コスト計算
def calculate_roi():
    # 前提条件
    team_size = 10
    avg_salary = 8_000_000  # 円/年

    # 改善効果
    rework_reduction = 0.25  # 手戻り25%削減
    incident_reduction = 0.06  # 障害6%削減

    # コスト削減
    rework_savings = team_size * avg_salary * rework_reduction
    incident_savings = 5_000_000 * incident_reduction  # 障害1件500万円

    # 導入コスト
    setup_cost = 2_000_000  # 初期設定
    training_cost = 1_000_000  # 教育

    # ROI
    annual_savings = rework_savings + incident_savings
    roi = (annual_savings - (setup_cost + training_cost)) / (setup_cost + training_cost)

    return {
        'annual_savings': annual_savings,
        'roi_percentage': roi * 100,
        'payback_months': (setup_cost + training_cost) / (annual_savings / 12)
    }

🎓 トラブルシューティング¶

よくある問題と解決策¶

問題1：Hooksが動作しない¶

# 権限確認
chmod +x .claude/hooks/*.py

# Python環境確認
python3 --version

# Hook設定確認
cat .claude/hooks/config.json

# デバッグモード
export CLAUDE_DEBUG=1

問題2：Copilotが指示を無視¶

# .github/copilot-instructions.mdの先頭に追加
## ⚠️ CRITICAL RULES - MUST FOLLOW

These rules override all other considerations:
1. NEVER skip phase gates
2. ALWAYS check approval flags
3. MUST run tests before commit

問題3：承認フラグの管理¶

# 承認スクリプト作成
cat > approve.sh << 'EOF'
#!/bin/bash
case $1 in
  spec)
    touch docs/spec/.approved
    echo "✅ Spec approved"
    ;;
  design)
    touch docs/design/.approved
    echo "✅ Design approved"
    ;;
  *)
    echo "Usage: ./approve.sh [spec|design]"
    ;;
esac
EOF
chmod +x approve.sh

🔮 今後の展望¶

次世代機能¶

AI監査官：承認プロセスの一部を自動化
品質予測：実装前に品質問題を予測
自動リファクタリング：設計改善を自動提案
マルチエージェント協調：複数AIの自動連携

統合予定ツール¶

Amazon Kiro: ネイティブ統合
MCP (Model Context Protocol): 外部システム連携
GitHub Issues: 自動タスク生成
Jira/Linear: タスク同期

📚 まとめ¶

核心的価値¶

✅ 仕様駆動を「推奨」から「強制」へ ✅ 技術的ガードレールで品質保証 ✅ エージェントの暴走を完全制御 ✅ 監査可能な開発プロセス

実装優先順位¶

必須: CLAUDE.md + settings.json (Claude) / copilot-instructions.md (Copilot)
推奨: Hooks/Gates + Instructions files
オプション: Subagents + Prompts + Firewall

次のアクション¶

# クイックスタート
git clone https://github.com/your-org/spec-first-template
cd spec-first-template
./setup.sh

成功の鍵

最初は小規模なプロジェクトで試し、チームの反応を見ながら段階的に展開することが成功への近道です。

🔗 関連リソース¶

Tags: #SpecFirst #ClaudeCode #GitHubCopilot #Hooks #Instructions #Gatekeeper #QualityGates #AgenticCoding #DevOps #SDLC