■ 1. ハーネスエンジニアリングの定義
- 「ハーネス」の定義は論者によって異なり、コンテキスト設計・出力検査・ガードレール・ドキュメント劣化対策など多義的に使われがちである
- Birgitta Bockeler氏がMartinFowler.comに公開した「Harness Engineering」記事を出発点とする
- 本資料における定義：モデルの外側でエージェントの振る舞いを制御・誘導・検証する仕組みの総称
- メタファー：馬具（手綱・鞍・ハミ）が馬を外から方向づけるように、フィードフォワード（FF）とフィードバック（FB）でAIエージェントを外から方向づける
■ 2. ハーネスの2種類：フィードフォワードとフィードバック
- フィードフォワード（動く前に方向づける）:
- 誰として何を目的に動くかを明示する
- 判断に必要な背景知識をあらかじめ渡す
- 何をもって完了とするかを事前に合意する
- 使える手段（ツール・権限）を必要な範囲に絞る
- 現在の局面を示す位置情報を伝える
- フィードバック（動いた後に自己修正を促す）:
- 出力を検査しやすい形で受け取る
- 異なる観点から複数回チェックする
- 不備があれば修正を促して再点検する
- 改善が停滞したら別の手立てに切り替える
- ステアリングループ：FFとFBを継続的に改善しエージェントを操縦するループであり、結果を見てFF・FB両方を調整し続ける
■ 3. ハーネスが制御する3領域
- 保守性（Maintainability）:
- コード品質・保守性を守る汎用的なハーネス
- 重複コード・スタイル違反・力技の修正・過剰な設計を捕捉する
- アーキテクチャフィットネス（Architecture Fitness）:
- アーキテクチャ特性を定義し測定するプロジェクト固有のハーネス
- 性能（レイテンシ・スループット・リソース効率）・可観測性（ログの質・トレース可能性）・構造（レイヤー違反・循環依存・結合度）を対象とする
- 振る舞い（Behaviour）:
- 期待した振る舞いをしているか検査する完全自動化が難しいハーネス
- 仕様・ユースケース・E2Eテスト・フィクスチャベース検証を対象とする
- ハーネステンプレート：FFとFBをパッケージ化したもの
■ 4. TAKTの概要
- YAMLでマルチエージェントワークフローを記述するオーケストレーター（指揮者「タクト」のメタファー）
- ハーネステンプレートをworkflow.yamlとして定義して動かすOSS
- インストール直後からビルトインテンプレートをそのまま利用可能（
npm install -g takt）- 構成要素:
- ワークフロー：STEPの有限状態機械
- ファセット：プロンプトの部品（Persona・Knowledge・Instruction・Output Contract・Policy）
■ 5. フィードフォワードの実装（6つの手法）
- Faceted Prompting（ファセットの組み立て）:
- プロンプトを5つのファセットに分離（Persona・Knowledge・Instruction・Output Contract・Policy）
- PersonaはSystem Prompt、その他はUser Messageとして文脈→タスク→制約の順に組み立てる
- PolicyをUser Messageの末尾に配置しRecency効果で遵守率を最大化する
- Quality Gates（完了条件の事前提示）:
- STEP完了前にエージェント自身が検証すべき項目を明示する
- ビルド成功・lint通過・テスト通過などをプロンプトに箇条書きで注入する
- ツール権限の制限:
required_permission_modeでreadonly / edit / fullを指定するallowed_toolsで使用可能なツールを明示列挙する- レビュアーにはEdit/Writeを渡さず暴走を防止する
- ワークフロー構造の自己認知:
- プロンプトに現在ステップ位置を自動注入しエージェントが前後関係を理解して動作する
- 単独STEPで完結させようとする独走を防ぎInstructionBuilderが各STEPで再構築する
- Persona Providers（適材適所のモデル選択）:
- ペルソナごとに別プロバイダー・モデルを指定する（例：実装はCodex・レビューはClaude）
provider_options.claude.effortで推論深度も指定可能- Team Leader（動的タスク分解）:
- リーダーエージェントがJSONでタスクを分割し各partを並列実行する
- 結果を集約して次STEPへ渡すことでFFを動的に広げる
■ 6. フィードバックの実装（7つの手法）
- Output Contract（判定可能な形の強制）:
- Result: APPROVE / REJECTを強制し
finding_id+family_tagで追跡可能にする- new / persists / resolved / reopenedで進捗を分類する
- 判定フェーズの分離:
- Phase 1（実行エージェント）とPhase 3（conductor・判定専用）を別エージェントに分離する
- 実行する人と判定する人を分けることで主観を判定から切り離す
- Rulesによる分岐:
- 文字列conditionはタグ
[STEP:N]で照合するai("……")で自然文条件をAIが判定する- nextにCOMPLETE / ABORT / 次STEP名を指定してルーティングする
- 改善ループ:
- レビュー結果に基づき修正→再レビューを繰り返す（ai_review ⇆ ai_fix・reviewers ⇆ fix）
pass_previous_response: falseで前回判断の引きずりを防ぐsession: refreshで会話セッション自体をリセット可能- Parallel Reviewers（多視点フィードバック）:
parallelで複数レビュアー（アーキ・フロント・テスト・セキュリティ等）を並列実行するall()/any()で集約判定し単一視点では見えない問題を補う- Loop Monitors（収束・発散の判定）:
- 対象cycleとthresholdを定義し閾値到達でJudge（supervisor）を起動する
finding_idの推移から収束・発散を判定し発散なら別ルート（ABORT等）に切り替える- Worktree Isolation（安全な実行基盤）:
- 各タスクをworktreeで隔離実行する（git worktreeではなく独自実装）
- 失敗してもメインブランチを汚さず並列修正を安全に同時実行できる