ハーネスの組み立て方
実装ガイド

1ハーネス＝AIの「作業ループ」を支える足場

まず5秒のおさらい。ハーネス（harness）とは、モデル本体ではなく、そのまわりの仕組み——道具・記憶・実行の段取り・検証・記録のこと。上手な人ほど、このループが「自動でうまく回る」ように足場を作り込んでいます。

flowchart LR
  A["①集める
必要な文脈だけ
コンテキストに載せる"] --> B["②動く
小さく実行する"]
  B --> C["③確かめる
テスト・差分・画面で検証"]
  C --> D["④記録する
コミット・進捗メモ・
CLAUDE.md更新"]
  D --> E["⑤片づける
/compact で軽くする"]
  E --> A
    

このページで作る部品は、すべてこの5つの動きのどれかを自動化・確実化するためのものです。たとえば「①集める」は CLAUDE.md とスキル、「③確かめる」は hooks と検証ループ、「④記録する」は進捗ファイルと Git——というふうに、部品とループの動きが対応しています。それを意識すると、「なぜこの足場が効くのか」が腑に落ちます。

2足場の「7つの部品」全体地図

ハーネスは、次の7部品の組み合わせでできています。置き場所といつ効くかが部品ごとに違うのがポイント。下の地図を見てから、必要な節へ飛んでください。

3部品①：記憶の足場（CLAUDE.md を「層」で設計）

CLAUDE.md は、Claude が毎回自動で読む取扱説明書。上手な人は、これを「個人の好み」「プロジェクトの約束」のように層（レイヤー）で分けて設計します。

🗂️置き場所で「適用範囲」が変わる

同じ書き方でも、置く場所によって「誰の・どのプロジェクトに効くか」が変わります。読み込まれたものは上書きではなく全部つながって渡されます。

🔗@インポートで「分割して読み込む」

CLAUDE.md が長くなったら、別ファイルに分けて @パス で取り込めます。本体はスッキリ、詳細は別ファイル——という設計ができます。

# このプロジェクトについて
個人開発のWebアプリ。Next.js + Supabase。

## 必ず守ること
- 返答とコード内のコメントは日本語で。
- 新しい依存を足す前に、必要かどうかを一言確認する。
- 秘密の値は .env に。コードに直書きしない。

## よく使うコマンド
- 開発サーバ: `npm run dev`
- テスト: `npm test`

# 詳しい決まりは別ファイルから取り込む
ビルド手順: @docs/build.md
コーディング規約: @docs/style.md

🌱育て方：「また説明した」がサイン

1. 最初は /init で雛形プロジェクトを分析して CLAUDE.md の下書きを作ってくれます。まずはこれを土台に。
2. 同じ説明を2回したら追記「またこれ説明したな」と思ったら、それは CLAUDE.md に書くべきルール。/memory で素早く開いて追記できます。
3. 短く保つ長すぎるとコンテキストを圧迫して逆効果。本当に効くルールだけを簡潔に。迷ったら消す。

4部品②：手順の足場（「検証つきスキル」を作る）

スキルの基本は 拡張§2 にあります。ここでは一歩進めて、「いまの状態を自動で読み込み、終わったら自分で確かめる」——足場として強いスキルの作り方を見ます。

🧱強いスキルの3点セット

この3つを盛り込んだ、実用的なスキルの例がこちらです。/ship 機能名 のように使います。

---
description: 変更を仕上げて安全にコミットする。「コミットして」「仕上げて」で発動。
argument-hint: "[機能名]"
allowed-tools: Bash(git *), Bash(npm test), Read
model: sonnet
---

# いまの状態（Claudeが読む前に自動実行されて埋め込まれる）
## 変更ファイル
!`git status --short`

## 直近の差分
!`git diff --stat`

# 指示
「$ARGUMENTS」の変更を仕上げます。次の順で進めてください。
1. 上の差分を確認し、やり残し（消し忘れのログ・直書きの値）がないか点検
2. `npm test` を実行し、緑になるまで直す
3. 通ったら、変更内容がわかる日本語のメッセージで git commit
4. コミットしたハッシュと要約を報告

🎯引数を「順番」で受け取る

$ARGUMENTS は打った言葉ぜんぶ。順番ごとに分けたいときは $1 $2（または $ARGUMENTS[0]）が使えます。

# /release v1.2 staging と打つと…
/release v1.2 staging
# 本文の中で $1 → "v1.2"、$2 → "staging" に置き換わる

📁サブフォルダで「名前空間」を作る

スキル/コマンドはフォルダで仲間分けできます。.claude/commands/git/commit.md に置くと /git:commit という名前になり、整理しやすくなります。

5部品③：分担の足場（サブエージェント）

大きな調査や定型レビューは、子分（サブエージェント）に任せると速く、しかも親の作業机（コンテキスト）が汚れません。子分は自分専用の記憶領域で働き、終わったら要点だけを親に返します。これが「コンテキスト分離」です。

flowchart TD
  P["親：司令塔
計画とまとめ役
（机はきれいなまま）"] --> A["子分A
コードを調査"]
  P --> B["子分B
テストを点検"]
  P --> C["子分C
ドキュメント確認"]
  A -->|"要点だけ返す"| R["親が統合"]
  B -->|"要点だけ返す"| R
  C -->|"要点だけ返す"| R
  R --> D["親が仕上げ"]
    

📝サブエージェントの作り方

専用の子分は .claude/agents/名前.md（プロジェクト用）または ~/.claude/agents/名前.md（全プロジェクト用）に置きます。frontmatter で性格を決め、本文がその子分のシステムプロンプト（指示書）になります。

---
name: code-reviewer
description: コードの変更をレビューする。品質・バグ・セキュリティを点検したいときに使う。
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたは丁寧なコードレビュアーです。次の観点で変更を点検し、
日本語で「良い点」「直すべき点（理由つき）」を箇条書きにしてください。

- バグや抜けたエラー処理がないか
- 直書きの秘密・危険なコマンドがないか
- 命名や構造が周りのコードと揃っているか

修正は提案だけ。勝手にファイルを書き換えないこと。

▶️呼び出し方は3通り

• 自動で振り分け「この変更をレビューして」と頼むと、description に合う子分へ Claude が自動で委譲します。
• 名前で指名「code-reviewer サブエージェントを使ってレビューして」と名指しすれば確実。
• メニューで管理/agents で、子分の一覧・新規作成・編集ができます。

6部品④：検証の足場（Hooks で「必ず」効かせる）

CLAUDE.md はお願い（AIが従うとは限らない）。一方 Hooks は命令（必ず実行される）です。「編集したら必ず整形」「このファイルは絶対に触らせない」——確実なルールは Hooks で作ります。基本の考え方は 拡張§4 に、ここでは実際の settings.json の中身を見ます。

🎨例A：編集後に「必ず」自動整形（PostToolUse）

ファイルを編集・作成したら、その編集したファイルだけを整形ツール（Prettier）にかける設定です。手作業ゼロでコードが整います。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -r prettier --write"
          }
        ]
      }
    ]
  }
}

🚫例B：守りたいファイルを「触らせない」（PreToolUse）

本番設定やマイグレーションなど「AIに勝手に編集されたくない」ファイルは、PreToolUse（ツールを使う前）で止められます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/protect.sh" }
        ]
      }
    ]
  }
}

#!/bin/bash
FILE=$(cat | jq -r '.tool_input.file_path')

# .env や migrations/ への編集を止める
if echo "$FILE" | grep -qE '\.env|/migrations/'; then
  echo "このファイルは保護されています: $FILE" >&2
  exit 2   # exit 2 = ブロック（理由が Claude に伝わる）
fi
exit 0     # exit 0 = 異議なし。通常通り進む

📅覚えておくと便利なイベント

7部品⑤：権限の足場（allow / deny を設計）

毎回「実行していい？」と聞かれるのは、安全な反面わずらわしい。「これは確認なしでOK」「これは絶対ダメ」を先に決めておくと、安全なまま快適に進められます。これも settings.json で設計します。

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read",
      "Edit(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Read(./.env)",
      "Edit(./.env)"
    ],
    "ask": [
      "Bash(git push *)"
    ]
  }
}

🏛️設定ファイルの「強さの順番」

設定は複数の場所に置けて、上にあるものほど強い（あとから勝つ）ルールです。

🔀パーミッションモード（その場の動き方）

セッション全体の「確認の厳しさ」は、Shift+Tab でその場で切り替えられます。巡回は default（表示は Manual）→ acceptEdits → plan の順で、auto（危険な操作だけ分類器AIが自動ブロック）や bypassPermissions は有効化しているときだけ加わります。

8検証ループ：ハーネスの心臓

ここがいちばん効きます。AIに「自分の答え合わせをする手段」を渡すと、AIは自分でミスに気づいて直し、品質を一気に上げます。逆に検証手段がないと、もっともらしいけれど動かないコード（ハルシネーション）が紛れ込みます。

🔁「作る相手」ごとの検証手段

sequenceDiagram
  participant U as あなた
  participant C as ClaudeCode
  participant T as テスト/実行
  U->>C: ①先に「失敗するテスト」を書いて
  C->>U: テスト作成（まだ赤）
  U->>C: ②このテストが通るよう実装して
  C->>T: 実装して npm test
  T-->>C: 失敗（赤）
  C->>C: 原因を読んで自分で修正
  C->>T: もう一度 npm test
  T-->>C: 成功（緑）
  C-->>U: 完成。/diff で最終確認を
    

9長時間エージェントの足場（公式の実践）

何時間・何セッションもかかる大きな作業は、コンテキストの限界と戦うことになります。Anthropic 公式の知見をもとに、「中断しても続きから安定して進める」足場の作り方をまとめます。

flowchart TD
  S1["セッション1
機能Aを実装→テスト緑→コミット"] --> P["PROGRESS.md 更新
「A完了 / 次はB」"]
  P --> S2["セッション2
PROGRESS.md を読む
→機能Bを実装→コミット"]
  S2 --> P2["PROGRESS.md 更新"]
  P2 --> S3["セッション3
続きから…"]
    

10自動化の足場（ヘッドレス claude -p）

人が画面の前にいなくても動く「自動化」も上級者の武器。-p（print）を付けると、Claude Code をスクリプトや CI/CD の一部として呼び出せます。結果を JSON で受け取り、次の処理へ流せます。

$ claude -p --bare --output-format json \
  --json-schema "$(cat schema.json)" \
  --max-budget-usd 0.50 \
  --allowedTools "Read,Bash(grep *)" \
  "このログからエラー件数を数えて、JSONで返して"

flowchart LR
  A["入力データ
ログ・CSVなど"] --> B["claude -p
（非対話で処理）"]
  B --> C["JSONで結果"]
  C --> D["次の処理へ
通知・保存・別スクリプト"]
    

11ハーネスを点検・デバッグする

足場を組むと、たまに「なんか動きが変」が起きます。そんなときの切り分け道具を知っておくと安心です。

12どれをいつ使う？決定ガイド

部品が増えると「結局どれを使えば？」と迷います。困りごとから逆引きで選べるようにしました。

flowchart TD
  Q["何に困ってる?"] --> A["毎回同じ前提を
説明している"]
  Q --> B["同じ手順を
くり返している"]
  Q --> C["重い調査で
机が散らかる"]
  Q --> D["うっかり危険操作を
確実に防ぎたい"]
  Q --> E["外部の道具と
つなぎたい"]
  Q --> F["人なしで
回したい"]
  A --> A2["CLAUDE.md §3"]
  B --> B2["スキル §4"]
  C --> C2["サブエージェント §5"]
  D --> D2["Hooks + 権限 §6/§7"]
  E --> E2["MCP（拡張§5）"]
  F --> F2["ヘッドレス §10"]
    

13実装チェックリスト & 次の一歩

今日から組める「足場づくり」の習慣です。全部いっぺんにやらなくてOK。上から1つずつ。