AIにコードを任せるほど、ドキュメントが重要になる — ハーネスエンジニアリングと自作ツールの設計

AIにコードを書かせるのは、もう当たり前になりました。

しかし、こんな違和感はないでしょうか。「AIは優秀なのに、毎朝記憶を失って出社してくる新人」のようだ、と。

この「賢いのに毎回忘れる」問題に有効なのが、ハーネスエンジニアリングという考え方です。本記事では、それを実践するために自作したドキュメント整備ツールを題材に、設計の理由と、実プロジェクトで動かして得られた知見を整理します。

対象は、Webアプリでもデスクトップアプリでも、AIエージェントに開発を任せるケース全般です。

AIが速すぎて、人間のレビューが追いつかない

「コードを書く」から「環境を整える」へ

近年、明確になってきた事実があります。

AIの作業スピードが、人間が確認できる速度を超えたということです。

エージェントは数分で数百行を書きます。一方、人間のレビュー速度は変わりません。ここに構造的なギャップが生じています。

このギャップを埋める考え方が「ハーネスエンジニアリング」です。

基本となるのは、次の等式です。

エージェント = モデル + ハーネス

モデルは、ChatGPT や Claude のような「頭脳」を指します。

ハーネスは、モデル以外のすべてです。

どんな指示(システムプロンプト＝AIへの最初の命令文)を与えるか
どんな道具(ツール)を使わせるか
どこまで許可し、どこで止めるか(制約)
結果をどうフィードバックするか

生のモデル単体では、エージェントになりません。

その周囲を固める”環境”がハーネスであり、それを設計するのがハーネスエンジニアリングです。

重要なのは、エンジニアの役割が 「自分でコードを書く」から「AIが確実に仕事を終えられる環境を整える」へ移った点です。

最大の課題は「記憶の喪失」

長時間動作するエージェントには、注意すべき性質があります。

作業メモリ(コンテキスト)が残り少なくなると、処理を雑に切り上げる傾向です。検証をスキップし、とりあえず動くものを出す。試験終了間際に解答欄を埋める状況に似ています。

さらに、セッションをまたぐと記憶はリセットされます。

つまりエージェントは、毎回ゼロから「このコードベースは何か」を探索し直すことになります。

ここに、明確な無駄があります。同じ探索を毎回繰り返しているのです。

なぜ「ドキュメント整備」を自動化したのか

リポジトリに書かれていないことは、存在しない

ハーネスエンジニアリングには複数の原則がありますが、特に効果が大きいのが次の一つです。

リポジトリに書かれていることが、すべて。

(この原則は “Repo as System of Record” と呼ばれます)

Slack の議論も、頭の中の設計意図も、エージェントには見えません。

したがって 「このプロジェクトはどういう構造で、どんなルールで動くか」をリポジトリ内に記述しておく必要があります。これにより、毎回の探索なしに、ドキュメントを読むだけで作業へ入れます。

ただし、分厚いマニュアルは逆効果

では、すべてを一つの巨大なドキュメントに書けばよいかというと、それは誤りです。

長文の中央に置かれた情報は、AIに十分活用されません(「Lost in the Middle」として知られる研究があります)。

分厚い指示ファイルは、次の三つの問題を抱えます。

コンテキストを圧迫する
更新されず陳腐化する
遵守されたか検証できない

ここで有効なのが 段階的開示(地図であって、マニュアルではない) という設計です。

入口ファイルは”地図”にする(目安50〜200行)。プロジェクト概要、主要コマンド、そして「詳細はこのファイル」という1行リンクのみを置く
詳細は別ファイルへ分離する。必要時にのみ開く

頻繁に使う情報は手元に、稀に使う情報は格納し、不要な情報は捨てる。

情報設計における”整理”そのものです。

自動化ツールとして実装した

この「リポジトリを正にする」「段階的開示で整理する」を毎回手作業で行うのは非効率です。

そこで専用のツールを実装しました。Claude Code(AIコーディング環境)の「skill」という拡張機構を用いており、名称は harness-docs です。これは Claude Code を使える環境であれば自作可能で、特別な依存はありません。

主な機能は次のとおりです。

対象コードベースを解析し、入口ファイル + 詳細ドキュメント(docs/) の体系を生成する
既存ドキュメントがあれば、実コードとの差分(ドリフト)を検出して更新する
全体を「段階的開示」の構造へ整える

結果として、エージェントは毎回の探索なしに、整備された地図を読むだけで作業へ入れます。

AIにAIをレビューさせる

ここからが、実装上もっとも重要だった設計判断です。

生成物を、生成した本人に採点させない

ドキュメントを自動生成すると、「内容は正しいか」という検証問題が生じます。

人間が全件チェックするなら、自動化の意味が失われます。

そこで採用したのが、「生成する役」と「審査する役」を別のエージェントに分離する設計です。

(画像生成の GAN における「生成器と識別器を分ける」発想を参考にしています)

ドキュメントを生成するエージェントと、レビューするエージェントを別人格にする
同一エージェントによる自己採点は、評価が甘くなる

人間でも、自分の書いた文章の誤りは見落としやすいものです。エージェントも同様です。

そのため harness-docs では、生成後に 独立した審査エージェントが実コードと照合してレビューします。

照合は具体的で、ドキュメント内に記述されたファイルパスやコマンドが、実コードに存在するかを逐一確認します。

適用結果：審査エージェントが差分を検出した

このツールを、実際の個人開発プロジェクト(macOS向けデスクトップアプリ)へ適用しました。

結果は明確でした。

審査エージェントが、過去の更新で見逃されていた誤りを複数検出しました。

ドキュメント記載のコンポーネント名が、実コードには既に存在しない(旧名のまま放置)
「ウィンドウは2つ」との記述に対し、実際は5つに増加していた
同一説明の2ファイル重複、上限値の古い記述など——いずれも実物と照合しなければ検出できない差分

これらは、生成者自身であれば「概ね正しい」と見過ごしていた類の誤りです。

検出結果を数値で示します。

副次的効果：ツール自体の不具合も判明した

さらに、自作ツールを自身に適用した結果、ツール側の不具合が2件判明しました。

言語判定処理がメイン設定ファイルのみを参照し、サブディレクトリ内の別言語を検出できていなかった
ドキュメントの孤立検出が、ディレクトリ単位のリンクを考慮していなかった

これは「ドッグフーディング(自作ツールの自己適用)」が持つ典型的な効果です。

実運用しなければ、設計の欠陥は表面化しません。 机上で完成したつもりでも、現場で初めて判明する欠陥が存在します。

ハーネスは「補償層」である — モデルの成長で不要になる

最後に、もっとも本質的な設計思想を述べます。

ハーネスエンジニアリングを検討する中で、示唆的な視点があります。

ハーネスは、モデルの欠点を補う”補償層”である。モデルが成長すれば、補償層は不要になる。

例えば「AIは記憶を失う」という欠点があるため、ドキュメントで記憶を外部化します。

しかし将来、モデルがより長い記憶を保持できるようになれば、その補償は不要になり得ます。

ここから導かれる結論が重要です。

競争優位は「ハーネスの厚さ」ではなく、「何を補っているかを理解し、追加・削除を判断できること」にあります。

ハーネスが複雑なほど、モデルの弱点に依存している
モデルが進化したとき、その複雑さは負債に転じる
削除できることは、何を補っていたかを理解していた証左

harness-docs も、「AIが毎回コードを探索し直す」という現在のモデルの弱点を補う層にすぎません。

数年後には不要になる可能性もあります。それで問題ありません。

何を補っているかを理解していれば、いつでも削除できるからです。

まとめ

要点を整理します。

ハーネスエンジニアリング = AIが確実に仕事を終えられる”環境”を設計すること。コードを書くより、環境を整える
リポジトリを正とし、段階的開示で整理する = エージェントに探索を繰り返させない。これを自動化したのが harness-docs
AIにAIをレビューさせ、補償層は”理解した上で”増減させる = 現時点でもっとも効果的な設計思想

そして核心は——何を補っているかを理解していれば、モデルが成長したときに迷わず削除できること。これがハーネスエンジニアリングにおける最重要の姿勢です。

導入の第一歩

「AIにコードを任せ始めたが、毎回同じ説明を繰り返している」と感じる場合、最初の一歩は単純です。

プロジェクトのルートに、薄い”地図”を1枚配置します。

例えば AGENTS.md(または CLAUDE.md)というファイルを作成し、次のように記述します。

# このプロジェクトについて
- 何をするアプリか: (一行で)
- 動かし方: npm run dev
- テスト: npm test
- 詳しい構成は → docs/ を参照

これだけで、AIエージェントの挙動は変わります。

分厚いマニュアルは不要です。まず地図から始めます。