Kemerd/hardware-in-the-loop

ハードウェアインザループ

あなたは、エージェントがエンジニアリングを行い、ゲートがそれを証明するハードウェアプロジェクトをセットアップ（または実行）しています。行動する前にこのファイル全体を読んでください。この方法はリポジトリの docs/ に記述されています（METHOD、PCB、CAD、FIRMWARE、SIM、SWARM、TOOLS、LESSONS）。このファイルは手順書です。

0. 最初にコストを伝える

何をするよりも先に、以下の内容をユーザーに明確に伝えてください：

この方法をエージェントのスウォームで実行するには費用がかかります。この手法が生まれたプロジェクトでは、スウォーム1日で400～500万トークンを消費しました。そのほとんどは、各々30～80万トークンのコンテキストを持つレーンエージェントを起動したことによるものです。より安価なモードは、サブエージェントなしの単一セッションで、ステップバイステップで作業し、長時間のマシンジョブは切り離して実行し、「中断した場所」セクションから再開します。どちらのモードにしますか？（推奨：単一セッション）

答えを mode（single または swarm）として記録してください。ユーザーがスウォームモードを選択するまでは、サブエージェントを生成しないでください。

1. オンボーディングインタビュー

references/interview.md のインタビューを質問ダイアログを通じて実行します：最大4つの質問のバッチで、各質問の最初の推奨デフォルト値を表示します。質問に答えがない場合はデフォルト値を採用し、その横に「デフォルト採用」と書き込みます。対象：プロジェクトの目標と完了条件、優先順位付きの目標、予算、数量、デフォルトの造形材料（カーボンファイバーナイロン / PETG / PLA / 機械加工アルミニウム）、締結方法（ヒートセットインサート / タップ成形 / ボルト貫通）、エンクロージャ（密閉 / 換気 / 開放）、機械的クリアランス、PCB製造・実装業者、MCUファミリ、主電源と最悪の過渡現象、基板クラスとコーティング、シミュレーションティア（ネイティブツイン / Isaac Sim / Unreal）とGPU、マシン制限（CPU上限デフォルト90％、システム用に空けるRAMデフォルト4 GB、空きディスク下限デフォルト50 GB）、アーカイブ場所、使用量トリップワイヤー（デフォルト95％）、確定判断事項。

材料、締結方法、エンクロージャのシール、クリアランスはプロジェクト決定事項です。これらを黙って選択せず、必ず質問し、推奨し、記録してください。

答えをターゲットリポジトリの .tmp/ にある answers.json に書き込みます（スキーマは references/interview.md にあります）。

2. スケルトンを生成する

python -I <skill>/scripts/scaffold.py --answers <repo>/.tmp/answers.json --dest <repo> [--with-examples] [--dry-run]

これにより、templates/（README_AGENT.md、PROJECT_STRUCTURE.md、REQUIREMENTS.md、README.md、CODING_RULES.md、.gitignore、.gitattributes、windows/ci.ps1 + windows/ci/（グループ audit と pcb）、tools/（監査 + 移植性、空の追跡ベースラインと権利放棄ファイル付き）、pcb/（DESIGN_STANDARDS.md、tools/kicad_env.py、tools/board_pipeline.py、tools/distributor_verify.py）、cad/（cad_plugins.py、render.py、mass_cg_table.py）、firmware/host_tests/hil_check.h、docs/bench/BENCH_REGISTER.md、docs/data/README.md、harness/swarm/（AGENT_RULES、スロット / detach / watch / マージロック / merge-to-dev / promote / WIPバックアップ / ハンドオフフック / ステータスラインスクリプト）および .claude/settings.local.json（ステータスライン + PostToolUseフック））をコピーし、テンプレート変数を埋め、harness/swarm/machine.env と harness/swarm/PLAN.md を選択されたモード用に書き込みます。既存のファイルを上書きすることはありません。保持されたファイルは手動で比較し、有用なものをマージしてください。--with-examples は、パイプラインのすべてのステップを実行するサンプル基板（2層3.3V LDOブレイクアウト）と、2つのプラグインを持つサンプルエンクロージャビルダーを追加します。

次に、pcb/DESIGN_STANDARDS.md のセクション0にある判断テーブルを、回答に基づいて埋めてください。

3. ツール

pwsh -File <skill>/scripts/setup_tools.ps1 -ToolsRoot <ユーザープロファイルの外のフォルダ> [-VerifyOnly]
bash <skill>/scripts/setup_tools.sh --tools-root <dir> [--verify-only]          # Linux

KiCad 10（winget）、Java 21（winget）、Freerouting 2.1.0（固定SHA-256）、OSS CAD Suite 2026-10-24（固定SHA-256、FPGAプロジェクトのみ）、CadQuery venv。<ToolsRoot>/hil_tools.env に HIL_FREEROUTING_JAR、HIL_JAVA、HIL_KICAD_CLI、HIL_CQ_PYTHON を書き込みます。マシン全体へのインストールを行う前にユーザーに確認し、まず -VerifyOnly を実行して不足しているものをユーザーに表示してください。ユーザープロファイルには何もインストールしません。

4. Git：main と dev

ターゲットリポジトリで（履歴が既にあるリポジトリでgitを実行する前に確認すること）：

git init -b main            # まだリポジトリでない場合
git add -A && git commit -m "プロジェクトスケルトン（ハードウェアインザループ手法）"
git branch dev
git push -u origin main dev # リモートが存在する場合

マシンに設定されているgit IDを使用します。帰属行や共同作成者トレーラーは不要です。force-pushは絶対に行わないでください。 次に、最初のCIパスを実行し、そのレポートをメインリファレンスとして保持します：

pwsh -File windows/ci.ps1 -Only audit

5. ハーネスを準備する

• .claude/settings.local.json は usage_statusline.py（ステータスライン、HIL_HANDOFF_PCT によるトリップワイヤー）と handoff_hook.sh（PostToolUse）を配線します。フックを証明します：touch harness/swarm/HANDOFF_SELFTEST を実行し、任意のツールを実行し、「hook is live」コンテキストが表示されることを確認し、ファイルを削除します。
• WIPバックアップを切り離して起動します：bash harness/swarm/detach.sh harness/swarm/wip_backup.sh .tmp/wip_backup.log。
• bash harness/swarm/locks/slot.sh status を確認します。
• リードセッションはメインチェックアウトから実行されます（そこに harness/ があります）。編集はワークツリーで行われます。

6. 作業：シングルセッションモード（デフォルト）

harness/swarm/PLAN.md（references/single-session-plan.md から）に従います：

1. 一度に1つの番号付きステップを、それを証明するゲートと共に実行します。
2. .claude/worktrees/main-work の swarm/main-work で作業します。各グリーンゲートの後にコミット、プッシュ、merge_to_dev.sh を実行します。
3. ヘビージョブ：eval "$(bash harness/swarm/locks/slot.sh take <種類> <あなた> "<ジョブ>" <GB>)" を実行し、使用後に解放します。
4. 長時間ジョブ：bash harness/swarm/detach.sh <チェーン.sh> <ログ> を実行し、すぐに bash harness/swarm/watch.sh <ログ> をバックグラウンドタスクとして実行します。ジョブの実行中に次のステップに進みます。
5. オーナーへの質問：バッチ処理し、最初に推奨デフォルトを表示。採用されたデフォルトは計画に書き込まれます。
6. 停止：「## Where I stopped」（完了したSHA、実行中のジョブのPIDとログ、正確な次のステップ）を追加します。

7. 作業：スウォームモード

docs/SWARM.md と references/wave-checklist.md に従います：

1. ウェーブ1、偵察：読み取り専用エージェントが、ファイル:行アンカー付きの検証済みファクトを harness/swarm/recon_<エリア>.md に書き込みます。
2. ウェーブ2、計画：PLAN.md（references/plan-template.md）にレーン、ファイルごとに1人のオーナー（レーン間の変更は harness/swarm/handoff/ のパッチファイルとして）、インターフェース追加、受理番号を含めます。briefs.md にレーンごとの1つのブリーフ（references/brief-template.md）を含めます。
3. ウェーブ3、ワークツリー swarm/<名前> でのレーン：機械的な作業（ポート、コーデック、レンダリング、テスト、ドキュメント）にはSonnet、繊細な作業（制御、物理、ジオメトリ、シグナルインテグリティ）にはOpus。各レーンは構造化レポート（references/structured-report.md）を返します。
4. ウェーブ4、懐疑論者：差分とレポートのみを持つ新しいエージェント。audit_placeholders.py --changed-since origin/dev --fail-on-new、レーンのCIグループ、3つの数値の再チェックを行います。
5. ウェーブ5、統合：すべてのレーンが merge_to_dev.sh を使用してdevにランディングします（常に、赤も含めて、MERGE_LOCK下で）。dev上で -Compare <メインレポート> -FailOn regressions を使用してフルCIを実行します。promote_dev.sh はゼロ回帰の場合のみ実行します。

レーンは少数に保ち、ブリーフは正確にします。大きなコンテキストを持つエージェントを起動するたびに実際のコストが発生します。

8. 規律（両モード共通）

• PCB：ジェネレータ優先（docs/PCB.md）。ERC 0/0、DRC 0違反 / 0未接続 / 0パリティ（デフォルト重要度）、購入したラインはすべてライブ検証、製造セット + STEP + SHA-256付き結果JSON。自動配置が失敗した場合は、あなたによる手動配置が期待されます。より多くの層は許可されます。価格差を報告してください。ルールの緩和には引用された根拠が必要です。
• CAD：ビルダー + プラグイン。部品変更のたびに質量 / ステーション / CGテーブル（cad/mass_cg_table.py）と、docs/cad_decisions/<日付>/<トピック>/ への適合および干渉PNG（cad/render.py）。
• ファームウェア：アウトオブツリービルド、hil_check.h を使用したホストスイート、実際のインターフェースを通じたシナリオ、シードスイープ、決定論。ハードウェア保留中はリスト化。
• 未完了の作業を完了として表示しない。ベンチオンリー定数には BENCH B-xx-nn IDを付与。
• マシン：スロット、通常より低い優先度、タイムアウト、自分が開始していないプロセスは決して kill しない、ルートから find しない、最初にディスクを確認、Unreal / GPUジョブは一度に1つ、オーナーがマシンの前にいる間はUnrealを起動しない。

9. ハンドオフと夜間運用

• HANDOFF_NOW が現れたら（フックが通知します）、新しい作業を開始するのを止め、その指示に従います：コミット、プッシュ、解放、harness/swarm/resume_<日付>/RESUME_<日付_時刻>_<レーン>.md（references/resume-doc.md）を書き込みます。
• オーナーが夜間に離れる前：切り離された夜間チェーンと翌朝の質問（references/overnight-questions.md）。夜間はデフォルト値で実行されます。採用されたデフォルトはすべて記録します。