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

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

---

## 파일 구조 개요

```
.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                   ← 서비스 연동 정보 (API 토큰 포함)
    ├── check-gitea.md                ← Gitea 현황 조회
    ├── check-vikunja.md              ← Vikunja 태스크 조회
    └── helpers/
        ├── vikunja_helper.py         ← Vikunja API 안전 래퍼
        └── wiki_helper.py            ← Gitea Wiki 래퍼
```

## 각 파일의 역할

### 🧠 `AGENT.md` — 에이전트 헌법
에이전트가 **모든 대화에서 따라야 하는 글로벌 규칙**입니다.

### 📋 `pre-task.md` — 사전 점검 체크리스트
모든 구현 작업 전에 실행하는 **4단계 체크리스트**.

### 🔴 `known-issues.md` — 과거 실패 기록
**가장 중요한 파일.** 에이전트가 같은 실수를 반복하지 않도록 실패를 기록합니다.

### 🔧 `debug.md` — 디버깅 전용 워크플로우
추측 기반 디버깅을 금지하는 5단계 절차.

### 📓 Devlog — 세션별 작업 기록 (start.md / end.md에서 관리)
- **Index** (`docs/devlog/YYYY-MM-DD.md`): 매 작업마다 1줄 (필수)
- **Entry** (`docs/devlog/entries/YYYYMMDD-NNN.md`): 설계 결정/미완료/삽질 시만 (선택)