diff --git a/.agents/workflows/check-gitea.md b/.agents/workflows/check-gitea.md new file mode 100644 index 0000000..f702ed7 --- /dev/null +++ b/.agents/workflows/check-gitea.md @@ -0,0 +1,40 @@ +--- +description: Gitea API로 저장소 커밋/이슈/PR 현황을 조회하는 워크플로우 +--- + +# Gitea 저장소 현황 조회 + +서비스 정보는 `.agents/workflows/services.md` 참조. + +// turbo-all + +## 절차 + +1. 최근 커밋 조회 (최신 10개): +```powershell +$h = @{Authorization="token {{GITEA_TOKEN}}"} +$commits = Invoke-RestMethod -Uri "{{GITEA_BASE_URL}}/api/v1/repos/{{GITEA_OWNER}}/{{GITEA_REPO}}/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 {{GITEA_TOKEN}}"} +$issues = Invoke-RestMethod -Uri "{{GITEA_BASE_URL}}/api/v1/repos/{{GITEA_OWNER}}/{{GITEA_REPO}}/issues?state=open&type=issues" -Headers $h +$issues | ForEach-Object { Write-Host "#$($_.number) $($_.title)" } +``` + +3. Wiki 페이지 목록: +```powershell +python .agents\workflows\helpers\wiki_helper.py list +``` + +4. Wiki 페이지 읽기: +```powershell +python .agents\workflows\helpers\wiki_helper.py read "Architecture" +``` + +5. Wiki 페이지 업데이트: +```powershell +python .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 new file mode 100644 index 0000000..084cff5 --- /dev/null +++ b/.agents/workflows/check-vikunja.md @@ -0,0 +1,41 @@ +--- +description: Vikunja API로 프로젝트 태스크 현황을 조회하는 워크플로우 +--- + +# Vikunja 태스크 현황 조회 + +서비스 정보는 `.agents/workflows/services.md` 참조. + +// turbo-all + +## 절차 + +1. 전체 목록: +```powershell +python .agents\workflows\helpers\vikunja_helper.py list +``` + +2. TODO만: +```powershell +python .agents\workflows\helpers\vikunja_helper.py list todo +``` + +3. DONE만: +```powershell +python .agents\workflows\helpers\vikunja_helper.py list done +``` + +4. 태스크 완료 처리 (**⚠️ 반드시 이 방법 사용 — 직접 API 호출 금지**): +```powershell +python .agents\workflows\helpers\vikunja_helper.py done {TASK_ID} +``` + +5. 새 태스크 생성: +```powershell +python .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 패턴을 사용합니다. diff --git a/.agents/workflows/end.md b/.agents/workflows/end.md index 7c0ed34..044f19b 100644 --- a/.agents/workflows/end.md +++ b/.agents/workflows/end.md @@ -1,5 +1,5 @@ --- -description: 세션 종료 시 학습 기록 + git commit (끝, 마무리, 커밋해, 완료) +description: 세션 종료 시 학습 기록 + Vikunja 동기화 + git commit (끝, 마무리, 커밋해, 완료) --- # 세션 종료 프로토콜 @@ -12,8 +12,8 @@ description: 세션 종료 시 학습 기록 + git commit (끝, 마무리, 커 이번 세션에서 발생한 실패, 시행착오, 새로 알게 된 사실을 정리합니다: -- [ ] `known-issues.md`에 추가할 항목이 있는지 확인 -- [ ] 있다면 `.agents/references/known-issues.md`에 표준 포맷으로 추가: +- [ ] `.agents/references/known-issues.md`에 추가할 항목이 있는지 확인 +- [ ] 있다면 아래 포맷으로 추가: ```markdown ### [날짜] [키워드] — 한줄 요약 @@ -23,7 +23,38 @@ description: 세션 종료 시 학습 기록 + git commit (끝, 마무리, 커 - **주의**: ... ``` -## 1. Git Commit & Push +## 1. Vikunja 동기화 + +> [!CAUTION] +> **반드시 `vikunja_helper.py` 사용.** 직접 API 호출 금지. + +### 1-1. 커밋 전수 검사 + +이번 세션의 모든 커밋을 확인하고 Vikunja에 매핑: + +```powershell +git log --oneline -20 +``` + +| 커밋 유형 | Vikunja 액션 | +|-----------|-------------| +| 기존 태스크 해당 작업 완료 | `python .agents\workflows\helpers\vikunja_helper.py done {ID}` | +| 신규 작업 완료 (기존 태스크 없음) | `python .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --done --labels Backend,Priority:High` | +| 작업 중 발견된 미완료 TODO | `python .agents\workflows\helpers\vikunja_helper.py create "제목" "설명" --labels Backend,Priority:Mid` | + +### 1-2. Wiki 동기화 (해당 시에만) + +| 코드 변경 | 대상 Wiki | +|-----------|----------| +| 서버 변경 | Architecture | +| 프론트엔드 변경 | Architecture | +| 새 모듈 추가 | Architecture | + +```powershell +python .agents\workflows\helpers\wiki_helper.py update "Architecture" /tmp/wiki_content.md +``` + +## 2. Git Commit & Push ```powershell git add -A @@ -44,11 +75,10 @@ type: feat|fix|refactor|test|docs|chore|ci|infra scope: (선택 — 모듈명 등) ``` -## 2. 최종 체크리스트 +## 3. 최종 체크리스트 - [ ] known-issues 업데이트 완료 +- [ ] Vikunja 태스크 생성/완료 처리됨 +- [ ] Wiki 동기화됨 (해당 시) - [ ] git push 완료 - [ ] 사용자에게 완료 보고 - -> [!TIP] -> 프로젝트별 워크플로우(Vikunja 동기화, Wiki 업데이트 등)가 있다면 여기에 단계를 추가하세요. diff --git a/.agents/workflows/helpers/vikunja_helper.py b/.agents/workflows/helpers/vikunja_helper.py new file mode 100644 index 0000000..300aa63 --- /dev/null +++ b/.agents/workflows/helpers/vikunja_helper.py @@ -0,0 +1,217 @@ +"""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" "desc" --labels Backend,Priority:High + python vikunja_helper.py create "title" "desc" --done --labels Frontend,Priority:Mid + python vikunja_helper.py label 75 Backend Priority:High # Add labels to task + 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") + +# ============================================================ +# ⚙️ CONFIGURATION — Change these values for your project +# ============================================================ +API_BASE = "{{VIKUNJA_BASE_URL}}/api/v1" # e.g. "https://plan.variet.net/api/v1" +TOKEN = "{{VIKUNJA_TOKEN}}" # e.g. "tk_070f8e0b..." +PROJECT_ID = 0 # e.g. 9 +# ============================================================ + +HEADERS = { + "Authorization": f"Bearer {TOKEN}", + "Content-Type": "application/json", +} + +# Label name → Vikunja label ID mapping +# Customize for your project's labels +LABEL_MAP = { + "Backend": 1, "Frontend": 2, "Engine": 3, "Infra": 4, "Test": 5, + "Priority:High": 6, "Priority:Mid": 7, "Priority:Low": 8, + "Agent": 17, "Tool": 18, "AI/LLM": 19, +} + + +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: + return api_get(f"/tasks/{task_id}") + + +def safe_update_task(task_id: int, updates: dict) -> dict: + 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): + 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): + 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"): + all_tasks = [] + page = 1 + while True: + batch = api_get(f"/projects/{PROJECT_ID}/tasks?per_page=50&page={page}") + if not batch: + break + all_tasks.extend(batch) + if len(batch) < 50: + break + page += 1 + + if filter_ == "todo": + all_tasks = [t for t in all_tasks if not t["done"]] + elif filter_ == "done": + all_tasks = [t for t in all_tasks if t["done"]] + + all_tasks.sort(key=lambda t: t["id"]) + for t in all_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(all_tasks)} tasks") + + +def add_labels(task_id: int, label_names: list): + for name in label_names: + label_id = LABEL_MAP.get(name) + if not label_id: + print(f" ⚠️ Unknown label '{name}'. Valid: {', '.join(LABEL_MAP.keys())}") + continue + try: + api_put(f"/tasks/{task_id}/labels", {"label_id": label_id}) + print(f" 🏷️ #{task_id} + {name} (id={label_id})") + except Exception as e: + if "already" in str(e).lower() or "409" in str(e): + print(f" 🏷️ #{task_id} already has {name}") + else: + print(f" ⚠️ #{task_id} label {name} failed: {e}") + + +def create_task(title: str, description: str = "", done: bool = False, labels: list = None): + 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 labels: + add_labels(task_id, labels) + + 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": + add_comment(int(sys.argv[2]), sys.argv[3]) + elif cmd == "desc": + set_description(int(sys.argv[2]), sys.argv[3]) + elif cmd == "list": + f = sys.argv[2] if len(sys.argv) > 2 else "all" + list_tasks(f) + elif cmd == "label": + if len(sys.argv) < 4: + print("Usage: vikunja_helper.py label TASK_ID Label1 Label2 ...") + return + add_labels(int(sys.argv[2]), sys.argv[3:]) + elif cmd == "create": + title = sys.argv[2] if len(sys.argv) > 2 else "" + desc = sys.argv[3] if len(sys.argv) > 3 and not sys.argv[3].startswith("--") else "" + is_done = "--done" in sys.argv + labels = None + for i, arg in enumerate(sys.argv): + if arg == "--labels" and i + 1 < len(sys.argv): + labels = sys.argv[i + 1].split(",") + break + if not title: + print("Error: title is required") + return + create_task(title, desc, done=is_done, labels=labels) + else: + print(f"Unknown command: {cmd}") + print(__doc__) + + +if __name__ == "__main__": + main() diff --git a/.agents/workflows/helpers/wiki_helper.py b/.agents/workflows/helpers/wiki_helper.py new file mode 100644 index 0000000..8e331b4 --- /dev/null +++ b/.agents/workflows/helpers/wiki_helper.py @@ -0,0 +1,100 @@ +"""Gitea Wiki helper: list, read, create, update wiki pages. + +Usage: + wiki_helper.py list — list all pages + wiki_helper.py read — read a page + wiki_helper.py create <title> <file> — create a page from file + wiki_helper.py update <title> <file> — update a page from file +""" +import sys, io, json, base64, urllib.request, urllib.error + +sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8') + +# ============================================================ +# ⚙️ CONFIGURATION — Change these values for your project +# ============================================================ +GITEA_BASE_URL = "{{GITEA_BASE_URL}}" # e.g. "https://git.variet.net" +GITEA_OWNER = "{{GITEA_OWNER}}" # e.g. "Variet" +GITEA_REPO = "{{GITEA_REPO}}" # e.g. "gravity_web" +GITEA_TOKEN = "{{GITEA_TOKEN}}" # e.g. "3a01b4b1..." +# ============================================================ + +BASE = f"{GITEA_BASE_URL}/api/v1/repos/{GITEA_OWNER}/{GITEA_REPO}/wiki" +HEADERS = {"Authorization": f"token {GITEA_TOKEN}", "Content-Type": "application/json"} + +def _req(method, path, data=None): + url = f"{BASE}{path}" + body = json.dumps(data).encode() if data else None + req = urllib.request.Request(url, data=body, headers=HEADERS, method=method) + try: + with urllib.request.urlopen(req) as resp: + return json.loads(resp.read().decode()) + except urllib.error.HTTPError as e: + err = e.read().decode() + print(f" ⚠️ HTTP {e.code}: {err}") + return None + +def _find_sub_url(title): + pages = _req("GET", "/pages") + if pages: + for p in pages: + if p.get("title", "").lower() == title.lower(): + return p.get("sub_url", title) + return title + +def list_pages(): + pages = _req("GET", "/pages") + if pages: + print(f"=== {len(pages)} Wiki Pages ===") + for p in pages: + print(f" {p.get('title', '?')}") + return pages + +def read_page(title): + sub = _find_sub_url(title) + page = _req("GET", f"/page/{sub}") + if page and page.get("content_base64"): + content = base64.b64decode(page["content_base64"]).decode("utf-8") + return content + return None + +def create_page(title, content): + data = { + "title": title, + "content_base64": base64.b64encode(content.encode()).decode(), + } + result = _req("POST", "/new", data) + if result: + print(f" ✅ Created wiki page: {title}") + return result + +def update_page(title, content): + sub = _find_sub_url(title) + data = { + "title": title, + "content_base64": base64.b64encode(content.encode()).decode(), + } + result = _req("PATCH", f"/page/{sub}", data) + if result: + print(f" ✅ Updated wiki page: {title}") + return result + +if __name__ == "__main__": + cmd = sys.argv[1] if len(sys.argv) > 1 else "list" + + if cmd == "list": + list_pages() + elif cmd == "read" and len(sys.argv) > 2: + content = read_page(sys.argv[2]) + if content: + print(content[:5000]) + else: + print(f" Page '{sys.argv[2]}' not found") + elif cmd == "create" and len(sys.argv) > 3: + with open(sys.argv[3], "r", encoding="utf-8") as f: + create_page(sys.argv[2], f.read()) + elif cmd == "update" and len(sys.argv) > 3: + with open(sys.argv[3], "r", encoding="utf-8") as f: + update_page(sys.argv[2], f.read()) + else: + print("Usage: wiki_helper.py list|read <title>|create <title> <file>|update <title> <file>") diff --git a/.agents/workflows/services.md b/.agents/workflows/services.md new file mode 100644 index 0000000..384c176 --- /dev/null +++ b/.agents/workflows/services.md @@ -0,0 +1,83 @@ +--- +description: 프로젝트 연동 서비스 URL, API 키, 프로젝트 정보 참조 +--- + +# 서비스 연동 정보 + +> [!CAUTION] +> 이 파일에는 API 토큰이 포함되어 있습니다. `.gitignore`에 `.agents/` 추가를 검토하세요. + +## 로컬 환경 + +| 항목 | 값 | +|------|-----| +| **Node.js** | 시스템 설치 (`node`, `npm`) | +| **Python (helper)** | `{{PYTHON_PATH}}` | +| **프로젝트 루트** | `{{PROJECT_ROOT}}` | +| **Shell** | PowerShell (`curl` = `Invoke-WebRequest` 별칭이므로 반드시 **`curl.exe`** 사용) | +| **서버 실행** | `{{SERVER_START_COMMAND}}` | + +## Gitea (Git Repository) + +| 항목 | 값 | +|------|-----| +| **Base URL** | `{{GITEA_BASE_URL}}` | +| **API Base** | `{{GITEA_BASE_URL}}/api/v1` | +| **Repo** | `{{GITEA_OWNER}}/{{GITEA_REPO}}` | +| **Token** | `{{GITEA_TOKEN}}` | +| **Auth Header** | `-H "Authorization: token {{GITEA_TOKEN}}"` | + +## Vikunja (Task Management) + +| 항목 | 값 | +|------|-----| +| **Base URL** | `{{VIKUNJA_BASE_URL}}` | +| **API Base** | `{{VIKUNJA_BASE_URL}}/api/v1` | +| **Project ID** | `{{VIKUNJA_PROJECT_ID}}` | +| **Token** | `{{VIKUNJA_TOKEN}}` | +| **Auth Header** | `-H "Authorization: Bearer {{VIKUNJA_TOKEN}}"` | + +## Vikunja 태스크 조회 + +> [!TIP] +> 태스크 목록은 항상 라이브 조회를 사용합니다. 하드코딩된 매핑은 유지하지 않습니다. + +```powershell +python .agents\workflows\helpers\vikunja_helper.py list todo +``` + +## 기타 서비스 + +| 서비스 | URL | 용도 | +|--------|-----|------| +| {{SERVICE_NAME}} | {{SERVICE_URL}} | {{SERVICE_PURPOSE}} | + +## AI 작업 프로토콜 + +> [!IMPORTANT] +> 아래 규칙은 모든 작업에 자동 적용됩니다. 유저가 별도 지시하지 않아도 따릅니다. + +### Vikunja = Single Source of Truth (SSOT) + +- **Vikunja가 유일한 작업 현황 관리 도구**입니다. +- 새 TODO 발견 시 → Vikunja에 태스크 생성 +- 작업 완료 시 → Vikunja 태스크 완료 처리 + +### Vikunja 태깅 규칙 + +**영역 라벨 (필수, 1개 이상):** `Backend` / `Frontend` / `Infra` / `Test` +**우선순위 라벨 (필수, 1개):** `Priority:High` / `Priority:Mid` / `Priority:Low` + +### 커밋 메시지 컨벤션 +``` +<type>(<scope>): <description> + +type: feat|fix|refactor|test|docs|chore|ci|infra +scope: (선택) +``` + +## PowerShell 주의사항 + +- `curl` → PowerShell에서 `Invoke-WebRequest`의 별칭. **반드시 `curl.exe`** 사용 +- `npm` → PowerShell에서 실행 정책 문제 시 `cmd /c npm` 사용 +- JSON 파이프 파싱 시 PowerShell 이스케이핑 문제 → `.py` 스크립트 파일로 만들어 실행 권장 diff --git a/.agents/workflows/start.md b/.agents/workflows/start.md index c19019b..806b7f8 100644 --- a/.agents/workflows/start.md +++ b/.agents/workflows/start.md @@ -8,12 +8,14 @@ description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워 // turbo-all -## 0. 에이전트 룰 로딩 +## 절차 + +### 0. 에이전트 룰 & 맥락 로딩 (자동) `.agents/AGENT.md`를 읽고 에이전트 행동 규칙을 로딩합니다. `.agents/references/known-issues.md`를 읽어 최근 이슈를 파악합니다. -## 1. Git 상태 확인 +### 1. Git 상태 확인 ```powershell git status --short @@ -22,16 +24,28 @@ git status --short git log --oneline -5 ``` -## 2. 프로젝트 레퍼런스 확인 +### 2. Vikunja TODO 태스크 -`.agents/references/` 디렉토리의 문서들을 스캔하여 프로젝트 맥락을 파악합니다. +```powershell +python .agents\workflows\helpers\vikunja_helper.py list todo +``` -## 3. 종합 보고 +### 3. Wiki 아키텍처 확인 (필요 시) + +```powershell +python .agents\workflows\helpers\wiki_helper.py read "Architecture" +``` + +### 4. 종합 보고 결과를 종합하여 사용자에게 보고: -- 마지막 커밋 + 변경 사항 +- 마지막 커밋 + 미완료 태스크 - known-issues에서 최근 추가된 항목 +- TODO 태스크 목록 (라벨 + 우선순위) - 다음 작업 제안 -> [!TIP] -> 프로젝트별 워크플로우(Vikunja, Gitea 등)가 있다면 여기에 단계를 추가하세요. +**우선순위 판단 기준:** +- P0: 핵심 기능 연결 관련 (전체 기능 불가) +- P1: 서버/통신 장애 +- P2: 기능 미완성/UX 개선 +- P3: 문서, 코드 정리 diff --git a/README.md b/README.md new file mode 100644 index 0000000..71fb10e --- /dev/null +++ b/README.md @@ -0,0 +1,72 @@ +# 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. {{PLACEHOLDER}} 값들을 프로젝트에 맞게 교체 +# - services.md → API URL, Token, Project ID +# - helpers/vikunja_helper.py → API_BASE, TOKEN, PROJECT_ID +# - helpers/wiki_helper.py → GITEA_BASE_URL, TOKEN, OWNER, REPO +# - check-gitea.md → Token, URL +# - references/ → 프로젝트별 아키텍처, 기술스택, 컨벤션 + +# 3. 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 래퍼 +``` + +## 교체해야 하는 `{{PLACEHOLDER}}` 목록 + +| Placeholder | 설명 | 파일 | +|-------------|------|------| +| `{{GITEA_BASE_URL}}` | Gitea 서버 URL | services.md, check-gitea.md, wiki_helper.py | +| `{{GITEA_OWNER}}` | Gitea 소유자명 | services.md, check-gitea.md, wiki_helper.py | +| `{{GITEA_REPO}}` | Gitea 저장소명 | services.md, check-gitea.md, wiki_helper.py | +| `{{GITEA_TOKEN}}` | Gitea API 토큰 | services.md, check-gitea.md, wiki_helper.py | +| `{{VIKUNJA_BASE_URL}}` | Vikunja 서버 URL | services.md, vikunja_helper.py | +| `{{VIKUNJA_TOKEN}}` | Vikunja API 토큰 | services.md, vikunja_helper.py | +| `{{VIKUNJA_PROJECT_ID}}` | Vikunja 프로젝트 ID | services.md, vikunja_helper.py | +| `{{PYTHON_PATH}}` | Python 실행 경로 | services.md | +| `{{PROJECT_ROOT}}` | 프로젝트 루트 경로 | services.md | +| `{{SERVER_START_COMMAND}}` | 서버 실행 명령어 | services.md | + +## 상세 가이드 + +[GUIDE.md](.agents/GUIDE.md) 참조. + +## 연구 기반 + +7개 AI 에이전트 플랫폼 (Claude, GPT, Gemini, Cursor, Cline, Roo, Windsurf) 분석 + Reflexion Framework, Context Engineering, Sentinel Check 등 최신 연구 기반. + +## License + +Internal — Variet