chore: Agent Guide 셋업 — agent_guide.git 기반 .agents 재구성 + 프로젝트별 설정

2026-03-10 22:51:14 +09:00
parent e1aca2b79f
commit 044200a786
11 changed files with 287 additions and 154 deletions
--- a/.agents/workflows/end.md
+++ b/.agents/workflows/end.md
@@ -1,129 +1,129 @@
 ---
-description: 세션 종료 시 devlog 기록 + git commit + Vikunja 동기화 (끝, 마무리, 커밋해, 완료)
+description: ?¸ì…˜ ì¢…ë£Œ ??devlog ê¸°ë¡<EFBFBD> + git commit + Vikunja ?™ê¸°??(?? ë§ˆë¬´ë¦? ì»¤ë°‹?? ?„ë£Œ)
 ---

-# 세션 종료 프로토콜
+# ?¸ì…˜ ì¢…ë£Œ ?„ë¡œ? ì½œ

-작업 완료, "끝", "마무리", "커밋해" 등 요청 시 이 워크플로우를 실행합니다.
+?‘ì—… ?„ë£Œ, "??, "ë§ˆë¬´ë¦?, "ì»¤ë°‹?? ???”ì² ?????Œí<C592>¬?Œë¡œ?°ë? ?¤í–‰?©ë‹ˆ??

 // turbo-all

-## 0. 학습 기록 (실패/시행착오 저장)
+## 0. ?™ìŠµ ê¸°ë¡<C3AB> (?¤íŒ¨/?œí–‰ì°©ì˜¤ ?€??

-이번 세션에서 발생한 실패, 시행착오, 새로 알게 된 사실을 정리합니다:
+?´ë²ˆ ?¸ì…˜?<3F>ì„œ ë°œìƒ<C3AC>???¤íŒ¨, ?œí–‰ì°©ì˜¤, ?ˆë¡œ ?Œê²Œ ???¬ì‹¤???•ë¦¬?©ë‹ˆ??

- [ ] `.agents/references/known-issues.md`에 추가할 항목이 있는지 확인
- [ ] 있다면 아래 포맷으로 추가:
+- [ ] `.agents/references/known-issues.md`??ì¶”ê?????ª©???ˆëŠ”ì§€ ?•ì<E280A2>¸
+- [ ] ?ˆë‹¤ë©??„ëž˜ ?¬ë§·?¼ë¡œ ì¶”ê?:

 ```markdown
-### [날짜] [키워드] — 한줄 요약
+### [? ì§œ] [?¤ì›Œ?? ???œì¤„ ?”ì•½
 - **ì¦<C3AC>ìƒ<C3AC>**: ...
- **원인**: ...
- **해결**: ...
+- **?<3F>ì<EFBFBD>¸**: ...
+- **?´ê²°**: ...
 - **ì£¼ì<C2BC>˜**: ...
 ```

 ## 1. Devlog ê¸°ë¡<C3AB>

-### Index 업데이트 (필수 — 매 작업)
+### Index ?…ë<E280A6>°?´íŠ¸ (?„ìˆ˜ ??ë§??‘ì—…)

-오늘 날짜의 index 파일에 완료된 작업 1줄을 추가합니다.
+?¤ëŠ˜ ? ì§œ??index ?Œì<C592>¼???„ë£Œ???‘ì—… 1ì¤„ì<E2809E>„ ì¶”ê??©ë‹ˆ??

- **파일**: `docs/devlog/YYYY-MM-DD.md`
- **형식**:
+- **?Œì<C592>¼**: `docs/devlog/YYYY-MM-DD.md`
+- **?•ì‹<C3AC>**:
 ```markdown
-| NNN | HH:MM | 작업 설명 | `커밋해시` | ✅ 또는 🔧 |
+| NNN | HH:MM | ?‘ì—… ?¤ëª… | `ì»¤ë°‹?´ì‹œ` | ???<3F>ëŠ” ?”§ |
 ```

 > [!TIP]
-> - ✅ = 완료, 🔧 = 미완료 (다음 세션에서 이어받기)
-> - 파일이 없으면 새로 생성 (테이블 헤더 포함)
+> - ??= ?„ë£Œ, ?”§ = ë¯¸ì™„ë£?(?¤ì<C2A4>Œ ?¸ì…˜?<3F>ì„œ ?´ì–´ë°›ê¸°)
+> - ?Œì<C592>¼???†ìœ¼ë©??ˆë¡œ ?<3F>ì„± (?Œì<C592>´ë¸??¤ë<C2A4>” ?¬í•¨)

-### Entry 작성 (선택적 — 필요할 때만)
+### Entry ?‘ì„± (? íƒ<C3AD>?????„ìš”???Œë§Œ)

 > [!IMPORTANT]
-> Entry는 **git/Vikunja/wiki에 없는 정보**가 있을 때만 작성합니다.
+> Entry??**git/Vikunja/wiki???†ëŠ” ?•ë³´**ê°€ ?ˆì<CB86>„ ?Œë§Œ ?‘ì„±?©ë‹ˆ??

-**Entry 작성 기준:**
- ✅ 설계 결정이 있었을 때 (왜 A가 아닌 B를 선택했는지)
- ✅ 미완료 사항이 있을 때 (다음 세션이 이어받아야 할 맥락)
- ✅ 삽질/트러블슈팅이 있었을 때 (같은 실수 방지)
+**Entry ?‘ì„± ê¸°ì?:**
+- ???¤ê³„ ê²°ì •???ˆì—ˆ????(??Aê°€ ?„ë‹Œ Bë¥?? íƒ<C3AD>?ˆëŠ”ì§€)
+- ??ë¯¸ì™„ë£??¬í•???ˆì<CB86>„ ??(?¤ì<C2A4>Œ ?¸ì…˜???´ì–´ë°›ì•„????ë§¥ë<C2A5>½)
+- ???½ì§ˆ/?¸ëŸ¬ë¸”ìŠˆ?…ì<E280A6>´ ?ˆì—ˆ????(ê°™ì? ?¤ìˆ˜ ë°©ì?)

-**Entry 불필요:**
- ❌ 단순 버그 픽스 (커밋 메시지로 충분)
- ❌ 문서 업데이트 (git diff로 충분)
- ❌ 이미 Vikunja 태스크에 상세 설명이 있는 경우
+**Entry ë¶ˆí•„??**
+- ???¨ìˆœ ë²„ê·¸ ?½ìŠ¤ (ì»¤ë°‹ ë©”ì‹œì§€ë¡?ì¶©ë¶„)
+- ??ë¬¸ì„œ ?…ë<E280A6>°?´íŠ¸ (git diffë¡?ì¶©ë¶„)
+- ???´ë? Vikunja ?œìŠ¤?¬ì—<C3AC> ?<3F>ì„¸ ?¤ëª…???ˆëŠ” ê²½ìš°

-**Entry 파일**: `docs/devlog/entries/YYYYMMDD-NNN.md`
+**Entry ?Œì<C592>¼**: `docs/devlog/entries/YYYYMMDD-NNN.md`
 ```markdown
-# 작업 제목
+# ?‘ì—… ?œëª©

- **시간**: YYYY-MM-DD HH:MM~HH:MM
- **Commit**: `해시`
- **Vikunja**: #태스크번호 → done/진행중
+- **?œê°„**: YYYY-MM-DD HH:MM~HH:MM
+- **Commit**: `?´ì‹œ`
+- **Vikunja**: #?œìŠ¤?¬ë²ˆ????done/ì§„í–‰ì¤?

-## 결정 사항
- 왜 이 방식을 선택했는지
+## ê²°ì • ?¬í•
+- ????ë°©ì‹<C3AC>??? íƒ<C3AD>?ˆëŠ”ì§€

-## 미완료
- 남은 작업 (있을 경우)
+## ë¯¸ì™„ë£?
+- ?¨ì? ?‘ì—… (?ˆì<CB86>„ ê²½ìš°)
 ```

 ---

-## 2. Vikunja 동기화
+## 2. Vikunja ?™ê¸°??

 > [!CAUTION]
-> **반드시 `vikunja_helper.py` 사용.** 직접 API 호출 금지.
-> Vikunja API는 POST 시 body에 없는 필드를 빈값으로 덮어씁니다.
+> **ë°˜ë“œ??`vikunja_helper.py` ?¬ìš©.** ì§<C3AC>ì ‘ API ?¸ì¶œ ê¸ˆì?.
+> Vikunja API??POST ??body???†ëŠ” ?„ë“œë¥?ë¹ˆê°’?¼ë¡œ ??–´?<3F>ë‹ˆ??

-### 2-1. 커밋 전수 검사
+### 2-1. ì»¤ë°‹ ?„ìˆ˜ ê²€??

-이번 세션의 **모든 커밋을 하나씩 검사**하고 Vikunja에 매핑합니다.
+?´ë²ˆ ?¸ì…˜??**ëª¨ë“  ì»¤ë°‹???˜ë‚˜??ê²€??*?˜ê³  Vikunja??ë§¤í•‘?©ë‹ˆ??

 ```powershell
 git log --oneline -20
 ```

-| 커밋 유형 | Vikunja 액션 |
+| ì»¤ë°‹ ? í˜• | Vikunja ?¡ì…˜ |
 |-----------|-------------|
-| 기존 태스크 해당 작업 **완료** | `C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\vikunja_helper.py done {ID}` |
-| 신규 작업 완료 (기존 태스크 없음) | `C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --done --labels Backend,Priority:High` |
-| 작업 중 발견된 **미완료 TODO** | `C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:Mid` |
+| ê¸°ì¡´ ?œìŠ¤???´ë‹¹ ?‘ì—… **?„ë£Œ** | `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. 완료 처리
+### 2-2. ?„ë£Œ ì²˜ë¦¬

 ```powershell
-C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\vikunja_helper.py done {TASK_ID}
+C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py done {TASK_ID}
 ```

-### 2-3. 신규 태스크 생성
+### 2-3. ? ê·œ ?œìŠ¤???<3F>ì„±

 ```powershell
-C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:High
+C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py create "?œëª©" "?¤ëª…" --labels Backend,Priority:High
 ```

-### 라벨 규칙
+### ?¼ë²¨ ê·œì¹™

-**영역 (필수 1개 이상):** `Backend` / `Frontend` / `Engine` / `Infra` / `Test`
-**우선순위 (필수 1개):** `Priority:High` / `Priority:Mid` / `Priority:Low`
+**?<3F>ì— (?„ìˆ˜ 1ê°??´ìƒ<C3AC>):** `Backend` / `Frontend` / `Engine` / `Infra` / `Test`
+**?°ì„ ?œìœ„ (?„ìˆ˜ 1ê°?:** `Priority:High` / `Priority:Mid` / `Priority:Low`

 ---

-## 3. Wiki 동기화 (해당 시에만)
+## 3. Wiki ?™ê¸°??(?´ë‹¹ ?œì—<C3AC>ë§?

-| 코드 변경 | 대상 Wiki |
+| ì½”ë“œ ë³€ê²?| ?€??Wiki |
 |-----------|----------|
-| 서버 변경 | Architecture |
-| 프론트엔드 변경 | Architecture |
-| 인프라 변경 | Architecture |
-| 새 모듈/패키지 추가 | Architecture |
+| ?œë²„ ë³€ê²?| Architecture |
+| ?„ë¡ ?¸ì—”??ë³€ê²?| Architecture |
+| ?¸í”„??ë³€ê²?| Architecture |
+| ??ëª¨ë“ˆ/?¨í‚¤ì§€ ì¶”ê? | Architecture |

 ```powershell
-C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\wiki_helper.py update "Architecture" /tmp/wiki_content.md
+C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\wiki_helper.py update "Architecture" /tmp/wiki_content.md
 ```

 ---
@@ -141,25 +141,25 @@ git commit -m "커밋 메시지"
 git push origin main
 ```

-**커밋 메시지 컨벤션:**
+**ì»¤ë°‹ ë©”ì‹œì§€ ì»¨ë²¤??**
 ```
 <type>(<scope>): <description>

 type: feat|fix|refactor|test|docs|chore|ci|infra
-scope: (선택)
+scope: (? íƒ<C3AD>)
 ```

 ---

-## 5. 최종 체크리스트
+## 5. ìµœì¢… ì²´í<C2B4>¬ë¦¬ìŠ¤??

 > [!WARNING]
-> 아래 항목 중 하나라도 누락되면 세션 종료를 완료할 수 없습니다.
+> ?„ëž˜ ??ª© ì¤??˜ë‚˜?¼ë<C2BC>„ ?„ë<E2809E>½?˜ë©´ ?¸ì…˜ ì¢…ë£Œë¥??„ë£Œ?????†ìŠµ?ˆë‹¤.

- [ ] known-issues 업데이트됨 (새 이슈가 있었다면)
- [ ] devlog index 업데이트됨
- [ ] devlog entry 작성됨 (필요한 경우만)
- [ ] Vikunja 태스크 생성/완료 처리됨 (커밋 전수 검사 기반)
- [ ] Wiki 동기화됨 (아키텍처 변경이 있었다면)
- [ ] git push 완료
- [ ] 사용자에게 완료 보고
+- [ ] known-issues ?…ë<E280A6>°?´íŠ¸??(???´ìŠˆê°€ ?ˆì—ˆ?¤ë©´)
+- [ ] devlog index ?…ë<E280A6>°?´íŠ¸??
+- [ ] devlog entry ?‘ì„±??(?„ìš”??ê²½ìš°ë§?
+- [ ] Vikunja ?œìŠ¤???<3F>ì„±/?„ë£Œ ì²˜ë¦¬??(ì»¤ë°‹ ?„ìˆ˜ ê²€??ê¸°ë°˜)
+- [ ] Wiki ?™ê¸°?”ë<E2809D>¨ (?„í‚¤?<3F>ì²˜ ë³€ê²½ì<C2BD>´ ?ˆì—ˆ?¤ë©´)
+- [ ] git push ?„ë£Œ
+- [ ] ?¬ìš©?<3F>ì—<C3AC>ê²??„ë£Œ ë³´ê³