Claude Code を「自分仕様」に最適化するには？ ハーネス設計で AI 開発が劇的に変わる実践ガイド

「Claude Code を入れたけど、何を設定すればいいか分からない」「他の人の設定を コピペしてるけど中身は知らない」「.claude フォルダの中、触っていいの?」—— 本記事では、Claude Code を「素のまま」ではなく 「自分仕様」に 最適化するための考え方と手順を、AI に詳しくない人向けにまとめます。 馬具 (ハーネス) のたとえを軸にすれば、設定ファイル・スキル・フック・MCP の役割が スッキリ整理できるはずです。

後半では筆者 (Sales Claw 開発者) が実際に使っている 32 スキル + 14 サブエージェント + 33 スラッシュコマンド + 8 フックの中身を全部開示し、なぜそれを選んだのかも 併記します。記事を最後まで読めば、「自分用の最適ハーネス」を 作るための材料がそろうはずです。

本記事は Anthropic 公式 Claude Code Docs (Overview / Settings / Skills / Subagents / Hooks / MCP / Slash Commands) と anthropics/claude-code GitHub リポジトリを 一次情報として参照しています。関連トピックは、 Claude Code スラッシュコマンド完全ガイド や MCP 完全ガイド 、 Claude Skills 使えるスキル 12 選 も併読してください。

1. そもそも「ハーネス」って何? — 馬具のたとえで一気に理解

Claude Code 本体は Anthropic がクラウドで提供する AI モデル (Claude Opus / Sonnet / Haiku) のことです。これだけだと「とても賢いけど、何をすべきかは毎回ユーザーが 指示しなければならない」状態。ここに ローカルマシン上のファイルやツールを"装備"させていくと、Claude が「自分でやるべきこと」を覚え、毎回指示しなくても動くようになります。 この装備品をひとまとめにしたのが ハーネスです。

【公式発表】 公式 Docs にはこのように 「terminal に住むエージェント型コーディングツール」と 書かれています。terminal (ターミナル) = ローカルマシンで動く前提なので、 Claude Code は 「ローカルファイルへのアクセスを前提に設計されている」のが ポイント。だからこそ、ローカルに置いたハーネス (設定ファイル群) を見て動きが変わるのです。

なぜ「ハーネス」というたとえが定着したのか

【著者見解】 Anthropic の Docs 自体は「configuration」「customization」「extensions」と 中立的な言葉を使います。「harness」という用語はローカル開発者コミュニティ (Hacker News / GitHub Discussions / 個人ブログ) で広まったたとえで、 英語圏では 2025 年後半から定着し始めました。日本語でも「ハーネス」「装備品」 「装着物」という言い方が増えていて、本記事ではこの用法を採用しています。 馬具のたとえが分かりやすい理由は、「同じ馬 (= Claude モデル本体) でも、装具で性能が 大きく変わる」という直感が伝わりやすいから、と筆者は見ています。

【未確認】 いつ「harness」というたとえが最初に登場したのか、誰が言い始めたのかは 筆者が調べた範囲では特定できませんでした (Hacker News と Reddit r/LocalLLaMA の 2025 年後半のスレッドに散発的に出てくるが、明確な起源は追えていません)。 Anthropic 公式 Docs での採用も 2026-05 時点で確認できていないので、 あくまで 「コミュニティ用語」として理解してください。 本記事の比喩は筆者なりの整理であって、唯一の正解というわけではありません。

2. 標準のままだと何が不便? — ハーネス最適化が必要な 5 つの理由

理由 1: 毎回同じ前提を書き直す問題

Claude Code を素のまま使うと、毎セッションで 「うちのプロジェクトは Next.js 16 で…」 「TypeScript の型は strict で…」「コミットメッセージは conventional commits で…」と 前置きを書き直すハメになります。これを CLAUDE.md (グローバルとプロジェクトの 2 段階) に書いておくと、Claude Code は毎回自動で読み込み、同じ前提を共有した 状態で会話を始められます。【公式発表】 Anthropic 公式 Docs は 「CLAUDE.md を使うと、Claude にプロジェクト固有の指示を常時与えられる」と説明しています。

理由 2: 危険なコマンドが素通りする問題

素の Claude Code は、ユーザーが許可すれば `rm -rf` や `git push --force` や `format` などの破壊的コマンドも実行します。事故を起こしたくなければ、 settings.json の permissions.deny に危険コマンドのパターンを書いて ブロックしておく必要があります。これがハーネスの「安全帯」部分。馬具で言うと 「シートベルト」に近い役割です。

理由 3: 専門知識を覚えない問題

Claude は汎用 AI なので、あなたの会社の DB スキーマ規約、TDD のやり方、 セキュリティチェックの観点などは知りません。毎回プロンプトで指示するのは非効率 なので、スキル (Skill) として「DB 設計の専門知識」「セキュリティレビューの 観点」をフォルダにまとめておき、Claude が必要なときに自動で読み込むようにします。 馬具で言うと「鞍 (くら) に荷物入れを付けておく」イメージ。

理由 4: 同じ作業を何度も繰り返す問題

ファイルを編集するたびに lint / 型チェック / テストを手動で走らせるのは時間のムダ。フック (Hook) を使うと、Edit / Write ツールが走った直後に自動で 品質チェックを走らせ、問題があれば次のステップに進めないようにできます。 馬具で言うと「手綱 (たづな) の役割を機械化」した感じです。

理由 5: 外部ツール連携が手作業の問題

Slack に通知したい、Notion に書き出したい、Playwright でブラウザを操作したい—— これらを毎回手で繋ぐのは非効率。MCP (Model Context Protocol) サーバを ハーネスに追加すると、Claude が 「使える道具一覧」として認識し、 必要なときに自動で呼び出します。馬具で言うと「サドルバッグに地図やコンパスを入れておく」 ようなものです。

3. ハーネスの 6 つの構成要素マップ

この表が頭に入っていれば、Claude Code の Docs を読むときも「いまどの部品の話をしてるんだろう?」がスッキリ追えるようになります。 以降の H2 では、(3) スキル × (4) サブエージェント、(5) フック × (2) settings.jsonという重要ペアを掘り下げます。

グローバルとプロジェクトの 2 段階

どの要素も 「グローバル (`~/.claude/` 配下、全プロジェクトで有効)」と「プロジェクト (`./.claude/` 配下、そのリポジトリだけ)」の 2 段階で持てます。原則として、自分専用の好み = グローバル、チーム共有 = プロジェクトと分けるのが安全です。プロジェクト側がグローバルを上書きするので、衝突したらプロジェクト優先 になります。【公式発表】 Anthropic 公式 Docs は両方の場所をサポートしており、 プロジェクト側設定をリポジトリにコミットしてチーム共有することを推奨しています。

4. Skills × Agents — 「いつ何を呼ぶか」設計の中核

Skill の仕組み

スキルは 「フォルダ + SKILL.md (説明書ファイル)」のセットです。 SKILL.md の冒頭メタデータに name (短い識別子) とdescription (いつ何のために使うかの説明) を書くと、Claude が常時 ヘッダーだけ把握しておき、ユーザー要求が description にマッチしたときに自動的に本体を 読み込んで発動します。Anthropic が 2025-10 に公式リリースした仕組みで、【公式発表】 2025-12 にオープンスタンダードとして公開されました。

Sales Claw が使っている代表的なスキル: blog-write (本記事を書いているスキル)、 note-publish (note.com 投稿)、api-design (REST API 設計)、postgres-patterns (DB クエリ最適化)、security-review (セキュリティ点検)など 32 個。 詳細は本記事末尾の H2 で全公開します。

Subagent の仕組み

サブエージェントは 「別プロセスとして起動する専門担当の Claude」です。 本体の Claude (オーケストレーター) が「コードレビューしたい」「セキュリティ点検したい」 と判断したら、サブエージェントを呼び出し、サブエージェントは別の文脈で作業して結果だけ 返します。【公式発表】 Claude Code Docs では「subagents are independent AI assistants with their own context and tools」と説明されています (=「独立した文脈とツールを 持つ補助 AI」)。

Sales Claw が使っている代表的なサブエージェント: code-reviewer (コード品質)、 security-reviewer (脆弱性検査)、database-reviewer (SQL / スキーマ)、e2e-runner (E2E テスト実行)、build-error-resolver (ビルドエラー解消)、harness-optimizer (ハーネス自体の改善)など 14 個。

どっちを使う? 判定フロー

筆者の運用ルール (【著者見解】):

1. 短時間で済む知識参照 (例: 「REST API の命名規約教えて」「PowerPoint の作り方教えて」) → Skill。同じ Claude が読み込んで答えるので軽い。
2. 長時間タスクで文脈を圧迫したくない (例: 「コードベース全体を探索して」) → Subagent。別文脈で動くので本体の会話履歴が汚れない。
3. 役割分業したい (例: コード書いた後にレビューもセキュリティチェックも欲しい) → Subagent。code-reviewer と security-reviewer に並列で投げられる。

5. Hooks × Permissions — 安全装置と自動化のつなぎ目

フックのタイミング (8 種類)

Claude Code が公式にサポートしているフックのタイミングは 【公式発表】 以下の 8 種類です:

• SessionStart: セッション開始時 (スキル一覧表示、メモリロード等)
• UserPromptSubmit: ユーザーがメッセージを送る直前 (前処理)
• PreToolUse: ツール (Bash / Edit / Write) 実行前 (ブロック判定可)
• PostToolUse: ツール実行後 (品質ゲート、PR 通知等)
• PreCompact: 文脈コンパクト前 (重要情報の保存)
• Stop: セッション終了時 (要約、通知、ゾンビプロセス掃除)
• SessionEnd: セッション完全終了マーカー
• Notification: Claude が通知を出すタイミング

筆者のハーネスでは SessionStart で「スキル一覧の表示 + claude-mem ロード」、 PreToolUse(Bash) で「git push リマインダー」、PostToolUse(Edit/Write) で「品質ゲート + post-edit 整形」、Stop で「セッション要約 + ゾンビプロセス掃除 + ntfy 通知」を 仕込んでいます。とくに Stop の `cleanup-zombies.ps1` は 「Claude Code が起動した chrome / playwright のゾンビが残る問題」を解決するために 書いた PowerShell スクリプトで、これだけでマシンの安定性が大幅に改善されました。

許可設定の鉄則

settings.json の `permissions` には allow (許可) / deny (拒否) / defaultMode の 3 つを書きます。筆者の運用ルール (【著者見解】):

1. Read は全許可: `Read(*)` を allow に入れる。読むだけなら安全。
2. Write は /tmp と Downloads だけ: 任意の場所に書かれると事故るので、 安全な場所だけ allow、それ以外は明示的に許可を求める。
3. Bash は破壊系を完全に deny: `Bash(rm *)` / `Bash(del *)` / `Bash(format *)` / `Bash(shutdown *)` / `Bash(taskkill *)` / `Bash(* --force*)` の 6 つは deny リスト固定。間違って実行されることがなくなる。
4. defaultMode は "auto": 許可されていないツールは確認プロンプトが出る。 いきなり実行しないので安全。

6. 実践: 自分用ハーネスを作る 6 ステップ

Step 1: CLAUDE.md を作る (Day 1 / 30 分)

まずホームに `~/.claude/CLAUDE.md` という名前のファイルを作り、自分の好み・職種・ ふだん書いているプロジェクトの中身を 200-500 字で書きます。例: 「日本語で答えてほしい」 「コミットメッセージは conventional commits で」「変更は最小限」など。これだけで毎セッションの 最初に毎回書いていた前置きが消えます。プロジェクトごとの細かい指示は、そのリポジトリ直下の`./CLAUDE.md` に書きます。中身はふつうの文章で OK、難しい構文は要りません。

Step 2: settings.json で deny リスト (Day 1 / 10 分)

`~/.claude/settings.json` を作って、最低限以下を入れます:

{
  "permissions": {
    "deny": [
      "Bash(rm *)",
      "Bash(del *)",
      "Bash(rmdir *)",
      "Bash(* --force*)",
      "Bash(format *)",
      "Bash(shutdown *)"
    ],
    "defaultMode": "auto"
  }
}

これで 「事故ったら一発で終わるコマンド」が動かなくなる状態になります。 これだけで Day 1 のセットアップは終わり。

Step 3: 公式スキル 4 つを入れる (Day 7 / 1 時間)

Anthropic 公式の pptx / xlsx / docx / pdf スキルを、Claude Code から/plugin marketplace add anthropics/skills と/plugin install anthropic-skills で導入します。 詳細は Claude Skills 使えるスキル 12 選 参照。これだけで「PowerPoint 作って」「Excel 整形して」「Word でひな形作って」 「PDF からテーブル抜いて」という日常事務が AI に投げられるようになります。

Step 4: サブエージェント 3 個入れる (Day 14 / 1 時間)

まず code-reviewer (コード品質)、security-reviewer (セキュリティ)、planner (設計プランナー) の 3 つを `~/.claude/agents/[name].md` に フロントマター付き Markdown として置きます。最初の 1 個は Claude に「サブエージェント 定義を書いて」と頼んで生成させ、目視で調整するのが楽です。

Step 5: フックを 1 つだけ入れて慣れる (Day 21 / 30 分)

まず SessionStart に「スキル一覧の表示」を 1 つだけ仕込んでみます。 これだけで「セッションを始めるたびに自分の手持ち装備が一目で分かる」状態になり、 ハーネスを使っている実感が湧きます。次に PostToolUse(Edit) で品質ゲートを足す、 などを段階追加。

Step 6: MCP を 1 つ追加 (Day 30 / 1 時間)

最後に MCP サーバを 1 つだけ追加します。最初はPlaywright MCP (ブラウザ自動操作) かSlack MCP がおすすめ。両方一気に入れると「何が動いているか 分からない」状態に戻るので、必ず 1 つずつ。

7. リスク・注意点 — 壊れる / 競合 / セキュリティ / コスト膨張

リスク 1: 入れ過ぎで遅くなる

スキルは Level 1 メタデータが 1 個あたり約 100 トークン常時ロード されます。100 個入れると 10,000 トークン分が毎セッション消費される計算。 Claude の判断速度も遅くなる傾向があります。【著者見解】 Sales Claw の運用では 「常用 30 個前後」が上限の目安で、 それを超えたら月 1 で棚卸し (使っていないスキルを削除) しています。

リスク 2: スキル名が競合する

description が似ているスキルが複数あると、Claude がどれを発動するか予測しにくく なります。【公式発表】 Anthropic 公式 Docs は 「Use unique, descriptive names」と警告しており、name は組織内で重複しないよう 命名規約を決めるべき、と説明しています。Sales Claw では「動詞-対象」の命名に統一 (blog-write, note-publish, security-scan 等)。

リスク 3: フックでセッションが起動しない

SessionStart フックでエラーが出るとセッション自体が起動しない or 真っ白になる ことがあります。筆者の対策: フックの先頭に `|| true` を 付けて、エラーでもセッションをブロックしないようにする。例:command="powershell.exe -File cleanup.ps1 || true"。 筆者は実際にこれで救われた経験あり (cleanup-zombies.ps1 がエラー終了したとき、 セッション開始がフリーズした)。

リスク 4: MCP のセキュリティ穴

第三者の MCP サーバを入れると、そのサーバが Claude にどんなツールを渡せるかがブラックボックスになりがちです。【公式発表】 Anthropic 公式 Docs は 「MCP servers run with your local privileges」と明記しており、信頼できないサーバは 絶対に追加しないよう警告しています。Sales Claw では公式 (Anthropic / Microsoft / Google 公式) か OSS で監査できるものだけに限定。

リスク 5: コスト膨張

サブエージェントは 1 起動あたり 30-60K トークン消費します。 コード変更のたびに code-reviewer + security-reviewer + database-reviewer を 自動起動すると、月のトークン消費が想定外に膨らみます。筆者の対策: サブエージェントの自動起動条件を 「影響ファイル 5 個以上」「認証 / API 系」 「SQL / スキーマ変更時」などに絞る (CLAUDE.md の自動起動テーブルとして明文化)。

8. 全公開: Sales Claw の実 harness (32 + 14 + 33 + 8)

スキル 32 個 (グローバル 30 + プロジェクト 2)

グローバル (~/.claude/skills/): api-design, backend-patterns, claude-office-skills, coding-standards, debug-issue, e2e-testing, explore-codebase, find-skills, frontend-patterns, frontend-slides, grant-rewrite, keiba-analysis, keiba-race-analyst, learned, postgres-patterns, proposal-master, refactor-safely, review-changes, search-first, security-review, security-scan, strategic-compact, task-planner, tdd-workflow, workspace-init + Anthropic 公式 マーケットプレイス導入の anthropic-skills (pptx / xlsx / docx / pdf 等)と cowork-plugin-management 系。

プロジェクト (./.claude/skills/): blog-write (本記事を書いているスキル)、 note-publish (note.com 投稿) の 2 つ。Sales Claw 専用なのでプロジェクト側に 置いてリポジトリにコミットしています。

サブエージェント 14 個

architect (アーキテクチャ設計)、bp-sales (営業自動化)、build-error-resolver (ビルドエラー解消)、code-reviewer (コード品質)、database-reviewer (DB / SQL)、 doc-updater (ドキュメント更新)、e2e-runner (E2E テスト)、harness-optimizer (ハーネス自身の改善)、loop-operator (自律ループ運用)、planner (設計プランナー)、 python-reviewer (Python レビュー)、refactor-cleaner (リファクタ清掃)、 security-reviewer (脆弱性検査)、tdd-guide (TDD ガイド)の 14 個。 「動詞 + 対象」または「役割名」で命名統一しています。

スラッシュコマンド 33 個

筆者がいちばん使うのは /claw (Sales Claw 開発レプル)、/ship (デプロイ準備)、 /eng-review (技術レビュー)、/ceo-review (プロダクト思考レビュー)、/eval (評価)、 /harness-audit (ハーネス監査)、/checkpoint (中間保存)の 7 つ。 他は /code-review, /security-review, /python-review, /quality-gate, /tdd, /e2e, /test-coverage, /build-fix, /refactor-clean, /update-codemaps, /update-docs, /verify, /plan, /orchestrate, /loop-start, /loop-status, /model-route, /pptx-build-public, /skill-create, /learn, /learn-eval, /promote, /instinct-export, /instinct-import, /instinct-status, /projects, /sessions, /evolve。

フック 8 個

SessionStart で スキル一覧表示 + claude-mem ロード + session-start.js。 UserPromptSubmit で claude-mem session-init。 PreToolUse(Bash) で git-push-reminder。 PreToolUse(Edit|Write) で suggest-compact。 PostToolUse(Bash) で post-bash-pr-created。 PostToolUse(Edit|Write|MultiEdit) で quality-gate.js + post-edit-all.js。 PreCompact で pre-compact.js。 Stop で claude-mem summarize + session-end.js + cost-tracker.js + ntfy-stop.py + cleanup-zombies.ps1。 計 8 種類のタイミングで合計 14 個のコマンドが自動実行されます。

この harness を組んでから、1 セッションあたりの平均会話往復が 12 回 → 6 回に減り、「同じことを 2 回説明する」がほぼ消えました。 これがハーネス最適化の本質的なメリットです。

9. まとめ — まず CLAUDE.md と deny の 2 つから

Claude Code のハーネス最適化は、「CLAUDE.md (前提) + settings.json (deny)」の 2 つから始めれば、Day 1 で 80% のメリットが得られます。残り 20% はスキル → サブエージェント → フック → MCP の順で 30 日かけて 段階導入するのが筆者の推奨です。

最大のコツは 「足し過ぎないこと」。 装着物は鎧 (よろい) と一緒で、重ねるほど動きが鈍くなります。 本記事末尾で公開した Sales Claw の 87 装着物も、1 年 5 か月かけて段階的に育てたものです。 まずは Day 1 の CLAUDE.md + deny 6 個から始めてみてください。

Sales Claw 自体は、これらのハーネスを使って BtoB の問い合わせフォーム営業を自動化するプロダクトです。「ポリシー制御付き自律運用」を方針に、送信前自動検査・ 営業 NG 検出・CAPTCHA 検出時停止・送信頻度制限・監査ログ保存によって、誤送信と規約違反 リスクを下げる設計を採用しています。詳しくは下記からどうぞ。

今すぐ Sales Claw で、営業をもっとスマートに。

無料・MIT ライセンス。インストールせずにライブデモも試せます。

無料でダウンロードライブデモを試すGitHub