refactor: .agents + .agent 단일 .agent 디렉토리로 통합 (agent_guide 포맷, 12→7 워크플로우 축소)
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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/
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -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>Œ ?‘ì—… ?œì•ˆ
|
||||
@@ -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 패턴을 사용합니다.
|
||||
|
||||
@@ -16,7 +16,7 @@ description: 에러/버그 발생 시 체계적 디버깅 워크플로우 (에
|
||||
|
||||
## 2단계: Known Issues 확인
|
||||
|
||||
`.agents/references/known-issues.md`를 읽고 동일하거나 유사한 문제가 있는지 확인합니다.
|
||||
`.agent/references/known-issues.md`를 읽고 동일하거나 유사한 문제가 있는지 확인합니다.
|
||||
|
||||
> [!CAUTION]
|
||||
> **known-issues 확인 없이 해결 시도를 시작하지 마세요.**
|
||||
@@ -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
|
||||
```
|
||||
165
.agent/workflows/end.md
Normal file
165
.agent/workflows/end.md
Normal file
@@ -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 완료
|
||||
- [ ] 사용자에게 완료 보고
|
||||
@@ -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: 버전별 변경 이력
|
||||
@@ -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]
|
||||
65
.agent/workflows/start.md
Normal file
65
.agent/workflows/start.md
Normal file
@@ -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, 문서 정리
|
||||
@@ -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 관련 페이지 업데이트
|
||||
@@ -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
|
||||
```
|
||||
@@ -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()
|
||||
@@ -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
|
||||
@@ -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
|
||||
```
|
||||
@@ -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 ?¨í„´???¬ìš©?©ë‹ˆ??
|
||||
@@ -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>ê²??„료 ë³´ê³
|
||||
@@ -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, 문서 ?•ë¦¬
|
||||
5
docs/devlog/2026-03-11.md
Normal file
5
docs/devlog/2026-03-11.md
Normal file
@@ -0,0 +1,5 @@
|
||||
# 2026-03-11 Devlog
|
||||
|
||||
| # | 시간 | 작업 | 커밋 | 상태 |
|
||||
|---|------|------|------|------|
|
||||
| 001 | 01:00 | .agents + .agent → 단일 .agent 통합 (agent_guide 포맷 기준, 12→7 워크플로우 축소) | `c6381a7` | ✅ |
|
||||
Reference in New Issue
Block a user