CD
3d3f74b082
- 5단계 파이프라인: 다운로드 → 프레임 추출 → 패턴 감지 → 중복 제거 → PDF 생성 - 3가지 패턴 지원: overlay, split, scroll - MSE 기반 픽셀 비교 프레임 중복 제거 - split 모드: 42% 크롭 + 밝기 필터 + Tab 라인 검증 - overlay 모드: 320x120 정규화 + 슬라이딩 윈도우 비교 - 프로젝트 문서 초기 작성 (architecture, tech-stack, STATUS, known-issues)
155 lines
7.0 KiB
Markdown
155 lines
7.0 KiB
Markdown
# 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 |
|