fix: cross-file consistency (GUIDE.md, AGENT.md, README.md)

.agents/GUIDE.md

@@ -23,17 +23,32 @@ AI 에이전트는 다음과 같은 문제를 자주 일으킵니다:
 
 ```
 .agents/
-├── AGENT.md                    ← 🧠 에이전트 헌법 (NEVER/ALWAYS 규칙)
-├── references/                 ← 📚 프로젝트 지식 베이스
-│   ├── architecture.md         ← 아키텍처 설명
-│   ├── tech-stack.md           ← 기술 스택 & 버전
-│   ├── conventions.md          ← 코딩 컨벤션
-│   └── known-issues.md         ← 🔴 과거 실패 기록 (핵심!)
-└── workflows/                  ← ⚙️ 행동 절차
-    ├── start.md                ← 세션 시작
-    ├── end.md                  ← 세션 종료 + 학습 기록
-    ├── pre-task.md             ← 작업 전 필수 체크리스트
-    └── debug.md                ← 디버깅 전용 절차
+├── AGENT.md                          ← 🧠 에이전트 헌법 (NEVER/ALWAYS 규칙)
+├── GUIDE.md                          ← 📖 이 가이드
+├── references/                       ← 📚 프로젝트 지식 베이스
+│   ├── architecture.md               ← 아키텍처 설명
+│   ├── tech-stack.md                 ← 기술 스택 & 버전
+│   ├── conventions.md                ← 코딩 컨벤션
+│   └── known-issues.md               ← 🔴 과거 실패 기록 (핵심!)
+└── workflows/                        ← ⚙️ 행동 절차
+    ├── start.md                      ← 세션 시작 (룰 로딩 + devlog 복구)
+    ├── end.md                        ← 세션 종료 (devlog + known-issues + Vikunja + Git)
+    ├── pre-task.md                   ← 작업 전 필수 체크리스트
+    ├── debug.md                      ← 디버깅 전용 절차
+    ├── services.md                   ← 서비스 연동 정보 + AI 작업 프로토콜
+    ├── check-gitea.md                ← Gitea 현황 조회
+    ├── check-vikunja.md              ← Vikunja 태스크 조회
+    └── helpers/
+        ├── vikunja_helper.py         ← Vikunja API 안전 래퍼
+        └── wiki_helper.py            ← Gitea Wiki 래퍼
+```
+
+**프로젝트 루트에 자동 생성되는 디렉토리:**
+```
+docs/devlog/                          ← 📓 세션별 작업 기록
+├── YYYY-MM-DD.md                     ← Index (매일 1줄씩 누적)
+└── entries/
+    └── YYYYMMDD-NNN.md               ← Entry (설계 결정/미완료 시만)
 ```
 
 ---
@@ -73,10 +88,17 @@ AI 에이전트는 다음과 같은 문제를 자주 일으킵니다:
 4. 수정 및 검증
 5. 기록 (known-issues에 추가)
 
+### 📓 Devlog — 세션별 작업 기록 (start.md / end.md에서 관리)
+
+known-issues가 **실패만** 기록한다면, devlog는 **전체 세션 이력**을 기록합니다:
+- **Index** (`docs/devlog/YYYY-MM-DD.md`): 매 작업마다 1줄 (필수)
+- **Entry** (`docs/devlog/entries/YYYYMMDD-NNN.md`): 설계 결정/미완료/삽질 시만 (선택)
+- **start.md**에서 자동으로 오늘/어제 devlog를 읽어 맥락 복구
+
 ### ▶️ `start.md` / ⏹️ `end.md` — 세션 관리
 
-- **start**: 에이전트 룰 로딩 + Git 상태 + 맥락 복구
-- **end**: 학습 기록 + Git commit/push
+- **start**: 에이전트 룰 로딩 + devlog 맥락 복구 + Git 상태 + Vikunja TODO
+- **end**: known-issues 업데이트 + devlog 기록 + Vikunja 동기화 + Git commit/push
 
 ---