windmill/HARNESS.md

# HARNESS.md

## 目的
- このリポジトリ（Windmill運用）で、Codex / Claude Code / ローカルLLMの協調作業を安全かつ再現可能にする。
- 大きい指示文より、コンテキスト設計・制約・検証・記録を優先する。

## 役割分担
- Codex: 要件分解、変更方針、レビュー観点、ドキュメント整備。
- Claude Code: 実装、コマンド実行、検証、差分反映。
- ローカルLLM: 下書き生成、軽量リファクタ提案、代替案提示。

## 依頼フォーマット（必須3行）
1. Purpose: 何を達成するか
2. Target: どのファイル/機能/環境か
3. Done: 何を確認できたら完了か

## 作業スコープ
- 主対象: `workflows/`, `mcp/`, `docker-compose-dev.yml`, `docker-compose.yml`, `sync_to_git.sh`, `HANDOFF.md`, `SERVER_SETUP.md`
- 原則: 1タスク1責務。仕様変更と大規模改修を同時に進めない。
- 仕様/挙動変更時は、同タスクでドキュメント更新まで行う。

## コンテキスト方針
- 長い会話ログは渡さない。
- 毎回渡す情報は最小化する:
  - 依頼3行（Purpose/Target/Done）
  - 関連ファイルのパス
  - 失敗コマンド + ログ先頭5行 + 末尾5行
  - 現在の前提・制約
- トークン圧迫時は要約スナップショットへ圧縮する。

## 安全レール
- 破壊的操作（削除、履歴改変、本番反映）は事前承認必須。
- シークレットをプロンプト/ログ/コミットに含めない。
- タスクに無関係なパスは編集しない。
- 想定外の差分を検知したら作業停止して確認する。

## 検証ポリシー（Windmill向け固定）
- L1 構成検証:
  - `docker compose -f docker-compose-dev.yml config`
- L2 サービス検証（必要時）:
  - `docker compose -f docker-compose-dev.yml up -d db windmill_server`
  - `docker compose -f docker-compose-dev.yml ps`
  - `docker compose -f docker-compose-dev.yml exec -T windmill_server curl -fsS http://localhost:8000/api/version`
- L3 変更対象別検証:
  - `mcp/` 変更時: `docker compose build windmill_mcp` と `docker compose up -d windmill_mcp`
  - `workflows/` 変更時: `wmill sync` 関連手順を `SERVER_SETUP.md` / `HANDOFF.md` に沿って確認
- 失敗時は必ずログを残す:
  - `docker compose -f docker-compose-dev.yml logs --tail=200 windmill_server`

## 品質ゲート
- 変更内容に対応するL1/L2/L3結果を記録して完了とする。
- サイレントな挙動変更は禁止（テスト/手順書更新を伴うこと）。
- 運用手順に影響する変更は `HANDOFF.md` または `SERVER_SETUP.md` を同時更新する。

## 記録ルール
- タスクごとに `state/tasks/<task_id>.md` を作成。
- 最低記録項目:
  - task_id
  - 依頼3行
  - 変更ファイル
  - 実行コマンドと結果
  - 未解決リスク/次アクション

## ゴールデンデータセット
- 再発した不具合は `tests/golden/` に再現手順/入出力を追加する。
- 修正時は可能な限り先に再現ケースを追加してから直す。

## 復旧方針
- 作業前にバックアップブランチを作る。
- 緊急時はバックアップブランチに即時復帰できる状態を維持する。