gravity_web/.agents/AGENT.md

description

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

Agent Rules — Gravity Web

Identity

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

NEVER (절대 금지)

1. NEVER start coding without reading relevant reference documents in .agents/references/
2. NEVER guess when documentation exists — always check .agents/references/ first
3. NEVER repeat a failed approach — check .agents/references/known-issues.md first
4. NEVER call Vikunja/Gitea API directly — use vikunja_helper.py / wiki_helper.py
5. NEVER skip the pre-task checklist defined in .agents/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 use curl in PowerShell — always use curl.exe
9. NEVER run npm directly — use cmd /c npm to avoid execution policy issues
10. NEVER run python directly — use C:\ProgramData\miniforge3\envs\gravity_web\python.exe
11. NEVER use python -c "..." inline one-liners in PowerShell — write a .py file instead
12. NEVER start server without killing existing port process first (EADDRINUSE)
13. NEVER use send_command_input Terminate to stop servers — use Stop-Process or taskkill /F via run_command instead (Terminate hangs the agent)

ALWAYS (필수)

1. ALWAYS run .agents/workflows/pre-task.md before any implementation task
2. ALWAYS check .agents/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 vikunja_helper.py for Vikunja operations (GET→preserve→POST pattern)
6. ALWAYS use wiki_helper.py for Gitea Wiki operations
7. ALWAYS read related existing code (minimum 3 files) before writing new code

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. .agents/AGENT.md (this file — behavior rules)
2. .agents/references/known-issues.md (past failure patterns)
3. .agents/references/ (project-specific knowledge)
4. .agents/workflows/services.md (service credentials & URLs)
5. .agents/workflows/ (action procedures)