unityctl CLAUDE.md

unityctl 프로젝트 인덱스

unityctl 작업 시작 시 가장 먼저 읽는 진입 문서입니다. 이 문서만 읽어도 현재 단계, 규칙, 다음 행동을 빠르게 파악할 수 있게 유지합니다.

저장소 경계

• Write Repo: . (저장소 루트 — clone 위치 무관)

시작 순서 (필수)

1. AGENTS.md (Codex) 또는 CLAUDE.md (Claude) — 동일 정책 진입 문서
2. docs/ref/architecture-mermaid.md
3. docs/status/PROJECT-STATUS.md
4. docs/ref/phase-roadmap.md
5. docs/ref/code-patterns.md (코드 작성 전 필수)

현재 상태 (2026-03-20)

• Phase 0~1B: Done
• Phase 1C (CI/CD): Done
• Phase 2A/2A+: Done (Foundation + Tools Metadata)
• Phase 2B (IPC Transport): Done
• Phase 2C (Async Commands): Done
• Phase 3B (Flight Recorder): Done
• Phase 3A (Session Layer): Done
• Phase 4A (Ghost Mode): Done
• Phase 3C (Watch Mode): Done
• Phase 4B (Scene Diff): Done
• Phase 5 (Agent Layer): Done
• Write API Phase A (PlayMode, PlayerSettings, AssetRefresh): Done
• Write API Phase B (GameObject CRUD, Scene Save): Done
• Write API Phase B.5 (Component CRUD): Done
• MCP Hybrid (unityctl_run + schema filter): Done
• Write API 확장 (Scene open/create, Undo/Redo, Phase C): Done
• Script Editing v1 (create/edit/delete/validate): Done
• Diagnostics (doctor + IPC 실패 자동 진단): Done
• P0 (Read API): Done (asset find/get-info/get-dependencies/reference-graph/get-labels/set-labels, gameobject find/get, component get, scene hierarchy, build-settings get-scenes/set-scenes)
• P3 (Screenshot/Visual Feedback): Done
• Tags & Layers + Editor Utility (tag/layer/console/define-symbols 10개 명령): Done
• Lighting & NavMesh (lighting bake/cancel/clear/get-settings/set-settings, navmesh bake/clear/get-settings 8개 명령): Done
• Physics Settings (physics get-settings/set-settings/get-collision-matrix/set-collision-matrix 4개 명령): Done
• Editor Utility 확장 (editor pause/focus-gameview/focus-sceneview 3개 명령): Done
• Script List (script list 1개 명령): Done
• MCP Context Optimization (C1 QueryTool + C2 Schema Category + C3 Description 경량화): Done (33→12 MCP 도구)
• Script Patch v2 (script patch — 줄 단위 삽입/삭제/교체): Done
• Script v2 (script-get-errors, script-find-refs, script-rename-symbol): Done
• UI Read Slice 1 (ui find, ui get, UGUI-first): Done
• UI Interaction Slice 1 (ui toggle, ui input, deterministic state set): Done
• Project Validate (project validate — 게임 준비 상태 검증): Done
• Mesh Create Primitive (mesh create-primitive — 기본 3D 도형 생성): Done
• Multi-Instance Routing Phase 1 (editor current/select + project-path selection fallback + target metadata): Done
• Production Domain Expansion (camera list/get, texture get/set-import-settings, scriptableobject find/get/set-property, shader find/get-properties — 9개 명령): Done
• Visual Verification v2 Phase 1 (workflow verify + artifact-first verification bundle): Done
• Visual Verification v2 Phase 1.5 (playSmoke + game-camera capture after settle): Done
• Phase G: Asset Import/Export Extension (asset-export, model-get-import-settings, audio-get-import-settings — 3개 명령): Done
• Phase H: Animation Workflow Extension (animation-list-clips/get-clip/get-controller/add-curve — 4개 명령): Done
• Phase C: Profiler Commands (profiler-get-stats/start/stop — 3개 명령): Done
• Phase I-1: UGUI Enhancement (ui-scroll/slider-set/dropdown-set — 3개 명령): Done
• Phase D: Volume/PostProcessing (volume-list/get/set-override/get-overrides, renderer-feature-list — 5개 명령, Reflection capability gating): Done
• Phase E: Cinemachine (cinemachine-list/get/set-property — 3개 명령, 2.x/3.x 런타임 감지): Done
• Phase I-2: UI Toolkit (uitk-find/get/set-value — 3개 명령, runtime UIDocument 체크): Done
• MCP Prompts (create_game_scene/debug_game/iterate_gameplay/setup_project — AI 워크플로우 가이드 4개): Done
• CLI Feedback Fixes (CLI-012 prefab instantiate, CLI-014 asset copy 외부 경로, CLI-000 IPC 30초 메시지 타임아웃): Done
• Token Optimization (status state 구분, hierarchy summary/maxDepth, component get summary, console get-entries dedupe): Done
• CLI Enhancement (profiler rendering stats, component add --name, component enable/disable, profiler --detailed): Done
• Exec Security Relaxation (BlockedPatterns-only, project code allowed): Done
• IPC Reload Resilience (heartbeat state 파일 + 클라이언트 reload-aware 재시도 + batch 폴백 억제): Done
• Type Introspection (type describe — 라이브 타입 리플렉션 + Unity Manual 링크, summary-by-default): Done
• IPC Reload Staleness Fix (reloading 상태를 15초가 아닌 리로드 예산 90초까지 신뢰 → 긴 도메인 리로드 중 IPC 드롭 방지) + asset-copy 목적지 프로젝트-루트 가드: Done
• Spatial Grounding (spatial describe/spatial check covers|inside|on-top-of|overlaps|aligned — 월드 AABB·true dimensions·표면 법선·술어 판정을 텍스트로. 스크린샷 없이 씬을 "측정된 공간 사실"로): Done (.NET 표면·핸들러 authored, Unity 컴파일은 에디터에서 확인)
• 공식 CLI 벤치마크 + 흡수 사다리 (unattended lifecycle fix, exec eval, 리졸버/속성명 통일, runtime status/logs): Done (전 항목 라이브 검증)
• v0.6.1 Reliability Patch (component get --full hidden serialized state, macOS process inventory, MCP Registry metadata sync): Done (Unity 6000.3.16f1 라이브 검증)
• v0.6.2 Distribution/Linux Patch (Claude Code/Codex workflow skill, NuGet README, Linux /proc process inventory): Done (Linux container /proc probe 검증)
• v0.6.3 IPC/Validation Hardening (listener shutdown race + bounded ping readiness probe + validation failure semantics): Done (Unity labs + 3-OS CI, Windows #12/#13 reporter 재검증 대기)
• Local Code Intelligence Slice (script find-refs Core local scanner, Editor/IPC 불필요): Done (closed-project 4.34s→0.21s, 20.7x)
• Distribution Ladder P1~P5 (README hero GIF, 저장소 메타, self-contained single-file 릴리스, mcp install + Unity 상태창, README 603→199줄): Done (Unity 6000.3.16f1 batchmode 컴파일 검증, 4 RID publish 재현)