Agent Guide — AI 에이전트 범용 워크플로우 시스템
AI 코딩 에이전트가 더 똑똑하게 동작하도록 설계된 범용 워크플로우 템플릿. 새 프로젝트에서
.agents/폴더를 통째로 복사하고,{{PLACEHOLDER}}를 교체하면 즉시 사용 가능합니다.
Quick Start
# 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 래퍼
교체해야 하는 값 (프로젝트별)
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 참조.
연구 기반
7개 AI 에이전트 플랫폼 (Claude, GPT, Gemini, Cursor, Cline, Roo, Windsurf) 분석 + Reflexion Framework, Context Engineering, Sentinel Check 등 최신 연구 기반.
License
Internal — Variet