---
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)
