Claude Codeをカスタマイズして「使うほど賢くなるAI環境」を作った話──ハーネスエンジニアリング実践

CLAUDE.mdが81行になっていた

Claude Codeの設定ファイルに、指示もルーティングテーブルもワークフローもエージェント定義も全部詰め込んで、セッションのたびにAIが丸ごと読み込む構造になっていた。毎回同じ説明を読み込む羽目になるし、慣れてきたころにセッションが切れてリセットされる。「プロンプトをうまく書く」だけでは解決しない問題がそこにあった。

そんなとき、X（Twitter）でハーネスエンジニアリングについての記事を見かけた。AIへの指示文ではなく、AIが動く環境そのものを整えるという考え方だ。「これ、Claude Codeでもできる？」と試しに聞いてみたところ、具体的な改善提案が5つ返ってきた。その記録をまとめておく。

※ この記事はシリーズ「Claude Code活用記」の第2回です。第1回（自分専用AI社員チームをClaude Codeで作った話）もあわせて読むと流れがつかみやすいと思います。

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

「ハーネス（harness）」は、馬具の「馬を制御・誘導するための装具」が語源。ハーネスエンジニアリングとは、AIが動く環境そのものを設計・調整して、AIの能力を最大限に引き出す技術のことを指す。

プロンプトを工夫してAIに「うまく答えさせる」のがプロンプトエンジニアリングだとすると、ハーネスエンジニアリングはもう一段上流の話。ファイル構成、権限設定、フック（自動処理）、記憶の仕組み——こういった「AIが動く箱」を整えることで、毎回のやり取りの質を底上げする。

※「プロンプトエンジニアリング」とは、AIに対する指示文（プロンプト）の書き方を工夫して、より精度の高い回答を引き出す技術のこと。

Claude Codeで言えば、設定ファイル群がそのまま「ハーネス」になる。「これ、Claude Codeで実践できる？」と聞いたところ、現状の設定を分析した上で5つの改善提案が返ってきた。

Claude Codeが提案してきた5つのこと

1. 「CLAUDE.md、長すぎるのでスリム化しましょう」

Before: 指示、ルーティングテーブル、ワークフロー、エージェント定義……すべてが1ファイルに詰まった81行のCLAUDE.md。

提案内容: 「このファイル、セッションのたびに全部読み込むのでコンテキストを消費します。コア原則だけ残して、詳細は.claude/rules/以下に分離しませんか？必要なときだけ読み込む方が効率的です」

After: 31行にスリム化。詳細ルールはオンデマンド読み込み方式に。

変わったこと: 起動時のコンテキスト消費が減り、必要な情報だけが読み込まれるようになった。「この設定、どこに書いてあるっけ？」という管理上の混乱も減った。

※「CLAUDE.md」とは、Claude Codeの設定ファイル。プロジェクトのルールや指示を書いておくと、セッション開始時にClaude Codeが自動で読み込んで動作に反映してくれる。

※「コンテキスト」とは、AIが一度に処理できる情報量のこと。会話の履歴や設定ファイルの内容などが含まれ、上限を超えると古い情報から忘れていく。

2. 「危険なコマンド、ブロックリストに入れておきましょう」

Before: 特に設定なし。AIが判断してくれるだろう、というなんとなくの信頼。

提案内容: 「settings.jsonで安全なコマンドのallowリストと、rm -rfやgit push --forceみたいな破壊的コマンドのdenyリストを明示した方がいいです」

変わったこと: 「本当に実行していいか」と毎回不安になる感覚が薄れた。ガードレールがあることで、AIに任せる範囲を広げやすくなった。

※「settings.json」とは、Claude Codeの動作設定を記述するJSONファイル。許可するコマンドや禁止するコマンドなどを定義できる。

※「allowリスト」とは、実行を許可するコマンドや操作を明示的にリスト化したもの。「denyリスト」はその逆で、実行を禁止するものを列挙する。allowリストにないものは実行しない、denyリストにあるものは絶対に実行しない、という形で安全性を担保する。

「設定ファイルで安全性を担保する」という発想が自分にはなかった。ガードの仕方を明文化することで、AIに任せる範囲の見通しが立てやすくなった。

3. 「.envへの書き込み、自動でブロックする仕組みを入れますね」

Before: .envや認証情報ファイルへの誤書き込みリスクは、自分が都度チェックするしかなかった。

提案内容: 「Hooksという機能で、.envや認証ファイル系への書き込みを自動ブロックできます。タスク完了時の確認チェックも仕込んでおきましょうか」

変わったこと: 「うっかり.envを書き換えられた」という事故が構造的に防げるようになった。安全を人間の注意力に頼らなくてよくなった点が大きい。

※「Hooks（フック）」とは、Claude Codeの特定のアクション（ファイル書き込み・コマンド実行など）の前後に自動で処理を挟める機能。ブラウザの拡張機能のようなイメージ。

セキュリティ的なミスは「やらかしてから気づく」パターンがほとんど。先回りしてガードの仕組みを入れておくことで、ミスが構造的に起きにくくなった。

4. 「学んだことを蓄積するファイル、作っておきますね」

Before: セッションをまたぐとAIは何も覚えていない。同じ失敗が繰り返される可能性がある。

提案内容: 「lessons-learned.mdというファイルを作って、ミスや発見を蓄積していきましょう。次回セッションから自動的に反映されるようにCLAUDE.mdから参照させます」

変わったこと: 同じ種類のミスが明らかに減った。また、記録を見返すことで「自分がAIにどんな指示をよく出しているか」が可視化されたのも面白い。

セッションをまたいでも知識が積み上がっていく——「複利型学習」とも呼べる仕組みで、使えば使うほど環境が賢くなっていく。この発想はそのまま採用した。

5. 「エージェント定義、公式フォーマットに書き換えてコスト下げましょう」

Before: エージェント（特定タスクを担当するAIの役割定義）はmarkdownで書いた説明文だけ。モデルもツールも無指定。

提案内容: 「公式ドキュメントを確認したところ、frontmatter形式で書くと各エージェントにモデルやツールの制限を指定できます。重い処理にはopus、軽い処理にはsonnetを割り当てればコスト最適化できますよ」

※「opus」「sonnet」とは、Claudeが提供するAIモデルの名称。opusが最も高性能・高コスト、sonnetはバランス型の中間モデル。処理の重さに応じて使い分けることでAPIコストを抑えられる。

※「APIコスト」とは、Claude等のAIをAPI（外部サービスとの接続口）経由で使う際に発生する利用料金のこと。処理するテキスト量やモデルの種類によって変動する。

変わったこと: APIコストの見通しが立てやすくなり、処理ごとの使い分けが自動化された。「このタスクは高いモデルを使わなくていい」という判断をAI任せにできる。

※「frontmatter（フロントマター）」とは、ファイルの先頭に書くメタ情報のブロック。YAMLという書式で「—」で囲んで記述する。Claude Codeではエージェントの設定に使われる。

コスト削減だけでなく、「このエージェントは何をするものか」が定義から明確になるので、設計の見通しもよくなる。

適用してみた実感と、役割の話

ここまでの5つは、「ハーネスエンジニアリングをClaude Codeで実践したい」という方向性を決めた上で、Claude Codeに「現状の設定の問題点を洗い出して、改善案を出して」と投げたら返ってきたものだ。公式ドキュメントの確認、ベストプラクティスの調査、設定ファイルの作成、動作確認まで含めて、だ。

実行の大部分はClaude Codeに任せた。ただ、何の概念を持ち込むかを決めて、「これで行こう」と判断したのはこちら側の話だ。

これは「AIに丸投げした」とは違う。丸投げは、何が起きているか理解せずに出力だけ受け取ること。任せるのは、目的と制約を定めたうえで、実行を委ねること。判断権は手元に残す。

設定を適用して数日の体感として、以下の変化があった。

コンテキスト消費が減った。 CLAUDE.mdをスリム化してオンデマンド読み込みにしたことで、セッションの「読み込み負担」が軽くなった。

同じミスが出にくくなった。 Hooksとlessons-learnedの組み合わせで、「また同じところで詰まる」が減ってきた気がする。

安心してAIに任せられるようになった。 settings.jsonのdenyリストがあるからこそ、「まあ走らせてみよう」と気軽に動かせる。過信でも過小評価でもない、適切な距離感。

まとめ——AIに「任せる」と「丸投げ」は違う

• ハーネスエンジニアリングは、AIへの指示文ではなく「AIが動く環境そのもの」を設計する考え方
• CLAUDE.mdのスリム化・denyリスト・Hooks・lessons-learned・エージェント定義の整備が主な施策
• 実行はClaude Codeに任せられるが、何を導入するか判断するのは人間の仕事
• 「使うほど賢くなる環境」は、最初から整っているわけではなく、設計して作るもの

Claude Codeが面白いのは、ただコードを書くだけじゃなく「こうした方がいいですよ」と環境の改善まで提案してくるところだ。使い始めて2日で、自分専用のAI開発環境が勝手に育っていく感覚がある。

自分もやってみたい人へ

Claude Codeを使っているなら、こう聞くだけでいい。

ハーネスエンジニアリングを実践したい。今の設定ファイルを分析して、改善提案を出して

Claude Codeが現状のCLAUDE.mdや設定ファイルを読み込んで、あなたの環境に合った改善案を出してくれる。この記事で紹介した5つと同じ提案が来るとは限らないけど、それでいい。環境が違えば課題も違う。

この記事で触れた設定の具体的なファイル構成や書き方は、また別の記事でまとめる予定。更新はX（@NPC_azusa）でお知らせするので、気になる方はフォローしておいてください。

※この記事はNPCの中の人の実務経験をもとに書いています。