CD
c92433b0b1
- tools/anissia_client.py: Anissia API 클라이언트 (편성표/자막) - tools/nyaa_client.py: Nyaa.si RSS 토렌트 검색 - tools/qbit_client.py: qBittorrent Web API 클라이언트 - tools/subtitle_downloader.py: Google Drive/Tistory/Naver 자막 파서 - tools/title_matcher.py: 제목 매칭 + NAS 폴더명 생성 - tools/anime_pipeline.py: 전체 파이프라인 오케스트레이터 - tools/nas_scanner.py: NAS 폴더/파일 스캔 - prompts/unified.md: anime 모드 추가 (AI 평문 의도 분류) - api/discord_bot.py: AI 평문 anime 핸들러 + /anime 슬래시 커맨드 - config.py: qBittorrent/NAS 설정 추가 - .agents/: agent_guide 워크플로우 통합 - docs/devlog: 세션 기록
164 lines
7.3 KiB
Markdown
164 lines
7.3 KiB
Markdown
# AI 에이전트 워크플로우 시스템 가이드
|
|
|
|
> 이 가이드는 AI 코딩 에이전트가 더 똑똑하게 동작하도록 설계된 범용 워크플로우 시스템의 사용법을 설명합니다.
|
|
|
|
---
|
|
|
|
## 왜 이 시스템이 필요한가?
|
|
|
|
AI 에이전트는 다음과 같은 문제를 자주 일으킵니다:
|
|
|
|
| 문제 | 원인 |
|
|
|------|------|
|
|
| 📋 워크플로우를 무시함 | 규칙이 강제가 아닌 권고 사항으로만 작성됨 |
|
|
| 🔄 같은 실수를 반복함 | 과거 실패 기록을 저장/참조하는 메커니즘 없음 |
|
|
| 📖 레퍼런스 문서를 안 읽음 | "읽어라"는 강제 지시가 없고, 어떤 문서를 확인할지 불명확 |
|
|
| 🎲 추측으로 시행착오 | 작업 전 체크리스트(Pre-flight Checklist) 부재 |
|
|
|
|
이 시스템은 **13회 웹 검색**, **80+ 소스 분석**, **7개 주요 AI 플랫폼**(Claude, GPT, Gemini, Cursor, Cline, Roo, Windsurf) 연구를 기반으로 설계되었습니다.
|
|
|
|
---
|
|
|
|
## 파일 구조 개요
|
|
|
|
```
|
|
.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 ← 서비스 연동 정보 + AI 작업 프로토콜
|
|
├── 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
|
|
|
|
---
|
|
|
|
## 사용법
|
|
|
|
### 새 프로젝트에 적용하기
|
|
|
|
1. `.agents/` 디렉토리를 프로젝트에 복사
|
|
2. `references/` 파일들을 프로젝트에 맞게 채우기:
|
|
- `architecture.md` — 프로젝트 구조 설명
|
|
- `tech-stack.md` — 사용 기술 및 버전
|
|
- `conventions.md` — 코딩 스타일 규칙
|
|
3. 프로젝트별 워크플로우가 있다면 `workflows/`에 추가
|
|
|
|
### 프로젝트별 워크플로우와 함께 사용하기
|
|
|
|
이 범용 워크플로우와 프로젝트별 워크플로우(예: Vikunja 동기화, Gitea 연동)는 **함께 사용**합니다:
|
|
|
|
```
|
|
.agents/
|
|
├── 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 |
|