77 lines
4.7 KiB
Markdown
77 lines
4.7 KiB
Markdown
# 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·셸·경로·도구를 확정한 뒤에 실행한다. 추정으로 시작하지 않는다."**
|
|
|
|
### PowerShell 5.1 기본 실행 규칙
|
|
|
|
- 시작 시 필요하면 `$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 여부를 별도로 확인한다.
|
|
|
|
---
|
|
|
|
## 규칙 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) 도구가 다중 패널/캐릭터를 자주 혼동 → 시각 판단은 **사용자 확인 + 스크린샷** 우선.
|