Claude CodeやCodexのようなAIエージェントを使った開発が、かなり現実的になってきました。
以前のAIコーディング支援は、どちらかというと「一部のコードを書いてもらう」「エラーの原因を聞く」「関数単位で補助してもらう」という使い方が中心でした。
しかし今は、リポジトリ全体を読ませ、仕様を整理させ、実装し、テストを回し、差分を確認し、場合によってはPRの説明まで作らせることができます。
その流れの中で、AGENTS.md、CLAUDE.md、Hook、MCP、Design.md、チェックリスト、サブエージェント、CI連携など、いわゆる「ハーネスエンジニアリング」の重要性が語られる機会が増えてきました。
私自身も、ハーネスは重要だと思っています。
AIエージェントはできることが増えました。
コードだけでなく、ドキュメント、テスト、設計、UI、リリース手順、GitHub上のやり取りまで、かなり広い範囲を見られるようになっています。
ただ、広く見られるということは、裏を返せば、何を見ればいいのかを人間側が定義しないと、見るべき範囲がいたずらに広がるということでもあります。
「この機能だけ直してほしい」と頼んだつもりでも、エージェントが周辺のコードを読み込みすぎたり、関係の薄い設計判断まで始めたり、不要なリファクタに踏み込んだりすることがあります。
結果として、コンテキストが汚れ、判断の焦点がぼやけ、出力の精度が下がることもあります。
だからこそ、目的、スコープ、禁止事項、実行すべきテスト、完了条件などを、あらかじめAGENTS.mdやCLAUDE.mdのようなファイルに書いておくことには意味があります。
毎回すべてをプロンプトで説明するのは現実的ではありません。
プロジェクトごとの前提を再利用可能な形で持たせることは、AIエージェントを安定して使ううえで有効です。
OpenAIのCodexのドキュメントでも、AGENTS.mdはリポジトリでの作業方法をエージェントに伝える場所として説明されています。
ビルド、テスト、lintコマンド、ディレクトリ構成、制約、完了条件などを書く場所です。
一方で、短く実用的なAGENTS.mdの方が、曖昧で長いファイルより有用であり、繰り返し起きたミスをもとに更新していくことが勧められています。
AnthropicのClaude Codeのドキュメントでも、CLAUDE.mdは永続的な指示を与えるための仕組みとして説明されています。
ただし、これも強制設定ではなく、あくまでコンテキストとして読まれるものです。
厳密に止めたい操作があるなら、Hookや権限制御のような仕組みを使う必要があります。
また、指示は具体的で簡潔なほど従われやすく、大きすぎるファイルはコンテキストを消費し、遵守率を下げる可能性があるとされています。
つまり、ハーネスが重要であること自体は間違いありません。
問題は、その次です。
ハーネスは、増やせば増やすほど良いのでしょうか。
私は、そうは思いません。
ハーネスは「文脈を整理する道具」であって、増やすこと自体が目的ではない
ハーネスという言葉は、少し広く使われています。
AGENTS.mdやCLAUDE.mdのような永続的な指示もハーネスです。
HookやCIのように、特定のタイミングで必ずチェックを走らせる仕組みもハーネスです。
MCPのように外部ツールや外部情報へ接続する仕組みもそうです。
Design.md、レビュー観点、リリース手順、権限制御、サブエージェント、スキル化された作業手順も、広い意味ではAIエージェントの振る舞いを安定させるためのハーネスと言えます。
これらはどれも有効です。
しかし、それぞれ役割が違います。
AGENTS.mdやCLAUDE.mdは、エージェントに「こういう前提で作業してほしい」と伝えるためのものです。
Hookは、特定のタイミングで必ず実行したい確認や制御に向いています。
CIやテストは、人間やAIの判断に依存せず、機械的に品質を確認するためのものです。
MCPは、リポジトリの外にある情報やツールが必要なときに使うものです。
Design.mdは、デザインの原則や判断基準を共有するためのものです。
それぞれに向き不向きがあります。
にもかかわらず、外部で見かけたハーネスを、そのまま自分のプロジェクトに持ち込んでしまうと、うまくいかないことがあります。
SNSやGitHubには、優れたAGENTS.md、Hook、Design.md、チェックリスト、MCP設定が数多くあります。
それ自体は悪いことではありません。
むしろ、他人の実践から学べることは多いです。
ただし、それらは多くの場合、その人のプロジェクト、その人の失敗経験、その人の制約に合わせて作られたものです。
自分のプロダクトの目的、規模、失敗コスト、開発体制を確認しないまま、「良さそうなもの」を全部取り込むと、ハーネスは品質を上げる仕組みではなく、コンテキストを増やすだけの荷物になります。
重要なのは、世の中にあるハーネスを集めることではありません。
自分たちのプロダクトでは、どの失敗を避けるべきなのか。
その失敗はどれくらい起きやすいのか。
起きたときの損失はどれくらい大きいのか。
そこから逆算して、必要なハーネスを選ぶことです。
よくある落とし穴
たとえば、AGENTS.mdに細かいコーディングルールを大量に書くケースがあります。
インデント、import順、フォーマット、命名規則、末尾改行、細かいlintルール。
もちろん、プロジェクトの規約をAIに伝えることは大事です。
しかし、それが機械的に検出できる内容なら、AGENTS.mdに長々と書くより、formatter、linter、型チェック、CIに任せた方が確実です。
AIへの指示は、AIが判断すべきことに使う。
機械的に判定できることは、機械的に判定する。
この分離は重要です。
MCPも同じです。
GitHub、Notion、Slack、Linear、DB、分析ツール、ドキュメント管理。
外部ツールとつなげることで、AIエージェントができることは大きく広がります。
しかし、目的が明確でないまま最初から全部つなぐと、エージェントが参照できる世界だけが広がっていきます。
外部情報が増えれば、判断材料も増えます。
しかし、判断材料が増えることと、判断が良くなることは同じではありません。
どの情報を、どの作業のために使うのかが明確でなければ、外部接続は力ではなくノイズになります。
Hookについても同じです。
破壊的なコマンドを止める、秘密情報の混入を防ぐ、コミット前に必ずテストを走らせる、特定ディレクトリの変更時に専用チェックを通す。
こうした明確な目的があるHookは有効です。
一方で、「何となく品質が上がりそうだから」と細かい確認をすべてHook化すると、運用が重くなります。
エージェントが本来の作業に入る前に多くの手順を踏む必要が出たり、Hook自体のメンテナンスが必要になったりします。
Hookは強い仕組みだからこそ、目的が明確なところに使うべきです。
Design.mdも同じです。
ブランドの一貫性が重要なプロダクト、複数人でUIを継続的に作るチーム、デザインシステムを持つ組織では、Design.mdは非常に有効です。
色、余白、コンポーネントの使い方、禁止表現、情報設計の原則を明文化することで、AIエージェントが作るUIのブレを減らせます。
しかし、探索段階の個人開発や、まだプロダクトの方向性が固まっていない段階では、最初から重いDesign.mdを書くより、まずモックを作らせて、見て、触って、違和感を返しながら改善する方が速い場合もあります。
文章で理想を先に固めるより、実物を見ながら判断した方がよい場面はあります。
ハーネスの適正量は、規模と失敗コストで変わる
ここで大事なのは、「ハーネスは少ないほど良い」という話でもないことです。
個人開発や小規模な試作では、ハーネスを増やしすぎるとかえって動きが鈍くなることがあります。
仕様もデザインも探索中で、作りながら考える段階では、最低限の前提だけを与えて、AIエージェントと対話しながら形にしていく方が向いています。
この段階で重要なのは、プロジェクトの目的、触ってよい範囲、実行すべき確認、破壊的操作の禁止、コミットやドキュメントのルールなどです。
まだ繰り返し発生していない問題まで先回りして仕組み化すると、ルールを維持すること自体が負担になります。
一方で、チーム開発や商用プロダクトでは話が変わります。
関わる人が増えると、暗黙知に頼れなくなります。
誰がAIエージェントを使っても、同じ品質基準で作業できる必要があります。
レビュー観点、CI、テスト、設計方針、リリース手順、権限制御、監査ログのような仕組みが重要になります。
さらに、顧客データ、決済、認証、セキュリティ、法務、医療、金融、App Store審査のように、失敗したときのコストが大きい領域では、ハーネス不足の方が危険です。
この場合は、「AIが気をつけてくれるはず」に頼るべきではありません。
禁止したい操作は権限制御やHookで止める。
壊れてはいけない仕様はテストで守る。
レビューが必要な変更はプロセスに組み込む。
守るべき規約はドキュメントに残す。
必要に応じて、AGENTS.mdやCLAUDE.mdだけでなく、CI、型チェック、lint、監査、承認フローまで含めて設計する必要があります。
同じAIエージェントを使っていても、個人開発の試作と、顧客データを扱う商用サービスでは、必要なハーネスは違います。
探索段階のUIと、ブランド一貫性が求められるプロダクトでも違います。
趣味のツールと、複数人で長期運用するプロダクトでも違います。
ハーネスは、プロジェクトの規模と失敗コストに応じて変えるべきです。
ハーネスを追加する前に考えること
私は、ハーネスを追加する前に、少なくとも次の問いを置くのがよいと思っています。
- そのハーネスは、何の失敗を防ぐためのものなのか。
- その失敗は、どれくらい頻繁に起きるのか。
- 起きたときの損失は、どれくらい大きいのか。
- AIへの指示で防ぐべきなのか。それともlint、test、CI、権限制御で機械的に防ぐべきなのか。
- 毎回エージェントが読む必要がある情報なのか。それとも必要なときだけ参照すればよい情報なのか。
- そのハーネスを誰がメンテナンスするのか。
これらに答えられないなら、そのハーネスはまだ追加しなくてもよいかもしれません。
逆に、何度も同じミスが起きている。
失敗したときの損失が大きい。
人間の注意では防ぎきれない。
チームで共有する必要がある。
そういう場合は、ハーネスを追加する合理性があります。
ハーネスは、AIを縛るためだけのものではありません。
人間とAIが、同じ前提で作業するための共有インフラです。
だからこそ、ハーネスは目的から逆算して設計すべきです。
まとめ
AIエージェントの品質を上げるうえで、ハーネスは重要です。
AGENTS.mdやCLAUDE.mdは、毎回説明しなくてもよい前提を共有するために役立ちます。
Hookは、特定のタイミングで必ず確認したいことを実行するために有効です。
CIやテストは、品質を機械的に確認するために必要です。
MCPは、外部情報や外部ツールが本当に必要なときに力を発揮します。
Design.mdも、デザイン判断の一貫性が求められる場面では強力です。
ただし、ハーネスを増やせば増やすほど品質が上がるわけではありません。
外部で見かけたベストプラクティスを、自分のプロジェクトにそのまま入れても、うまく機能するとは限りません。
他人のハーネスは、他人の目的、他人の制約、他人の失敗経験から生まれたものです。
大事なのは、ハーネスを集めることではありません。
自分たちが何を作りたいのか。
いつまでに、誰に、どの水準で届けたいのか。
失敗したときに何が困るのか。
どの品質はAIへの指示で担保し、どの品質はテストやCIで担保し、どの判断は人間が見るべきなのか。
そこから逆算して、必要なハーネスを選ぶことです。
ハーネスは少ないほど良いのでも、多いほど良いのでもありません。
目的、規模、失敗コストに対して、過不足がないことが重要です。
AIエージェント時代に本当に必要なのは、ハーネスを増やすことではなく、目的に対して適切なハーネスを選ぶ力なのだと思います。