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

.agents/AGENT.md

@@ -44,7 +44,8 @@ description: 모든 작업에 자동 적용되는 에이전트 행동 규칙.
 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/` (action procedures)
+4. `.agents/workflows/services.md` (service credentials & protocols)
+5. `.agents/workflows/` (action procedures)
 
 ## PowerShell Notes
 

.agents/GUIDE.md

@@ -24,16 +24,31 @@ AI 에이전트는 다음과 같은 문제를 자주 일으킵니다:
 ```
 .agents/
 ├── AGENT.md                          ← 🧠 에이전트 헌법 (NEVER/ALWAYS 규칙)
+├── GUIDE.md                          ← 📖 이 가이드
 ├── references/                       ← 📚 프로젝트 지식 베이스
 │   ├── architecture.md               ← 아키텍처 설명
 │   ├── tech-stack.md                 ← 기술 스택 & 버전
 │   ├── conventions.md                ← 코딩 컨벤션
 │   └── known-issues.md               ← 🔴 과거 실패 기록 (핵심!)
 └── workflows/                        ← ⚙️ 행동 절차
-    ├── start.md                ← 세션 시작
-    ├── end.md                  ← 세션 종료 + 학습 기록
+    ├── start.md                      ← 세션 시작 (룰 로딩 + devlog 복구)
+    ├── end.md                        ← 세션 종료 (devlog + known-issues + Vikunja + Git)
     ├── pre-task.md                   ← 작업 전 필수 체크리스트
-    └── debug.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
 
 ---
 

README.md

@@ -10,14 +10,15 @@
 git clone https://git.variet.net/Variet/agent_guide.git
 cp -r agent_guide/.agents/ your-project/.agents/
 
-# 2. {{PLACEHOLDER}} 값들을 프로젝트에 맞게 교체
-#    - services.md → API URL, Token, Project ID
-#    - helpers/vikunja_helper.py → API_BASE, TOKEN, PROJECT_ID
-#    - helpers/wiki_helper.py → GITEA_BASE_URL, TOKEN, OWNER, REPO
-#    - check-gitea.md → Token, URL
-#    - references/ → 프로젝트별 아키텍처, 기술스택, 컨벤션
+# 2. 프로젝트별 값 2개만 교체
+#    - {{GITEA_REPO}} → services.md, check-gitea.md, wiki_helper.py
+#    - {{VIKUNJA_PROJECT_ID}} → services.md, vikunja_helper.py (PROJECT_ID)
+#    - references/ → 프로젝트별 아키텍처, 기술스택, 컨벤션 채우기
 
-# 3. AI 에이전트에게 "시작" 또는 "/start" 명령
+# 3. docs/devlog/ 디렉토리 생성
+mkdir -p docs/devlog/entries
+
+# 4. AI 에이전트에게 "시작" 또는 "/start" 명령
 ```
 
 ## 파일 구조