하드웨어 인 더 루프은(는) 무엇을 하나요?

에이전트가 엔지니어링을 수행하고 게이트가 이를 검증하는 하드웨어 프로젝트를 설정(또는 실행)하고 있습니다. 작업을 수행하기 전에 이 전체 파일을 읽으십시오. 이 방법은 저장소의 docs/ (METHOD, PCB, CAD, FIRMWARE, SIM, SWARM, TOOLS, LESSONS)에 설명되어 있습니다; 이 파일은 절차입니다.

0. 먼저 비용을 알리십시오

다른 어떤 것보다 먼저 사용자에게 다음과 같이 명확하게 말하십시오:

에이전트 스웜으로 이 방법을 실행하는 것은 비용이 많이 듭니다. 이 방법이 만들어진 프로젝트에서는 스웜 하루에 4-5백만 토큰이 소모되었으며, 대부분 각각 300-800k 토큰의 컨텍스트를 가진 레인 에이전트를 깨우는 데 사용되었습니다. 더 저렴한 모드는 단일 세션(서브에이전트 없이 단계별로 작업하고, 긴 머신 작업은 분리하여 실행하며, "Where I stopped" 섹션에서 재개)입니다. 어떤 모드를 원하십니까? (권장: 단일 세션)

답변을 mode (single 또는 swarm)에 기록하십시오. 사용자가 스웜 모드를 선택하기 전에는 서브에이전트를 생성하지 마십시오.

1. 온보딩 인터뷰

references/interview.md의 인터뷰를 질문 대화 상자를 통해 실행하십시오: 한 번에 최대 4개의 질문 배치, 모든 질문에서 권장 기본값을 먼저 제시하십시오. 질문에 답변이 없으면 기본값을 취하고 옆에 "default taken"이라고 기록하십시오. 다루는 내용: 프로젝트 목표 및 완료 정의, 우선순위별 목표, 예산, 수량, 기본 인쇄 재료(카본 파이버 나일론 / PETG / PLA / 가공 알루미늄), 체결(열세트 인서트 / 셀프 태핑 / 관통 볼트), 인클로저(밀폐 / 통풍 / 개방), 기계적 여유, PCB 제조 및 조립 업체, MCU 제품군, 주 전원 및 최악의 과도 상태, 보드 클래스 및 코팅, 시뮬레이션 계층(네이티브 트윈 / Isaac Sim / Unreal) 및 GPU, 머신 한계(CPU 제한 기본 90%, 시스템용 예비 RAM 기본 4GB, 여유 디스크 최소 기본 50GB), 아카이브 위치, 사용량 트립와이어(기본 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, 슬롯 / 분리 / 감시 / 병합 잠금 / 병합-투-데브 / 승격 / WIP 백업 / 핸드오프 훅 / 상태 라인 스크립트) 및 .claude/settings.local.json (상태 라인 + PostToolUse 훅))을 복사하고, 템플릿 변수를 채우며, 선택한 모드에 대해 harness/swarm/machine.env 및 harness/swarm/PLAN.md를 작성합니다. 기존 파일을 절대 덮어쓰지 않습니다; 유지된 파일을 수동으로 비교하고 유용한 것을 병합하십시오. --with-examples는 예제 보드(모든 파이프라인 단계를 실행하는 2층 3.3V LDO 브레이크아웃)와 두 개의 플러그인이 있는 예제 인클로저 빌더를 추가합니다.

그런 다음 답변을 바탕으로 pcb/DESIGN_STANDARDS.md의 결정 테이블(섹션 0)을 채우십시오.

3. 도구

#### Windows
pwsh -File <skill>/scripts/setup_tools.ps1 -ToolsRoot <사용자 프로필 외부 폴더> [-VerifyOnly]

#### Linux
bash <skill>/scripts/setup_tools.sh --tools-root <dir> [--verify-only]

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 "Project skeleton (hardware-in-the-loop method)"
git branch dev
git push -u origin main dev # 원격이 있는 경우

머신에 구성된 git 아이덴티티를 사용하십시오. 귀속 라인이나 공동 작성자 트레일러는 없습니다. 절대 강제 푸시하지 마십시오. 그런 다음 첫 번째 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/가 있음); 편집은 작업 트리(worktrees)에서 이루어집니다.

6. 작업: 단일 세션 모드 (기본값)

harness/swarm/PLAN.md (references/single-session-plan.md에서 가져옴)를 따르십시오:

한 번에 하나의 번호가 매겨진 단계, 각 단계마다 이를 증명하는 게이트가 있습니다.
.claude/worktrees/main-work의 swarm/main-work에서 작업하십시오; 커밋, 푸시, 모든 녹색 게이트 후 merge_to_dev.sh를 실행하십시오.
무거운 작업: eval "$(bash harness/swarm/locks/slot.sh take <kind> <you> "<job>" <GB>)", 완료 후 해제하십시오.
긴 작업: bash harness/swarm/detach.sh <chain.sh> <log>를 실행하고 즉시 bash harness/swarm/watch.sh <log>를 백그라운드 작업으로 실행하십시오; 작업이 실행되는 동안 다음 단계를 계속하십시오.
소유자 질문: 배치로, 권장 기본값을 먼저 제시하십시오; 기본값이 취해지면 계획에 기록하십시오.
중지: "## Where I stopped"를 추가하십시오 (완료된 SHA, 실행 중인 작업의 PID 및 로그, 정확한 다음 단계).

7. 작업: 스웜 모드

docs/SWARM.md 및 references/wave-checklist.md를 따르십시오:

웨이브 1, 정찰: 읽기 전용 에이전트가 파일:라인 앵커가 있는 검증된 사실을 harness/swarm/recon_<area>.md에 작성합니다.
웨이브 2, 계획: PLAN.md (references/plan-template.md)에는 레인, 파일당 한 명의 소유자 (교차 레인 변경은 harness/swarm/handoff/의 패치 파일로), 인터페이스 추가, 승인 번호가 포함됩니다; briefs.md에는 레인당 하나의 브리프 (references/brief-template.md)가 포함됩니다.
웨이브 3, swarm/<name>의 작업 트리에서의 레인: 기계 작업(포트, 코덱, 렌더, 테스트, 문서)에는 Sonnet, 미묘한 작업(제어, 물리, 기하학, 신호 무결성)에는 Opus. 각 레인은 구조화된 보고서 (references/structured-report.md)를 반환합니다.
웨이브 4, 회의론자: diff와 보고서만 있는 새 에이전트; audit_placeholders.py --changed-since origin/dev --fail-on-new, 레인의 CI 그룹, 세 개의 숫자를 재확인합니다.
웨이브 5, 통합: 모든 레인이 merge_to_dev.sh로 dev에 랜딩합니다 (항상, 빨간색 포함, MERGE_LOCK 아래); -Compare <main report> -FailOn regressions로 dev에서 전체 CI; promote_dev.sh는 회귀가 없을 때만.

레인을 적게 유지하고 브리프를 정확하게 유지하십시오; 큰 컨텍스트 에이전트를 깨울 때마다 실제 비용이 발생합니다.

8. 규율 (두 모드 모두)

PCB: 발전기 우선 (docs/PCB.md). ERC 0/0, DRC 0 위반 / 0 미연결 / 기본 심각도에서 0 패리티, 구매된 모든 라인이 실시간으로 검증됨, fab 세트 + STEP + SHA-256이 포함된 결과 JSON. 자동 배치기가 실패할 때는 사용자가 직접 배치하는 것이 예상됩니다. 더 많은 레이어가 허용됩니다; 가격 차이를 보고하십시오. 규칙을 완화하려면 인용된 근거가 필요합니다.
CAD: 빌더 + 플러그인; 모든 부품 변경 시 질량 / 스테이션 / CG 테이블 (cad/mass_cg_table.py); docs/cad_decisions/<date>/<topic>/에 핏 및 충돌 PNG (cad/render.py).
펌웨어: 아웃-오브-트리 빌드, hil_check.h가 있는 호스트 스위트, 실제 인터페이스를 통한 시나리오, 시드 스위프, 결정론; 하드웨어 보류 목록.
완료되지 않은 작업을 완료된 것으로 표시하지 마십시오; 벤치 전용 상수는 BENCH B-xx-nn ID를 얻습니다.
머신: 슬롯, below-normal 우선순위, 타임아웃, 시작하지 않은 작업을 절대 죽이지 말고, 루트에서 find를 실행하지 말고, 먼저 디스크를 확인하고, 한 번에 하나의 Unreal/GPU 작업, 소유자가 머신에 있을 때 Unreal을 실행하지 마십시오.

9. 핸드오프 및 야간

HANDOFF_NOW가 나타나면 (훅이 알려줌), 새 작업을 시작하지 말고 그 지시를 따르십시오: 커밋, 푸시, 해제, harness/swarm/resume_<date>/RESUME_<date_time>_<lane>.md (references/resume-doc.md)를 작성하십시오.
소유자가 밤에 떠나기 전: 분리된 야간 체인과 아침 질문 (references/overnight-questions.md). 야간은 기본값으로 실행됩니다; 취해진 모든 기본값을 기록하십시오.

하드웨어 인 더 루프