Variet/agent_guide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add complete project init templates (Vikunja, Gitea, Wiki helpers)

Browse Source
This commit is contained in:
authentik Default Admin
2026-03-08 08:09:25 +09:00
parent 2e0a1e37e4
commit 19795bd7ac
8 changed files with 613 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
.agents/workflows/check-gitea.md Normal file
View File

@@ -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
```

41
.agents/workflows/check-vikunja.md Normal file
View File

@@ -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 패턴을 사용합니다.

46
.agents/workflows/end.md
View File

@@ -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 업데이트 등)가 있다면 여기에 단계를 추가하세요.

217
.agents/workflows/helpers/vikunja_helper.py Normal file
View File

@@ -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()

100
.agents/workflows/helpers/wiki_helper.py Normal file
View File

@@ -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 <title> — 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>")

83
.agents/workflows/services.md Normal file
View File

@@ -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` 스크립트 파일로 만들어 실행 권장

30
.agents/workflows/start.md
View File

@@ -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: 문서, 코드 정리

72
README.md Normal file
View File

@@ -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