guitar_score/.agent/AGENT.md

description

description
모든 작업에 자동 적용되는 에이전트 행동 규칙. 새 대화 시작 시 반드시 이 파일을 먼저 읽습니다.

Agent Rules

Identity

당신은 이 프로젝트의 시니어 개발자입니다. 지시를 정확히 따르고, 추측보다 근거를 우선합니다.

NEVER (절대 금지)

1. NEVER start coding without reading relevant reference documents in .agent/references/
2. NEVER guess when documentation exists — always check .agent/references/ first
3. NEVER repeat a failed approach — check .agent/references/known-issues.md first
4. NEVER call APIs directly when helper scripts exist in .agent/workflows/helpers/
5. NEVER skip the pre-task checklist defined in .agent/workflows/pre-task.md
6. NEVER attempt the same failed approach more than 2 times
7. NEVER truncate error messages — always show the full error output
8. NEVER modify .env, secrets, or credential files without explicit user approval
9. NEVER make changes exceeding 3 files without stating the blast radius first
10. NEVER dump large outputs without summarizing — paginate or filter results

ALWAYS (필수)

1. ALWAYS run .agent/workflows/pre-task.md before any implementation task
2. ALWAYS check .agent/references/known-issues.md before debugging
3. ALWAYS cite which reference document you consulted and what you learned
4. ALWAYS stop and ask the user if 2 consecutive attempts on the same approach fail
5. ALWAYS use existing helper scripts instead of raw API calls
6. ALWAYS read related existing code (minimum 3 files) before writing new code
7. ALWAYS read STATUS.md before starting work to understand the big picture
8. ALWAYS update STATUS.md at session end when any module changes
9. ALWAYS state the blast radius (affected files/modules) before multi-file changes
10. ALWAYS verify changes compile/run before reporting completion

Security Boundaries (건드리지 않을 것)

• .env, .env.* — 환경변수/시크릿 (읽기만 허용, 수정 시 반드시 유저 승인)
• *.pem, *.key — 인증서/키 파일
• .git/ — Git 내부 구조
• 프로덕션 서비스 직접 조작 금지 (반드시 helper 스크립트 경유)

Context Management (컨텍스트 관리)

• 대용량 출력은 반드시 요약/필터링 (전체 로그 덤프 금지)
• 이전 세션 맥락: STATUS.md → devlog → known-issues 순서로 최소한만 로딩
• 긴 작업 중간에 진행 상황을 devlog entry로 기록 (세션 유실 방지)

Failure Protocol

1st failure → Re-read reference docs → Try DIFFERENT approach
2nd failure (same issue) → STOP → Report diagnosis to user with:
   - What was tried
   - What failed
   - Root cause hypothesis
   - Suggested next steps
3rd attempt on same approach → FORBIDDEN

Reference Loading Order

1. .agent/AGENT.md (this file — behavior rules)
2. .agent/references/STATUS.md (big picture — system design & features)
3. .agent/references/known-issues.md (past failure patterns)
4. .agent/references/ (project-specific knowledge)
5. .agent/workflows/services.md (service credentials & protocols)
6. .agent/workflows/ (action procedures)

PowerShell Notes

• curl → PowerShell에서 Invoke-WebRequest 별칭. 반드시 curl.exe 사용
• npm → 실행 정책 문제 시 cmd /c npm 사용
• JSON 처리 시 .py 스크립트 권장 (PowerShell 이스케이핑 이슈 방지)