harness-engineering.md

Harness Engineering

概要

ハーネスエンジニアリングは、モデルそのものではなく、モデルが安定・安全・再現可能に働くための周辺環境を設計する考え方です。

このリポジトリでは、AGENTS.md や CLAUDE.md を単なるメモではなく、エージェントの実行基盤を整えるための入口として扱います。重要なのは文書を増やすことではなく、何を読ませ、何を触らせ、どう検証し、失敗からどう改善するかを一体で設計することです。

基本方針

1. 薄い入口を作る

AGENTS.md と CLAUDE.md は短く保ちます。最初に必要な事実だけを書き、詳細は個別文書へ逃がします。

2. 深い知識は docs/ に分離する

設計、判断理由、進行中の計画、運用方針は docs/ 配下に置きます。入口文書に長文を集約しません。

3. 文書だけでなく作業ループも設計する

ハーネスには次の要素を含めます。

• どの文書を先に読むか
• いつ計画を作るか
• どのコマンドで検証するか
• 何を完了条件とみなすか
• どの操作を禁止または要承認にするか

4. 失敗したらハーネス全体を見直す

失敗時に長文ルールを追加するのではなく、原因が入口不足なのか、文書配置なのか、検証不足なのか、権限設計なのかを見直します。

文書の役割分担

AGENTS.md

全エージェント共通の最小契約を置きます。

• リポジトリの目的
• ディレクトリの地図
• build / test / lint / format
• 共通の作業ルール
• 完了条件
• 深い文書へのリンク

CLAUDE.md

Claude Code 向けの追加ガイドを置きます。

• 起動時に読む順番
• 変更前の探索手順
• どの変更でプランを必須にするか
• 既存パターンやテストを先に確認する方針
• 将来的に .claude/ 配下へ分割する前提

docs/

深い知識を配置します。

• docs/architecture.md: アーキテクチャ全体像
• docs/overview.md: 全体像、現在地、次の順番
• docs/decisions.md: 設計判断の記録
• docs/coding-rules.md: 実装・レビューの詳細ルール
• docs/plans/: 実装計画
• docs/harness-engineering.md: エージェント運用の設計原則

推奨する読み順

共通

1. AGENTS.md
2. 変更対象に近い docs/ 文書
3. 対象 crate / テスト / 既存実装

Claude Code

1. AGENTS.md
2. CLAUDE.md
3. 関連する docs/ 文書
4. 対象コードとテスト

計画とスコープ

このリポジトリでは、実装前にプランを提示して合意を取る運用を共通ルールにします。

次のいずれかに該当する変更は、短くてもプランを明示します。

• 振る舞いが変わる変更
• 複数ファイルにまたがる変更
• テスト戦略の変更
• ドキュメント構造の変更

検証ループ

エージェントは編集後に、影響範囲に応じて検証方法を選びます。

• フォーマット: cargo fmt
• Lint: cargo clippy --workspace
• 全体テスト: cargo test --workspace
• 部分テスト: 対象 crate の cargo test -p <crate>

変更に応じて必要な検証を明示し、未実行の検証があれば完了扱いにしません。

完了条件

作業完了とみなす最低条件は次です。

• 変更意図がコードまたは文書から追える
• 必要なテスト、lint、format の実行状況が明確
• 振る舞い変更があれば関連文書が更新されている
• 次に見るべき文書や残課題があれば明示されている

権限と安全性

危険操作は明示的な依頼なしに行いません。

• 破壊的な git 操作をしない
• secrets や認証情報を変更しない
• 実行意図が不明なコマンドを走らせない
• 必要最小限の差分で進める

継続改善

同じ種類の失敗やレビュー指摘が繰り返されたら、次の順で見直します。

1. 入口文書が長すぎないか
2. 詳細知識の配置先が曖昧でないか
3. 検証手順が不足していないか
4. 完了条件が弱くないか
5. 権限や禁止事項が曖昧でないか

ルールの追加は、その失敗を次回防げる最小限の粒度で行います。