agent_guide/README.md

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 래퍼

교체해야 하는 {{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 참조.

연구 기반

7개 AI 에이전트 플랫폼 (Claude, GPT, Gemini, Cursor, Cline, Roo, Windsurf) 분석 + Reflexion Framework, Context Engineering, Sentinel Check 등 최신 연구 기반.

License

Internal — Variet