ハーネスエンジニアリングとは：AI開発を支える3層設計
この記事で学べること
- 継続的なAI作業で、会話だけでは品質が安定しない理由
- ルール・作業手順・検証を統合するハーネスエンジニアリングの考え方
- このサイトの3層構造を参考に、自分のプロジェクトへ仕組みを配置する方法
ハーネスエンジニアリングはルール・手順・検証を統合する
本記事では、ハーネス（AI作業を支えるルール、手順、検証の仕組み）を設計する実践を「ハーネスエンジニアリング」と呼びます。このサイトでは、会話だけで同じ前提を渡す方法から、共有ルール、Skills、自動検査を役割別に管理する方法へ移りました。製品の公式機能とサイト独自の3層設計を分けると、自分のプロジェクトで追加すべき仕組みを判断できます。
最後まで読むと、「ハーネスエンジニアリングは何を設計し、製品機能とどう分けるのか」という問いを、自分の状況に照らして判断するための材料を持ち帰れます。
ハーネスをルール・手順・検証の3層で設計する
AIを個人的な質問への回答に使う場合と、プロジェクトに継続的に組み込んで使う場合では、直面する問題が異なります。
プロジェクトでAIを使い始めると、次のような状況が繰り返し起きます。先週AIに依頼して設定した内容を、今週また別の会話で依頼すると、異なる方法で実装される。ルールを守ってほしいと一度伝えても、次の会話では守られていない。
基盤モデルは、別セッションの内容を自動的に恒久保存しているわけではありません。製品側の履歴、Memory、プロジェクト設定、外部ファイルなどが利用できない場合、前回のルールや判断は次のセッションへ自動的には引き継がれません。Claude Codeでは、CLAUDE.md のようなメモリファイルを使ってプロジェクト文脈を渡す仕組みが公式に説明されています。[1]
指示、ツール、権限、環境、検証、フィードバックを一体として設計する考え方は、エージェントハーネスやHarness Engineeringと表現される場合があります。目的は、AIエージェントを安定して動かすことです。
本記事では、この考え方をAI Learning Playgroundへ適用した独自の3層構造を紹介します。
本サイトでは、AIに同じ品質で作業してもらうためのルール、設定、検証、引き継ぎ、レビューの仕組みをまとめて「ハーネスエンジニアリング」と呼んでいます。これは私の実践を整理した用語であり、特定ベンダーの公式名称ではありません。
ハーネスはAIの動きを制約・接続・検証する役割から名付けられた
ハーネス（harness）は馬具を指し、力を正しい方向へ制御する道具です。AIにも、プロジェクトの目的に沿って一貫して動くための制御を組み合わせます。この役割を表すために、ハーネスという名前を使っています。
AIそのものを変えるのではなく、AIが参照する設定・ルール・手順を整えることで、プロジェクト全体での動作を安定させることが目的です。
公式仕様とこのサイトの設計を分ける
Claude Codeの公式仕様として確認できる要素は4つあります。CLAUDE.mdによるプロジェクトメモリ、許可・権限・実行環境の設定、Hooks、Skillsです。[1][2][3][4]
Hooks（実行前後などの決まったタイミングで自動処理を動かす仕組み）と、特定タスク向けの手順や資料をまとめるSkillsを組み合わせます。
「ハーネスエンジニアリング」という呼び方、shared/への共通ルール集約、CLAUDE.md・shared/・教訓ログの3層構造は、このサイト独自の整理です。公式機能を利用していますが、Claude Codeがこの3層構造を公式パターンとして定義しているわけではありません。
| 観点 | 位置づけ |
|---|---|
CLAUDE.md をプロジェクト文脈として使う | Claude Code公式仕様に基づく |
| 設定、権限、Hooks、Skillsを組み合わせて使う | Claude Code公式機能に基づく |
shared/ を共通ルールの一次情報源にする | AI Learning Playground独自の設計 |
| 「ハーネスエンジニアリング」という用語 | このサイトの実践を説明するための独自用語 |
| 3層構造として整理すること | このサイトの運用パターン |
このサイトではルール・Skill・検証を別の層で管理する
このサイトでは、上記の公式機能と独自設計を組み合わせ、ハーネスを次の3層に分けて実装しています。
1. プロジェクト設定（CLAUDE.md）
AIがプロジェクトを開始するときに最初に読む設定ファイルです。「このプロジェクトでは何をしてはいけないか」「どのディレクトリに何があるか」「使ってよいコマンドはどれか」といった基本方針を記述します。新入社員に渡す「オリエンテーション資料」に相当します。
2. ルール・スキル集（shared/ディレクトリ）
具体的な作業ごとの手順や制約をまとめたファイル群です。たとえば「コンテンツの書き方」「デプロイ手順」「レビューの基準」などが該当します。プロジェクトの「業務マニュアル」です。AIはタスクに応じて該当するファイルを参照します。
3. 教訓ログ（lessons.md）
過去に発生した問題と対処方法を記録するファイルです。製品側の履歴やMemoryに依存できない場合、同じ問題が繰り返されることがあります。教訓ログをAIが読むことで、過去に解決済みの問題を再現しにくくするための情報を提供します。
ハーネスは業務ルールと確認手順から設計できる
ハーネスエンジニアリングの構成要素は、いずれもMarkdownテキストファイルです。プログラミングの知識は必須ではありません。「どんなルールを守ってほしいか」「何をしてはいけないか」「どういう手順で作業してほしいか」を言葉で整理できれば、ハーネスを設計できます。
逆に言えば、この設計なしにAIをプロジェクトに組み込むと、会話のたびにルールを再説明する手間が発生し、AIの判断が会話ごとにばらつくという状況が続きます。
まとめ：公式機能と独自設計を分け、必要な3層だけを配置する
ハーネスエンジニアリングは、AIをプロジェクトの中で継続的かつ一貫して動かしやすくする設計です。CLAUDE.md、設定、Hooks、Skillsは公式仕様に基づきます。shared/への集約と3層構造はAI Learning Playground独自のパターンです。
両者を分けると、製品仕様として期待できる範囲と、プロジェクト側で設計する範囲を判断しやすくなります。
具体例は、CLAUDE.mdの書き方と効果とAI AgentのSkillsと指示ファイルの使い分けで確認できます。共通ルールの配置はshared/ディレクトリの設計、自動処理はClaude Code hooksの使い方で扱っています。
最初に、現在AIへ毎回説明している前提を1つ選び、ルール、作業手順、検証のどこへ置くか決めます。この3層はAI Learning Playgroundの整理方法であり、すべての製品やプロジェクトに共通する公式構成ではありません。
参考文献
- Anthropic, How Claude remembers your project, Claude Code Docs
- Anthropic, Claude Code settings, Claude Code Docs
- Anthropic, Hooks reference, Claude Code Docs
- Anthropic, Extend Claude with skills, Claude Code Docs
最新のリリースやアップデートの詳細は、公式サイト・公式ドキュメントを確認してください。