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/ に再現手順/入出力を追加する。
• 修正時は可能な限り先に再現ケースを追加してから直す。

復旧方針

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