第14章 — 実践: ゼロからハーネスを組む

新しいプロジェクト

ユウキに新しいミッションが与えられた。社内の新規プロダクトのテックリードだ。チームは8人。前のプロジェクトで培ったハーネスエンジニアリングの知識を、最初から活かすチャンスだ。

「今度は最初からハーネスを組む。スパゲッティコードの二の舞は御免だ」

ハーネス構築の全体像

Loading diagram...

Day 1: 基盤構築

ディレクトリ構造

project-root/
├── .claude/
│   ├── CLAUDE.md          # プロジェクトルール
│   ├── settings.json      # 権限と Hooks
│   ├── settings.local.json # 個人設定（.gitignore）
│   ├── rules/             # パス限定ルール
│   │   ├── api.md
│   │   ├── components.md
│   │   └── tests.md
│   ├── commands/           # チーム共有コマンド
│   │   ├── commit.md
│   │   ├── pr.md
│   │   └── review.md
│   └── agents/             # カスタムエージェント
│       ├── api-reviewer.md
│       └── db-checker.md
├── CLAUDE.local.md          # 個人用（.gitignore）
├── .mcp.json               # MCP 設定
└── ...

最小限の CLAUDE.md

初日に書くのは最小限でいい。プロジェクトが育つにつれて追記する。

# new-product
 
## 概要
- B2B SaaS の在庫管理ツール
- スタック: Next.js 15 (App Router) + TypeScript + Drizzle ORM + PostgreSQL
- デプロイ: Vercel
 
## セットアップ
pnpm install && pnpm dev
 
## 規約
- TypeScript strict。any 禁止
- コンポーネントは named export
- DB アクセスは src/db/queries/ 経由
- ユーザー入力は zod バリデーション必須
 
## テスト
- pnpm test（Vitest）
- 新機能にはテスト必須

最小限の settings.json

{
  "permissions": {
    "deny": [
      "Read(**/.env*)",
      "Edit(**/.env*)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "bash ~/.claude/block-destructive.sh \"$TOOL_INPUT\"",
        "description": "破壊的コマンドをブロック"
      },
      {
        "matcher": "Edit|Write",
        "command": "bash ~/.claude/guard-secrets.sh \"$TOOL_INPUT\"",
        "description": "秘密鍵の混入をブロック"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "biome format --write \"$FILEPATH\" 2>/dev/null; true",
        "description": "自動フォーマット"
      }
    ]
  }
}

Week 1: 品質ゲートの確立

パス限定ルールの追加

<!-- .claude/rules/api.md -->
---
paths:
  - "src/app/api/**/*.ts"
---
# API ルール
- 全エンドポイントで認証ミドルウェアを使用
- リクエストは zod スキーマでバリデーション
- レスポンス形式: { data, error, pagination }
- エラーは HttpError クラスを throw

チーム共有コマンドの作成

<!-- .claude/commands/commit.md -->
変更を Conventional Commits 形式でコミットする。
 
1. git diff --staged で変更を確認
2. 論理単位に分割
3. type(scope): description 形式でコミット
4. push はしない

<!-- .claude/commands/pr.md -->
現在のブランチから PR を作成する。
 
1. git log main..HEAD と git diff main...HEAD で全変更を確認
2. タイトル（70文字以内）と要約（3点以内）を作成
3. gh pr create で作成

Week 2: 専門家チームの編成

チームに必要なエージェントを特定する

Loading diagram...

MCP の導入

{
  "mcpServers": {
    "github": {
      "command": "gh",
      "args": ["mcp"],
      "description": "GitHub Issue/PR"
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp"],
      "description": "ドキュメント参照"
    }
  }
}

Week 3: 自動化とワークフロー

コードレビュー Workflow

export const meta = {
  name: 'team-review',
  description: 'チームの変更をマルチ観点でレビュー',
  phases: [
    { title: 'Review' },
    { title: 'Verify' },
  ],
}
 
const REVIEWERS = [
  { key: 'bugs', prompt: 'バグの可能性を探せ' },
  { key: 'security', prompt: 'セキュリティリスクを探せ' },
  { key: 'perf', prompt: 'パフォーマンス問題を探せ' },
]
 
phase('Review')
const results = await pipeline(
  REVIEWERS,
  (r) => agent(r.prompt, {
    label: `review:${r.key}`,
    phase: 'Review',
    schema: FINDINGS
  }),
  (review) => parallel(
    review.findings.map(f => () =>
      agent(`反駁せよ: ${f.title}`, {
        phase: 'Verify',
        schema: VERDICT
      }).then(v => ({ ...f, verdict: v }))
    )
  )
)
 
return results.flat().filter(Boolean)
  .filter(f => f.verdict && !f.verdict.refuted)

段階的導入のチェックリスト

INFO

一度にすべてを導入しようとしない。段階的に、チームが消化できるペースで進める。

Phase 1（Day 1）— 必須

CLAUDE.md にプロジェクト概要とスタックを記載
settings.json に秘密鍵ガード Hook を設定
settings.json に破壊的操作ブロック Hook を設定
permissions.deny で .env, .ssh, .aws を保護

Phase 2（Week 1）— 品質

PostToolUse に自動フォーマット Hook を追加
rules/ にファイル種別ごとのルールを追加
/commit と /pr コマンドを作成
CLAUDE.md にコーディング規約を追記

Phase 3（Week 2）— 専門化

プロジェクト固有のカスタムエージェントを1〜2体作成
MCP で GitHub 連携を設定
レビュー用の Skill を作成

Phase 4（Week 3+）— 自動化

レビュー Workflow を構築
セキュリティ監査 Workflow を構築
チーム全体の Skill を統一

チームへの展開

オンボーディングの設計

新メンバーが入ったとき、ハーネスがあれば立ち上がりが早い。

Loading diagram...

ハーネスの共有と進化

## チームルール
- .claude/ 配下の変更は PR レビュー必須
- 新しい Skill は全員で議論してからマージ
- 月1回のハーネスレトロスペクティブを実施

効果測定

ユウキのチームは、ハーネス導入前後で以下の変化を観測した。

Loading chart...

注目すべきは、導入初週は開発速度が一時的に下がること。ハーネスのセットアップと学習にコストがかかるからだ。しかし2週目以降は急速に回復し、4週目には導入前を超える。品質スコアは一貫して向上し続ける。

「最初の1週間は投資だ」とユウキはチームに説明した。「でも1ヶ月後には、その投資の何倍もの見返りがある」

よくある質問

「小さなプロジェクトにもハーネスは必要？」

最小限でいい。CLAUDE.md とセキュリティ Hook だけで十分。5分で設定できる。

「既存プロジェクトにも導入できる？」

できる。Day 1 の構成から始めて、段階的に追加する。既存のコードを変更する必要はない。

「Cursor など他のツールでも使える？」

CLAUDE.md のようなプロジェクトルールファイルは Cursor（.cursorrules）にも存在する。ただし Hooks、Skills、Subagents、Workflow は Claude Code 固有の機能。

ユウキの成長

新プロジェクト開始から3ヶ月。チームの8人全員がハーネスを使いこなしていた。

「半年前のぼくは、AI に何でも丸投げしていた。今は、AI が最高のパフォーマンスを発揮できる環境を設計している。エンジニアの仕事が変わったんだ——コードを書くことから、コードを書く仕組みを設計することへ」

最終章では、ハーネスエンジニアリングの未来と、これからのエンジニアに求められるスキルを展望する。