# AGENT.md — 에이전트 운영 수칙 (Vignette)

이 저장소에서 자동화 에이전트/서브에이전트가 일할 때의 운영 수칙. 상세 프로젝트
지침은 [`CLAUDE.md`](./CLAUDE.md) 참조.

**작업 전 관련 가이드를 먼저 읽어라**: [`README.md`](./README.md) ·
[로컬 실행](./docs/guides/local-development.md) · [아키텍처](./docs/guides/architecture.md) ·
[테스트](./docs/guides/testing.md) · [원천문서·갭](./docs/guides/source-docs-and-gaps.md) ·
SSOT [`docs/dev_dashboard.html`](./docs/dev_dashboard.html). 동작/구조 변경 시 해당 문서와 SSOT를 갱신.

---

## ⚠️ 규칙 0 — 무조건 OS를 먼저 파악한다 (필수, 최우선)

**모든 작업의 첫 단계는 OS·셸·경로·도구 환경 확정이다.** 명령을 한 줄이라도
실행하기 전에 다음을 확인하라. 생략하면 환경 차이로 반드시 시간을 버린다.

- [ ] **OS / 셸 확인** — 주 환경은 **Windows 11 + PowerShell**. POSIX 가정 금지.
- [ ] **경로 규칙** — Windows 절대경로, 한글·공백 경로 빈번. `-LiteralPath` 사용,
      외부 도구엔 **ASCII 이름으로 로컬 복사 후** 전달.
- [ ] **PowerShell 5.1 함정** — 인라인 if/else·삼항 없음, 네이티브 stderr `2>&1` 금지,
      파일 출력은 `-Encoding utf8`.
- [ ] **외부 CLI 블로킹 검증** — GUI 런처는 즉시 detach. 실제 작업 바이너리
      (예: `soffice.bin`)를 직접 호출하고 `-Wait` 동작을 확인. 좀비/락 먼저 정리.
- [ ] **도구 가용성 탐지 우선** — 변환·처리 전 LibreOffice/pandoc/python lib/
      Playwright 브라우저 설치 여부와 경로를 먼저 잡는다.

> **"OS·셸·경로·도구를 확정한 뒤에 실행한다. 추정으로 시작하지 않는다."**

---

## 규칙 1 — 증거 정직성

- 가짜 증거로 DONE 표기 금지. 실증 불가/외부 의존/소유자 결정 항목은
  `docs/ops/backlog-*.md`에 분류·추적.
- 변경 후 검증(typecheck / E2E 게이트)을 실제로 돌리고 결과를 그대로 보고.

## 규칙 2 — 범위·권한

- 소유자(윤찬) 단독 결정 사안은 임의 결정 금지.
- 전 페이지 공용 셸 변경 등 광범위 영향 작업은 회귀 검증을 동반.

## 규칙 3 — 출력

- 한글로 소통. 커밋 메시지에 Claude/Co-Authored-By 문구 금지.

## 규칙 4 — 이미지 생성 / 아바타 리깅

- "이미지 생성·만들어·그려줘" 요청 → `~/.claude/skills/codex-image` 스킬 사용.
  gpt-image-2 래퍼 `~/.codex/imagegen-headless/codex_imagegen.sh`(ChatGPT 구독 인증, **API 키 금지**).
  codex 0.140+는 결과가 rollout JSONL에 base64로 인라인 → 래퍼의 추출 스크립트만 결정적(직접 `codex exec` 금지).
- 누끼: `object-separation` 스킬(BiRefNet, `~/.venvs/object-separation`).
- 아바타 래스터 리깅(파츠 분리) 파이프라인·재현 절차는 **CLAUDE.md §4** 와
  [`docs/ops/handoff-avatar-seoyeon-2026-06-27.md`](./docs/ops/handoff-avatar-seoyeon-2026-06-27.md) 참조.
- 비전(analyze_image) 도구가 다중 패널/캐릭터를 자주 혼동 → 시각 판단은 **사용자 확인 + 스크린샷** 우선.