From 044200a786e6dd28ca4392c2d50e7cb06a3331f8 Mon Sep 17 00:00:00 2001 From: CD Date: Tue, 10 Mar 2026 22:51:14 +0900 Subject: [PATCH] =?UTF-8?q?chore:=20Agent=20Guide=20=EC=85=8B=EC=97=85=20?= =?UTF-8?q?=E2=80=94=20agent=5Fguide.git=20=EA=B8=B0=EB=B0=98=20.agents=20?= =?UTF-8?q?=EC=9E=AC=EA=B5=AC=EC=84=B1=20+=20=ED=94=84=EB=A1=9C=EC=A0=9D?= =?UTF-8?q?=ED=8A=B8=EB=B3=84=20=EC=84=A4=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/AGENT.md | 1 - .agents/README.md | 67 +++++++++ .agents/references/architecture.md | 74 +++++++--- .agents/references/tech-stack.md | 46 +++++-- .agents/workflows/check-gitea.md | 24 ++-- .agents/workflows/check-vikunja.md | 34 ++--- .agents/workflows/end.md | 142 ++++++++++---------- .agents/workflows/helpers/vikunja_helper.py | 2 +- .agents/workflows/helpers/wiki_helper.py | 4 +- .agents/workflows/start.md | 42 +++--- docs/devlog/2026-03-10.md | 5 + 11 files changed, 287 insertions(+), 154 deletions(-) create mode 100644 .agents/README.md create mode 100644 docs/devlog/2026-03-10.md diff --git a/.agents/AGENT.md b/.agents/AGENT.md index 113e0d7..148d8b9 100644 --- a/.agents/AGENT.md +++ b/.agents/AGENT.md @@ -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 이스케이핑 이슈 방지) diff --git a/.agents/README.md b/.agents/README.md new file mode 100644 index 0000000..a27f130 --- /dev/null +++ b/.agents/README.md @@ -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 diff --git a/.agents/references/architecture.md b/.agents/references/architecture.md index 7cfb37c..91e9bb5 100644 --- a/.agents/references/architecture.md +++ b/.agents/references/architecture.md @@ -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` | ## 데이터 흐름 - - -(데이터 흐름을 여기에 작성하세요) +``` +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 보고 +``` diff --git a/.agents/references/tech-stack.md b/.agents/references/tech-stack.md index af6ce80..bd07d4b 100644 --- a/.agents/references/tech-stack.md +++ b/.agents/references/tech-stack.md @@ -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 | 토렌트 다운로드 | diff --git a/.agents/workflows/check-gitea.md b/.agents/workflows/check-gitea.md index 3d8e7bd..f528246 100644 --- a/.agents/workflows/check-gitea.md +++ b/.agents/workflows/check-gitea.md @@ -1,40 +1,40 @@ --- -description: Gitea API로 저장소 커밋/이슈/PR 현황을 조회하는 워크플로우 +description: Gitea API???소 커밋/?슈/PR ?황??조회?는 ?크?로?? --- -# 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 ?이지 목록: ```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 ?이지 ?기: ```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 ?이지 ?데?트: ```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 "?이지-?목" /tmp/wiki_content.md ``` diff --git a/.agents/workflows/check-vikunja.md b/.agents/workflows/check-vikunja.md index dfcbf8e..7ad4150 100644 --- a/.agents/workflows/check-vikunja.md +++ b/.agents/workflows/check-vikunja.md @@ -1,41 +1,41 @@ --- -description: Vikunja API로 프로젝트 태스크 현황을 조회하는 워크플로우 +description: Vikunja API??로?트 ?스???황??조회?는 ?크?로?? --- -# Vikunja 태스크 현황 조회 +# Vikunja ?스???황 조회 -서비스 정보는 `.agents/workflows/services.md` 참조. +?비???보??`.agents/workflows/services.md` 참조. // turbo-all -## 절차 +## ?차 -1. 전체 목록: +1. ?체 목록: ```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. ?스???료 처리 (**?️ 반드????방법 ?용 ??직접 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. ???스???성: ```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}'` 같? 직접 API ?출???용?? 마세?? +> Vikunja API??POST ??body???함?? ?? ?드?빈값?로 ???니?? +> `vikunja_helper.py`???? GET ??기존 ?드 보존 ??POST ?턴???용?니?? diff --git a/.agents/workflows/end.md b/.agents/workflows/end.md index da4983d..3c5bb24 100644 --- a/.agents/workflows/end.md +++ b/.agents/workflows/end.md @@ -1,129 +1,129 @@ --- -description: 세션 종료 시 devlog 기록 + git commit + Vikunja 동기화 (끝, 마무리, 커밋해, 완료) +description: ?션 종료 ??devlog 기록 + git commit + Vikunja ?기??(?? 마무? 커밋?? ?료) --- -# 세션 종료 프로토콜 +# ?션 종료 ?로?콜 -작업 완료, "끝", "마무리", "커밋해" 등 요청 시 이 워크플로우를 실행합니다. +?업 ?료, "??, "마무?, "커밋?? ???청 ?????크?로?? ?행?니?? // turbo-all -## 0. 학습 기록 (실패/시행착오 저장) +## 0. ?습 기록 (?패/?행착오 ??? -이번 세션에서 발생한 실패, 시행착오, 새로 알게 된 사실을 정리합니다: +?번 ?션?서 발생???패, ?행착오, ?로 ?게 ???실???리?니?? -- [ ] `.agents/references/known-issues.md`에 추가할 항목이 있는지 확인 -- [ ] 있다면 아래 포맷으로 추가: +- [ ] `.agents/references/known-issues.md`??추????????는지 ?인 +- [ ] ?다??래 ?맷?로 추?: ```markdown -### [날짜] [키워드] — 한줄 요약 +### [?짜] [?워?? ???줄 ?약 - **증상**: ... -- **원인**: ... -- **해결**: ... +- **?인**: ... +- **?결**: ... - **주의**: ... ``` ## 1. Devlog 기록 -### Index 업데이트 (필수 — 매 작업) +### Index ?데?트 (?수 ????업) -오늘 날짜의 index 파일에 완료된 작업 1줄을 추가합니다. +?늘 ?짜??index ?일???료???업 1줄을 추??니?? -- **파일**: `docs/devlog/YYYY-MM-DD.md` -- **형식**: +- **?일**: `docs/devlog/YYYY-MM-DD.md` +- **?식**: ```markdown -| NNN | HH:MM | 작업 설명 | `커밋해시` | ✅ 또는 🔧 | +| NNN | HH:MM | ?업 ?명 | `커밋?시` | ???는 ? | ``` > [!TIP] -> - ✅ = 완료, 🔧 = 미완료 (다음 세션에서 이어받기) -> - 파일이 없으면 새로 생성 (테이블 헤더 포함) +> - ??= ?료, ? = 미완?(?음 ?션?서 ?어받기) +> - ?일???으??로 ?성 (?이??더 ?함) -### Entry 작성 (선택적 — 필요할 때만) +### Entry ?성 (?택?????요???만) > [!IMPORTANT] -> Entry는 **git/Vikunja/wiki에 없는 정보**가 있을 때만 작성합니다. +> Entry??**git/Vikunja/wiki???는 ?보**가 ?을 ?만 ?성?니?? -**Entry 작성 기준:** -- ✅ 설계 결정이 있었을 때 (왜 A가 아닌 B를 선택했는지) -- ✅ 미완료 사항이 있을 때 (다음 세션이 이어받아야 할 맥락) -- ✅ 삽질/트러블슈팅이 있었을 때 (같은 실수 방지) +**Entry ?성 기?:** +- ???계 결정???었????(??A가 ?닌 B??택?는지) +- ??미완??항???을 ??(?음 ?션???어받아????맥락) +- ???질/?러블슈?이 ?었????(같? ?수 방?) -**Entry 불필요:** -- ❌ 단순 버그 픽스 (커밋 메시지로 충분) -- ❌ 문서 업데이트 (git diff로 충분) -- ❌ 이미 Vikunja 태스크에 상세 설명이 있는 경우 +**Entry 불필??** +- ???순 버그 ?스 (커밋 메시지?충분) +- ??문서 ?데?트 (git diff?충분) +- ???? Vikunja ?스?에 ?세 ?명???는 경우 -**Entry 파일**: `docs/devlog/entries/YYYYMMDD-NNN.md` +**Entry ?일**: `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/진행? -## 결정 사항 -- 왜 이 방식을 선택했는지 +## 결정 ?항 +- ????방식???택?는지 -## 미완료 -- 남은 작업 (있을 경우) +## 미완? +- ?? ?업 (?을 경우) ``` --- -## 2. Vikunja 동기화 +## 2. Vikunja ?기?? > [!CAUTION] -> **반드시 `vikunja_helper.py` 사용.** 직접 API 호출 금지. -> Vikunja API는 POST 시 body에 없는 필드를 빈값으로 덮어씁니다. +> **반드??`vikunja_helper.py` ?용.** 직접 API ?출 금?. +> Vikunja API??POST ??body???는 ?드?빈값?로 ???니?? -### 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}` | +| ?규 ?업 ?료 (기존 ?스???음) | `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] -> 모든 커밋이 기존 또는 신규 태스크에 매핑되었는지 확인. +> 모든 커밋??기존 ?는 ?규 ?스?에 매핑?었?? ?인. -### 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. ?규 ?스???성 ```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` +**?역 (?수 1??상):** `Backend` / `Frontend` / `Engine` / `Infra` / `Test` +**?선?위 (?수 1?:** `Priority:High` / `Priority:Mid` / `Priority:Low` --- -## 3. Wiki 동기화 (해당 시에만) +## 3. Wiki ?기??(?당 ?에? -| 코드 변경 | 대상 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: feat|fix|refactor|test|docs|chore|ci|infra -scope: (선택) +scope: (?택) ``` --- -## 5. 최종 체크리스트 +## 5. 최종 체크리스?? > [!WARNING] -> 아래 항목 중 하나라도 누락되면 세션 종료를 완료할 수 없습니다. +> ?래 ?? ??나?도 ?락?면 ?션 종료??료?????습?다. -- [ ] known-issues 업데이트됨 (새 이슈가 있었다면) -- [ ] devlog index 업데이트됨 -- [ ] devlog entry 작성됨 (필요한 경우만) -- [ ] Vikunja 태스크 생성/완료 처리됨 (커밋 전수 검사 기반) -- [ ] Wiki 동기화됨 (아키텍처 변경이 있었다면) -- [ ] git push 완료 -- [ ] 사용자에게 완료 보고 +- [ ] known-issues ?데?트??(???슈가 ?었?면) +- [ ] devlog index ?데?트?? +- [ ] devlog entry ?성??(?요??경우? +- [ ] Vikunja ?스???성/?료 처리??(커밋 ?수 검??기반) +- [ ] Wiki ?기?됨 (?키?처 변경이 ?었?면) +- [ ] git push ?료 +- [ ] ?용?에??료 보고 diff --git a/.agents/workflows/helpers/vikunja_helper.py b/.agents/workflows/helpers/vikunja_helper.py index 4e30bc1..6ab298a 100644 --- a/.agents/workflows/helpers/vikunja_helper.py +++ b/.agents/workflows/helpers/vikunja_helper.py @@ -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 = { diff --git a/.agents/workflows/helpers/wiki_helper.py b/.agents/workflows/helpers/wiki_helper.py index d83354e..bf63161 100644 --- a/.agents/workflows/helpers/wiki_helper.py +++ b/.agents/workflows/helpers/wiki_helper.py @@ -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" # ============================================================ diff --git a/.agents/workflows/start.md b/.agents/workflows/start.md index e2bb446..c573955 100644 --- a/.agents/workflows/start.md +++ b/.agents/workflows/start.md @@ -1,23 +1,23 @@ --- -description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워크플로우 (시작, continue, 이어서, 작업 시작) +description: ?션 ?작 ???로?트 맥락??빠르?복구?는 ?크?로??(?작, continue, ?어?? ?업 ?작) --- -# 세션 시작 프로토콜 +# ?션 ?작 ?로?콜 -새 대화 시작, "continue", "이어서", "작업 시작" 등 요청 시 이 워크플로우를 실행합니다. +??????작, "continue", "?어??, "?업 ?작" ???청 ?????크?로?? ?행?니?? // turbo-all -## 절차 +## ?차 -### 0. 에이전트 룰 & 맥락 로딩 (자동) +### 0. ?이?트 ?& 맥락 로딩 (?동) -`.agents/AGENT.md`를 읽고 에이전트 행동 규칙을 로딩합니다. -`.agents/references/known-issues.md`를 읽어 최근 이슈를 파악합니다. +`.agents/AGENT.md`??고 ?이?트 ?동 규칙??로딩?니?? +`.agents/references/known-issues.md`??어 최근 ?슈??악?니?? ### 1. Devlog 맥락 복구 -오늘 + 어제 devlog index를 읽고 최근 작업 흐름을 파악합니다. +?늘 + ?제 devlog index??고 최근 ?업 ?름???악?니?? ```powershell $today = Get-Date -Format "yyyy-MM-dd" @@ -33,10 +33,10 @@ if (Test-Path "docs\devlog\$today.md") { } ``` -미완료(🔧) 항목이 있으면 해당 entry 파일을 읽어 이어받기 맥락을 확보합니다: +미완??) ?????으??당 entry ?일???어 ?어받기 맥락???보?니?? - Entry 경로: `docs/devlog/entries/YYYYMMDD-NNN.md` -### 2. Git 상태 확인 +### 2. Git ?태 ?인 ```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 태스크 목록 (라벨 + 우선순위) -- 다음 작업 제안 +결과?종합?여 ?용?에?보고: +- 마???업 맥락 + 미완??? (devlog ? 기반) +- TODO ?스??목록 (?벨 + ?선?위) +- ?음 ?업 ?안 -**우선순위 판단 기준** (라벨만으로 판단 금지): -- P0: 최근 커밋에서 스키마/모델/인터페이스 변경 → 연쇄 영향 점검 -- P1: 서버 기동/API 응답 장애 -- P2: 기능 미완성/UX 개선 -- P3: 정확도 향상, 신규 기능, CI/CD, 문서 정리 +**?선?위 ?단 기?** (?벨만으??단 금?): +- P0: 최근 커밋?서 ?키?모델/?터?이??변????쇄 ?향 ?? +- P1: ?버 기동/API ?답 ?애 +- P2: 기능 미완??UX 개선 +- P3: ?확???상, ?규 기능, CI/CD, 문서 ?리 diff --git a/docs/devlog/2026-03-10.md b/docs/devlog/2026-03-10.md new file mode 100644 index 0000000..e688c40 --- /dev/null +++ b/docs/devlog/2026-03-10.md @@ -0,0 +1,5 @@ +# 2026-03-10 Devlog + +| # | 시간 | 작업 | 커밋 | 상태 | +|---|------|------|------|------| +| 1 | 22:23~22:49 | Agent Guide 셋업 (agent_guide.git → .agents/, 플레이스홀더 교체, Python 경로, reference 작성) | (커밋 예정) | ✅ |