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

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

---

## 왜 이 시스템이 필요한가?

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

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

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

---

## 파일 구조 개요

```
.agent/
├── 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                   ← 서비스 연동 + 작업 프로토콜 + 개발/테스트 명령어
    ├── 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

---

## 사용법

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

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

```
.agent/
├── 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 |