* 目次 [#x325b63f]
#contents
* 主張 [#beac300e]
モデル性能より運用（ハーネス）で差がつく
** よくある失敗例： [#ub7a326a]
- stateがなく、会話ログだけを頼りに再開する
- AIが「終わった」と誤認し、未完タスクを放置する
- 方針変更が会話中に起き、誰も気づかない
これらはすべて「正本が存在しない」ことが原因である。
* SWEの分解式 [#p6a8ab03]
SWE≈1−(1−Π(Pi×Ci))k
※ これは厳密な数学モデルではなく、運用改善ポイントを可視化するための思考モデルである。
- ハーネスはCi（文脈保持）を1 に近づけ
- QdrantはPi（判断精度）を底上げし
- State管理はk（有効再試行） を増やす
Qdrantは必須ではない。
本記事のハーネスは「ファイル正本」だけでも成立する。
Qdrantは「過去の理由や議論を思い出す」ための補助輪である。
** リポジトリ直下にこれを作る [#u0964ff2]
/harness
/spec
feature_list.yaml
constraints.md
/state
state.yaml
progress.md
open_questions.md
/run
session_plan.md
session_report.md
/logs
decisions.md
*** 説明 [#zb7677e0]
- feature_list.yaml = 完了条件（これが“終わった判定”の基準）
- state.yaml = 現在の確定状態（最新版はここ）
- progress.md = 人間が読む引き継ぎ（短文）
- decisions.md = 意思決定ログ（なぜそうしたか）
- open_questions.md = 未解決論点（ここを放置しない）
* Initializer エージェント（設定してくれる役） [#d4f1936c]
Initializer は原則として「最初」または「大きな方針転換時」にのみ実行する。
通常の作業では Worker だけを回す。
あなたは「Harness Initializer」です。長期稼働エージェントのためのハーネス（外部状態・進捗・完了条件）を初期化します。
目的:
- このリポジトリで長期タスクを安全に継続できるよう、/harness 以下に正本を作る。
- 次回以降の作業エージェントが「何を読めばよいか」「何をやればよいか」を迷わない状態にする。
必須成果物（作成・更新）:
1) /harness/spec/feature_list.yaml
- 完了条件をチェックリスト化する
- 各項目に id, description, acceptance_criteria, status(todo|doing|done) を持たせる
2) /harness/state/state.yaml
- 現在の確定方針・制約・重要変数（採用技術、方針、前提）を1箇所に集約
3) /harness/state/progress.md
- 直近の進捗、現状、次の一手を短く
4) /harness/logs/decisions.md
- 主要な決定と理由を追記（決定ID、日付、要約、理由、影響範囲）
5) /harness/state/open_questions.md
- 未確定事項を列挙し、解決のための最小質問を添える
ルール:
- 会話やコードから読み取れる事実だけを書く。推測は "Assumption:" と明示する。
- 正本は /harness/state/state.yaml。ここに書かれた内容が最新版。
- 進捗やログは短く、重複を書かない（stateに寄せる）。
- 完了条件（feature_list）が空/曖昧なら、最小の粒度に分割して埋める。
出力:
- まず、作成/更新するファイル一覧と、その中身を提示する（ファイルごとに見出し）。
- 次に、Workerエージェントが次回読むべき順序（読み込み手順）を1つの箇条書きで提示する。
* Worker エージェント（継続実装役） [#i9f9ee37]
あなたは「Harness Worker」です。/harness を正本として、長期タスクを1ステップずつ進めます。
開始手順（必須）:
1) /harness/state/state.yaml を読む（これが最新版）
2) /harness/spec/feature_list.yaml を読む（完了条件と未完了を確認）
3) /harness/state/progress.md と /harness/state/open_questions.md を読む（直近状況）
4) 必要なら /harness/logs/decisions.md を参照（理由の整合性確認）
作業ルール:
- 1セッションでやるのは「小さな1〜3タスク」だけ。未完の大作業を残さない。
- 変更後は必ず「検証」をする（テスト、ビルド、動作確認、または代替の検証手順）。
- セッション終了時に必ず /harness/state/progress.md と feature_list.yaml の status を更新する。
- 仕様や方針を変える必要がある場合は、勝手にstateを書き換えず、open_questions.md に提案として追加し、decisions.md に“提案”として記録する。
セッション終了条件（必須）:
- 作業結果が保存されている（ファイル更新）
- 進捗が更新されている（progress, feature_list）
- 次の一手が明確（progressに Next を書く）
- 未解決の判断は open_questions に隔離されている
出力:
- 今回やったこと（Done）
- 検証結果（Verify）
- 次にやること（Next）
- 更新したファイル一覧（Files）
*** もし「Excel正本」もやるなら（企業向け） [#u2d61b5d]
Excelを正本にする場合は、Workerのルールにこれを足すだけでOKです：
state.yaml の代わりに “Excel（Nodes/Edges/Decisions）” が正本
Workerは毎回「Excel→state.yamlへ“同期用サマリ”を生成」してから動く
つまり Excelが公式、state.yamlがAI用キャッシュ になります。
* feature_list.yaml のテンプレ [#y14b3023]
features:
- id: F-001
description: "（例）資格管理の一覧画面を表示できる"
acceptance_criteria:
- "一覧取得APIが200で返る"
- "空状態・エラー状態が表示できる"
status: todo
- id: F-002
description: "（例）新規登録ができる"
acceptance_criteria:
- "バリデーションが動く"
- "登録後に一覧へ反映される"
status: todo
status: done # acceptance_criteria をすべて満たした場合のみ
