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

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

작업 전 관련 가이드를 먼저 읽어라: README.md · 로컬 실행 · 아키텍처 · 테스트 · 원천문서·갭 · SSOT 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·셸·경로·도구를 확정한 뒤에 실행한다. 추정으로 시작하지 않는다."

시작 시 필요하면 $ErrorActionPreference='Stop', [Console]::OutputEncoding=[System.Text.UTF8Encoding]::new($false), $OutputEncoding=[System.Text.UTF8Encoding]::new($false)를 먼저 둔다.
PowerShell 7/Bash 문법 금지: ? :, ??, &&, ||, ForEach-Object -Parallel, heredoc(<<EOF), FOO=bar command. 명시적 if/else, $env:FOO='bar'를 쓴다.
제어문은 파이프라인 값이 아니다. foreach { } | ... 대신 & { foreach (...) { ... } } | ... 형태로 감싼다.
경로는 -LiteralPath/Resolve-Path -LiteralPath/Join-Path로 처리한다. 한글·공백 경로는 외부 CLI 전달 전 ASCII 임시 경로 복사를 우선 검토한다.
Windows PowerShell 5.1의 -Encoding UTF8은 BOM을 쓴다. UTF-8 no BOM이 필요하면 [IO.File]::WriteAllText($path,$text,[Text.UTF8Encoding]::new($false))를 쓴다.
네이티브 exe는 문자열 조립 대신 & $exe @args로 호출하고 $LASTEXITCODE를 확인한다. stderr를 2>&1로 합치지 말고 필요하면 stdout/stderr를 분리 캡처한다.
JSON API는 Invoke-RestMethod/Invoke-WebRequest를 우선 사용한다. 진짜 curl은 curl.exe로 호출한다.
인라인 Python/Node가 BOM/인용 문제를 내면 python -c, UTF-8 no BOM 임시 파일, base64 전달을 사용한다. Python은 필요 시 PYTHONUTF8=1, python -X utf8.
Start-Process는 필요할 때만 쓰고 -Wait -PassThru로 ExitCode와 산출물을 검증한다. GUI 런처 detach 여부를 별도로 확인한다.

"이미지 생성·만들어·그려줘" 요청 → ~/.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 참조.
비전(analyze_image) 도구가 다중 패널/캐릭터를 자주 혼동 → 시각 판단은 사용자 확인 + 스크린샷 우선.