# factory00 AI Agent Onboarding Guide

> **이 문서의 대상**: factory00 프로젝트에 처음 진입하는 외부 AI 에이전트 (Codex Pro 등) 및 협업 파트너.
> **목적**: 첫 세션에서 프로젝트를 빠르게 파악하고, 기획·문서·코드 검토 작업에 곧바로 진입할 수 있도록 최적의 진입 경로와 컨텍스트를 제공한다.

마지막 갱신: 2026-05-15 · 현 버전 **v0.1.161** · 26번째 stable seal `v0.1.161-rotary-data-stable`

---

## 0. 30초 요약

| 항목 | 값 |
|---|---|
| 프로젝트 | factory00 — 기계설비 경량 디지털 트윈 시뮬레이터 |
| 한 줄 | "코딩 없이 설비 배치·속성 설정·동작 테스트하는 SimCity-스타일 트윈 툴" |
| 엔진 | Unity 6 (URP · UI Toolkit) |
| 플랫폼 | Windows 데스크탑 standalone (`.zip` 단일 배포) |
| 단위 | Transform mm (scaled) · 사용자 입력 m · 경계에서 ×1000 / ÷1000 변환 의무 |
| Phase | Phase 5 (시뮬레이션 완결) + Phase 6 (입출력 모듈) + Phase 7 (인터페이스 에뮬레이션) 진행 중 |
| 첫 PLC 타겟 | 미츠비시 MX Component (협업자 SDK 도착 대기) |
| 외부 영구 URL | https://os-file-server.tail2b816d.ts.net/ (Tailscale Funnel) |

---

## 1. 첫 진입 7단계 navigation

외부 URL에서 다음 순서로 읽으면 1시간 내에 프로젝트 전체 컨텍스트가 형성된다.

| 단계 | 문서 | 목적 | 예상 시간 |
|---|---|---|---|
| 1 | **본 문서** `AGENT-ONBOARDING.md` | 진입 가이드·30초 요약·navigation | 5분 |
| 2 | `INDEX.md` | 현 버전·빌드 다운로드·잔존 backlog SSOT | 10분 |
| 3 | `topics/architecture/0001-product-vision.md` | 제품 비전·정체성 (SSOT) | 10분 |
| 4 | `topics/stable-history.md` | 26개 stable seal 흐름 — 프로젝트 진화 타임라인 | 10분 |
| 5 | `USER-GUIDE-v0.1.158.md` | 최신 사용자 가이드 — 단축키·기능·F12 데모 | 10분 |
| 6 | `journal/2026-05-12-autonomous-day-summary.md` | 직전 작업일 종합 (Photosensor·Servo·Emulation·Rotary) | 10분 |
| 7 | `topics/specs/README.md` + 4 spec | 진행 중·예약 모듈 spec | 15분 |

### 1.1 작업 유형별 추가 read 권고

| 작업 유형 | 추가로 읽을 문서 |
|---|---|
| 기획·로드맵 검토 | `topics/architecture/` ADR 22개 (특히 0001 vision / 0006 phase3 / 0011 phase4 / 0014 phase5 scope) · `topics/competitive/` (경쟁 분석) |
| UI·UX 검토 | `topics/ui-design/` (디자인 시스템·토큰 SSOT) · `topics/ui/` |
| 코드·아키텍처 검토 | §3 코드 진입점 표 · `Assets/Scripts/Game/Factory00Bootstrap.cs` · `Assets/Scripts/Events/EventBus.cs` |
| 시행착오·차단 사항 검토 | §4 알려진 차단 / §5 시행착오 |
| 다음 작업 진입 | §6 다음 사이클 계획 (v0.1.162~165) |

---

## 2. 프로젝트 현재 상태 (2026-05-15 기준)

### 2.1 완성된 모듈 (Phase 5/6/7)

- **시뮬레이션 코어** (Phase 5 봉인) — Bootstrap / EventBus / SimulationLoop / Part / Constraint 인스턴스 기반 인접 시뮬레이션
- **Photosensor 직접반사형** (v0.1.143~151, P1~P3 완결)
  - 데이터 모델 + 50ms 폴러 + Inspector 9 위젯 + 와이어프레임 cone 시각화
  - JSON Save/Load + Modbus 코일 sync (SensorPlcBridge)
  - 메이커 프리셋 3종 (OMRON · SICK · Keyence)
- **Servo Axis Actuator** (v0.1.152~155, P1~P3 완결)
  - IActuator 인터페이스 + ServoAxisActuator (Mathf.MoveTowards/SmoothStep · float 리미트)
  - ActuatorDriver 매 프레임 + Inspector 9 위젯 + ActuatorPlcBridge 양방향 (Coil 4종 rising edge + RegPos write)
  - 메이커 프리셋 3종 (Mitsubishi MR-J5 · Yaskawa Sigma-X · Panasonic Minas A6)
- **Interface Emulation Demo** (v0.1.156~158, P1+P2 완결)
  - F12 키 1회 → Photosensor + Servo 자동 부착 + Phase A 어셈블리 → Phase B 실 감지 전진/정지 → Phase C Home 복귀
  - EventBus.OnSensorStateChanged 실 감지 기반 (timer fallback)

### 2.2 진행 중 (v0.1.160~161)

- **Rotary Actuator** (회전 액추에이터)
  - v0.1.160: spec 340라인 (§0~§13)
  - v0.1.161: P1.1 데이터 모델 — RotaryActuatorActuator (~170라인, Quaternion.AngleAxis localRotation, Mathf.DeltaAngle wrap-aware, 0.1° 임계값 publish) + AxisAngleChangedEvent + EventBus.OnAxisAngle

### 2.3 누적 메트릭

| 항목 | 값 |
|---|---|
| 누적 stable seal | 26개 (v0.1.000 ~ v0.1.161) |
| 빌드 zip 누적 | 136개 |
| ADR (architecture) | 22개 (0001~0022 + archive) |
| Spec 문서 | 4개 (photosensor / servo-axis / rotary / interface-emulation) |
| Release notes | 119개 |
| Journal | 21개 (2026-05-10 ~ 2026-05-12) |

---

## 3. 코드베이스 진입점

> **주의**: 코드는 외부 URL에 노출되지 않는다. 본 표는 협업자가 GitHub clone 또는 별도 인수받은 코드 트리에서 확인할 위치 안내용.

GitHub repo: `github.com/ruelveldic/factory00` (private)

| 영역 | 진입 파일 | 비고 |
|---|---|---|
| 메인 부트스트랩 | `Assets/Scripts/Game/Factory00Bootstrap.cs` | ~4250라인 · UI 바인딩 + 시뮬 루프 + 단축키 + 데모 코루틴 |
| 이벤트 버스 | `Assets/Scripts/Events/EventBus.cs` | 인스턴스 기반 pub/sub · Action 이벤트 |
| 이벤트 페이로드 | `Assets/Scripts/Events/AxisEvents.cs` · `SensorEvents.cs` | readonly struct |
| 시뮬레이션 루프 | `Assets/Scripts/Simulation/SimulationLoop.cs` | 매 프레임 driver invocation |
| Part / Constraint | `Assets/Scripts/Sim/Part.cs` · `Constraint.cs` | 인스턴스 기반 인접 |
| Actuator 인터페이스 | `Assets/Scripts/Actuators/IActuator.cs` | ServoAxisActuator / RotaryActuatorActuator 구현 |
| Servo Axis | `Assets/Scripts/Actuators/ServoAxisActuator.cs` · `ServoAxisPresets.cs` | Mathf.MoveTowards + 메이커 프리셋 |
| Rotary Actuator | `Assets/Scripts/Actuators/RotaryActuatorActuator.cs` | Quaternion.AngleAxis · 0.1° 임계값 |
| 액추에이터 드라이버 | `Assets/Scripts/Actuators/ActuatorDriver.cs` | 매 프레임 UpdateActuator 호출 |
| PLC 브릿지 | `Assets/Scripts/PLC/SensorPlcBridge.cs` · `ActuatorPlcBridge.cs` | Modbus 양방향 sync |
| Photosensor | `Assets/Scripts/Sensors/PhotoSensorComponent.cs` · `PhotoSensorVisualizer.cs` | OverlapSphere + cone 시각화 |
| 카메라 컨트롤 | `Assets/Scripts/Camera/CameraViewController.cs` | F1~F4 view callback |
| 빌드 스크립트 | `Assets/Editor/BuildScript.cs` | `executeMethod BuildBatch` |
| URP 셋업 | `Assets/Editor/SetupUrpPipeline.cs` | Always Included Shaders 등록 |
| UXML 메인 | `Assets/UI/MainHUD.uxml` · `TopBar.uxml` | UI Toolkit |
| USS 토큰 | `Assets/UI/Theme/tokens.uss` · `components.uss` · `layout.uss` | 디자인 토큰 SSOT |

### 3.1 핵심 컨벤션

- **단위**: Unity Transform = mm (scaled). 사용자 입력은 m. `Physics.OverlapSphere` 반경 = mm. → 경계마다 ×1000 / ÷1000 변환 의무. 룰: `.claude/rules/unit-mm-conversion.md`
- **Z-up**: 산업용 CAD 컨벤션. Y-up 가정 코드 금지.
- **버전**: SemVer-like `vMAJOR.MINOR.PATCH` (PATCH는 3자리 zero-padding). 사이클당 PATCH +1. 룰: `.claude/rules/version-numbering.md`
- **Commit**: Conventional Commits + scope에 버전 코드 (`fix(v0.1.001): ...`). 룰: `.claude/rules/git-commit-convention.md`
- **이벤트 페이로드 단위**: float 필드는 단위 주석 의무 (`public readonly float Position; // m`)
- **셰이더 fallback**: LineRenderer 등 `Shader.Find` 호출 시 `factory00/OutlineAlwaysOnTop` fallback 의무 (Sprites/Default strip 회피). 룰: `.claude/rules/unity-shader-runtime-fallback.md`

---

## 4. 알려진 차단 사항 (시도 금지)

다음은 이미 여러 차례 검증·확정된 영구 차단 사항. 다시 시도하지 말 것.

### 4.1 헤드리스 마우스 자동화 영구 금지

WSL → schtasks `/it` Session 1 PowerShell 환경에서 Win32 마우스 API (`SetCursorPos` / `mouse_event` / `SendInput` / `PostMessage WM_LBUTTONDOWN`)는 **모두 실효 없음** 확정 (UIPI / Session 격리 보안 정책).

- **금지**: 마우스 click / drag / hover 자동화 시도 일체
- **금지**: AutoIt / NirCmd 등 외부 도구 마우스 시뮬 (동일 권한 환경, 효과 의문)
- **대체**: 모든 주요 UI 동작에 키보드 단축키 매핑 의무 (ESC=⚙ toggle, F11=≡, `/`=검색 focus, F1~F4=카메라 view 등)
- **마우스 click 검증**: 사용자 PC 직접 (Stage 2 fallback)만 가능

룰: `.claude/rules/qa-real-input-only.md` ★ 절

### 4.2 키보드 자동화는 PostMessage WM_KEYDOWN

- `SendInput` 차단 → `PostMessage(hwnd, WM_KEYDOWN, VK, 0)` 우회 PASS
- Unity `Input.GetKeyDown` 폴링 + UI Toolkit `KeyDownEvent` 양쪽 발화
- VK 코드 예: F1=0x70, F2=0x71, F12=0x7B, ESC=0x1B, Tab=0x09

### 4.3 헤드리스 빌드 캡처는 1920×1080 SSOT

- 도구: `Tools/qa/capture-unity-1920.sh` — Unity ScreenCapture API (`UnityEditor.Recorder`가 아닌 런타임 ScreenCapture)
- 1280×720 / 1707×1067 등 다른 해상도 캡처는 deprecated
- PrintWindow API ps1 deprecated (lock screen 충돌 + 비결정적)

룰: `.claude/rules/unity-build-capture-headless.md`

### 4.4 동시 Unity 빌드 lock

`/mnt/c/work/.unity-build.lock` 점유 시 다른 Unity 빌드 차단. IL2CPP 4~6GB 메모리 경쟁 회피.

룰: `.claude/rules/unity-build-coordination.md`

---

## 5. 주요 시행착오 / 회귀 패턴 (재발방지 의무)

| 회귀 패턴 | 증상 | Root Cause | 해결 |
|---|---|---|---|
| 단위 mm/m mismatch | "감지가 안 됨" / "범위가 너무 작음" | m 값을 mm scaled Physics에 직접 전달 | 경계마다 ×1000 변환 (`unit-mm-conversion.md`) |
| LineRenderer 마젠타 폴리곤 | Editor 정상 / Release 빌드 마젠타 | `Sprites/Default` 셰이더 빌드 strip | `factory00/OutlineAlwaysOnTop` fallback (`unity-shader-runtime-fallback.md`) |
| 빌드 후 multi-instance log pollution | Player.log 초기화 메시지 중복 | factory00.exe 잔존 프로세스 + 새 빌드 동시 실행 | autoQA 시작 전 `Stop-Process` 의무 |
| Lit toggle 3분열 | Toggle 외부 sync 시 항상 false | useLitShader / VM / UXML 3중 SSOT | `_litMode` PlayerPrefs 단일 SSOT (v0.1.108) |
| Inspector vec3 drag | 드래그 좌표 환산 깨짐 | UI Toolkit drag delta 좌표계 mismatch | 수동 좌표 변환 (v0.1.099) |
| PostMessage 첫 키만 캐치 | 두 번째 keydown 미발화 | Input.GetKeyDown 폴링 1프레임 race | RegisterCallback path 양쪽 안전망 + frame throttle |
| panel-root 자식 USS class 미적용 | 우하단 AxisIndicator 안 보임 | `uiDocument.rootVisualElement.Add()` 자식 element는 USS class 자동 적용 안 됨 | inline self-style 필수 (v0.1.127) |
| autoQA 종료 안 됨 | factory00.exe 1시간+ 누적 | `Application.Quit` 코드 누락 + 자동 안전망 누락 | 시퀀스 끝 5초 grace + Quit 코루틴 + 빌드 후 Stop-Process |

전체 트러블슈팅 분산 기록: `topics/troubleshooting/`, `journal/` 21개. 통합 KNOWN-ISSUES 문서는 향후 작성 예정.

---

## 6. 다음 작업 계획

### 6.1 Rotary Actuator P1.2~P3 (4 사이클 예약)

| 사이클 | 단계 | 분량 | 핵심 |
|---|---|---|---|
| v0.1.162 | P1.2 | ~80라인 | ActuatorDriver Rotary 등록 + Bootstrap LoadProject 복원 |
| v0.1.163 | P1.3 | ~250라인 | Inspector RenderRotaryActuatorBlock + 프리셋 드롭다운 |
| v0.1.164 | P2 | ~80라인 | RotaryActuatorPlcBridge — 양방향 Modbus sync (deg×10 wrap) |
| v0.1.165 | P3 | ~80라인 | RotaryActuatorPresets — Mitsubishi MR-J5 / Yaskawa SGM7J / Panasonic Minas A6 |

spec: `topics/specs/2026-05-12-actuator-rotary.md` §9 분할 계획

### 6.2 새 모듈 spec 후보 (P2 예약)

- 관통형 photosensor (through-beam)
- 근접 센서 (proximity / inductive)
- 초음파 센서 (ultrasonic distance)

spec README: `topics/specs/README.md` P2 섹션

### 6.3 영속 backlog

- **InspectorVM / MotorTableVM 분리** (task #39 deferred) — Bootstrap 슬림화. PartTypeRegistry / SimulationLoop refactor 시점에 자연 분리
- **ForceLayoutStyles Tier 1 USS 이전** (~100라인) — `journal/2026-05-11-v0.1.114-force-layout-backlog.md`
- **wiki/downloads/ zip 보존 정책** — 136개 누적, 정리 기준 결정 필요

### 6.4 PLC 통합

- 미츠비시 MX Component SDK 도착 대기 (협업자 측)
- 도착 시 첫 통합 spec 작성 (RegisterMap / Coil 매핑 / Lifecycle)
- MES/PLC 자동 생성은 **하지 않음** (CodeFlex / TwinWorks 경쟁 회피)

---

## 7. 빌드·실행·캡처 통합 절차

### 7.1 빌드 (Windows standalone)

```bash
# WSL bash
UNITY="/mnt/c/Program Files/Unity/Hub/Editor/6000.0.73f1/Editor/Unity.exe"
"$UNITY" -batchmode -quit -nographics \
  -projectPath "C:/work/factory00" \
  -executeMethod BuildScript.BuildBatch \
  -logFile "C:/work/factory00/Builds/build-v0.1.NNN.log"
```

- Unity 6 (`6000.0.73f1`)
- 단일 zip 산출: `factory00/Builds/Windows/factory00.exe` + `factory00_Data/`
- IL2CPP 4~6GB 메모리. 동시 Unity 빌드 lock 의무

### 7.2 실행 (헤드리스)

Parsec VDD 가상 디스플레이 + `schtasks /it` Session 1:

```bash
powershell.exe -Command "schtasks /create /tn 'factory00_run' \
  /tr 'C:\\work\\factory00\\Builds\\Windows\\factory00.exe -screen-fullscreen 0 -screen-width 1920 -screen-height 1080' \
  /sc once /st 23:59 /it /f"
powershell.exe -Command "schtasks /run /tn 'factory00_run'"
```

### 7.3 캡처

```bash
bash /mnt/c/work/factory00/Tools/qa/capture-unity-1920.sh \
  --output /mnt/c/work/factory00/wiki/qa-screenshots/latest/<step>.png
```

### 7.4 사이클 종료 + 외부 게시

```bash
bash /mnt/c/work/factory00/wiki/publish-cycle.sh v0.1.NNN <slug>
```

자동: zip 생성 + qa-screenshots wiki 복사 + INDEX/latest-builds.html 갱신 + 외부 URL HTTP 200 검증 + factory00.exe Stop-Process

---

## 8. 외부 공개 톤 정책

이 wiki는 협업 파트너에게 노출되므로 다음 톤 정책을 준수한다.

- ✅ 허용: "Founding Team" / "Lean Team" / "Engineering Lead" / "BD Lead" / "협업자" (특정 역할)
- ❌ 금지: "솔로 개발" / "1인 개발" / 인원 수 명시
- ✅ 허용: ADR / 시행착오 / 알려진 차단 사항의 솔직 기록 (기술 신뢰)
- ❌ 금지: 부서 분리("Engineering Department" 등) 다수 인원 연상 표현

룰: `.claude/rules/external-deliverable-tone.md`

---

## 9. 협업 워크플로

### 9.1 외부 AI 에이전트 (Codex Pro / Claude 등)

| 단계 | 작업 | 비고 |
|---|---|---|
| 1 | 본 문서 + INDEX.md + USER-GUIDE 최신 read | 30분 |
| 2 | ADR + stable-history + journal 최근 5건 read | 1시간 |
| 3 | 작업 유형 결정 (기획 / 문서 / 검토 / spec drafting) | — |
| 4 | 산출물 작성 (md / spec / 검토 보고) | 코드 직접 수정은 권한·환경상 제한 |
| 5 | 협업자에게 산출물 전달 → 코드 반영 협의 | — |

### 9.2 사용자 (PC 보유 메인 개발)

- WSL bash + Claude Code Opus 4.7
- 빌드·캡처·자동화 일괄 수행
- stable seal 결정·외부 URL 게시·git push

### 9.3 협업자 (BD / GTM)

- 미츠비시 MX Component SDK 도착 후 첫 PLC 통합 협업
- 사업 미팅 자료 / 협업자 자료 작성 시 본 wiki의 외부 톤 정책 준수

---

## 10. 빠른 링크

| 카테고리 | 링크 |
|---|---|
| 메인 진입 | [`INDEX.md`](INDEX.md) · [`index.html`](index.html) |
| 빌드 다운로드 + 스크린샷 | [`latest-builds.html`](latest-builds.html) — 사이클별 SSOT (v0.1.193 build-downloads.html 통합) |
| 사용자 가이드 (최신) | [`USER-GUIDE-v0.1.158.md`](USER-GUIDE-v0.1.158.md) |
| 안정화 봉인 흐름 | [`topics/stable-history.md`](topics/stable-history.md) |
| 아키텍처 ADR | [`topics/architecture/`](topics/architecture/) |
| Spec | [`topics/specs/README.md`](topics/specs/README.md) |
| UI 디자인 | [`topics/ui-design/`](topics/ui-design/) · [`topics/ui/`](topics/ui/) |
| 경쟁 분석 | [`topics/competitive/`](topics/competitive/) |
| QA | [`topics/qa/`](topics/qa/) |
| 트러블슈팅 | [`topics/troubleshooting/`](topics/troubleshooting/) |
| 릴리스 노트 | [`topics/release-notes/`](topics/release-notes/) |
| Journal | [`journal/`](journal/) |
| 데모 | [`topics/demo/`](topics/demo/) |

---

## 11. 본 문서 갱신 정책

- 신규 stable seal 봉인 시 §0 / §2 / §6 갱신
- 새 영구 차단 사항 발견 시 §4 갱신
- 새 시행착오·회귀 패턴 발견 시 §5 갱신
- 외부 URL 도메인 변경 시 §0 갱신
- 새 모듈 spec 진입 시 §6.2 갱신

본 문서는 외부 AI 에이전트의 첫 진입 SSOT. 갱신 누락 시 협업자가 outdated 정보로 작업 진입 → 비용 폭발.

---

**문의 / 협업**: 본 wiki 외부 URL (`https://os-file-server.tail2b816d.ts.net/`)을 통해 모든 산출물 접근 가능. 코드 트리 인수는 사용자 측 별도 진행.