docs: initial AI agent universal workflow system

2026-03-08 07:54:54 +09:00
commit 2e0a1e37e4
10 changed files with 536 additions and 0 deletions
--- a/.agents/AGENT.md
+++ b/.agents/AGENT.md
@@ -0,0 +1,53 @@
+---
+description: 모든 작업에 자동 적용되는 에이전트 행동 규칙. 새 대화 시작 시 반드시 이 파일을 먼저 읽습니다.
+---
+
+# Agent Rules
+
+## Identity
+
+당신은 이 프로젝트의 시니어 개발자입니다. 지시를 정확히 따르고, 추측보다 근거를 우선합니다.
+
+## NEVER (절대 금지)
+
+1. NEVER start coding without reading relevant reference documents in `.agents/references/`
+2. NEVER guess when documentation exists — always check `.agents/references/` first
+3. NEVER repeat a failed approach — check `.agents/references/known-issues.md` first
+4. NEVER call APIs directly when helper scripts exist in `.agents/workflows/helpers/`
+5. NEVER skip the pre-task checklist defined in `.agents/workflows/pre-task.md`
+6. NEVER attempt the same failed approach more than 2 times
+7. NEVER truncate error messages — always show the full error output
+
+## ALWAYS (필수)
+
+1. ALWAYS run `.agents/workflows/pre-task.md` before any implementation task
+2. ALWAYS check `.agents/references/known-issues.md` before debugging
+3. ALWAYS cite which reference document you consulted and what you learned
+4. ALWAYS stop and ask the user if 2 consecutive attempts on the same approach fail
+5. ALWAYS use existing helper scripts instead of raw API calls
+6. ALWAYS read related existing code (minimum 3 files) before writing new code
+
+## Failure Protocol
+
+```
+1st failure → Re-read reference docs → Try DIFFERENT approach
+2nd failure (same issue) → STOP → Report diagnosis to user with:
+   - What was tried
+   - What failed
+   - Root cause hypothesis
+   - Suggested next steps
+3rd attempt on same approach → FORBIDDEN
+```
+
+## Reference Loading Order
+
+1. `.agents/AGENT.md` (this file — behavior rules)
+2. `.agents/references/known-issues.md` (past failure patterns)
+3. `.agents/references/` (project-specific knowledge)
+4. `.agents/workflows/` (action procedures)
+
+## PowerShell Notes
+
+- `curl` → PowerShell에서 `Invoke-WebRequest` 별칭. **반드시 `curl.exe`** 사용
+- `npm` → 실행 정책 문제 시 `cmd /c npm` 사용
+- JSON 처리 시 `.py` 스크립트 권장 (PowerShell 이스케이핑 이슈 방지)
--- a/.agents/GUIDE.md
+++ b/.agents/GUIDE.md
@@ -0,0 +1,141 @@
+# AI 에이전트 워크플로우 시스템 가이드
+
+> 이 가이드는 AI 코딩 에이전트가 더 똑똑하게 동작하도록 설계된 범용 워크플로우 시스템의 사용법을 설명합니다.
+
+---
+
+## 왜 이 시스템이 필요한가?
+
+AI 에이전트는 다음과 같은 문제를 자주 일으킵니다:
+
+| 문제 | 원인 |
+|------|------|
+| 📋 워크플로우를 무시함 | 규칙이 강제가 아닌 권고 사항으로만 작성됨 |
+| 🔄 같은 실수를 반복함 | 과거 실패 기록을 저장/참조하는 메커니즘 없음 |
+| 📖 레퍼런스 문서를 안 읽음 | "읽어라"는 강제 지시가 없고, 어떤 문서를 확인할지 불명확 |
+| 🎲 추측으로 시행착오 | 작업 전 체크리스트(Pre-flight Checklist) 부재 |
+
+이 시스템은 **13회 웹 검색**, **80+ 소스 분석**, **7개 주요 AI 플랫폼**(Claude, GPT, Gemini, Cursor, Cline, Roo, Windsurf) 연구를 기반으로 설계되었습니다.
+
+---
+
+## 파일 구조 개요
+
+```
+.agents/
+├── AGENT.md                    ← 🧠 에이전트 헌법 (NEVER/ALWAYS 규칙)
+├── references/                 ← 📚 프로젝트 지식 베이스
+│   ├── architecture.md         ← 아키텍처 설명
+│   ├── tech-stack.md           ← 기술 스택 & 버전
+│   ├── conventions.md          ← 코딩 컨벤션
+│   └── known-issues.md         ← 🔴 과거 실패 기록 (핵심!)
+└── workflows/                  ← ⚙️ 행동 절차
+    ├── start.md                ← 세션 시작
+    ├── end.md                  ← 세션 종료 + 학습 기록
+    ├── pre-task.md             ← 작업 전 필수 체크리스트
+    └── debug.md                ← 디버깅 전용 절차
+```
+
+---
+
+## 각 파일의 역할
+
+### 🧠 `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에 추가)
+
+### ▶️ `start.md` / ⏹️ `end.md` — 세션 관리
+
+- **start**: 에이전트 룰 로딩 + Git 상태 + 맥락 복구
+- **end**: 학습 기록 + 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 |
--- a/.agents/references/architecture.md
+++ b/.agents/references/architecture.md
@@ -0,0 +1,35 @@
+# Architecture
+
+> 이 프로젝트의 아키텍처를 설명하는 문서입니다.
+> AI 에이전트는 구현 전 이 문서를 반드시 확인합니다.
+
+## 프로젝트 개요
+
+<!-- 프로젝트의 목적과 핵심 기능을 간략히 서술 -->
+
+(프로젝트 설명을 여기에 작성하세요)
+
+## 디렉토리 구조
+
+```
+project-root/
+├── src/                  # 소스 코드
+├── tests/                # 테스트
+├── docs/                 # 문서
+├── .agents/              # AI 에이전트 설정
+└── ...
+```
+
+## 핵심 모듈
+
+<!-- 각 모듈의 역할과 의존 관계를 설명 -->
+
+| 모듈 | 역할 | 의존성 |
+|------|------|--------|
+| (모듈명) | (역할 설명) | (의존하는 모듈) |
+
+## 데이터 흐름
+
+<!-- 주요 데이터 흐름을 Mermaid 다이어그램이나 텍스트로 설명 -->
+
+(데이터 흐름을 여기에 작성하세요)
--- a/.agents/references/conventions.md
+++ b/.agents/references/conventions.md
@@ -0,0 +1,45 @@
+# Coding Conventions
+
+> AI 에이전트는 코드를 작성하기 전 이 컨벤션을 확인합니다.
+
+## 네이밍
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 변수/함수 | camelCase | `getUserData()` |
+| 클래스 | PascalCase | `UserService` |
+| 상수 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| 파일명 | kebab-case | `user-service.js` |
+| CSS 클래스 | kebab-case | `.nav-header` |
+
+## 코드 스타일
+
+- 들여쓰기: (2 spaces / 4 spaces / tab)
+- 세미콜론: (사용 / 미사용)
+- 따옴표: (single / double)
+- 줄바꿈: LF (Unix style)
+
+## 커밋 메시지
+
+```
+<type>(<scope>): <description>
+
+type: feat|fix|refactor|test|docs|chore|ci|infra
+scope: (선택)
+```
+
+**예시:**
+- `feat(server): add WebSocket reconnection logic`
+- `fix(frontend): resolve button overlap on mobile`
+- `docs: update API documentation`
+
+## 주석
+
+- 한국어/영어 혼용 가능
+- TODO 주석: `// TODO: 설명` 형식
+- 복잡한 로직에는 반드시 WHY(왜) 주석 추가
+
+## 테스트
+
+- 테스트 파일 위치: (예: `__tests__/` 또는 `*.test.js`)
+- 테스트 네이밍: `should [expected behavior] when [condition]`
--- a/.agents/references/known-issues.md
+++ b/.agents/references/known-issues.md
@@ -0,0 +1,43 @@
+# Known Issues & Lessons Learned
+
+> **이 파일은 SSOT(Single Source of Truth)입니다.**
+> 디버깅이나 구현 전에 **반드시** 이 파일을 확인하세요.
+> 세션 종료 시 새로 발견된 이슈를 이 파일에 추가합니다.
+
+---
+
+## 포맷
+
+각 항목은 아래 형식을 따릅니다:
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: 무엇이 잘못되었는가
+- **원인**: 근본 원인
+- **해결**: 올바른 해결 방법
+- **주의**: 재발 방지를 위한 교훈
+```
+
+---
+
+## 공통 이슈
+
+### [2026-03-08] PowerShell curl — Invoke-WebRequest 충돌
+- **증상**: `curl` 명령이 예상과 다른 응답 형식을 반환
+- **원인**: PowerShell에서 `curl`은 `Invoke-WebRequest`의 별칭
+- **해결**: **`curl.exe`**를 명시적으로 사용
+- **주의**: HTTP 관련 모든 명령에서 `curl.exe` 사용 필수
+
+### [2026-03-08] PowerShell npm — 실행 정책 오류
+- **증상**: `npm run` 명령이 `실행 정책` 관련 오류로 실패
+- **원인**: PowerShell 스크립트 실행 정책이 제한적으로 설정됨
+- **해결**: `cmd /c npm run dev` 형식으로 cmd를 통해 실행
+- **주의**: npm 관련 명령은 항상 `cmd /c` 접두어 사용 권장
+
+---
+
+## 프로젝트별 이슈
+
+> 아래에 프로젝트 특화 이슈를 추가하세요.
+
+(아직 기록된 프로젝트별 이슈가 없습니다)
--- a/.agents/references/tech-stack.md
+++ b/.agents/references/tech-stack.md
@@ -0,0 +1,37 @@
+# Tech Stack
+
+> AI 에이전트는 구현 전 이 문서를 확인하여 올바른 기술/버전을 사용합니다.
+
+## 언어 & 런타임
+
+| 항목 | 버전 | 비고 |
+|------|------|------|
+| (예: Node.js) | (예: 20.x) | (설치 경로 등) |
+| (예: Python) | (예: 3.12) | (가상환경 경로 등) |
+
+## 프레임워크
+
+| 항목 | 버전 | 용도 |
+|------|------|------|
+| (예: Express) | (예: 4.18) | (서버) |
+| (예: React) | (예: 18.x) | (프론트엔드) |
+
+## 패키지 관리
+
+- 패키지 매니저: (npm / yarn / pnpm / pip 등)
+- Lock 파일: (package-lock.json / yarn.lock 등)
+
+## 개발 도구
+
+| 도구 | 명령어 |
+|------|--------|
+| 개발 서버 | (예: `cmd /c npm run dev`) |
+| 빌드 | (예: `cmd /c npm run build`) |
+| 테스트 | (예: `cmd /c npm test`) |
+| 린트 | (예: `cmd /c npm run lint`) |
+
+## 환경 변수
+
+| 변수명 | 용도 | 기본값 |
+|--------|------|--------|
+| (예: PORT) | (서버 포트) | (3000) |
--- a/.agents/workflows/debug.md
+++ b/.agents/workflows/debug.md
@@ -0,0 +1,52 @@
+---
+description: 에러/버그 발생 시 체계적 디버깅 워크플로우 (에러, 안돼요, 왜 안돼, 버그, 디버그, 수정)
+---
+
+# Debug Workflow
+
+> [!IMPORTANT]
+> 추측으로 코드를 수정하지 마세요. 반드시 이 순서를 따릅니다.
+
+## 1단계: 정보 수집 (추측 금지)
+
+- [ ] 에러 메시지 **전문** 확인 (절대 잘라내지 않기)
+- [ ] 관련 로그 파일 확인
+- [ ] 환경 정보 확인 (OS, Node/Python 버전, 의존성 버전 등)
+- [ ] 에러가 발생하는 **정확한 입력/조건** 파악
+
+## 2단계: Known Issues 확인
+
+`.agents/references/known-issues.md`를 읽고 동일하거나 유사한 문제가 있는지 확인합니다.
+
+> [!CAUTION]
+> **known-issues 확인 없이 해결 시도를 시작하지 마세요.**
+> 이미 해결된 문제를 다시 삽질하는 것은 시간 낭비입니다.
+
+## 3단계: 근본 원인 분석
+
+- [ ] 에러가 발생하는 **정확한 코드 위치** 확인
+- [ ] 가설을 세우고, 가설을 검증할 수 있는 **최소한의 테스트** 수행
+- [ ] 가설이 틀렸다면 **즉시 다른 가설로 전환**
+
+> [!WARNING]
+> **동일한 접근을 2회 초과 시도하지 마세요.**
+> 2회 실패 시 유저에게 보고하고 판단을 요청합니다.
+> 보고 내용: 시도한 것 / 실패한 것 / 원인 가설 / 다음 제안
+
+## 4단계: 수정 및 검증
+
+- [ ] 수정 적용
+- [ ] 동일 에러가 재현되지 않는지 확인
+- [ ] 사이드 이펙트(다른 기능에 영향) 없는지 확인
+
+## 5단계: 기록
+
+- [ ] `known-issues.md`에 새 항목 추가 (아래 포맷 사용)
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: 무엇이 잘못되었는가
+- **원인**: 근본 원인
+- **해결**: 올바른 해결 방법
+- **주의**: 재발 방지를 위한 교훈
+```
--- a/.agents/workflows/end.md
+++ b/.agents/workflows/end.md
@@ -0,0 +1,54 @@
+---
+description: 세션 종료 시 학습 기록 + git commit (끝, 마무리, 커밋해, 완료)
+---
+
+# 세션 종료 프로토콜
+
+작업 완료, "끝", "마무리", "커밋해" 등 요청 시 이 워크플로우를 실행합니다.
+
+// turbo-all
+
+## 0. 학습 기록 (실패/시행착오 저장)
+
+이번 세션에서 발생한 실패, 시행착오, 새로 알게 된 사실을 정리합니다:
+
+- [ ] `known-issues.md`에 추가할 항목이 있는지 확인
+- [ ] 있다면 `.agents/references/known-issues.md`에 표준 포맷으로 추가:
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: ...
+- **원인**: ...
+- **해결**: ...
+- **주의**: ...
+```
+
+## 1. Git Commit & Push
+
+```powershell
+git add -A
+git status --short
+```
+```powershell
+git commit -m "커밋 메시지"
+```
+```powershell
+git push origin main
+```
+
+**커밋 메시지 컨벤션:**
+```
+<type>(<scope>): <description>
+
+type: feat|fix|refactor|test|docs|chore|ci|infra
+scope: (선택 — 모듈명 등)
+```
+
+## 2. 최종 체크리스트
+
+- [ ] known-issues 업데이트 완료
+- [ ] git push 완료
+- [ ] 사용자에게 완료 보고
+
+> [!TIP]
+> 프로젝트별 워크플로우(Vikunja 동기화, Wiki 업데이트 등)가 있다면 여기에 단계를 추가하세요.
--- a/.agents/workflows/pre-task.md
+++ b/.agents/workflows/pre-task.md
@@ -0,0 +1,39 @@
+---
+description: 모든 구현 작업 전 실행하는 사전 점검 체크리스트 (pre-task, 준비, 시작 전, 계획, 구현)
+---
+
+# Pre-Task Checklist
+
+> [!IMPORTANT]
+> 코딩을 시작하기 전에 반드시 이 체크리스트를 순서대로 완료하세요.
+> 체크리스트를 건너뛸 경우 불필요한 시행착오가 발생합니다.
+
+## 1단계: 요구사항 정리
+
+- [ ] 유저 요청을 구체적 작업 항목으로 분해
+- [ ] 변경 범위(scope)를 명확히 정의 (영향받는 파일/모듈)
+- [ ] 성공 기준(acceptance criteria) 확인
+
+## 2단계: 레퍼런스 확인 (추측 금지)
+
+- [ ] `.agents/references/architecture.md` — 현재 아키텍처 확인
+- [ ] `.agents/references/tech-stack.md` — 기술 스택 및 버전 확인
+- [ ] `.agents/references/conventions.md` — 코딩 컨벤션 확인
+- [ ] `.agents/references/known-issues.md` — 과거 실패 패턴 확인
+- [ ] 관련 기존 코드 최소 3개 파일 읽기
+
+> [!CAUTION]
+> 레퍼런스 문서가 존재하는 주제에 대해 추측하지 마세요.
+> 문서가 없으면 유저에게 확인을 요청하세요.
+
+## 3단계: 계획 수립
+
+- [ ] 변경할 파일 목록 작성
+- [ ] 의존성 순서 파악 (어떤 파일부터 수정해야 하는가?)
+- [ ] 리스크 식별 (어디서 실패할 가능성이 높은가?)
+- [ ] 테스트 방법 결정 (어떻게 검증할 것인가?)
+
+## 4단계: 유저 확인
+
+- [ ] 계획을 유저에게 보고하고 승인받기 (변경 파일 3개 이상인 경우)
+- [ ] 작은 변경은 바로 실행하되, 변경 내용을 명확히 설명
--- a/.agents/workflows/start.md
+++ b/.agents/workflows/start.md
@@ -0,0 +1,37 @@
+---
+description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워크플로우 (시작, continue, 이어서, 작업 시작)
+---
+
+# 세션 시작 프로토콜
+
+새 대화 시작, "continue", "이어서", "작업 시작" 등 요청 시 이 워크플로우를 실행합니다.
+
+// turbo-all
+
+## 0. 에이전트 룰 로딩
+
+`.agents/AGENT.md`를 읽고 에이전트 행동 규칙을 로딩합니다.
+`.agents/references/known-issues.md`를 읽어 최근 이슈를 파악합니다.
+
+## 1. Git 상태 확인
+
+```powershell
+git status --short
+```
+```powershell
+git log --oneline -5
+```
+
+## 2. 프로젝트 레퍼런스 확인
+
+`.agents/references/` 디렉토리의 문서들을 스캔하여 프로젝트 맥락을 파악합니다.
+
+## 3. 종합 보고
+
+결과를 종합하여 사용자에게 보고:
+- 마지막 커밋 + 변경 사항
+- known-issues에서 최근 추가된 항목
+- 다음 작업 제안
+
+> [!TIP]
+> 프로젝트별 워크플로우(Vikunja, Gitea 등)가 있다면 여기에 단계를 추가하세요.