refactor: sync .agents/ with agent_guide template (helpers/ subdir, devlog, pre-task, debug, references)

.agents/workflows/check-gitea.md

@@ -26,15 +26,15 @@ $issues | ForEach-Object { Write-Host "#$($_.number) $($_.title)" }
 
 3. Wiki 페이지 목록:
 ```powershell
-python .agents\workflows\wiki_helper.py list
+python .agents\workflows\helpers\wiki_helper.py list
 ```
 
 4. Wiki 페이지 읽기:
 ```powershell
-python .agents\workflows\wiki_helper.py read "Architecture"
+python .agents\workflows\helpers\wiki_helper.py read "Architecture"
 ```
 
 5. Wiki 페이지 업데이트:
 ```powershell
-python .agents\workflows\wiki_helper.py update "페이지-제목" /tmp/wiki_content.md
+python .agents\workflows\helpers\wiki_helper.py update "페이지-제목" /tmp/wiki_content.md
 ```

.agents/workflows/check-vikunja.md

@@ -12,27 +12,27 @@ description: Vikunja API로 gravity_web 프로젝트 태스크 현황을 조회
 
 1. 전체 목록:
 ```powershell
-python .agents\workflows\vikunja_helper.py list
+python .agents\workflows\helpers\vikunja_helper.py list
 ```
 
 2. TODO만:
 ```powershell
-python .agents\workflows\vikunja_helper.py list todo
+python .agents\workflows\helpers\vikunja_helper.py list todo
 ```
 
 3. DONE만:
 ```powershell
-python .agents\workflows\vikunja_helper.py list done
+python .agents\workflows\helpers\vikunja_helper.py list done
 ```
 
 4. 태스크 완료 처리 (**⚠️ 반드시 이 방법 사용 — 직접 API 호출 금지**):
 ```powershell
-python .agents\workflows\vikunja_helper.py done {TASK_ID}
+python .agents\workflows\helpers\vikunja_helper.py done {TASK_ID}
 ```
 
 5. 새 태스크 생성:
 ```powershell
-python .agents\workflows\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:High
+python .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:High
 ```
 
 > [!CAUTION]

.agents/workflows/debug.md

@@ -0,0 +1,50 @@
+---
+description: 에러/버그 발생 시 체계적 디버깅 워크플로우 (에러, 안돼요, 왜 안돼, 버그, 디버그, 수정)
+---
+
+# Debug Workflow
+
+> [!IMPORTANT]
+> 추측으로 코드를 수정하지 마세요. 반드시 이 순서를 따릅니다.
+
+## 1단계: 정보 수집 (추측 금지)
+
+- [ ] 에러 메시지 **전문** 확인 (절대 잘라내지 않기)
+- [ ] 관련 로그 파일 확인
+- [ ] 환경 정보 확인 (OS, Node 버전 등)
+- [ ] 에러가 발생하는 **정확한 입력/조건** 파악
+
+## 2단계: Known Issues 확인
+
+`.agents/references/known-issues.md`를 읽고 동일하거나 유사한 문제가 있는지 확인합니다.
+
+> [!CAUTION]
+> **known-issues 확인 없이 해결 시도를 시작하지 마세요.**
+
+## 3단계: 근본 원인 분석
+
+- [ ] 에러가 발생하는 **정확한 코드 위치** 확인
+- [ ] 가설을 세우고, 가설을 검증할 수 있는 **최소한의 테스트** 수행
+- [ ] 가설이 틀렸다면 **즉시 다른 가설로 전환**
+
+> [!WARNING]
+> **동일한 접근을 2회 초과 시도하지 마세요.**
+> 2회 실패 시 유저에게 보고: 시도한 것 / 실패한 것 / 원인 가설 / 다음 제안
+
+## 4단계: 수정 및 검증
+
+- [ ] 수정 적용
+- [ ] 동일 에러가 재현되지 않는지 확인
+- [ ] 사이드 이펙트(다른 기능에 영향) 없는지 확인
+
+## 5단계: 기록
+
+- [ ] `known-issues.md`에 새 항목 추가:
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: 무엇이 잘못되었는가
+- **원인**: 근본 원인
+- **해결**: 올바른 해결 방법
+- **주의**: 재발 방지를 위한 교훈
+```

.agents/workflows/end.md

@@ -1,5 +1,5 @@
 ---
-description: 세션 종료 시 git commit + Vikunja 동기화
+description: 세션 종료 시 devlog 기록 + git commit + Vikunja 동기화 (끝, 마무리, 커밋해, 완료)
 ---
 
 # 세션 종료 프로토콜
@@ -8,14 +8,74 @@ description: 세션 종료 시 git commit + Vikunja 동기화
 
 // turbo-all
 
-## 1. Vikunja 동기화
+## 0. 학습 기록 (실패/시행착오 저장)
+
+이번 세션에서 발생한 실패, 시행착오, 새로 알게 된 사실을 정리합니다:
+
+- [ ] `.agents/references/known-issues.md`에 추가할 항목이 있는지 확인
+- [ ] 있다면 아래 포맷으로 추가:
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: ...
+- **원인**: ...
+- **해결**: ...
+- **주의**: ...
+```
+
+## 1. Devlog 기록
+
+### Index 업데이트 (필수 — 매 작업)
+
+오늘 날짜의 index 파일에 완료된 작업 1줄을 추가합니다.
+
+- **파일**: `docs/devlog/YYYY-MM-DD.md`
+- **형식**:
+```markdown
+| NNN | HH:MM | 작업 설명 | `커밋해시` | ✅ 또는 🔧 |
+```
+
+### Entry 작성 (선택적 — 필요할 때만)
+
+> [!IMPORTANT]
+> Entry는 **git/Vikunja/wiki에 없는 정보**가 있을 때만 작성합니다.
+
+**Entry 작성 기준:**
+- ✅ 설계 결정이 있었을 때 (왜 A가 아닌 B를 선택했는지)
+- ✅ 미완료 사항이 있을 때 (다음 세션이 이어받아야 할 맥락)
+- ✅ 삽질/트러블슈팅이 있었을 때 (같은 실수 방지)
+
+**Entry 불필요:**
+- ❌ 단순 버그 픽스 (커밋 메시지로 충분)
+- ❌ 문서 업데이트 (git diff로 충분)
+- ❌ 이미 Vikunja 태스크에 상세 설명이 있는 경우
+
+**Entry 파일**: `docs/devlog/entries/YYYYMMDD-NNN.md`
+```markdown
+# 작업 제목
+
+- **시간**: YYYY-MM-DD HH:MM~HH:MM
+- **Commit**: `해시`
+- **Vikunja**: #태스크번호 → done/진행중
+
+## 결정 사항
+- 왜 이 방식을 선택했는지
+
+## 미완료
+- 남은 작업 (있을 경우)
+```
+
+---
+
+## 2. Vikunja 동기화
 
 > [!CAUTION]
 > **반드시 `vikunja_helper.py` 사용.** 직접 API 호출 금지.
+> Vikunja API는 POST 시 body에 없는 필드를 빈값으로 덮어씁니다.
 
-### 1-1. 커밋 전수 검사
+### 2-1. 커밋 전수 검사
 
-이번 세션의 모든 커밋을 확인하고 Vikunja에 매핑:
+이번 세션의 **모든 커밋을 하나씩 검사**하고 Vikunja에 매핑합니다.
 
 ```powershell
 git log --oneline -20
@@ -23,11 +83,14 @@ git log --oneline -20
 
 | 커밋 유형 | Vikunja 액션 |
 |-----------|-------------|
-| 기존 태스크 해당 작업 완료 | `python .agents\workflows\vikunja_helper.py done {ID}` |
-| 신규 작업 완료 (기존 태스크 없음) | `python .agents\workflows\vikunja_helper.py create "제목" "설명" --done --labels Backend,Priority:High` |
-| 작업 중 발견된 미완료 TODO | `python .agents\workflows\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:Mid` |
+| 기존 태스크 해당 작업 **완료** | `python .agents\workflows\helpers\vikunja_helper.py done {ID}` |
+| 신규 작업 완료 (기존 태스크 없음) | `python .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --done --labels Backend,Priority:High` |
+| 작업 중 발견된 **미완료 TODO** | `python .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:Mid` |
 
-### 1-2. Wiki 동기화 (해당 시에만)
+> [!IMPORTANT]
+> 모든 커밋이 기존 또는 신규 태스크에 매핑되었는지 확인.
+
+### 2-2. Wiki 동기화 (해당 시에만)
 
 | 코드 변경 | 대상 Wiki |
 |-----------|----------|
@@ -36,10 +99,12 @@ git log --oneline -20
 | 프론트엔드 변경 | Architecture |
 
 ```powershell
-python .agents\workflows\wiki_helper.py update "Architecture" /tmp/wiki_content.md
+python .agents\workflows\helpers\wiki_helper.py update "Architecture" /tmp/wiki_content.md
 ```
 
-## 2. Git Commit & Push
+---
+
+## 3. Git Commit & Push
 
 ```powershell
 git add -A
@@ -60,9 +125,17 @@ type: feat|fix|refactor|test|docs|chore|ci|infra
 scope: server|frontend|cdp|infra (선택)
 ```
 
-## 3. 최종 체크리스트
+---
 
-- [ ] Vikunja 태스크 생성/완료 처리됨
+## 4. 최종 체크리스트
+
+> [!WARNING]
+> 아래 항목 중 하나라도 누락되면 세션 종료를 완료할 수 없습니다.
+
+- [ ] known-issues 업데이트됨 (새 이슈가 있었다면)
+- [ ] devlog index 업데이트됨
+- [ ] devlog entry 작성됨 (필요한 경우만)
+- [ ] Vikunja 태스크 생성/완료 처리됨 (커밋 전수 검사 기반)
 - [ ] Wiki 동기화됨 (해당 시)
 - [ ] git push 완료
 - [ ] 사용자에게 완료 보고

.agents/workflows/pre-task.md

@@ -0,0 +1,38 @@
+---
+description: 모든 구현 작업 전 실행하는 사전 점검 체크리스트 (pre-task, 준비, 시작 전, 계획, 구현)
+---
+
+# Pre-Task Checklist
+
+> [!IMPORTANT]
+> 코딩을 시작하기 전에 반드시 이 체크리스트를 순서대로 완료하세요.
+
+## 1단계: 요구사항 정리
+
+- [ ] 유저 요청을 구체적 작업 항목으로 분해
+- [ ] 변경 범위(scope)를 명확히 정의 (영향받는 파일/모듈)
+- [ ] 성공 기준(acceptance criteria) 확인
+
+## 2단계: 레퍼런스 확인 (추측 금지)
+
+- [ ] `.agents/references/architecture.md` — 현재 아키텍처 확인
+- [ ] `.agents/references/tech-stack.md` — 기술 스택 및 버전 확인
+- [ ] `.agents/references/conventions.md` — 코딩 컨벤션 확인
+- [ ] `.agents/references/known-issues.md` — 과거 실패 패턴 확인
+- [ ] 관련 기존 코드 최소 3개 파일 읽기
+
+> [!CAUTION]
+> 레퍼런스 문서가 존재하는 주제에 대해 추측하지 마세요.
+> 문서가 없으면 유저에게 확인을 요청하세요.
+
+## 3단계: 계획 수립
+
+- [ ] 변경할 파일 목록 작성
+- [ ] 의존성 순서 파악 (어떤 파일부터 수정해야 하는가?)
+- [ ] 리스크 식별 (어디서 실패할 가능성이 높은가?)
+- [ ] 테스트 방법 결정 (어떻게 검증할 것인가?)
+
+## 4단계: 유저 확인
+
+- [ ] 계획을 유저에게 보고하고 승인받기 (변경 파일 3개 이상인 경우)
+- [ ] 작은 변경은 바로 실행하되, 변경 내용을 명확히 설명

.agents/workflows/services.md

@@ -43,7 +43,7 @@ description: Gravity Web 프로젝트 연동 서비스 URL, API 키, 프로젝
 > 태스크 목록은 항상 라이브 조회를 사용합니다. 하드코딩된 매핑은 유지하지 않습니다.
 
 ```powershell
-python .agents\workflows\vikunja_helper.py list todo
+python .agents\workflows\helpers\vikunja_helper.py list todo
 ```
 
 ## 기타 서비스

.agents/workflows/start.md

@@ -1,5 +1,5 @@
 ---
-description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워크플로우
+description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워크플로우 (시작, continue, 이어서, 작업 시작)
 ---
 
 # 세션 시작 프로토콜
@@ -10,7 +10,33 @@ description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워
 
 ## 절차
 
-### 1. Git 상태 확인
+### 0. 에이전트 룰 & 맥락 로딩 (자동)
+
+`.agents/AGENT.md`를 읽고 에이전트 행동 규칙을 로딩합니다.
+`.agents/references/known-issues.md`를 읽어 최근 이슈를 파악합니다.
+
+### 1. Devlog 맥락 복구
+
+오늘 + 어제 devlog index를 읽고 최근 작업 흐름을 파악합니다.
+
+```powershell
+$today = Get-Date -Format "yyyy-MM-dd"
+$yesterday = (Get-Date).AddDays(-1).ToString("yyyy-MM-dd")
+if (Test-Path "docs\devlog\$today.md") {
+    Write-Host "=== Devlog: $today ==="
+    Get-Content "docs\devlog\$today.md"
+} elseif (Test-Path "docs\devlog\$yesterday.md") {
+    Write-Host "=== Devlog: $yesterday (no entry for today yet) ==="
+    Get-Content "docs\devlog\$yesterday.md"
+} else {
+    Write-Host "=== No recent devlog found ==="
+}
+```
+
+미완료(🔧) 항목이 있으면 해당 entry 파일을 읽어 이어받기 맥락을 확보합니다:
+- Entry 경로: `docs/devlog/entries/YYYYMMDD-NNN.md`
+
+### 2. Git 상태 확인
 
 ```powershell
 git status --short
@@ -19,27 +45,21 @@ git status --short
 git log --oneline -5
 ```
 
-### 2. Vikunja TODO 태스크
+### 3. Vikunja TODO 태스크
 
 ```powershell
-python .agents\workflows\vikunja_helper.py list todo
-```
-
-### 3. Wiki 아키텍처 확인 (필요 시)
-
-```powershell
-python .agents\workflows\wiki_helper.py read "Architecture"
+python .agents\workflows\helpers\vikunja_helper.py list todo
 ```
 
 ### 4. 종합 보고
 
 결과를 종합하여 사용자에게 보고:
-- 마지막 커밋 + 미완료 태스크
+- 마지막 작업 맥락 + 미완료 항목 (devlog 🔧 기반)
 - TODO 태스크 목록 (라벨 + 우선순위)
 - 다음 작업 제안
 
-**우선순위 판단 기준:**
-- P0: CDP 연결 관련 (Antigravity 연결이 안되면 전체 기능 불가)
-- P1: 서버/WebSocket 통신 장애
+**우선순위 판단 기준** (라벨만으로 판단 금지):
+- P0: 핵심 기능 연결 관련 (전체 기능 불가)
+- P1: 서버/통신 장애
 - P2: 기능 미완성/UX 개선
 - P3: 문서, 코드 정리