chore: Agent Guide 셋업 — agent_guide.git 기반 .agents 재구성 + 프로젝트별 설정
This commit is contained in:
@@ -49,7 +49,6 @@ description: 모든 작업에 자동 적용되는 에이전트 행동 규칙.
|
||||
|
||||
## PowerShell Notes
|
||||
|
||||
- **Python**: `C:\ProgramData\miniforge3\envs\gravity_web\python.exe` 사용 (시스템 `python` 대신)
|
||||
- `curl` → PowerShell에서 `Invoke-WebRequest` 별칭. **반드시 `curl.exe`** 사용
|
||||
- `npm` → 실행 정책 문제 시 `cmd /c npm` 사용
|
||||
- JSON 처리 시 `.py` 스크립트 권장 (PowerShell 이스케이핑 이슈 방지)
|
||||
|
||||
67
.agents/README.md
Normal file
67
.agents/README.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# 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,35 +1,75 @@
|
||||
# Architecture
|
||||
|
||||
> 이 프로젝트의 아키텍처를 설명하는 문서입니다.
|
||||
> AI 에이전트는 구현 전 이 문서를 반드시 확인합니다.
|
||||
> Variet Agent — Gemini CLI 기반 AI Agent Team 시스템
|
||||
|
||||
## 프로젝트 개요
|
||||
|
||||
<!-- 프로젝트의 목적과 핵심 기능을 간략히 서술 -->
|
||||
|
||||
(프로젝트 설명을 여기에 작성하세요)
|
||||
사용자가 디스코드에서 자연어 명령 → AI Agent Team이 코드 분석/분해/실행 → Gitea CI로 PR/빌드/배포.
|
||||
Gemini CLI를 서브프로세스(`asyncio.create_subprocess_exec`)로 래핑하여 역할별 독립 컨텍스트로 호출.
|
||||
|
||||
## 디렉토리 구조
|
||||
|
||||
```
|
||||
project-root/
|
||||
├── src/ # 소스 코드
|
||||
├── tests/ # 테스트
|
||||
├── docs/ # 문서
|
||||
├── .agents/ # AI 에이전트 설정
|
||||
└── ...
|
||||
variet-agent/
|
||||
├── main.py # 진입점 (FastAPI + Discord Bot 동시 실행)
|
||||
├── config.py # .env 기반 설정 관리
|
||||
├── api/
|
||||
│ ├── server.py # FastAPI REST 서버
|
||||
│ ├── discord_bot.py # Discord Bot (NLU + PCRS 파이프라인 + 애니 핸들러)
|
||||
│ └── models.py # 요청/응답 모델
|
||||
├── core/
|
||||
│ ├── task_pipeline.py # PCRS: Plan → Code → Review → Summarize
|
||||
│ ├── gemini_caller.py # Gemini CLI 래퍼 (text/agent 모드)
|
||||
│ ├── context_manager.py # 관련 파일 선별 + 토큰 예산 제어
|
||||
│ ├── project_indexer.py # 프로젝트 구조 스캔/캐시
|
||||
│ ├── workspace.py # 워크스페이스 관리 (채널 ↔ 프로젝트 매핑)
|
||||
│ ├── file_applier.py # 코드 변경 적용
|
||||
│ └── docs_manager.py # 문서/세션 기록
|
||||
├── tools/ # 자동화 도구 (애니메이션 파이프라인)
|
||||
│ ├── anime_pipeline.py # 통합 파이프라인 (검색/다운/자막/상태)
|
||||
│ ├── anissia_client.py # Anissia 편성표 API
|
||||
│ ├── nyaa_client.py # Nyaa 토렌트 검색
|
||||
│ ├── qbit_client.py # qBittorrent 제어
|
||||
│ ├── nas_scanner.py # NAS 파일 스캔
|
||||
│ ├── title_matcher.py # 제목 매칭 (로마지/퍼지)
|
||||
│ └── subtitle_downloader.py # 자막 다운로더
|
||||
├── integrations/
|
||||
│ ├── gitea_client.py # Gitea API (PR/이슈)
|
||||
│ ├── vikunja_client.py # Vikunja 태스크 관리
|
||||
│ └── ci_monitor.py # CI 결과 모니터링
|
||||
└── prompts/ # AI 역할별 프롬프트
|
||||
├── unified.md # NLU 분류 (chat/task/anime/clarify)
|
||||
├── planner.md # 태스크 분해
|
||||
├── coder.md # 코드 구현
|
||||
├── reviewer.md # 코드 리뷰
|
||||
└── summarizer.md # 총평 생성
|
||||
```
|
||||
|
||||
## 핵심 모듈
|
||||
|
||||
<!-- 각 모듈의 역할과 의존 관계를 설명 -->
|
||||
|
||||
| 모듈 | 역할 | 의존성 |
|
||||
|------|------|--------|
|
||||
| (모듈명) | (역할 설명) | (의존하는 모듈) |
|
||||
| `discord_bot.py` | 사용자 인터페이스 + NLU 분류 | `workspace.py`, `gemini_caller.py`, `task_pipeline.py` |
|
||||
| `task_pipeline.py` | PCRS 오케스트레이션 (Inner/Outer 루프) | `gemini_caller.py`, `context_manager.py`, `project_indexer.py` |
|
||||
| `gemini_caller.py` | Gemini CLI 서브프로세스 호출 (text/agent) | `prompts/` |
|
||||
| `context_manager.py` | 태스크 기반 파일 선별 + 토큰 예산 | `project_indexer.py` |
|
||||
| `workspace.py` | 채널 ↔ 프로젝트 경로 매핑, workspaces.json 관리 | — |
|
||||
| `anime_pipeline.py` | 애니 자동화 통합 | `anissia_client.py`, `nyaa_client.py`, `qbit_client.py`, `nas_scanner.py` |
|
||||
|
||||
## 데이터 흐름
|
||||
|
||||
<!-- 주요 데이터 흐름을 Mermaid 다이어그램이나 텍스트로 설명 -->
|
||||
|
||||
(데이터 흐름을 여기에 작성하세요)
|
||||
```
|
||||
Discord 메시지
|
||||
→ on_message()
|
||||
→ _unified_call() — NLU 분류 (chat/task/anime/clarify)
|
||||
├─ chat → 즉답
|
||||
├─ clarify → 질문 임베드
|
||||
├─ anime → _handle_anime() → AnimePipeline
|
||||
└─ task → _handle_task()
|
||||
→ TaskPipeline.plan() — Planner (태스크 분해)
|
||||
→ TaskPipeline.code_parallel() — Coder (에이전트 모드, cwd=프로젝트)
|
||||
→ TaskPipeline.planner_verify() — 내부 자가검증 (Inner Loop)
|
||||
→ TaskPipeline.batch_review() — Reviewer (Outer Loop)
|
||||
→ TaskPipeline.summarize() — 총평
|
||||
→ Discord Embed 보고
|
||||
```
|
||||
|
||||
@@ -6,32 +6,54 @@
|
||||
|
||||
| 항목 | 버전 | 비고 |
|
||||
|------|------|------|
|
||||
| (예: Node.js) | (예: 20.x) | (설치 경로 등) |
|
||||
| (예: Python) | (예: 3.12) | (가상환경 경로 등) |
|
||||
| Python | 3.12+ | `C:\ProgramData\miniforge3\envs\agent_chat\python.exe` |
|
||||
| Gemini CLI | v0.32+ (AI Ultra) | `gemini --model gemini-3-flash-preview` |
|
||||
|
||||
## 프레임워크
|
||||
|
||||
| 항목 | 버전 | 용도 |
|
||||
|------|------|------|
|
||||
| (예: Express) | (예: 4.18) | (서버) |
|
||||
| (예: React) | (예: 18.x) | (프론트엔드) |
|
||||
| FastAPI | 최신 | REST API 서버 |
|
||||
| discord.py | 2.x | Discord Bot |
|
||||
| uvicorn | 최신 | ASGI 서버 |
|
||||
| httpx | 최신 | 비동기 HTTP 클라이언트 (tools/) |
|
||||
|
||||
## 패키지 관리
|
||||
|
||||
- 패키지 매니저: (npm / yarn / pnpm / pip 등)
|
||||
- Lock 파일: (package-lock.json / yarn.lock 등)
|
||||
- 패키지 매니저: pip (conda env `agent_chat`)
|
||||
- 의존성 파일: `requirements.txt`
|
||||
- 가상환경: `C:\ProgramData\miniforge3\envs\agent_chat`
|
||||
|
||||
## 개발 도구
|
||||
|
||||
| 도구 | 명령어 |
|
||||
|------|--------|
|
||||
| 개발 서버 | (예: `cmd /c npm run dev`) |
|
||||
| 빌드 | (예: `cmd /c npm run build`) |
|
||||
| 테스트 | (예: `cmd /c npm test`) |
|
||||
| 린트 | (예: `cmd /c npm run lint`) |
|
||||
| 봇 실행 | `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` |
|
||||
|
||||
## 환경 변수
|
||||
## 환경 변수 (.env)
|
||||
|
||||
| 변수명 | 용도 | 기본값 |
|
||||
|--------|------|--------|
|
||||
| (예: PORT) | (서버 포트) | (3000) |
|
||||
| DISCORD_BOT_TOKEN | Discord 봇 토큰 | (필수) |
|
||||
| API_HOST | API 서버 호스트 | 0.0.0.0 |
|
||||
| API_PORT | API 서버 포트 | 8000 |
|
||||
| GITEA_URL | Gitea 서버 | https://git.variet.net |
|
||||
| GITEA_TOKEN | Gitea API 토큰 | (필수) |
|
||||
| GITEA_REPO | Gitea 저장소 | Variet/variet-agent |
|
||||
| VIKUNJA_URL | Vikunja 서버 | https://plan.variet.net |
|
||||
| VIKUNJA_TOKEN | Vikunja API 토큰 | (필수) |
|
||||
| VIKUNJA_PROJECT_ID | Vikunja 프로젝트 ID | 7 |
|
||||
| QBIT_URL | qBittorrent URL | http://localhost:8080 |
|
||||
| NAS_ANIME_PATH | NAS 애니 경로 | \\\\192.168.10.10\NasData\Video\Animation |
|
||||
|
||||
## 외부 서비스
|
||||
|
||||
| 서비스 | URL | 용도 |
|
||||
|--------|-----|------|
|
||||
| Gitea | git.variet.net | Git 저장소, PR, CI |
|
||||
| Vikunja | plan.variet.net | 태스크 관리 (프로젝트 #7) |
|
||||
| Anissia | anissia.net | 애니 편성표/자막 |
|
||||
| Nyaa | nyaa.si | 토렌트 검색 |
|
||||
| qBittorrent | localhost:8080 | 토렌트 다운로드 |
|
||||
|
||||
@@ -1,40 +1,40 @@
|
||||
---
|
||||
description: Gitea API로 저장소 커밋/이슈/PR 현황을 조회하는 워크플로우
|
||||
description: Gitea APIë¡??€?¥ì†Œ 커밋/?´ìŠˆ/PR ?„황??조회?˜ëŠ” ?Œí<C592>¬?Œë¡œ??
|
||||
---
|
||||
|
||||
# Gitea 저장소 현황 조회
|
||||
# Gitea ?€?¥ì†Œ ?„황 조회
|
||||
|
||||
서비스 정보는 `.agents/workflows/services.md` 참조.
|
||||
?œë¹„???•ë³´??`.agents/workflows/services.md` 참조.
|
||||
|
||||
// turbo-all
|
||||
|
||||
## 절차
|
||||
## ?ˆì°¨
|
||||
|
||||
1. 최근 커밋 조회 (최신 10개):
|
||||
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. 열린 이슈 조회:
|
||||
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 페이지 목록:
|
||||
3. Wiki ?˜ì<CB9C>´ì§€ 목ë¡<C3AB>:
|
||||
```powershell
|
||||
C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\wiki_helper.py list
|
||||
C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\wiki_helper.py list
|
||||
```
|
||||
|
||||
4. Wiki 페이지 읽기:
|
||||
4. Wiki ?˜ì<CB9C>´ì§€ ?½ê¸°:
|
||||
```powershell
|
||||
C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\wiki_helper.py read "Architecture"
|
||||
C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\wiki_helper.py read "Architecture"
|
||||
```
|
||||
|
||||
5. Wiki 페이지 업데이트:
|
||||
5. Wiki ?˜ì<CB9C>´ì§€ ?…ë<E280A6>°?´íŠ¸:
|
||||
```powershell
|
||||
C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\wiki_helper.py update "페이지-제목" /tmp/wiki_content.md
|
||||
C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\wiki_helper.py update "?˜ì<CB9C>´ì§€-?œëª©" /tmp/wiki_content.md
|
||||
```
|
||||
|
||||
@@ -1,41 +1,41 @@
|
||||
---
|
||||
description: Vikunja API로 프로젝트 태스크 현황을 조회하는 워크플로우
|
||||
description: Vikunja APIë¡??„ë¡œ?<3F>트 ?œìŠ¤???„황??조회?˜ëŠ” ?Œí<C592>¬?Œë¡œ??
|
||||
---
|
||||
|
||||
# Vikunja 태스크 현황 조회
|
||||
# Vikunja ?œìŠ¤???„황 조회
|
||||
|
||||
서비스 정보는 `.agents/workflows/services.md` 참조.
|
||||
?œë¹„???•ë³´??`.agents/workflows/services.md` 참조.
|
||||
|
||||
// turbo-all
|
||||
|
||||
## 절차
|
||||
## ?ˆì°¨
|
||||
|
||||
1. 전체 목록:
|
||||
1. ?„ì²´ 목ë¡<C3AB>:
|
||||
```powershell
|
||||
C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\vikunja_helper.py list
|
||||
C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py list
|
||||
```
|
||||
|
||||
2. TODO만:
|
||||
2. TODO�
|
||||
```powershell
|
||||
C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\vikunja_helper.py list todo
|
||||
C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py list todo
|
||||
```
|
||||
|
||||
3. DONE만:
|
||||
3. DONE�
|
||||
```powershell
|
||||
C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\vikunja_helper.py list done
|
||||
C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py list done
|
||||
```
|
||||
|
||||
4. 태스크 완료 처리 (**⚠️ 반드시 이 방법 사용 — 직접 API 호출 금지**):
|
||||
4. ?œìŠ¤???„료 처리 (**? ï¸<C3AF> 반드????방법 ?¬ìš© ??ì§<C3AC>ì ‘ API ?¸ì¶œ 금ì?**):
|
||||
```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}
|
||||
```
|
||||
|
||||
5. 새 태스크 생성:
|
||||
5. ???œìŠ¤???<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
|
||||
```
|
||||
|
||||
> [!CAUTION]
|
||||
> **절대로** `Invoke-RestMethod -Method Post -Body '{"done": true}'` 같은 직접 API 호출을 사용하지 마세요.
|
||||
> Vikunja API는 POST 시 body에 포함되지 않은 필드를 빈값으로 덮어씁니다.
|
||||
> `vikunja_helper.py`는 항상 GET → 기존 필드 보존 → POST 패턴을 사용합니다.
|
||||
> **?ˆë?ë¡?* `Invoke-RestMethod -Method Post -Body '{"done": true}'` ê°™ì? ì§<C3AC>ì ‘ API ?¸ì¶œ???¬ìš©?˜ì? 마세??
|
||||
> Vikunja API??POST ??body???¬í•¨?˜ì? ?Šì? ?„ë“œë¥?빈값?¼ë¡œ ??–´?<3F>니??
|
||||
> `vikunja_helper.py`????ƒ<> GET ??기존 ?„ë“œ ë³´ì¡´ ??POST ?¨í„´???¬ìš©?©ë‹ˆ??
|
||||
|
||||
@@ -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>ê²??„료 ë³´ê³
|
||||
|
||||
@@ -29,7 +29,7 @@ if sys.stdout.encoding != "utf-8":
|
||||
# ============================================================
|
||||
API_BASE = "https://plan.variet.net/api/v1"
|
||||
TOKEN = "tk_070f8e0b715e818bb7178c3815ed5389040eddca"
|
||||
PROJECT_ID = 7 # variet-agent 프로젝트
|
||||
PROJECT_ID = 7 # Variet Agent 프로젝트
|
||||
# ============================================================
|
||||
|
||||
HEADERS = {
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Gitea Wiki helper: list, read, create, update wiki pages.
|
||||
"""Gitea Wiki helper: list, read, create, update wiki pages.
|
||||
|
||||
Usage:
|
||||
wiki_helper.py list — list all pages
|
||||
@@ -15,7 +15,7 @@ sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
|
||||
# ============================================================
|
||||
GITEA_BASE_URL = "https://git.variet.net"
|
||||
GITEA_OWNER = "Variet"
|
||||
GITEA_REPO = "variet-agent" # ← 프로젝트별 변경 필요
|
||||
GITEA_REPO = "variet-agent" # Variet Agent 프로젝트
|
||||
GITEA_TOKEN = "3a01b4b15a39921572e64c413353e870d4d2161b"
|
||||
# ============================================================
|
||||
|
||||
|
||||
@@ -1,23 +1,23 @@
|
||||
---
|
||||
description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워크플로우 (시작, continue, 이어서, 작업 시작)
|
||||
description: ?¸ì…˜ ?œìž‘ ???„ë¡œ?<3F>트 맥ë<C2A5>½??ë¹ ë¥´ê²?복구?˜ëŠ” ?Œí<C592>¬?Œë¡œ??(?œìž‘, continue, ?´ì–´?? ?‘ì—… ?œìž‘)
|
||||
---
|
||||
|
||||
# 세션 시작 프로토콜
|
||||
# ?¸ì…˜ ?œìž‘ ?„ë¡œ? 콜
|
||||
|
||||
새 대화 시작, "continue", "이어서", "작업 시작" 등 요청 시 이 워크플로우를 실행합니다.
|
||||
???€???œìž‘, "continue", "?´ì–´??, "?‘ì—… ?œìž‘" ???”ì² ?????Œí<C592>¬?Œë¡œ?°ë? ?¤í–‰?©ë‹ˆ??
|
||||
|
||||
// turbo-all
|
||||
|
||||
## 절차
|
||||
## ?ˆì°¨
|
||||
|
||||
### 0. 에이전트 룰 & 맥락 로딩 (자동)
|
||||
### 0. ?<3F>ì<EFBFBD>´?„트 ë£?& 맥ë<C2A5>½ 로딩 (?<3F>ë<EFBFBD>™)
|
||||
|
||||
`.agents/AGENT.md`를 읽고 에이전트 행동 규칙을 로딩합니다.
|
||||
`.agents/references/known-issues.md`를 읽어 최근 이슈를 파악합니다.
|
||||
`.agents/AGENT.md`ë¥??½ê³ ?<3F>ì<EFBFBD>´?„트 ?‰ë<E280B0>™ 규칙??로딩?©ë‹ˆ??
|
||||
`.agents/references/known-issues.md`ë¥??½ì–´ 최근 ?´ìŠˆë¥??Œì•…?©ë‹ˆ??
|
||||
|
||||
### 1. Devlog 맥ë<C2A5>½ 복구
|
||||
|
||||
오늘 + 어제 devlog index를 읽고 최근 작업 흐름을 파악합니다.
|
||||
?¤ëŠ˜ + ?´ì œ devlog indexë¥??½ê³ 최근 ?‘ì—… ?<3F>름???Œì•…?©ë‹ˆ??
|
||||
|
||||
```powershell
|
||||
$today = Get-Date -Format "yyyy-MM-dd"
|
||||
@@ -33,10 +33,10 @@ if (Test-Path "docs\devlog\$today.md") {
|
||||
}
|
||||
```
|
||||
|
||||
미완료(🔧) 항목이 있으면 해당 entry 파일을 읽어 이어받기 맥락을 확보합니다:
|
||||
미완ë£??”§) ??ª©???ˆìœ¼ë©??´ë‹¹ entry ?Œì<C592>¼???½ì–´ ?´ì–´ë°›ê¸° 맥ë<C2A5>½???•ë³´?©ë‹ˆ??
|
||||
- Entry 경로: `docs/devlog/entries/YYYYMMDD-NNN.md`
|
||||
|
||||
### 2. Git 상태 확인
|
||||
### 2. Git ?<3F>태 ?•ì<E280A2>¸
|
||||
|
||||
```powershell
|
||||
git status --short
|
||||
@@ -45,21 +45,21 @@ git status --short
|
||||
git log --oneline -5
|
||||
```
|
||||
|
||||
### 3. Vikunja TODO 태스크
|
||||
### 3. Vikunja TODO ?œìŠ¤??
|
||||
|
||||
```powershell
|
||||
C:\ProgramData\miniforge3\envs\gravity_web\python.exe .agents\workflows\helpers\vikunja_helper.py list todo
|
||||
C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py list todo
|
||||
```
|
||||
|
||||
### 4. 종합 ë³´ê³
|
||||
|
||||
결과를 종합하여 사용자에게 보고:
|
||||
- 마지막 작업 맥락 + 미완료 항목 (devlog 🔧 기반)
|
||||
- TODO 태스크 목록 (라벨 + 우선순위)
|
||||
- 다음 작업 제안
|
||||
ê²°ê³¼ë¥?종합?˜ì—¬ ?¬ìš©?<3F>ì—<C3AC>ê²?ë³´ê³ :
|
||||
- 마ì?ë§??‘ì—… 맥ë<C2A5>½ + 미완ë£???ª© (devlog ?”§ 기반)
|
||||
- TODO ?œìŠ¤??목ë¡<C3AB> (?¼ë²¨ + ?°ì„ ?œìœ„)
|
||||
- ?¤ì<C2A4>Œ ?‘ì—… ?œì•ˆ
|
||||
|
||||
**우선순위 판단 기준** (라벨만으로 판단 금지):
|
||||
- P0: 최근 커밋에서 스키마/모델/인터페이스 변경 → 연쇄 영향 점검
|
||||
- P1: 서버 기동/API 응답 장애
|
||||
- P2: 기능 미완성/UX 개선
|
||||
- P3: 정확도 향상, 신규 기능, CI/CD, 문서 정리
|
||||
**?°ì„ ?œìœ„ ?<3F>단 기ì?** (?¼ë²¨ë§Œìœ¼ë¡??<3F>단 금ì?):
|
||||
- P0: 최근 커밋?<3F>ì„œ ?¤í‚¤ë§?모ë<C2A8>¸/?¸í„°?˜ì<CB9C>´??ë³€ê²????°ì‡„ ?<3F>í–¥ ?<3F>ê?
|
||||
- P1: ?œë²„ 기ë<C2B0>™/API ?‘답 ?¥ì•
|
||||
- P2: 기능 미완??UX ê°œì„
|
||||
- P3: ?•í™•???¥ìƒ<C3AC>, ? ê·œ 기능, CI/CD, 문서 ?•ë¦¬
|
||||
|
||||
5
docs/devlog/2026-03-10.md
Normal file
5
docs/devlog/2026-03-10.md
Normal file
@@ -0,0 +1,5 @@
|
||||
# 2026-03-10 Devlog
|
||||
|
||||
| # | 시간 | 작업 | 커밋 | 상태 |
|
||||
|---|------|------|------|------|
|
||||
| 1 | 22:23~22:49 | Agent Guide 셋업 (agent_guide.git → .agents/, 플레이스홀더 교체, Python 경로, reference 작성) | (커밋 예정) | ✅ |
|
||||
Reference in New Issue
Block a user