dear-agent AGENTS.md

<워크스페이스> 작업 지침

📋 이 파일은 '워크스페이스 양식'의 일부다. 이 폴더를 새 워크스페이스로 만들라는 요청을 받거나 <...> placeholder가 남아 있으면, 다른 작업을 시작하기 전에 먼저 USAGE.md의 1~8단계를 순서대로 수행한다. (요약: _example/·스크래치 정리 → README 교체 → 이름·소개 placeholder 채우기 → 이 📋 안내 줄 삭제 → 분류 폴더 만들고 _templates/ 복사로 잎 생성 → 생성기 실행 → 확인 후 USAGE.md 삭제.) 구축이 끝나면 이 안내 줄을 지운다.

에이전트 운영 가이드. 문서 체계의 단일 기준은 CONVENTIONS.md.

문서 규약 (항상 적용)

프로젝트 작업은 CONVENTIONS.md를 따른다. 핵심 트리거-동작:

• 코드 수정·기능 추가 작업은, 응답을 끝내기 전에 해당 프로젝트의 HANDOFF.md(frontmatter 포함)를 갱신하고 마친다.
• 폴더 구조가 바뀌면 누락 MD를 만들고(_templates/ 복사), 상위 _INDEX.md와 루트 OVERVIEW.md를 build-index.ps1(PowerShell 없으면 python3 build-index.py) 실행으로 재생성한다(HANDOFF frontmatter 스캔, 컨테이너 자동 탐색).
• 새 프로젝트 폴더엔 _templates/에서 PLAN·HANDOFF·CLAUDE를 먼저 만든다.
• _INDEX.md·OVERVIEW.md는 생성물 — 직접 편집 금지.
• 이 규약은 3중으로 강제된다: 이 CLAUDE.md(상시 컨텍스트) · dear-agent 스킬(작업 시작·종료·구조 변경 절차) · .claude/settings.json 훅(SessionStart 브리핑 주입 + Stop의 HANDOFF 미갱신 차단). 세션 종료 절차는 /handoff로도 호출할 수 있다.

참고 자산 (선택)

워크스페이스 공유 스킬·프롬프트·가이드가 있으면 docs/에 두고 여기 기술. 없으면 이 섹션 삭제.

서브에이전트·병렬 작업 (모든 AI 도구 공통)

작업을 안전하게 독립적인 하위 작업으로 나눌 수 있고 병렬화가 속도·품질·검증 신뢰도를 실질적으로 높인다고 판단되면, 에이전트는 사용자에게 별도로 요청·승인받지 않고 스스로 서브에이전트(subagents)·병렬 에이전트(parallel agent work)·작업 위임(delegation)을 사용한다. 단순·강하게 순차적·긴밀히 결합된 작업이나 병렬화 비용이 이득보다 큰 작업은 단일 에이전트로 진행한다. 사용 여부·분할 방식·에이전트 수는 주 에이전트가 작업 성격에 맞게 판단하고, 위임하는 각 작업은 구체적·독립적 범위로 좁힌다. 주 에이전트가 결과 통합·충돌 확인·최종 검증·사용자 보고를 책임진다. 멀티에이전트를 쓴다고 기존 승인·안전·파괴적 작업·commit/push 규칙이 확장·완화되지 않는다 — 각 서브에이전트에도 그대로 적용된다. 기능이 없거나 병렬화가 부적절하면 단일 에이전트로 계속하며, 멀티에이전트를 쓴다는 이유만으로 사전 승인을 다시 묻지 않는다.

세션 절차 (모든 AI 도구 공통)

Claude Code에서는 훅이 이 절차를 자동 보조하지만, Codex 등 다른 도구에서는 이 텍스트가 규칙의 전부다.

• 시작: HANDOFF.md를 먼저 읽는다 — 마지막 작업 / 다음 할 일 / 막힌 것.
• 종료 (코드·기능을 수정했다면 필수): HANDOFF.md를 갱신한다 — 본문(마지막 작업/다음 할 일/막힌 것)과 frontmatter(status · updated YYYY-MM-DD · summary 한 줄). 굵직한 변경(기능 완성·버그 수정·버전업)은 LOG.md에 한 줄 추가.
• commit/push는 명시 요청 시에만. push는 의미 단위로 묶는다.
• 커밋 히스토리가 도구 간 공유 맥락이다 — 커밋 메시지를 성실히 쓴다.