edf/.agents/GUIDE.md

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): 설계 결정/미완료/삽질 시만 (선택)