# AGENTS.md — RoomfitV2

## Architecture Guard

모든 에이전트는 코드 작성 시 아래 규칙을 반드시 준수한다.

### 절대 규칙

1. **presentation/ → core/ 직접 import 금지**
   - presentation은 domain/providers/만 import
   - core 타입이 필요하면 domain에서 `export`로 re-export
   - 유일한 예외: `core/logger/log_viewer_screen.dart` (공유 UI)

2. **core/ → features/ import 금지**
   - core는 features를 모른다

3. **새 기능 = domain facade 먼저**
   - presentation 코드를 쓰기 전에 domain/providers/에 facade provider를 먼저 만든다
   - "일단 되게 하고 나중에 분리" 금지

4. **TDD 필수**
   - Red → Green → Refactor
   - 테스트 없는 코드 커밋 금지

5. **커밋 분리**
   - structural (구조) 커밋과 behavioral (동작) 커밋을 절대 섞지 않는다

6. **네이밍 규칙 준수**
   - Commands: `{Verb}{Target}Command` (Get/Set/Start/Stop/Reset/Adjust/Force)
   - Responses: `{Target}Response`
   - Command와 Response는 같은 Target 명사를 공유

### 프로토콜 데이터 규칙 (CRITICAL)

7. **ReportResponse는 dev 36B 포맷 기준으로 유지**
   - MCU 기본은 v3(12B)이지만, 앱은 `0xF5 0x20`으로 dev report 활성화
   - v3(12B)가 오면 graceful fallback (나머지 0)
   - **절대 v3 전용으로 축소하지 말 것** — 속도/가속도/전류/모드 데이터 누락됨
   - v3의 `[6-7]` loadL은 `fLoadLRaw`에 매핑됨, speedL이 아님

8. **물리 단위 변환은 PhysicalUnits에만 존재**
   - 하드코딩된 상수 금지, PhysicalUnits 헬퍼 사용
   - 새 단위 추가 시 PhysicalUnits에 상수 + 헬퍼 추가

### 검증 명령어

```bash
# 아키텍처 위반 체크 (0건이어야 함)
grep -r "import.*core/" lib/features/*/presentation/ | grep -v "log_viewer_screen"
grep -r "import.*features/" lib/core/

# 전체 테스트
flutter test && dart test packages/roomfit_protocol/

# 정적 분석
flutter analyze
```

### 에이전트별 지침

| 에이전트 | 역할 | 주의사항 |
|---------|------|---------|
| Explore | 코드베이스 탐색 | 아키텍처 위반 발견 시 즉시 보고 |
| Refactor | 리팩토링 | structural/behavioral 커밋 분리. 네이밍 규칙 준수 |
| Debug | 디버깅 | AppLogger 사용. print() 금지 |
| Orchestrator | 병렬 작업 | 각 서브태스크도 아키텍처 규칙 적용 |