variet-agent/.agents/GUIDE.md

AI 에이전트 워크플로우 시스템 가이드

이 가이드는 AI 코딩 에이전트가 더 똑똑하게 동작하도록 설계된 범용 워크플로우 시스템의 사용법을 설명합니다.

---

왜 이 시스템이 필요한가?

AI 에이전트는 다음과 같은 문제를 자주 일으킵니다:

문제	원인
📋 워크플로우를 무시함	규칙이 강제가 아닌 권고 사항으로만 작성됨
🔄 같은 실수를 반복함	과거 실패 기록을 저장/참조하는 메커니즘 없음
📖 레퍼런스 문서를 안 읽음	"읽어라"는 강제 지시가 없고, 어떤 문서를 확인할지 불명확
🎲 추측으로 시행착오	작업 전 체크리스트(Pre-flight Checklist) 부재

이 시스템은 13회 웹 검색, 80+ 소스 분석, 7개 주요 AI 플랫폼(Claude, GPT, Gemini, Cursor, Cline, Roo, Windsurf) 연구를 기반으로 설계되었습니다.

---

파일 구조 개요

.agents/
├── AGENT.md                          ← 🧠 에이전트 헌법 (NEVER/ALWAYS 규칙)
├── GUIDE.md                          ← 📖 이 가이드
├── references/                       ← 📚 프로젝트 지식 베이스
│   ├── architecture.md               ← 아키텍처 설명
│   ├── tech-stack.md                 ← 기술 스택 & 버전
│   ├── conventions.md                ← 코딩 컨벤션
│   └── known-issues.md               ← 🔴 과거 실패 기록 (핵심!)
└── workflows/                        ← ⚙️ 행동 절차
    ├── start.md                      ← 세션 시작 (룰 로딩 + devlog 복구)
    ├── end.md                        ← 세션 종료 (devlog + known-issues + Vikunja + Git)
    ├── pre-task.md                   ← 작업 전 필수 체크리스트
    ├── debug.md                      ← 디버깅 전용 절차
    ├── services.md                   ← 서비스 연동 정보 + AI 작업 프로토콜
    ├── check-gitea.md                ← Gitea 현황 조회
    ├── check-vikunja.md              ← Vikunja 태스크 조회
    └── helpers/
        ├── vikunja_helper.py         ← Vikunja API 안전 래퍼
        └── wiki_helper.py            ← Gitea Wiki 래퍼

프로젝트 루트에 자동 생성되는 디렉토리:

docs/devlog/                          ← 📓 세션별 작업 기록
├── YYYY-MM-DD.md                     ← Index (매일 1줄씩 누적)
└── entries/
    └── YYYYMMDD-NNN.md               ← Entry (설계 결정/미완료 시만)

---

각 파일의 역할

🧠 AGENT.md — 에이전트 헌법

에이전트가 모든 대화에서 따라야 하는 글로벌 규칙입니다.

핵심 메커니즘:

• NEVER 규칙: "절대 ~하지 마라" — 연구에 따르면 금지 규칙이 더 잘 지켜집니다
• Failure Protocol: 동일 접근 2회 실패 시 자동 중단 → 유저에게 보고
• Reference Loading Order: 어떤 문서를 먼저 읽을지 우선순위 명시

📋 pre-task.md — 사전 점검 체크리스트

모든 구현 작업 전에 실행하는 4단계 체크리스트:

1. 요구사항 정리
2. 레퍼런스 확인 (추측 금지)
3. 계획 수립
4. 유저 확인

🔴 known-issues.md — 과거 실패 기록

가장 중요한 파일. 에이전트가 같은 실수를 반복하는 근본 원인은 실패를 기억하지 못하기 때문입니다. 이 파일은:

• 세션 종료 시 에이전트가 자동으로 새 이슈를 추가
• 디버깅/구현 전에 에이전트가 반드시 확인
• 시간이 지날수록 축적 학습 효과

🔧 debug.md — 디버깅 전용 워크플로우

추측 기반 디버깅을 금지하는 5단계 절차:

1. 정보 수집 (에러 전문 확인)
2. known-issues 확인
3. 근본 원인 분석 (가설 → 검증)
4. 수정 및 검증
5. 기록 (known-issues에 추가)

📓 Devlog — 세션별 작업 기록 (start.md / end.md에서 관리)

known-issues가 실패만 기록한다면, devlog는 전체 세션 이력을 기록합니다:

• Index (docs/devlog/YYYY-MM-DD.md): 매 작업마다 1줄 (필수)
• Entry (docs/devlog/entries/YYYYMMDD-NNN.md): 설계 결정/미완료/삽질 시만 (선택)
• start.md에서 자동으로 오늘/어제 devlog를 읽어 맥락 복구

▶️ start.md / ⏹️ end.md — 세션 관리

• start: 에이전트 룰 로딩 + devlog 맥락 복구 + Git 상태 + Vikunja TODO
• end: known-issues 업데이트 + devlog 기록 + Vikunja 동기화 + Git commit/push

---

사용법

새 프로젝트에 적용하기

1. .agents/ 디렉토리를 프로젝트에 복사
2. references/ 파일들을 프로젝트에 맞게 채우기:
   • architecture.md — 프로젝트 구조 설명
   • tech-stack.md — 사용 기술 및 버전
   • conventions.md — 코딩 스타일 규칙
3. 프로젝트별 워크플로우가 있다면 workflows/에 추가

프로젝트별 워크플로우와 함께 사용하기

이 범용 워크플로우와 프로젝트별 워크플로우(예: Vikunja 동기화, Gitea 연동)는 함께 사용합니다:

.agents/
├── AGENT.md                    ← 범용 (공통)
├── references/                 ← 범용 + 프로젝트 특화
│   ├── known-issues.md         ← 범용 (공통)
│   └── ...                     ← 프로젝트에 맞게 작성
└── workflows/
    ├── pre-task.md             ← 범용 (공통)
    ├── debug.md                ← 범용 (공통)
    ├── start.md                ← 범용 기반 + 프로젝트 단계 추가
    ├── end.md                  ← 범용 기반 + 프로젝트 단계 추가
    ├── services.md             ← ⭐ 프로젝트별
    ├── check-vikunja.md        ← ⭐ 프로젝트별
    ├── check-gitea.md          ← ⭐ 프로젝트별
    └── helpers/
        ├── vikunja_helper.py   ← ⭐ 프로젝트별
        └── wiki_helper.py      ← ⭐ 프로젝트별

다른 AI IDE에서도 사용하기

대상 플랫폼	방법
Cursor	AGENT.md → .cursor/rules/agent.mdc (alwaysApply)
Claude Code	AGENT.md → CLAUDE.md, references를 @import
Windsurf	AGENT.md → .windsurfrules 또는 .windsurf/rules/agent.md
Cline/Roo	루트에 AGENTS.md로 복사
Gemini	AGENT.md → .gemini/GEMINI.md

---

연구 근거 요약

이 시스템의 각 설계 결정은 학술 연구와 실무 사례에 근거합니다:

설계 결정	근거
NEVER > ALWAYS (금지 규칙 우선)	Community 검증 — "NEVER use X" ≫ "always prefer Y"
2회 실패 시 자동 중단	Streak Breaker / Sentinel Check 연구
실패 기록 누적	Reflexion Framework (텍스트 피드백 기반 자기 교정)
사전 체크리스트 강제	Claude Skills 체크리스트 + GPT Chain-of-Thought
Progressive Disclosure	Anthropic Context Engineering (2025)
300줄 이하 규칙	Claude CLAUDE.md 공식 권장 (토큰 효율성)
코드 예시 > 설명	GitHub Copilot Agents, AGENTS.md 공통 Best Practice