こんにちは、キャディで Quote というアプリケーションを開発している plant こと石田 (@plant_ja) です。
ハーネスエンジニアリングという言葉を目にする機会が増えてきましたね。「何をやるべきか」については OpenAI の Harness engineering: leveraging Codex in an agent-first world や逆瀬川さんの Claude Code / Codex ユーザーのための誰でもわかるHarness Engineeringベストプラクティス が非常に参考になります。
本記事では「何を」ではなく「どう始めるか」に焦点を当てています。Claude Code の場合だと Rules、Skills、Hooks、Subagents、さらには custom linter や pre-commit や pre-push、これらの構成要素を眺めているだけで「ちゃんとやろうとしたら大変そうだな」という気持ちになりますよね。
この記事では、そのハードルを下げるための1つのシンプルなアプローチを紹介します。
- この記事のゴール
- ハーネス整備のハードル
- ルール整備によって変わったこと
- なぜうまくいったのか : 枠組みがあると更新のハードルが下がる
- 始め方 : 枠組みだけ先に作る
- Rules 以外にも枠組みは作れる
- 終わりに
この記事のゴール
この記事のゴールは、ハーネスエンジニアリングの着手のハードルを下げることです。
「完璧なハーネスを最初から作り込まなきゃ」と構えるのではなく、「とりあえず枠組みを作って、そこからチームで育てていく」という発想を持って、気軽にハーネスの整備を始められるようになることが目標です。
ハーネス整備のハードル
コーディングエージェントに実装させた結果、期待に満たないコードが生成されることがありますよね。
効率の悪さを感じながらも、その度に毎回「コードから自明なコードコメントは不要です」「as unknown as のような危険な型キャストは使わないでください」という細かい指摘をすることになっていました。アーキテクチャ周りのドキュメントは充実していたのですが、実装の細部のガイドラインはまだまだ整備されていませんでした。
重要性は理解したものの、ハーネス整備にあたってのいくつかの心理的なハードルによって中々整備が進められていないという状況が数週間ほど続きました。
「そもそもハーネスエンジニアリングについての目線をチームで揃えないと」
「どういう形式でルールを整備するべきなんだろう、先にチームで議論しないと」
「ルールファイルを新たに追加したくなったけど、流石に実装 PR とは分けたほうがいいよな」
そんなことを考えつつ、ハーネスエンジニアリングについての目線をチームで揃えたり、custom linter を整備するなどの活動を進めたのですが、「やっぱり Rules ファイルの整備が手っ取り早く品質を向上させるためのアプローチだ」と考え、重い腰を上げて自分が開発しているアプリケーションのバックエンドの実装ルールを Claude Code の Rules ファイルとして整備することにしました。
Rules ファイルは、レイヤーを横断した汎用的な Rules (coding-style.md, testing.md) や、レイヤー毎の実装ルール (usecase.md, usecase_testing.md) に大別することとしました。
Rules を整備するために、既存の実装から実装パターンを推論して Rules ファイルを生成するスキルを作成しました。ファイルの生成自体はそこまで時間がかからずにできたのですが、実装方針がふわっとしている部分について意思決定を下したり、細かいニュアンスの修正など、想像以上にルールのレビューに時間がかかり、全てのレイヤーに対してのルールを作り切るまでに丸一日を費やしました。
しかし、ハーネスエンジニアリングの土台整備という観点だと、ここまでやる必要はなかったということに後に気づくことになります。
ルール整備によって変わったこと
バックエンドの Rules ファイルが一通り整った上で、実装を進める中で「これもルールに盛り込みたいな〜」という点がいくつも出てきます。そこで、ルール更新用のスキル（/update-coding-rule）を作り、/update-coding-rule コードから自明なコードコメントは不要です という指示を Claude Code に出すと、対応するルールファイルを探して追加・更新してくれるようにしました。実装の途中で出る細かい不満が、そのままチームで管理している品質基準へのフィードバックになるわけです。
PR レビューのコメント URL を渡しても同じことができるようにしました。/update-coding-rule <PR のコメント URL>と指示するだけで、スキルが該当スレッドを取得して、PR レビューでの指摘をルール化してくれます。
このスキルを何回か使っていく中で、「実装中の細かい不満をチームの品質基準に反映させる」という作業に対しての心理的なハードルがとても下がっていることに気づきました。
なぜうまくいったのか : 枠組みがあると更新のハードルが下がる
ここからが気づきです。ルールが育つようになった理由は、「充実したルールファイルを最初から用意した」からではなく、「ルールファイルをどこに・どんな形で置くか」という枠組みが決まっていたからです。
枠組みがあると、ハーネス整備に際してのハードルがグッと下がります。ハーネスの形式は既に決まっているので、その中身をリッチにしていくという営みは日常の開発の延長線上で容易に行うことができます。
この経験を経て、重要なのはルール内容の充実度ではなく、誰でも更新しやすい状態になっていることだと気づきました。内容がスカスカでも、「これはここに追加すればいいんだ」という道筋が見えていることの方が大切なのだと。
始め方 : 枠組みだけ先に作る
ここからが実践です。私は1日かけてルール全体をいきなり整備しましたが、そこまでやる必要はありませんでした。
枠組み（ほぼ空のルールファイル群）だけ先に作ってしまえば、始められます。
プロンプト例
プロジェクトのアーキテクチャをざっと分析してもらい、Rules ファイルの骨組みを作るプロンプトの例です。 自分がメインに利用しているのが Claude Code なので、Claude Code に特化した内容になっています。
このプロジェクトのアーキテクチャを分析して、Rules ファイルの骨組みを作ってください。
## ルールドキュメントの種類
ルールドキュメントは下記の 2 種類に大別します。
### 1. 汎用ルール
レイヤーを横断する共通方針です。ユーザーにどのような汎用ルールを作成したいかを
インタビューした上で、必要なものを作成してください。
例 : `coding-style.md`, `testing.md`, `error-handling.md`, `observability.md`
### 2. レイヤー別ルール
レイヤーごとにサブディレクトリを作り、実装ルールとテストルールを分離します。
例 : `usecase/usecase.md`, `usecase/usecase_testing.md`
## ルールドキュメントの要件
- 各ルールドキュメントには概要のセクションを用意して、ルール自体の説明を書く
- coding-style.md の例 : XXXプロジェクトのコーディングスタイルに関する横断ルール
- usecase/usecase_testing.md の例 : Usecase 固有のテストルール。共通のテストルールは
testing.md を参照。本ドキュメントの規約が testing.md と競合する場合、本ドキュメントを優先する。
- 既存のコードから明らかに読み取れるルールがあれば、セクションを追加して1~2個ほど簡潔に記入しても構わない
## .claude/rules/ のインデックスファイル
ルールドキュメント本体の置き場所はユーザーにインタビューして決めてください。
`.claude/rules/` 配下のファイルはインデックスとして扱い、ルール本体への参照だけを記載します。ディレクトリ構成はルール本体のディレクトリ構造と一致させるようにします。
frontmatter の `paths` で対象ファイルパスを指定し、本文にはルールドキュメントへのパスを書きます。
以下は Usecase のテストルールのインデックスファイルの例です。
---
paths:
- "src/usecase/**/*.spec.ts"
---
# Usecase テストルール
Usecase のテストを新規作成・修正する場合、計画開始前もしくは作業開始前に以下のルールファイルを読み込むこと:
<ルールドキュメントへのパス>
このプロンプトを Claude Code に渡すと、「ここに何を置くか」という地図ができます。
Rules 以外にも枠組みは作れる
今回は Rules の整備を例に挙げましたが、同じ発想は Rules ファイル以外でも使えると考えています。例えば Skills であれば、API の stub を生成するスキル（/create-api-stub）を最低限の機能で作っておくだけで、使う中で「リクエストパラメーターのバリデーションもこの時点で入れるようにしよう」などといったフィードバックが自然と集まるようになります。Hooks であれば、Stop hooks や PostToolUse hooks などの各タイミングで走らせるための専用のスクリプト (例: stop-hook-script.js) を用意しておき、そこを少しずつ充実させていくなどのアプローチが取れるかもしれません。
枠組みと責務が明確だと、更新・拡張のハードルが下がる。 Rules に限らず、この原則は共通しているはずです。
終わりに
ハーネスエンジニアリングは、完璧な仕組みを設計してからスタートするものではないと思っています。見出しだけのルールファイルでも、空っぽのスキルでも、「ここに足していける」という場所があるだけで、チームの誰かが気づいたことを反映できるようになります。
開発とハーネス整備を区別せず、同じタスクの中で完結させる。この感覚が根づくと、ハーネスは勝手に育っていくのではないでしょうか。
この記事で取り上げたような課題感をお持ちの方は、ぜひ枠組みを作るところからスタートしてみませんか？
また、キャディでは一緒に働く仲間を大募集中なので、興味があれば下記もぜひご覧ください。
