0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@KuwadaKouhei(Kouhei Kuwada)

今日から始めるハーネスエンジニアリング: 個人開発者のための最初の5ステップ

0
Posted at

はじめに

「同じプロンプトを毎回貼り付けている」「AIに毎回プロジェクトの説明をしている」「危険なコマンドを止め忘れて事故った」——AIコーディングを使い始めると、こうした 「AIそのもの」ではなく「AIを取り巻く環境」 の課題に必ずぶつかります。

この「環境」を意図的に設計する営みが、最近 ハーネスエンジニアリング (Harness Engineering) と呼ばれるようになってきました。ハーネス1とは「馬具」のこと。LLMという賢い馬を、目的地まで安全に走らせるための馬具を整える仕事、というイメージです。

本記事では、ジュニアエンジニアや個人開発者がまず手を付けるべき 5つの具体的ステップ を順序立てて紹介します。Claude Code を例に解説しますが、考え方は Cursor / Cline / Codex CLI など他のエージェント型ツールにも転用できます。

対象読者

  • 最近「ハーネスエンジニアリング」という言葉をよく聞くが、何から手を付ければいいか分からない 方
  • これからハーネスエンジニアリングを 始めてみたい 方
  • AIコーディングツール（Claude Code / Cursor / Cline など）を 触ったことはあるが、本格的にカスタマイズしたことはない 方
  • プロンプトエンジニアリングは聞くけれど、ハーネスエンジニアリングは初耳という方
  • 個人開発・副業開発で AIに任せる範囲を広げたい ジュニア〜中堅エンジニア

動作環境

項目 バージョン
Claude Code v2.x 以降
OS macOS / Windows / Linux いずれも可
前提知識 ターミナル操作、JSON/Markdown が読める

TL;DR

  • ハーネスエンジニアリングとは、LLM本体ではなく「LLMを取り巻く実行環境」を設計する 営み
  • 個人開発者が今日から始めるなら、以下の5ステップを この順番 で進めるのが最短ルート
    1. CLAUDE.md に「自分・プロジェクトの取扱説明書」を書く
    2. settings.json で権限を整え、許可プロンプトの摩擦を減らす
    3. Slash Command / Skill で繰り返し作業をテンプレ化する
    4. Hooks で安全装置と自動化を仕込む
    5. Memory で会話を超えた知識を持たせる
  • すべて コードを書く必要はない。テキストファイルとJSONを編集するだけで効果が出る

ハーネスエンジニアリングとは何か

ハーネスを構成する代表的な要素

「LLMを賢くする」のではなく、「LLMが賢く動ける環境を整える」のがハーネスエンジニアリングです。

プロンプトエンジニアリングとの違い

「結局プロンプトエンジニアリングとどう違うの？」という疑問は、ほぼ全員が最初にぶつかる壁です。ここを丁寧に整理します。

一言で表すと

プロンプトはセリフ、ハーネスはステージ。

役者（LLM）にどんな名セリフを覚えさせても、舞台の照明・音響・小道具が整っていなければ良い演劇にはなりません。逆にステージだけ立派でもセリフが空っぽなら何も伝わりません。両者は 対立するものではなく、層が違う のです。

比較表で並べてみる

観点 プロンプトエンジニアリング ハーネスエンジニアリング
何を扱うか LLMへの 入力テキスト LLMを 取り巻く実行環境全体
編集対象 プロンプト文字列 設定ファイル・ツール定義・フック・権限
効果の持続 その会話・その1回限り すべての会話に永続して効く
主なスキル 言葉選び・構造化・例示 システム設計・運用・セキュリティ
代表テクニック Few-shot, Chain-of-Thought, Role指定 CLAUDE.md, Hooks, MCP, 権限制御
失敗の主因 指示があいまい・例が不十分 権限が緩い・コンテキストが古い
改善のサイクル 即時（書いて投げて結果を見る） 中長期（運用して気づいて整える）
たとえ 名セリフを書く脚本家 舞台装置を組む舞台監督

同じ問題を「両者で解く」と何が違うか

具体的に、「コミットメッセージを Conventional Commits 形式で書かせたい」 という同じゴールを、両者のアプローチで解いてみます。

プロンプトエンジニアリング的アプローチ

以下の差分を読み、Conventional Commits 形式でメッセージを生成してください。
形式: <type>(<scope>): <description>
type は feat / fix / chore / docs / refactor から選んでください。
description は50文字以内、命令形、英語、末尾にピリオドなし。

例:
- feat(auth): add OAuth2 login flow
- fix(api): handle null response from /users

差分:
（差分が続く）

メリット: その場ですぐ書けて、すぐ効く。
デメリット: 次の会話でも、その次でも、毎回これを貼り付ける必要がある。チームで揃えるのも難しい。

ハーネスエンジニアリング的アプローチ

.claude/commands/commit.md
---
description: ステージング済みの変更をConventional Commits形式でコミットする
---

`git diff --cached` を読み、以下のルールでコミットメッセージを生成してから `git commit` を実行してください。

- 形式: `<type>(<scope>): <description>`
- type: feat / fix / chore / docs / refactor
- description: 50文字以内、命令形、英語、末尾ピリオドなし
- scope は変更が集中するディレクトリ名

メリット: 一度書けば /commit の1コマンドで永続的に使える。チームで .claude/ を共有すれば全員に効く。
デメリット: 初回のセットアップにひと手間かかる。

どこが「層が違う」のか

ハーネスは 「すべてのプロンプトの下敷き」 として常に効いています。だから、ハーネスを整えると プロンプトが短くて済む ようになります。これは「プロンプトエンジニアリングが要らなくなる」ということではなく、「プロンプトが本来やるべきこと（その会話固有の指示）に集中できる」ということです。

どちらから始めるべきか

状況 優先すべき側
ChatGPTのWeb版だけを使っている プロンプトエンジニアリング（ハーネスを触る余地が少ない）
Claude Code / Cursor / Cline などエージェント型を使っている ハーネスエンジニアリング（効果が累積する）
同じ訂正を3回以上している ハーネスエンジニアリング（プロンプトでは解けない問題）
単発のコード生成・文章生成 プロンプトエンジニアリング
業務に組み込みたい・チームで使いたい ハーネスエンジニアリング（再現性と安全性のため）

両者は 置き換え関係ではなく積み上げ関係 です。良いハーネスの上で良いプロンプトを書く——これが理想形。本記事はその「土台側」をどう積むかにフォーカスしています。

よくある誤解

  • 誤解1: 「ハーネスエンジニアリング = プロンプトを設定ファイルに書くこと」
    → 違います。CLAUDE.md は確かにシステムプロンプト的に効きますが、ハーネスはそれだけでなく 権限・ツール・フック・メモリ など複数の仕組みの総称です。
  • 誤解2: 「プロンプトエンジニアリングはもう古い」
    → 違います。ハーネスを整えても、最終的にAIに何をさせるかを伝えるのはプロンプトです。両方のスキルが必要 です。
  • 誤解3: 「ハーネスは大企業がやるもの」
    → 個人開発こそ恩恵が大きいです。設定するのも使うのも自分なので、自分の作業パターンに完全フィットするハーネスを作れます。

ステップ1: CLAUDE.md に「取扱説明書」を書く

最初の一歩は テキストファイル1つ から始まります。

なぜ最初にやるべきか

毎回チャットで「このプロジェクトはNext.jsで〜」「私はバックエンド寄りで〜」と説明するのは、プロンプトの 無駄打ち です。CLAUDE.md に書いておけば、すべての会話で自動的にコンテキストとして読み込まれます。

書く場所と優先順位

配置場所 用途 例
~/.claude/CLAUDE.md すべてのプロジェクトで共通の好み 言語ポリシー、コミュニケーション流儀
<project>/CLAUDE.md そのプロジェクト固有の情報 アーキテクチャ、テスト実行コマンド
<project>/.claude/CLAUDE.md プロジェクト個人設定（gitignore対象） 個人API鍵の参照先など

最小構成のテンプレート

~/.claude/CLAUDE.md
## 言語ポリシー
- 内部処理は英語で考え、ユーザーへの返答は日本語で行う

## 開発ポリシー
- .envファイルは決して読まない
- try-catchでエラーを握りつぶさない
- 何かを変更した際は最後にどこを変更したかを説明する

## コミュニケーション
- 質問への回答は日本語
- 技術用語は英語のまま使ってよい
/CLAUDE.md
## このプロジェクトについて
個人開発のタスク管理アプリ。Next.js 15 + Prisma + PostgreSQL。

## よく使うコマンド
- 開発サーバー: `pnpm dev`
- テスト: `pnpm test`
- DBマイグレーション: `pnpm prisma migrate dev`

## アーキテクチャの約束
- API は `app/api/**/route.ts` に配置
- DB アクセスは `lib/db/` のリポジトリ経由のみ
- 直接 `prisma.` をコンポーネントから呼ばない

最初は完璧を目指さず、5〜10行から始める のがコツです。AIに「あ、それ毎回言ってるな」と感じたら追記する、で十分育っていきます。

よくある失敗

- ## このプロジェクトの全ファイル
- - app/page.tsx: ホームページ
- - app/api/users/route.ts: ユーザーAPI
- - (50行続く...)
+ ## アーキテクチャの約束
+ - API は app/api/**/route.ts に配置
+ - DB アクセスは lib/db/ のリポジトリ経由のみ

ファイル一覧をベタ書きするのはNGです。それは ls で取れる情報。コードを読んでも分からない暗黙ルール を書きましょう。

ステップ2: settings.json で権限を整える

CLAUDE.md でAIに「何を知っているか」を渡したら、次は「何をしてよいか」を決めます。

なぜ重要か

権限設定が雑だと、次のどちらかが起こります。

  • 緩すぎ: AIが本番DBにアクセスしたり、rm -rf を実行できる状態
  • 厳しすぎ: 毎回「このコマンドを実行していい？」と聞かれて作業が止まる

ハーネスエンジニアリングの肝は 「安全とスループットの最適点を探る」 ことです。

段階的に許可する

~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(pnpm test:*)",
      "Bash(pnpm lint:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Read(./**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

allow はプレフィックス一致です。Bash(pnpm:*) のように広く許可すると、pnpm publish（パッケージ公開）まで通ってしまいます。動詞単位で絞る のが安全です。

スコープの使い分け

ファイル 効果範囲 用途
~/.claude/settings.json 全プロジェクト共通 自分のグローバル方針
<project>/.claude/settings.json プロジェクト共有 チームで合意した許可リスト
<project>/.claude/settings.local.json 個人ローカル 自分だけの一時的な許可

個人開発でも、deny だけは早めに入れる ことを強くおすすめします。.env の読み取り禁止、rm -rf 禁止は最低ライン。

ステップ3: 繰り返し作業を Slash Command / Skill にする

「毎週金曜にリリースノートを書く」「PR作成前に必ずテストを実行する」——こうした 定型タスク は、Slash Command や Skill にしておくと、/release-note の一言で呼び出せます。

Slash Command の最小例

.claude/commands/release-note.md
---
description: 直近1週間のコミットからリリースノートを作る
---

直近7日間の `git log` を読み、以下の形式でリリースノートを作成してください。

## 追加された機能
- ...

## 修正された不具合
- ...

## その他の変更
- ...

ユーザー向けの言葉で書いてください。コミットハッシュは含めないでください。

これで /release-note と打てば、毎回同じ品質でリリースノートが出来上がります。

Slash Command と Skill の違い

項目 Slash Command Skill
起動 /コマンド名 をユーザーが明示 AIが文脈から自動判断して起動
適した用途 明示的に呼びたい定型タスク 「Qiita記事を書く時は必ずこの手順」のような自動適用
配置 .claude/commands/ .claude/skills/

最初は Slash Command から作る のがおすすめ。明示的に呼ぶので挙動が予測しやすく、デバッグも楽です。慣れてきたら Skill 化を検討しましょう。

ステップ4: Hooks で安全装置と自動化を仕込む

Hooks は 「特定のイベントが起きたら必ず実行されるシェルコマンド」 です。AIの判断を待たずに、ハーネス側で機械的に処理を挟めます。

よく使う2大用途

例1: ファイル保存後に自動フォーマット

.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm prettier --write $CLAUDE_TOOL_OUTPUT_FILE_PATH"
          }
        ]
      }
    ]
  }
}

「AIにフォーマットを意識させる」のではなく、ハーネス側で機械的にやる。これがハーネスエンジニアリングの思想です。

例2: 危険コマンドの直前ブロック

.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node ./.claude/hooks/guard-prod-db.js"
          }
        ]
      }
    ]
  }
}

guard-prod-db.js が exit code 1 を返せば、そのコマンドは実行されません。「本番DBの接続文字列が含まれていたら止める」のようなチェックを書いておけば、プロンプトを信用せずに防げます。

Hooks は強力な反面、シェルコマンドが実行される ため、無検証のスクリプトをコピペすると重大なリスクになります。自分で読んで理解できるものだけ入れてください。

ステップ5: Memory で会話を超えた知識を持たせる

ここまで来たら最後の仕上げ。過去の会話で得た知識を、未来の会話に持ち越す 仕組みです。

Memory とは

Claude Code には、ファイルベースで保存・読み出しされる Memory システムがあります。例えば以下のような情報が、自動または明示的に保存されます。

  • ユーザーの役割・好み（user メモリ）
  • フィードバック・避けるべき対応（feedback メモリ）
  • プロジェクトの進行状況・期限（project メモリ）
  • 外部システムへの参照（reference メモリ）

個人開発者にとっての価値

「同じ説明を何度もしなくて済む」 これがMemoryの本質的な効果です。

始め方

最小の運用としては、以下の2つだけで十分です。

  1. AIに「これは覚えておいて」と伝える（明示保存）
  2. たまに ~/.claude/projects/<project>/memory/MEMORY.md を覗いて、古くなった項目を消す

Memoryは「永続するから便利」ですが、裏を返せば「間違った前提を覚え続ける」リスクもあります。プロジェクト方針が変わったらメモリも更新する、という運用習慣をセットで持ちましょう。

まずどこから手を付けるか: 1日プラン

時間 やること 成果物
30分 グローバル CLAUDE.md を書く 自分の好みが反映されたAI
30分 ~/.claude/settings.json の deny を整える .env 読まない・rm -rfさせないAI
30分 Slash Command を1つ作る（/commit など） 定型作業のワンコマンド化
30分 プロジェクト CLAUDE.md に5行書く プロジェクト固有の文脈伝達

合計2時間。今日のうちにここまでやれば、明日からの開発体験が確実に変わります。Hooks と Memory の本格活用は、慣れてからで構いません。

続けるためのコツ

「AIに同じことを2回言ったら設定化する」

これがハーネスエンジニアリングの 黄金ルール です。同じ訂正を繰り返している自分に気づいたら、それは CLAUDE.md / Skill / Hook のいずれかにすべきサイン。

設定ファイルもバージョン管理する

.claude/ ディレクトリは Git 管理対象にしましょう。ハーネスは 資産 です。プロジェクトのコードと同じくらい価値があります。ただし settings.local.json と個人鍵は .gitignore に。

定期的に見直す

3ヶ月に1度、CLAUDE.md と settings.json を読み返してください。古い項目は AIにとってのノイズ です。捨てる勇気もハーネスエンジニアの仕事です。

まとめ

  • ハーネスエンジニアリング = LLMを取り巻く実行環境の設計。プロンプトを磨くより構造的な改善が得られる
  • 個人開発者が今日から始めるなら CLAUDE.md → 権限 → Slash Command → Hooks → Memory の順
  • 一度に全部やろうとしない。「同じことを2回言ったら設定化」 を合言葉に育てていく
  • 設定ファイルは資産。バージョン管理し、定期的に見直す

AIをどれだけ賢く使えるかは、AI本体の性能より 「あなたが整えたハーネスの質」 で決まる時代に入っています。今日の30分が、明日からの開発時間を着実に押し上げてくれるはずです。

参考資料

  1. 日本語では「装具」「拘束具」と訳されることもありますが、AI文脈では「LLMを取り巻く実行環境一式」を指します。プロンプトだけではなく、ツール定義・権限・フック・メモリ・コンテキスト管理などを含む広い概念です。 ↩

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?