CD
3d3f74b082
- 5단계 파이프라인: 다운로드 → 프레임 추출 → 패턴 감지 → 중복 제거 → PDF 생성 - 3가지 패턴 지원: overlay, split, scroll - MSE 기반 픽셀 비교 프레임 중복 제거 - split 모드: 42% 크롭 + 밝기 필터 + Tab 라인 검증 - overlay 모드: 320x120 정규화 + 슬라이딩 윈도우 비교 - 프로젝트 문서 초기 작성 (architecture, tech-stack, STATUS, known-issues)
7.0 KiB
7.0 KiB
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단계 체크리스트:
- 요구사항 정리
- 레퍼런스 확인 (추측 금지)
- 계획 수립
- 유저 확인
🔴 known-issues.md — 과거 실패 기록
가장 중요한 파일. 에이전트가 같은 실수를 반복하는 근본 원인은 실패를 기억하지 못하기 때문입니다. 이 파일은:
- 세션 종료 시 에이전트가 자동으로 새 이슈를 추가
- 디버깅/구현 전에 에이전트가 반드시 확인
- 시간이 지날수록 축적 학습 효과
🔧 debug.md — 디버깅 전용 워크플로우
추측 기반 디버깅을 금지하는 5단계 절차:
- 정보 수집 (에러 전문 확인)
- known-issues 확인
- 근본 원인 분석 (가설 → 검증)
- 수정 및 검증
- 기록 (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 |