Claude Codeの出力を安定させる「ハーネス設計」—2階層化とコミット時推論ジャッジの実践

Claude Codeをはじめとする生成AIコーディングツールが実務に浸透する中、多くの開発チームが直面するのが「出力の不安定性」です。同じ指示を出しても毎回微妙に異なるコードが生成される、プロジェクトの規約を無視した実装が混入する、レビュー負荷が予想以上に高い——こうした課題は、モデルの性能だけでは解決できません。

今回紹介するのは、実プロジェクトで運用されている「ハーネス（馬具）」という概念です。馬具が馬の力を制御し方向づけるように、AIモデルの出力を適切にガイドし、品質を担保する仕組みを構築する考え方です。

ツールの量ではなく、制御点の質で勝負する

従来のアプローチでは「どんなツールを追加するか」に焦点が当たりがちでした。しかし実プロジェクトで効果を上げているのは、**ツールの量ではなく制御点の戦略的配置**です。

ハーネス設計における制御点とは、AIの入出力に対して「いつ」「どのように」介入するかを定義したポイントです。闇雲に制約を増やすのではなく、プロジェクトの特性に合わせて育てていく発想が重要になります。

実践されている2つの制御点

#### ① 入口制御：CLAUDE.md / .claude/rules/ の2階層化

最初の制御点は「入力段階」に置かれます。具体的には以下の3チャネル構造でルールを注入します：

この2階層化により、「グローバルな一貫性」と「ローカルな柔軟性」を両立できます。例えば、フロントエンドとバックエンドで異なる規約を適用しつつ、全体のアーキテクチャ原則は統一するといった運用が可能になります。

#### ② 出口制御：pre-commit × Claude CLI による意味的整合性ジャッジ

2つ目の制御点は「出力後、コミット前」に配置されます。従来のlinterやformatterは構文的な問題しか検出できませんでしたが、ここでは**推論型ジャッジ**を導入します。

pre-commitフックとClaude CLIを組み合わせることで、コミット時に以下をチェックします：

構文チェックツールが「形式」を見るのに対し、推論型ジャッジは「意味」を評価します。これにより、技術的には正しいが設計思想に反するコードを早期に検出できます。

GitHub CopilotやCursorとの本質的な違い

GitHub CopilotやCursorも優れたAIコーディングツールですが、それらとの決定的な違いは**制御の粒度と明示性**にあります。

Copilotは主にエディタ内でのリアルタイム補完に特化しており、プロジェクト全体の規約適用は間接的です。Cursorはより広範なコンテキスト理解を持ちますが、制御ルールの構造化という点では発展途上です。

一方、今回紹介されたハーネス設計は：

という特徴を持ちます。これは「個人の生産性向上」から「チームの品質保証体制」へのパラダイムシフトを示しています。

メリット：予測可能性と学習ループの確立

最大のメリットは**出力の予測可能性向上**です。ハーネスが適切に機能すれば、AIの出力がプロジェクトの期待値から大きく外れることが減り、レビュー時間が削減されます。

さらに重要なのは**学習ループの確立**です。pre-commitでの推論ジャッジが指摘した問題を分析し、それをCLAUDE.mdや.claude/rules/にフィードバックすることで、システム全体が賢くなっていきます。これは単なるツール利用ではなく、プロジェクト固有の「AI活用知見」の蓄積プロセスです。

注意点：初期コストとメンテナンス負荷

一方で注意すべき点もあります。

**初期設計コスト**は無視できません。CLAUDE.mdと.claude/rules/の構造設計、推論ジャッジのプロンプト設計には相応の時間が必要です。小規模プロジェクトや短期プロトタイプには過剰投資になる可能性があります。

また**メンテナンス負荷**も発生します。プロジェクトの進化に合わせてルールセットを更新し続ける必要があり、「ルールのルール」を誰が管理するかという問題も生じます。

適用すべきプロジェクトの条件

このアプローチが特に効果を発揮するのは：

1. **中長期運用が前提のプロジェクト**（3ヶ月以上）

2. **複数人が並行開発するチーム体制**

3. **ドメイン固有の規約や設計原則が明確**

4. **品質の一貫性がビジネス価値に直結する**（金融、医療、基盤システムなど）

逆に、週末の個人プロジェクトやハッカソンのような短期集中型では、ハーネス設計のコストが利益を上回る可能性が高いです。

ステップ1：CLAUDE.mdファイルをプロジェクトルートに作成する

まずは最小構成から始めましょう。以下の項目を含むCLAUDE.mdを作成します：

# プロジェクト概要
[プロジェクトの目的とドメイン]

# コーディング原則
- 原則1: [具体的な原則]
- 原則2: [具体的な原則]

# 禁止事項
- [絶対に避けるべきパターン]

ポイントは**具体性**です。「綺麗なコードを書く」ではなく「エラーハンドリングは必ずResult型を使用し、panicは使わない」といった実行可能なレベルまで落とし込みます。

ステップ2：.claude/rules/ディレクトリで部分的ルールを試す

次に、特定領域のルールを追加します：

mkdir -p .claude/rules
echo "# API層のルール\n- すべてのエンドポイントにrate limitを設定\n- レスポンスは必ずJSON:APIフォーマット" > .claude/rules/api.md

これをAPIディレクトリでの作業時に参照させることで、コンテキスト依存の制御を実現します。

ステップ3：簡易版の推論ジャッジをpre-commitに追加する

フル実装は難しくても、簡易版から始められます。`.pre-commit-config.yaml`に以下を追加：

- repo: local
  hooks:
    - id: semantic-check
      name: Semantic Consistency Check
      entry: bash -c 'git diff --cached | claude-cli "このdiffがCLAUDE.mdの原則に違反していないか、違反している場合のみ具体的に指摘せよ"'
      language: system
      pass_filenames: false

これだけでも、明らかな原則違反を早期発見できます。

Claude Codeをはじめとする生成AIツールは、「使う」段階から「制御する」段階に移行しています。ハーネス設計という考え方は、その制御を戦略的に、かつチーム全体で共有可能な形で実現するアプローチです。

ツールの機能追加競争に惑わされず、自分たちのプロジェクトに必要な制御点を見極め、段階的に育てていく——この地道なプロセスこそが、AI時代の持続可能な開発体制を作ります。

この情報は @Hiroyasu Mitani さんの投稿を参考にしています。