# .agent-rules.md — Agent 가드레일 (50% 룰 + 패턴 통일 + 로그 포맷)

> 이 파일은 CLAUDE.md의 보충 자산입니다. 50% 룰 적발(같은 일을 하는 경쟁 패턴)을 명문화해
> Agent의 variance를 줄이고, 어떤 패턴을 사용할지 결정적으로 만듭니다.

마지막 업데이트: YYYY-MM-DD

---

## 1. 패턴 통일 (50% 룰 적발)

> 같은 일을 하는 두 가지 이상의 방법이 코드베이스에 공존하면, agent가 50% 확률로 잘못된 쪽을 선택합니다.

### Rule 1 — HTTP 클라이언트
- ✅ 사용: `lib/http.ts`의 fetch 래퍼 (`httpGet`, `httpPost`)
- 🚫 DEPRECATED: `axios` 직접 import, 원시 `fetch()` 호출
- 위치: `src/lib/http.ts`
- 마이그레이션: `axios` 사용처는 PR로 점진 교체

### Rule 2 — 에러 처리
- ✅ 사용: `lib/errors.ts`의 `AppError` 클래스 + catch 시 `logger.error`
- 🚫 DEPRECATED: `console.log` / `throw new Error(string)`
- 예외: `tests/` 디렉토리는 `console.log` OK

### Rule 3 — DB 쿼리
- ✅ 사용: `lib/db/queries/` 의 정의된 함수만
- 🚫 DEPRECATED: 라우트 핸들러에서 `prisma.X` 직접 호출
- 새 쿼리는 `queries/` 디렉토리에 추가

> 본인 repo에 맞춰 위 3개를 교체하세요. 3~5개가 적정 — 너무 많으면 안 지켜지고, 너무 적으면 효과 ↓.

---

## 2. 에이전트별 가드레일 (Pillar IV)

### Sub-agent로 위임 OK
- 코드베이스 탐색 (Explore agent) — 큰 출력 흡수
- 독립 리뷰 — PR diff에 대한 객관적 평가
- 마이그레이션 같은 반복 작업 — 작은 패턴 전환을 N개 파일에 적용

### Sub-agent로 위임 NO
- DB 마이그레이션 작성 — 메인 컨텍스트에서 사람이 검토
- 결제·인증 변경 — 메인 컨텍스트에서 Plan Mode 필수
- 의존성 추가 — `package.json` deny list 확인 필요

---

## 3. 구조화 로그 포맷 (Pillar IV — Agent self-correction 입력)

> JSON line. 한 줄당 한 이벤트. jq로 필터 가능.

```json
{"ts":"2026-05-19T14:30:00.000Z","module":"auth","level":"info","event":"session_create","userId":"u_123","ttl":3600}
{"ts":"2026-05-19T14:30:01.000Z","module":"payment","level":"error","event":"charge_failed","userId":"u_123","reason":"insufficient_funds"}
```

**필수 필드**: `ts`, `module`, `level`, `event`
**선택 필드**: `userId`, `requestId`, 도메인별 컨텍스트

**Agent 자기검증 흐름**:
```bash
# 변경 후 자동으로 호출 가능
tail -n 100 .logs/dev.log | jq 'select(.level=="error")'
```
→ 결과가 비면 ✅, 아니면 메시지를 읽고 자기수정.

---

## 4. 컨벤션 (Consistency over DRY — Pillar IV)

> Agent에게는 반복이 추상화보다 저렴합니다.

- 새 API 라우트 추가 시: `src/app/api/<route>/route.ts` — 다른 라우트의 코드를 **복사 후 수정**, 새 추상화 만들지 말 것
- 새 React 컴포넌트: `src/components/<Name>.tsx` + `<Name>.test.tsx` 쌍
- 새 도메인 모듈: `src/lib/<area>/index.ts` + `<area>.test.ts`

---

## 5. 변경 이력 (선택)

- YYYY-MM-DD: 초기 작성
- YYYY-MM-DD: HTTP 클라이언트 통일 룰 추가
- ...