refactor: .agents + .agent 단일 .agent 디렉토리로 통합 (agent_guide 포맷, 12→7 워크플로우 축소)

2026-03-11 01:02:33 +09:00
parent d50d3d86af
commit c6381a7672
26 changed files with 300 additions and 763 deletions
--- a/.agents/AGENT.md
+++ b/.agents/AGENT.md
@@ -10,18 +10,18 @@ description: 모든 작업에 자동 적용되는 에이전트 행동 규칙.

 ## 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 APIs directly when helper scripts exist in `.agents/workflows/helpers/`
-5. NEVER skip the pre-task checklist defined in `.agents/workflows/pre-task.md`
+1. NEVER start coding without reading relevant reference documents in `.agent/references/`
+2. NEVER guess when documentation exists — always check `.agent/references/` first
+3. NEVER repeat a failed approach — check `.agent/references/known-issues.md` first
+4. NEVER call APIs directly when helper scripts exist in `.agent/workflows/helpers/`
+5. NEVER skip the pre-task checklist defined in `.agent/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

 ## ALWAYS (필수)

-1. ALWAYS run `.agents/workflows/pre-task.md` before any implementation task
-2. ALWAYS check `.agents/references/known-issues.md` before debugging
+1. ALWAYS run `.agent/workflows/pre-task.md` before any implementation task
+2. ALWAYS check `.agent/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 existing helper scripts instead of raw API calls
@@ -41,11 +41,11 @@ description: 모든 작업에 자동 적용되는 에이전트 행동 규칙.

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

 ## PowerShell Notes

--- a/.agents/GUIDE.md
+++ b/.agents/GUIDE.md
@@ -22,7 +22,7 @@ AI 에이전트는 다음과 같은 문제를 자주 일으킵니다:
 ## 파일 구조 개요

 ```
-.agents/
+.agent/
 ├── AGENT.md                          ← 🧠 에이전트 헌법 (NEVER/ALWAYS 규칙)
 ├── GUIDE.md                          ← 📖 이 가이드
 ├── references/                       ← 📚 프로젝트 지식 베이스
@@ -35,7 +35,7 @@ AI 에이전트는 다음과 같은 문제를 자주 일으킵니다:
    ├── end.md                        ← 세션 종료 (devlog + known-issues + Vikunja + Git)
    ├── pre-task.md                   ← 작업 전 필수 체크리스트
    ├── debug.md                      ← 디버깅 전용 절차
-    ├── services.md                   ← 서비스 연동 정보 + AI 작업 프로토콜
+    ├── services.md                   ← 서비스 연동 + 작업 프로토콜 + 개발/테스트 명령어
    ├── check-gitea.md                ← Gitea 현황 조회
    ├── check-vikunja.md              ← Vikunja 태스크 조회
    └── helpers/
@@ -104,21 +104,12 @@ known-issues가 **실패만** 기록한다면, devlog는 **전체 세션 이력*

 ## 사용법

-### 새 프로젝트에 적용하기
-
-1. `.agents/` 디렉토리를 프로젝트에 복사
-2. `references/` 파일들을 프로젝트에 맞게 채우기:
-   - `architecture.md` — 프로젝트 구조 설명
-   - `tech-stack.md` — 사용 기술 및 버전
-   - `conventions.md` — 코딩 스타일 규칙
-3. 프로젝트별 워크플로우가 있다면 `workflows/`에 추가
-
 ### 프로젝트별 워크플로우와 함께 사용하기

 이 범용 워크플로우와 프로젝트별 워크플로우(예: Vikunja 동기화, Gitea 연동)는 **함께 사용**합니다:

 ```
-.agents/
+.agent/
 ├── AGENT.md                    ← 범용 (공통)
 ├── references/                 ← 범용 + 프로젝트 특화
 │   ├── known-issues.md         ← 범용 (공통)
@@ -128,7 +119,7 @@ known-issues가 **실패만** 기록한다면, devlog는 **전체 세션 이력*
    ├── debug.md                ← 범용 (공통)
    ├── start.md                ← 범용 기반 + 프로젝트 단계 추가
    ├── end.md                  ← 범용 기반 + 프로젝트 단계 추가
-    ├── services.md             ← ⭐ 프로젝트별
+    ├── services.md             ← ⭐ 프로젝트별 (서비스 + 프로토콜 + 개발/테스트)
    ├── check-vikunja.md        ← ⭐ 프로젝트별
    ├── check-gitea.md          ← ⭐ 프로젝트별
    └── helpers/
--- a/.agents/references/architecture.md
+++ b/.agents/references/architecture.md
--- a/.agents/references/conventions.md
+++ b/.agents/references/conventions.md
--- a/.agents/references/known-issues.md
+++ b/.agents/references/known-issues.md
--- a/.agents/references/tech-stack.md
+++ b/.agents/references/tech-stack.md
@@ -6,7 +6,7 @@

 | 항목 | 버전 | 비고 |
 |------|------|------|
-| Python | 3.12+ | `C:\ProgramData\miniforge3\envs\agent_chat\python.exe` |
+| Python | 3.12+ | `C:\ProgramData\miniforge3\envs\variet-agent\python.exe` |
 | Gemini CLI | v0.32+ (AI Ultra) | `gemini --model gemini-3-flash-preview` |

 ## 프레임워크
@@ -20,17 +20,17 @@

 ## 패키지 관리

- 패키지 매니저: pip (conda env `agent_chat`)
+- 패키지 매니저: pip (conda env `variet-agent`)
 - 의존성 파일: `requirements.txt`
- 가상환경: `C:\ProgramData\miniforge3\envs\agent_chat`
+- 가상환경: `C:\ProgramData\miniforge3\envs\variet-agent`

 ## 개발 도구

 | 도구 | 명령어 |
 |------|--------|
-| 봇 실행 | `run_bot.bat` 또는 `C:\ProgramData\miniforge3\envs\agent_chat\python.exe main.py` |
-| 테스트 | `C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m pytest tests/ -v` |
-| Vikunja 조회 | `C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py list todo` |
+| 봇 실행 | `run_bot.bat` 또는 `C:\ProgramData\miniforge3\envs\variet-agent\python.exe main.py` |
+| 테스트 | `C:\ProgramData\miniforge3\envs\variet-agent\python.exe -m pytest tests/ -v` |
+| Vikunja 조회 | `C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py list todo` |

 ## 환경 변수 (.env)

--- a/.agent/workflows/check-gitea.md
+++ b/.agent/workflows/check-gitea.md
@@ -1,5 +1,5 @@
 ---
-description: Gitea API로 variet-agent 저장소 커밋/이슈/PR 현황을 조회하는 워크플로우
+description: Gitea API로 저장소 커밋/이슈/PR 현황을 조회하는 워크플로우
 ---

 # Gitea 저장소 현황 조회
@@ -32,7 +32,15 @@ Invoke-RestMethod -Uri "https://git.variet.net/api/v1/repos/Variet/variet-agent/

 4. Wiki 페이지 목록:
 ```powershell
-$h = @{Authorization="token 3a01b4b15a39921572e64c413353e870d4d2161b"}
-$pages = Invoke-RestMethod -Uri "https://git.variet.net/api/v1/repos/Variet/variet-agent/wiki/pages" -Headers $h
-$pages | ForEach-Object { Write-Host $_.title }
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py list
+```
+
+5. Wiki 페이지 읽기:
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py read "Architecture"
+```
+
+6. Wiki 페이지 업데이트:
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py update "페이지-제목" /tmp/wiki_content.md
 ```
--- a/.agent/workflows/check-status.md
+++ b/.agent/workflows/check-status.md
@@ -1,43 +0,0 @@
---
-description: ?„ë¡œ?<3F>íŠ¸ ?„ì²´ ?‘ì—… ?„í™©??ì¢…í•© ì²´í<C2B4>¬?˜ëŠ” ?Œí<C592>¬?Œë¡œ??(Git + Vikunja + ë¡œì»¬)
---
-
-# ?„ë¡œ?<3F>íŠ¸ ?„í™© ì¢…í•© ì²´í<C2B4>¬
-
-"?‘ì—…?<3F>í™© ì²´í<C2B4>¬", "?„í™© ?•ì<E280A2>¸", "status check" ???”ì² ?????Œí<C592>¬?Œë¡œ?°ë? ?¤í–‰?©ë‹ˆ??
-
-// turbo-all
-
-## ?ˆì°¨
-
-1. Git ë¡œì»¬ ?<3F>íƒœ ?•ì<E280A2>¸:
-```powershell
-git -C "c:\Users\Certes\Desktop\variet-agent" status --short
-```
-```powershell
-git -C "c:\Users\Certes\Desktop\variet-agent" log --oneline -5
-```
-
-2. Vikunja ?œìŠ¤???„í™© ì¡°íšŒ:
-```powershell
-$h = @{Authorization="Bearer tk_070f8e0b715e818bb7178c3815ed5389040eddca"}
-$tasks = Invoke-RestMethod -Uri "https://plan.variet.net/api/v1/projects/7/tasks?per_page=50" -Headers $h
-$todo = $tasks | Where-Object { -not $_.done }
-$done = $tasks | Where-Object { $_.done }
-Write-Host "=== Vikunja: TODO $($todo.Count), DONE $($done.Count) ==="
-$todo | ForEach-Object { Write-Host "  #$($_.id) $($_.title)" }
-```
-
-3. Gitea ìµœê·¼ ì»¤ë°‹ ?•ì<E280A2>¸ (ë¦¬ëª¨??:
-```powershell
-$h = @{Authorization="token 3a01b4b15a39921572e64c413353e870d4d2161b"}
-$commits = Invoke-RestMethod -Uri "https://git.variet.net/api/v1/repos/Variet/variet-agent/commits?limit=5&sha=main" -Headers $h
-Write-Host "=== Gitea: Recent Commits ==="
-$commits | ForEach-Object { Write-Host "  $($_.sha.Substring(0,7)) $($_.commit.message.Split("`n")[0])" }
-```
-
-4. ê²°ê³¼ë¥?ì¢…í•©?˜ì—¬ ?¬ìš©?<3F>ì—<C3AC>ê²?ë³´ê³ :
-   - ë¡œì»¬ uncommitted ë³€ê²??¬ë?
-   - ë¡œì»¬ vs ë¦¬ëª¨??ì»¤ë°‹ ì°¨ì<C2A8>´
-   - TODO ?œìŠ¤??ëª©ë¡<C3AB> + ?°ì„ ?œìœ„
-   - ?¤ì<C2A4>Œ ?‘ì—… ?œì•ˆ
--- a/.agent/workflows/check-vikunja.md
+++ b/.agent/workflows/check-vikunja.md
@@ -1,50 +1,55 @@
 ---
-description: Vikunja APIë¡?Variet Agent ?„ë¡œ?<3F>íŠ¸ ?œìŠ¤???„í™©??ì¡°íšŒ?˜ëŠ” ?Œí<C592>¬?Œë¡œ??
+description: Vikunja API로 프로젝트 태스크 현황을 조회하는 워크플로우
 ---

-# Vikunja ?œìŠ¤???„í™© ì¡°íšŒ
+# Vikunja 태스크 현황 조회

-?œë¹„???•ë³´??`.agent/workflows/services.md` ì°¸ì¡°.
+서비스 정보는 `.agent/workflows/services.md` 참조.

 // turbo-all

-## ?ˆì°¨
+## 절차

-1. ê°„íŽ¸ ì¡°íšŒ (TODO/DONE ë¦¬ìŠ¤??:
+1. 전체 목록:
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py list
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py list
 ```

-2. TODOë§?ì¡°íšŒ:
+2. TODO만:
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py list todo
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py list todo
 ```

-3. DONEë§?ì¡°íšŒ:
+3. DONE만:
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py list done
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py list done
 ```

-4. ?œìŠ¤???„ë£Œ ì²˜ë¦¬ (**? ï¸<C3AF> ë°˜ë“œ????ë°©ë²• ?¬ìš© ??ì§<C3AC>ì ‘ API ?¸ì¶œ ê¸ˆì?**):
+4. 태스크 완료 처리 (반드시 이 방법 사용, 직접 API 호출 금지):
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py done {TASK_ID}
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py done {TASK_ID}
 ```
-   ?¬ëŸ¬ ?œìŠ¤???™ì‹œ:
+   복수 태스크 처리:
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py done 71 77 78
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py done 71 77 78
 ```

-5. ?œìŠ¤??ì½”ë©˜??ì¶”ê?:
+5. 태스크에 코멘트 추가:
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py comment {TASK_ID} "?´ìš©"
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py comment {TASK_ID} "내용"
 ```

-6. ???œìŠ¤???<3F>ì„±:
+6. 새 태스크 생성:
 ```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agent\workflows\vikunja_helper.py create "?œëª©" "?¤ëª…"
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:High
+```
+
+7. 태스크에 라벨 추가:
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py label {TASK_ID} Backend Priority:High
 ```

 > [!CAUTION]
-> **?ˆë?ë¡?* `Invoke-RestMethod -Method Post -Body '{"done": true}'` ê°™ì? ì§<C3AC>ì ‘ API ?¸ì¶œ???¬ìš©?˜ì? ë§ˆì„¸??
-> Vikunja API??POST ??body???¬í•¨?˜ì? ?Šì? ?„ë“œë¥?ë¹ˆê°’?¼ë¡œ ??–´?<3F>ë‹ˆ??
-> `vikunja_helper.py`????ƒ<> GET ??ê¸°ì¡´ ?„ë“œ ë³´ì¡´ ??POST ?¨í„´???¬ìš©?˜ì—¬ title/description ë³´ì¡´??ë³´ìž¥?©ë‹ˆ??
+> 절대로 Invoke-RestMethod로 직접 API를 호출하지 마세요.
+> Vikunja API는 POST 시 body에 포함되지 않은 필드를 빈값으로 덮어씁니다.
+> vikunja_helper.py는 항상 GET 후 기존 필드 보존 후 POST 패턴을 사용합니다.
--- a/.agents/workflows/debug.md
+++ b/.agents/workflows/debug.md
@@ -16,7 +16,7 @@ description: 에러/버그 발생 시 체계적 디버깅 워크플로우 (에

 ## 2단계: Known Issues 확인

-`.agents/references/known-issues.md`를 읽고 동일하거나 유사한 문제가 있는지 확인합니다.
+`.agent/references/known-issues.md`를 읽고 동일하거나 유사한 문제가 있는지 확인합니다.

 > [!CAUTION]
 > **known-issues 확인 없이 해결 시도를 시작하지 마세요.**
--- a/.agent/workflows/dev.md
+++ b/.agent/workflows/dev.md
@@ -1,21 +0,0 @@
---
-description: ê°œë°œ ?œë²„ ?¤í–‰ ë°©ë²•
---
-
-## ?˜ê²½ ?¤ì •
-
-1. Python ?˜ê²½ ?œì„±??
-// turbo
-```
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m pip install -r requirements.txt
-```
-
-2. API ?œë²„ ?¤í–‰
-```
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m uvicorn api.server:app --reload --host 0.0.0.0 --port 8100
-```
-
-3. Discord Bot ?¤í–‰ (ë³„ë<E2809E>„ ?°ë???
-```
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m api.discord_bot
-```
--- a/.agent/workflows/end.md
+++ b/.agent/workflows/end.md
@@ -0,0 +1,165 @@
+---
+description: 세션 종료 시 devlog 기록 + git commit + Vikunja 동기화 (끝, 마무리, 커밋해, 완료)
+---
+
+# 세션 종료 프로토콜
+
+작업 완료, "끝", "마무리", "커밋해" 등 요청 시 이 워크플로우를 실행합니다.
+
+// turbo-all
+
+## 0. 학습 기록 (실패/시행착오 저장)
+
+이번 세션에서 발생한 실패, 시행착오, 새로 알게 된 사실을 정리합니다:
+
+- [ ] `.agent/references/known-issues.md`에 추가할 항목이 있는지 확인
+- [ ] 있다면 아래 포맷으로 추가:
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: ...
+- **원인**: ...
+- **해결**: ...
+- **주의**: ...
+```
+
+## 1. Devlog 기록
+
+### Index 업데이트 (필수 — 매 작업)
+
+오늘 날짜의 index 파일에 완료된 작업 1줄을 추가합니다.
+
+- **파일**: `docs/devlog/YYYY-MM-DD.md`
+- **형식**:
+```markdown
+| NNN | HH:MM | 작업 설명 | `커밋해시` | ✅ 또는 🔧 |
+```
+
+> [!TIP]
+> - ✅ = 완료, 🔧 = 미완료 (다음 세션에서 이어받기)
+> - 파일이 없으면 새로 생성 (테이블 헤더 포함)
+
+### 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에 없는 필드를 빈값으로 덮어씁니다.
+
+### 2-1. 커밋 전수 검사
+
+이번 세션의 **모든 커밋을 하나씩 검사**하고 Vikunja에 매핑합니다.
+
+```powershell
+git log --oneline -20
+```
+
+| 커밋 유형 | Vikunja 액션 |
+|-----------|-------------|
+| 기존 태스크 해당 작업 **완료** | `C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py done {ID}` |
+| 신규 작업 완료 (기존 태스크 없음) | `C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py create "제목" "설명" --done --labels Backend,Priority:High` |
+| 작업 중 발견된 **미완료 TODO** | `C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:Mid` |
+
+> [!IMPORTANT]
+> 모든 커밋이 기존 또는 신규 태스크에 매핑되었는지 확인.
+
+### 2-2. 완료 처리
+
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py done {TASK_ID}
+```
+
+### 2-3. 신규 태스크 생성
+
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:High
+```
+
+### 라벨 규칙
+
+**영역 (필수 1개 이상):** `Backend` / `Frontend` / `Engine` / `Infra` / `Test`
+**우선순위 (필수 1개):** `Priority:High` / `Priority:Mid` / `Priority:Low`
+
+---
+
+## 3. Wiki 동기화 (해당 시에만)
+
+| 코드 변경 | 대상 Wiki |
+|-----------|----------|
+| 서버 변경 | Architecture |
+| 프론트엔드 변경 | Architecture |
+| 인프라 변경 | Architecture |
+| 새 모듈/패키지 추가 | Architecture |
+
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py update "Architecture" /tmp/wiki_content.md
+```
+
+---
+
+## 4. Git Commit & Push
+
+```powershell
+git add -A
+git status --short
+```
+```powershell
+git commit -m "커밋 메시지"
+```
+```powershell
+git push origin main
+```
+
+**커밋 메시지 컨벤션:**
+```
+<type>(<scope>): <description>
+
+type: feat|fix|refactor|test|docs|chore|ci|infra
+scope: (선택)
+```
+
+---
+
+## 5. 최종 체크리스트
+
+> [!WARNING]
+> 아래 항목 중 하나라도 누락되면 세션 종료를 완료할 수 없습니다.
+
+- [ ] known-issues 업데이트됨 (새 이슈가 있었다면)
+- [ ] devlog index 업데이트됨
+- [ ] devlog entry 작성됨 (필요한 경우만)
+- [ ] Vikunja 태스크 생성/완료 처리됨 (커밋 전수 검사 기반)
+- [ ] Wiki 동기화됨 (아키텍처 변경이 있었다면)
+- [ ] git push 완료
+- [ ] 사용자에게 완료 보고
--- a/.agent/workflows/git.md
+++ b/.agent/workflows/git.md
@@ -1,47 +0,0 @@
---
-description: Git 및 Gitea 워크플로우
---
-
-## 저장소 정보
- **Remote**: https://git.variet.net/Variet/variet-agent.git
- **기본 브랜치**: main
- **Vikunja 프로젝트**: https://plan.variet.net/projects/7
-
-## 커밋 컨벤션
-```
-feat: 새 기능
-fix: 버그 수정
-docs: 문서 변경
-refactor: 리팩토링
-test: 테스트 추가/수정
-chore: 빌드/설정 변경
-```
-
-## 작업 흐름
-
-1. 브랜치 생성
-// turbo
-```
-git checkout -b feat/feature-name
-```
-
-2. 커밋
-// turbo
-```
-git add -A && git commit -m "feat: description"
-```
-
-3. 푸시
-```
-git push origin feat/feature-name
-```
-
-4. Gitea에서 PR 생성 또는 API로 자동 생성
-
-## Wiki 업데이트
-작업 완료 시 Gitea Wiki에 관련 내용 업데이트. 
-Wiki 구조:
- Home: 프로젝트 개요
- Architecture: 아키텍처 설명
- Design-Decisions: 설계 결정 이유
- Changelog: 버전별 변경 이력
--- a/.agents/workflows/helpers/vikunja_helper.py
+++ b/.agents/workflows/helpers/vikunja_helper.py
--- a/.agents/workflows/helpers/wiki_helper.py
+++ b/.agents/workflows/helpers/wiki_helper.py
--- a/.agents/workflows/pre-task.md
+++ b/.agents/workflows/pre-task.md
@@ -16,10 +16,10 @@ description: 모든 구현 작업 전 실행하는 사전 점검 체크리스트

 ## 2단계: 레퍼런스 확인 (추측 금지)

- [ ] `.agents/references/architecture.md` — 현재 아키텍처 확인
- [ ] `.agents/references/tech-stack.md` — 기술 스택 및 버전 확인
- [ ] `.agents/references/conventions.md` — 코딩 컨벤션 확인
- [ ] `.agents/references/known-issues.md` — 과거 실패 패턴 확인
+- [ ] `.agent/references/architecture.md` — 현재 아키텍처 확인
+- [ ] `.agent/references/tech-stack.md` — 기술 스택 및 버전 확인
+- [ ] `.agent/references/conventions.md` — 코딩 컨벤션 확인
+- [ ] `.agent/references/known-issues.md` — 과거 실패 패턴 확인
 - [ ] 관련 기존 코드 최소 3개 파일 읽기

 > [!CAUTION]
--- a/.agent/workflows/start.md
+++ b/.agent/workflows/start.md
@@ -0,0 +1,65 @@
+---
+description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워크플로우 (시작, continue, 이어서, 작업 시작)
+---
+
+# 세션 시작 프로토콜
+
+새 대화 시작, "continue", "이어서", "작업 시작" 등 요청 시 이 워크플로우를 실행합니다.
+
+// turbo-all
+
+## 절차
+
+### 0. 에이전트 룰 & 맥락 로딩 (자동)
+
+`.agent/AGENT.md`를 읽고 에이전트 행동 규칙을 로딩합니다.
+`.agent/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
+```
+```powershell
+git log --oneline -5
+```
+
+### 3. Vikunja TODO 태스크
+
+```powershell
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\vikunja_helper.py list todo
+```
+
+### 4. 종합 보고
+
+결과를 종합하여 사용자에게 보고:
+- 마지막 작업 맥락 + 미완료 항목 (devlog 🔧 기반)
+- TODO 태스크 목록 (라벨 + 우선순위)
+- 다음 작업 제안
+
+**우선순위 판단 기준** (라벨만으로 판단 금지):
+- P0: 최근 커밋에서 스키마/모델/인터페이스 변경 → 연쇄 영향 점검
+- P1: 서버 기동/API 응답 장애
+- P2: 기능 미완성/UX 개선
+- P3: 정확도 향상, 신규 기능, CI/CD, 문서 정리
--- a/.agent/workflows/sync.md
+++ b/.agent/workflows/sync.md
@@ -1,18 +0,0 @@
---
-description: 작업 동기화 및 진행 보고 절차
---
-
-## 작업 시작 시
-1. Vikunja (plan.variet.net/projects/7) 에서 해당 태스크를 "진행 중"으로 변경
-2. 관련 브랜치 생성 (feat/ 또는 fix/)
-
-## 작업 중간 동기화
-1. 의미 있는 단위로 커밋 + 푸시
-2. 필요 시 Gitea Wiki 업데이트 (Architecture, Changelog 등)
-3. 사용자에게 디스코드 또는 Vikunja 코멘트로 진행 상황 보고
-
-## 작업 완료 시
-1. Gitea PR 생성
-2. Vikunja 태스크 "완료"로 변경
-3. Changelog 업데이트
-4. Wiki 관련 페이지 업데이트
--- a/.agent/workflows/test.md
+++ b/.agent/workflows/test.md
@@ -1,24 +0,0 @@
---
-description: ?ŒìŠ¤???¤í–‰ ë°©ë²•
---
-
-## ?¨ìœ„ ?ŒìŠ¤??
-// turbo
-```
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m pytest tests/ -v
-```
-
-## Context Manager ?¨ê³¼ ?ŒìŠ¤??
-```
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m tests.test_context_manager
-```
-
-## Task Pipeline E2E
-```
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m tests.test_pipeline_e2e
-```
-
-## Gemini CLI ?°ë<C2B0>™ ?ŒìŠ¤??
-```
-gemini -p "Hello, respond with 'OK'" --approval-mode yolo -o json
-```
--- a/.agent/workflows/vikunja_helper.py
+++ b/.agent/workflows/vikunja_helper.py
@@ -1,171 +0,0 @@
-"""Vikunja safe task updater — preserves existing fields when updating tasks.
-
-Usage:
-  python vikunja_helper.py done 75              # Mark task #75 as done
-  python vikunja_helper.py done 71 77 78        # Mark multiple tasks done
-  python vikunja_helper.py undone 75            # Mark task #75 as not done
-  python vikunja_helper.py comment 75 "text"    # Add comment to task #75
-  python vikunja_helper.py desc 75 "text"       # Set description (appends if exists)
-  python vikunja_helper.py create "title" "description"          # Create a new task
-  python vikunja_helper.py create "title" "description" --done   # Create and mark done
-  python vikunja_helper.py list                 # List all tasks
-  python vikunja_helper.py list todo            # List TODO only
-  python vikunja_helper.py list done            # List DONE only
-"""
-
-import sys
-import json
-import urllib.request
-import urllib.error
-import io
-
-# Fix Windows console encoding (cp949 → utf-8)
-if sys.stdout.encoding != "utf-8":
-    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
-
-API_BASE = "https://plan.variet.net/api/v1"
-TOKEN = "tk_070f8e0b715e818bb7178c3815ed5389040eddca"
-PROJECT_ID = 7
-
-HEADERS = {
-    "Authorization": f"Bearer {TOKEN}",
-    "Content-Type": "application/json",
-}
-
-
-def api_get(path: str):
-    req = urllib.request.Request(f"{API_BASE}{path}", headers=HEADERS)
-    with urllib.request.urlopen(req) as resp:
-        return json.loads(resp.read().decode("utf-8"))
-
-
-def api_post(path: str, data: dict):
-    body = json.dumps(data).encode("utf-8")
-    req = urllib.request.Request(f"{API_BASE}{path}", data=body, headers=HEADERS, method="POST")
-    with urllib.request.urlopen(req) as resp:
-        return json.loads(resp.read().decode("utf-8"))
-
-
-def api_put(path: str, data: dict):
-    body = json.dumps(data).encode("utf-8")
-    req = urllib.request.Request(f"{API_BASE}{path}", data=body, headers=HEADERS, method="PUT")
-    with urllib.request.urlopen(req) as resp:
-        return json.loads(resp.read().decode("utf-8"))
-
-
-def get_task(task_id: int) -> dict:
-    """GET full task object — preserves all fields."""
-    return api_get(f"/tasks/{task_id}")
-
-
-def safe_update_task(task_id: int, updates: dict) -> dict:
-    """Safely update task: GET first, then POST with preserved fields."""
-    task = get_task(task_id)
-    safe_body = {
-        "title": task.get("title", ""),
-        "description": task.get("description", ""),
-        "priority": task.get("priority", 0),
-        "done": task.get("done", False),
-    }
-    safe_body.update(updates)
-    return api_post(f"/tasks/{task_id}", safe_body)
-
-
-def mark_done(task_ids: list[int]):
-    for tid in task_ids:
-        result = safe_update_task(tid, {"done": True})
-        title = result.get("title", "?")
-        print(f"  ✅ #{tid} → done=True  [{title}]")
-
-
-def mark_undone(task_ids: list[int]):
-    for tid in task_ids:
-        result = safe_update_task(tid, {"done": False})
-        title = result.get("title", "?")
-        print(f"  ⬜ #{tid} → done=False  [{title}]")
-
-
-def add_comment(task_id: int, comment: str):
-    result = api_put(f"/tasks/{task_id}/comments", {"comment": comment})
-    print(f"  💬 #{task_id} comment added (id={result.get('id', '?')})")
-
-
-def set_description(task_id: int, desc: str, append: bool = True):
-    task = get_task(task_id)
-    existing = task.get("description", "") or ""
-    if append and existing:
-        new_desc = existing.rstrip() + "\n\n" + desc
-    else:
-        new_desc = desc
-    result = safe_update_task(task_id, {"description": new_desc})
-    print(f"  📝 #{task_id} description updated [{result.get('title', '?')}]")
-
-
-def list_tasks(filter_: str = "all"):
-    tasks = api_get(f"/projects/{PROJECT_ID}/tasks?per_page=100")
-    if filter_ == "todo":
-        tasks = [t for t in tasks if not t["done"]]
-    elif filter_ == "done":
-        tasks = [t for t in tasks if t["done"]]
-
-    tasks.sort(key=lambda t: t["id"])
-    for t in tasks:
-        status = "✅" if t["done"] else "⬜"
-        desc = (t.get("description") or "")[:50].replace("\n", " ")
-        labels = ", ".join(l["title"] for l in (t.get("labels") or []))
-        print(f"  {status} #{t['id']:3d}  {t['title'][:40]:<40}  [{labels}]  {desc}")
-    print(f"\n  Total: {len(tasks)} tasks")
-
-
-def create_task(title: str, description: str = "", done: bool = False):
-    """Create a new task in the project."""
-    payload = {"title": title, "description": description}
-    result = api_put(f"/projects/{PROJECT_ID}/tasks", payload)
-    task_id = result["id"]
-    print(f"  ✨ #{task_id} created: {result.get('title', '?')}")
-    if done:
-        result = safe_update_task(task_id, {"done": True})
-        print(f"  ✅ #{task_id} → done=True")
-    return result
-
-
-def main():
-    if len(sys.argv) < 2:
-        print(__doc__)
-        return
-
-    cmd = sys.argv[1].lower()
-
-    if cmd == "done":
-        ids = [int(x) for x in sys.argv[2:]]
-        mark_done(ids)
-    elif cmd == "undone":
-        ids = [int(x) for x in sys.argv[2:]]
-        mark_undone(ids)
-    elif cmd == "comment":
-        tid = int(sys.argv[2])
-        comment = sys.argv[3]
-        add_comment(tid, comment)
-    elif cmd == "desc":
-        tid = int(sys.argv[2])
-        desc = sys.argv[3]
-        set_description(tid, desc)
-    elif cmd == "list":
-        f = sys.argv[2] if len(sys.argv) > 2 else "all"
-        list_tasks(f)
-    elif cmd == "create":
-        title = sys.argv[2] if len(sys.argv) > 2 else ""
-        desc = sys.argv[3] if len(sys.argv) > 3 else ""
-        is_done = "--done" in sys.argv
-        if not title:
-            print("Error: title is required")
-            print('  Usage: vikunja_helper.py create "title" "description" [--done]')
-            return
-        create_task(title, desc, done=is_done)
-    else:
-        print(f"Unknown command: {cmd}")
-        print(__doc__)
-
-
-if __name__ == "__main__":
-    main()
--- a/.agents/README.md
+++ b/.agents/README.md
@@ -1,67 +0,0 @@
-# Agent Guide — AI 에이전트 범용 워크플로우 시스템
-
-> AI 코딩 에이전트가 더 똑똑하게 동작하도록 설계된 범용 워크플로우 템플릿.
-> 새 프로젝트에서 `.agents/` 폴더를 통째로 복사하고, `{{PLACEHOLDER}}`를 교체하면 즉시 사용 가능합니다.
-
-## Quick Start
-
-```bash
-# 1. 이 레포를 클론하거나 .agents/ 폴더를 복사
-git clone https://git.variet.net/Variet/agent_guide.git
-cp -r agent_guide/.agents/ your-project/.agents/
-
-# 2. 프로젝트별 값 2개만 교체
-#    - {{GITEA_REPO}} → services.md, check-gitea.md, wiki_helper.py
-#    - {{VIKUNJA_PROJECT_ID}} → services.md, vikunja_helper.py (PROJECT_ID)
-#    - references/ → 프로젝트별 아키텍처, 기술스택, 컨벤션 채우기
-
-# 3. docs/devlog/ 디렉토리 생성
-mkdir -p docs/devlog/entries
-
-# 4. AI 에이전트에게 "시작" 또는 "/start" 명령
-```
-
-## 파일 구조
-
-```
-.agents/
-├── AGENT.md                          ← 🧠 글로벌 NEVER/ALWAYS 규칙
-├── GUIDE.md                          ← 📖 상세 가이드
-├── references/                       ← 📚 프로젝트 지식 베이스
-│   ├── architecture.md               ← 아키텍처 (템플릿)
-│   ├── tech-stack.md                 ← 기술 스택 (템플릿)
-│   ├── conventions.md                ← 코딩 컨벤션 (템플릿)
-│   └── known-issues.md               ← 과거 실패 기록 (공통 이슈 포함)
-└── workflows/                        ← ⚙️ 행동 절차
-    ├── start.md                      ← 세션 시작 (룰 로딩 + Git + Vikunja + Wiki)
-    ├── end.md                        ← 세션 종료 (학습 기록 + Vikunja + Git)
-    ├── pre-task.md                   ← 작업 전 필수 체크리스트
-    ├── debug.md                      ← 체계적 디버깅
-    ├── services.md                   ← 서비스 연동 정보 ({{PLACEHOLDER}})
-    ├── check-gitea.md                ← Gitea 현황 조회
-    ├── check-vikunja.md              ← Vikunja 태스크 조회
-    └── helpers/
-        ├── vikunja_helper.py         ← Vikunja API 안전 래퍼
-        └── wiki_helper.py            ← Gitea Wiki 래퍼
-```
-
-## 교체해야 하는 값 (프로젝트별)
-
-> Gitea/Vikunja 토큰은 이미 입력되어 있습니다. 프로젝트별로 아래 2개만 교체하면 됩니다.
-
-| Placeholder | 설명 | 파일 |
-|-------------|------|------|
-| `{{GITEA_REPO}}` | Gitea 저장소명 | services.md, check-gitea.md, wiki_helper.py |
-| `{{VIKUNJA_PROJECT_ID}}` | Vikunja 프로젝트 ID | services.md, vikunja_helper.py (`PROJECT_ID`) |
-
-## 상세 가이드
-
-[GUIDE.md](.agents/GUIDE.md) 참조.
-
-## 연구 기반
-
-7개 AI 에이전트 플랫폼 (Claude, GPT, Gemini, Cursor, Cline, Roo, Windsurf) 분석 + Reflexion Framework, Context Engineering, Sentinel Check 등 최신 연구 기반.
-
-## License
-
-Internal — Variet
--- a/.agents/workflows/check-gitea.md
+++ b/.agents/workflows/check-gitea.md
@@ -1,40 +0,0 @@
---
-description: Gitea APIë¡??€?¥ì†Œ ì»¤ë°‹/?´ìŠˆ/PR ?„í™©??ì¡°íšŒ?˜ëŠ” ?Œí<C592>¬?Œë¡œ??
---
-
-# Gitea ?€?¥ì†Œ ?„í™© ì¡°íšŒ
-
-?œë¹„???•ë³´??`.agents/workflows/services.md` ì°¸ì¡°.
-
-// turbo-all
-
-## ?ˆì°¨
-
-1. ìµœê·¼ ì»¤ë°‹ ì¡°íšŒ (ìµœì‹  10ê°?:
-```powershell
-$h = @{Authorization="token 3a01b4b15a39921572e64c413353e870d4d2161b"}
-$commits = Invoke-RestMethod -Uri "https://git.variet.net/api/v1/repos/Variet/variet-agent/commits?limit=10&sha=main" -Headers $h
-$commits | ForEach-Object { Write-Host "$($_.sha.Substring(0,7)) $($_.commit.message.Split("`n")[0])" }
-```
-
-2. ?´ë¦° ?´ìŠˆ ì¡°íšŒ:
-```powershell
-$h = @{Authorization="token 3a01b4b15a39921572e64c413353e870d4d2161b"}
-$issues = Invoke-RestMethod -Uri "https://git.variet.net/api/v1/repos/Variet/variet-agent/issues?state=open&type=issues" -Headers $h
-$issues | ForEach-Object { Write-Host "#$($_.number) $($_.title)" }
-```
-
-3. Wiki ?˜ì<CB9C>´ì§€ ëª©ë¡<C3AB>:
-```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\wiki_helper.py list
-```
-
-4. Wiki ?˜ì<CB9C>´ì§€ ?½ê¸°:
-```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\wiki_helper.py read "Architecture"
-```
-
-5. Wiki ?˜ì<CB9C>´ì§€ ?…ë<E280A6>°?´íŠ¸:
-```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\wiki_helper.py update "?˜ì<CB9C>´ì§€-?œëª©" /tmp/wiki_content.md
-```
--- a/.agents/workflows/check-vikunja.md
+++ b/.agents/workflows/check-vikunja.md
@@ -1,41 +0,0 @@
---
-description: Vikunja APIë¡??„ë¡œ?<3F>íŠ¸ ?œìŠ¤???„í™©??ì¡°íšŒ?˜ëŠ” ?Œí<C592>¬?Œë¡œ??
---
-
-# Vikunja ?œìŠ¤???„í™© ì¡°íšŒ
-
-?œë¹„???•ë³´??`.agents/workflows/services.md` ì°¸ì¡°.
-
-// turbo-all
-
-## ?ˆì°¨
-
-1. ?„ì²´ ëª©ë¡<C3AB>:
-```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py list
-```
-
-2. TODOë§?
-```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py list todo
-```
-
-3. DONEë§?
-```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py list done
-```
-
-4. ?œìŠ¤???„ë£Œ ì²˜ë¦¬ (**? ï¸<C3AF> ë°˜ë“œ????ë°©ë²• ?¬ìš© ??ì§<C3AC>ì ‘ API ?¸ì¶œ ê¸ˆì?**):
-```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py done {TASK_ID}
-```
-
-5. ???œìŠ¤???<3F>ì„±:
-```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py create "?œëª©" "?¤ëª…" --labels Backend,Priority:High
-```
-
-> [!CAUTION]
-> **?ˆë?ë¡?* `Invoke-RestMethod -Method Post -Body '{"done": true}'` ê°™ì? ì§<C3AC>ì ‘ API ?¸ì¶œ???¬ìš©?˜ì? ë§ˆì„¸??
-> Vikunja API??POST ??body???¬í•¨?˜ì? ?Šì? ?„ë“œë¥?ë¹ˆê°’?¼ë¡œ ??–´?<3F>ë‹ˆ??
-> `vikunja_helper.py`????ƒ<> GET ??ê¸°ì¡´ ?„ë“œ ë³´ì¡´ ??POST ?¨í„´???¬ìš©?©ë‹ˆ??
--- a/.agents/workflows/end.md
+++ b/.agents/workflows/end.md
@@ -1,165 +0,0 @@
---
-description: ?¸ì…˜ ì¢…ë£Œ ??devlog ê¸°ë¡<C3AB> + git commit + Vikunja ?™ê¸°??(?? ë§ˆë¬´ë¦? ì»¤ë°‹?? ?„ë£Œ)
---
-
-# ?¸ì…˜ ì¢…ë£Œ ?„ë¡œ? ì½œ
-
-?‘ì—… ?„ë£Œ, "??, "ë§ˆë¬´ë¦?, "ì»¤ë°‹?? ???”ì² ?????Œí<C592>¬?Œë¡œ?°ë? ?¤í–‰?©ë‹ˆ??
-
-// turbo-all
-
-## 0. ?™ìŠµ ê¸°ë¡<C3AB> (?¤íŒ¨/?œí–‰ì°©ì˜¤ ?€??
-
-?´ë²ˆ ?¸ì…˜?<3F>ì„œ ë°œìƒ<C3AC>???¤íŒ¨, ?œí–‰ì°©ì˜¤, ?ˆë¡œ ?Œê²Œ ???¬ì‹¤???•ë¦¬?©ë‹ˆ??
-
- [ ] `.agents/references/known-issues.md`??ì¶”ê?????ª©???ˆëŠ”ì§€ ?•ì<E280A2>¸
- [ ] ?ˆë‹¤ë©??„ëž˜ ?¬ë§·?¼ë¡œ ì¶”ê?:
-
-```markdown
-### [? ì§œ] [?¤ì›Œ?? ???œì¤„ ?”ì•½
- **ì¦<C3AC>ìƒ<C3AC>**: ...
- **?<3F>ì<EFBFBD>¸**: ...
- **?´ê²°**: ...
- **ì£¼ì<C2BC>˜**: ...
-```
-
-## 1. Devlog ê¸°ë¡<C3AB>
-
-### Index ?…ë<E280A6>°?´íŠ¸ (?„ìˆ˜ ??ë§??‘ì—…)
-
-?¤ëŠ˜ ? ì§œ??index ?Œì<C592>¼???„ë£Œ???‘ì—… 1ì¤„ì<E2809E>„ ì¶”ê??©ë‹ˆ??
-
- **?Œì<C592>¼**: `docs/devlog/YYYY-MM-DD.md`
- **?•ì‹<C3AC>**:
-```markdown
-| NNN | HH:MM | ?‘ì—… ?¤ëª… | `ì»¤ë°‹?´ì‹œ` | ???<3F>ëŠ” ?”§ |
-```
-
-> [!TIP]
-> - ??= ?„ë£Œ, ?”§ = ë¯¸ì™„ë£?(?¤ì<C2A4>Œ ?¸ì…˜?<3F>ì„œ ?´ì–´ë°›ê¸°)
-> - ?Œì<C592>¼???†ìœ¼ë©??ˆë¡œ ?<3F>ì„± (?Œì<C592>´ë¸??¤ë<C2A4>” ?¬í•¨)
-
-### Entry ?‘ì„± (? íƒ<C3AD>?????„ìš”???Œë§Œ)
-
-> [!IMPORTANT]
-> Entry??**git/Vikunja/wiki???†ëŠ” ?•ë³´**ê°€ ?ˆì<CB86>„ ?Œë§Œ ?‘ì„±?©ë‹ˆ??
-
-**Entry ?‘ì„± ê¸°ì?:**
- ???¤ê³„ ê²°ì •???ˆì—ˆ????(??Aê°€ ?„ë‹Œ Bë¥?? íƒ<C3AD>?ˆëŠ”ì§€)
- ??ë¯¸ì™„ë£??¬í•???ˆì<CB86>„ ??(?¤ì<C2A4>Œ ?¸ì…˜???´ì–´ë°›ì•„????ë§¥ë<C2A5>½)
- ???½ì§ˆ/?¸ëŸ¬ë¸”ìŠˆ?…ì<E280A6>´ ?ˆì—ˆ????(ê°™ì? ?¤ìˆ˜ ë°©ì?)
-
-**Entry ë¶ˆí•„??**
- ???¨ìˆœ ë²„ê·¸ ?½ìŠ¤ (ì»¤ë°‹ ë©”ì‹œì§€ë¡?ì¶©ë¶„)
- ??ë¬¸ì„œ ?…ë<E280A6>°?´íŠ¸ (git diffë¡?ì¶©ë¶„)
- ???´ë? Vikunja ?œìŠ¤?¬ì—<C3AC> ?<3F>ì„¸ ?¤ëª…???ˆëŠ” ê²½ìš°
-
-**Entry ?Œì<C592>¼**: `docs/devlog/entries/YYYYMMDD-NNN.md`
-```markdown
-# ?‘ì—… ?œëª©
-
- **?œê°„**: YYYY-MM-DD HH:MM~HH:MM
- **Commit**: `?´ì‹œ`
- **Vikunja**: #?œìŠ¤?¬ë²ˆ????done/ì§„í–‰ì¤?
-
-## ê²°ì • ?¬í•
- ????ë°©ì‹<C3AC>??? íƒ<C3AD>?ˆëŠ”ì§€
-
-## ë¯¸ì™„ë£?
- ?¨ì? ?‘ì—… (?ˆì<CB86>„ ê²½ìš°)
-```
-
---
-
-## 2. Vikunja ?™ê¸°??
-
-> [!CAUTION]
-> **ë°˜ë“œ??`vikunja_helper.py` ?¬ìš©.** ì§<C3AC>ì ‘ API ?¸ì¶œ ê¸ˆì?.
-> Vikunja API??POST ??body???†ëŠ” ?„ë“œë¥?ë¹ˆê°’?¼ë¡œ ??–´?<3F>ë‹ˆ??
-
-### 2-1. ì»¤ë°‹ ?„ìˆ˜ ê²€??
-
-?´ë²ˆ ?¸ì…˜??**ëª¨ë“  ì»¤ë°‹???˜ë‚˜??ê²€??*?˜ê³  Vikunja??ë§¤í•‘?©ë‹ˆ??
-
-```powershell
-git log --oneline -20
-```
-
-| ì»¤ë°‹ ? í˜• | Vikunja ?¡ì…˜ |
-|-----------|-------------|
-| ê¸°ì¡´ ?œìŠ¤???´ë‹¹ ?‘ì—… **?„ë£Œ** | `C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py done {ID}` |
-| ? ê·œ ?‘ì—… ?„ë£Œ (ê¸°ì¡´ ?œìŠ¤???†ì<E280A0>Œ) | `C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py create "?œëª©" "?¤ëª…" --done --labels Backend,Priority:High` |
-| ?‘ì—… ì¤?ë°œê²¬??**ë¯¸ì™„ë£?TODO** | `C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py create "?œëª©" "?¤ëª…" --labels Backend,Priority:Mid` |
-
-> [!IMPORTANT]
-> ëª¨ë“  ì»¤ë°‹??ê¸°ì¡´ ?<3F>ëŠ” ? ê·œ ?œìŠ¤?¬ì—<C3AC> ë§¤í•‘?˜ì—ˆ?”ì? ?•ì<E280A2>¸.
-
-### 2-2. ?„ë£Œ ì²˜ë¦¬
-
-```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py done {TASK_ID}
-```
-
-### 2-3. ? ê·œ ?œìŠ¤???<3F>ì„±
-
-```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py create "?œëª©" "?¤ëª…" --labels Backend,Priority:High
-```
-
-### ?¼ë²¨ ê·œì¹™
-
-**?<3F>ì— (?„ìˆ˜ 1ê°??´ìƒ<C3AC>):** `Backend` / `Frontend` / `Engine` / `Infra` / `Test`
-**?°ì„ ?œìœ„ (?„ìˆ˜ 1ê°?:** `Priority:High` / `Priority:Mid` / `Priority:Low`
-
---
-
-## 3. Wiki ?™ê¸°??(?´ë‹¹ ?œì—<C3AC>ë§?
-
-| ì½”ë“œ ë³€ê²?| ?€??Wiki |
-|-----------|----------|
-| ?œë²„ ë³€ê²?| Architecture |
-| ?„ë¡ ?¸ì—”??ë³€ê²?| Architecture |
-| ?¸í”„??ë³€ê²?| Architecture |
-| ??ëª¨ë“ˆ/?¨í‚¤ì§€ ì¶”ê? | Architecture |
-
-```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\wiki_helper.py update "Architecture" /tmp/wiki_content.md
-```
-
---
-
-## 4. Git Commit & Push
-
-```powershell
-git add -A
-git status --short
-```
-```powershell
-git commit -m "ì»¤ë°‹ ë©”ì‹œì§€"
-```
-```powershell
-git push origin main
-```
-
-**ì»¤ë°‹ ë©”ì‹œì§€ ì»¨ë²¤??**
-```
-<type>(<scope>): <description>
-
-type: feat|fix|refactor|test|docs|chore|ci|infra
-scope: (? íƒ<C3AD>)
-```
-
---
-
-## 5. ìµœì¢… ì²´í<C2B4>¬ë¦¬ìŠ¤??
-
-> [!WARNING]
-> ?„ëž˜ ??ª© ì¤??˜ë‚˜?¼ë<C2BC>„ ?„ë<E2809E>½?˜ë©´ ?¸ì…˜ ì¢…ë£Œë¥??„ë£Œ?????†ìŠµ?ˆë‹¤.
-
- [ ] known-issues ?…ë<E280A6>°?´íŠ¸??(???´ìŠˆê°€ ?ˆì—ˆ?¤ë©´)
- [ ] devlog index ?…ë<E280A6>°?´íŠ¸??
- [ ] devlog entry ?‘ì„±??(?„ìš”??ê²½ìš°ë§?
- [ ] Vikunja ?œìŠ¤???<3F>ì„±/?„ë£Œ ì²˜ë¦¬??(ì»¤ë°‹ ?„ìˆ˜ ê²€??ê¸°ë°˜)
- [ ] Wiki ?™ê¸°?”ë<E2809D>¨ (?„í‚¤?<3F>ì²˜ ë³€ê²½ì<C2BD>´ ?ˆì—ˆ?¤ë©´)
- [ ] git push ?„ë£Œ
- [ ] ?¬ìš©?<3F>ì—<C3AC>ê²??„ë£Œ ë³´ê³ 
--- a/.agents/workflows/start.md
+++ b/.agents/workflows/start.md
@@ -1,65 +0,0 @@
---
-description: ?¸ì…˜ ?œìž‘ ???„ë¡œ?<3F>íŠ¸ ë§¥ë<C2A5>½??ë¹ ë¥´ê²?ë³µêµ¬?˜ëŠ” ?Œí<C592>¬?Œë¡œ??(?œìž‘, continue, ?´ì–´?? ?‘ì—… ?œìž‘)
---
-
-# ?¸ì…˜ ?œìž‘ ?„ë¡œ? ì½œ
-
-???€???œìž‘, "continue", "?´ì–´??, "?‘ì—… ?œìž‘" ???”ì² ?????Œí<C592>¬?Œë¡œ?°ë? ?¤í–‰?©ë‹ˆ??
-
-// turbo-all
-
-## ?ˆì°¨
-
-### 0. ?<3F>ì<EFBFBD>´?„íŠ¸ ë£?& ë§¥ë<C2A5>½ ë¡œë”© (?<3F>ë<EFBFBD>™)
-
-`.agents/AGENT.md`ë¥??½ê³  ?<3F>ì<EFBFBD>´?„íŠ¸ ?‰ë<E280B0>™ ê·œì¹™??ë¡œë”©?©ë‹ˆ??
-`.agents/references/known-issues.md`ë¥??½ì–´ ìµœê·¼ ?´ìŠˆë¥??Œì•…?©ë‹ˆ??
-
-### 1. Devlog ë§¥ë<C2A5>½ ë³µêµ¬
-
-?¤ëŠ˜ + ?´ì œ devlog indexë¥??½ê³  ìµœê·¼ ?‘ì—… ?<3F>ë¦„???Œì•…?©ë‹ˆ??
-
-```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 ?Œì<C592>¼???½ì–´ ?´ì–´ë°›ê¸° ë§¥ë<C2A5>½???•ë³´?©ë‹ˆ??
- Entry ê²½ë¡œ: `docs/devlog/entries/YYYYMMDD-NNN.md`
-
-### 2. Git ?<3F>íƒœ ?•ì<E280A2>¸
-
-```powershell
-git status --short
-```
-```powershell
-git log --oneline -5
-```
-
-### 3. Vikunja TODO ?œìŠ¤??
-
-```powershell
-C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py list todo
-```
-
-### 4. ì¢…í•© ë³´ê³ 
-
-ê²°ê³¼ë¥?ì¢…í•©?˜ì—¬ ?¬ìš©?<3F>ì—<C3AC>ê²?ë³´ê³ :
- ë§ˆì?ë§??‘ì—… ë§¥ë<C2A5>½ + ë¯¸ì™„ë£???ª© (devlog ?”§ ê¸°ë°˜)
- TODO ?œìŠ¤??ëª©ë¡<C3AB> (?¼ë²¨ + ?°ì„ ?œìœ„)
- ?¤ì<C2A4>Œ ?‘ì—… ?œì•ˆ
-
-**?°ì„ ?œìœ„ ?<3F>ë‹¨ ê¸°ì?** (?¼ë²¨ë§Œìœ¼ë¡??<3F>ë‹¨ ê¸ˆì?):
- P0: ìµœê·¼ ì»¤ë°‹?<3F>ì„œ ?¤í‚¤ë§?ëª¨ë<C2A8>¸/?¸í„°?˜ì<CB9C>´??ë³€ê²????°ì‡„ ?<3F>í–¥ ?<3F>ê?
- P1: ?œë²„ ê¸°ë<C2B0>™/API ?‘ë‹µ ?¥ì• 
- P2: ê¸°ëŠ¥ ë¯¸ì™„??UX ê°œì„ 
- P3: ?•í™•???¥ìƒ<C3AC>, ? ê·œ ê¸°ëŠ¥, CI/CD, ë¬¸ì„œ ?•ë¦¬
--- a/docs/devlog/2026-03-11.md
+++ b/docs/devlog/2026-03-11.md
@@ -0,0 +1,5 @@
+# 2026-03-11 Devlog
+
+| # | 시간 | 작업 | 커밋 | 상태 |
+|---|------|------|------|------|
+| 001 | 01:00 | .agents + .agent → 단일 .agent 통합 (agent_guide 포맷 기준, 12→7 워크플로우 축소) | `pending` | ✅ |