ANYON 계획 에이전트 - 완벽 가이드

📚 문서 구성

이 디렉토리에는 계획 에이전트를 설계부터 배포까지 완벽하게 구현하는데 필요한 모든 문서가 있습니다.

---

🗺️ 문서 로드맵

1️⃣ 먼저 읽어야 할 문서 (이해하기)

문서	내용	읽는데 걸리는 시간
설계 문서	계획 에이전트의 전체 아키텍처, 입출력 구조, LangGraph 워크플로우	15분
통합 전략	ANYON에 통합하는 방법, 3단계 전략, 팀 역할 분담	10분
KPI 문서	성능 측정 지표, 대시보드 설계, 목표 설정	10분

2️⃣ 실제로 개발할 때 (실행하기)

문서	내용	개발 시간
Quick Start	5분 만에 프로젝트 시작, 복사-붙여넣기 가능	5분
개발 가이드	Day 1부터 Day 14까지 단계별 완전 구현, 모든 코드 포함	2주

---

🎯 어떤 순서로 읽어야 할까?

시나리오 A: "빨리 시작하고 싶어요!"

1. Quick Start (5분)
   → 바로 실행 가능한 최소 버전 만들기
   
2. 개발 가이드 Day 1-3 (1주)
   → LangGraph 기본 구현
   
3. 통합 전략 Phase 2-3 (1주)
   → API 서버화 + ANYON 통합

시나리오 B: "제대로 이해하고 시작하고 싶어요"

1. 설계 문서 (15분)
   → 전체 구조 파악
   
2. 통합 전략 (10분)
   → 개발 계획 이해
   
3. Quick Start (5분)
   → 기본 실행 확인
   
4. 개발 가이드 전체 (2주)
   → 단계별 완전 구현
   
5. KPI 문서 (10분)
   → 성능 측정 준비

시나리오 C: "투자자/상사에게 보고해야 해요"

1. 설계 문서 (15분)
   → 기술 아키텍처 이해
   
2. KPI 문서 (10분)
   → 성과 측정 방법
   
3. 통합 전략 (10분)
   → 일정 및 비용

---

📊 각 문서 상세 설명

1. 설계 문서 (planning_agent_design.md)

내용:

• 계획 에이전트의 전체 아키텍처
• 6개 노드 (collect_context → analyze_technical → generate_steps → validate_deps → estimate → finalize)
• 입출력 데이터 구조
• LangGraph 워크플로우 다이어그램
• 개발 에이전트와의 인터페이스

이런 사람에게 추천:

• ✅ CTO / 기술 리드
• ✅ 전체 시스템 구조를 이해하고 싶은 사람
• ✅ 다른 팀원에게 설명해야 하는 사람

핵심 내용:

Epic → [계획 에이전트] → 실행 가능한 단계별 계획
       6개 노드 처리
       ↓
       {
         "steps": [...],
         "parallel_groups": [...],
         "estimated_hours": 5
       }

---

2. KPI 문서 (planning_agent_kpi.md)

내용:

• 10개 카테고리의 성능 지표
• 실행 성공률, 병렬화 효율성 등 핵심 KPI
• 실시간 대시보드 설계
• 주간/월간 리포트 템플릿
• 장기 목표 로드맵

이런 사람에게 추천:

• ✅ CEO / PM
• ✅ 성과 측정이 필요한 사람
• ✅ 투자자 보고 준비하는 사람

핵심 지표:

North Star Metrics:
1. 계획 실행 성공률: 85% → 95%
2. 병렬화 효율성: 30% → 50% 시간 단축

주요 KPI:
- 의존성 정확도: 95%
- 사용자 만족도: 4.5/5
- 생성 속도: <60초
- 비용: $0.10/Epic

---

3. 통합 전략 (planning_agent_integration_strategy.md)

내용:

• 3단계 점진적 통합 (프로토타입 → API → 완전 통합)
• 3인 팀 역할 분담 및 2주 일정
• MVP 포함 여부 결정
• 위험 관리 및 비용 분석
• 실전 조언 및 체크리스트

이런 사람에게 추천:

• ✅ 전체 팀
• ✅ 프로젝트 매니저
• ✅ "어떻게 시작하지?" 고민하는 사람

핵심 전략:

Phase 1 (1-2주): 독립 프로토타입
  → CLI 실행 가능
  → CTO 혼자 개발

Phase 2 (3-5일): REST API 서비스화
  → FastAPI + Docker
  → ANYON과 API 통신

Phase 3 (5-7일): 완전 통합
  → 칸반보드 UI 연결
  → 전체 시스템 완성

---

4. Quick Start (planning_agent_quickstart.md)

내용:

• 5분 만에 실행 가능한 최소 버전
• 복사-붙여넣기 명령어
• 즉시 실행 및 테스트
• 일반적인 문제 해결

이런 사람에게 추천:

• ✅ 지금 당장 시작하고 싶은 사람
• ✅ 개발 경험이 많지 않은 사람
• ✅ 빠른 프로토타입이 필요한 사람

실행 순서:

# 1. 프로젝트 생성 (1분)
mkdir planning-agent && cd planning-agent
python3.11 -m venv venv
source venv/bin/activate

# 2. 의존성 설치 (1분)
pip install -r requirements.txt

# 3. 환경 설정 (30초)
# .env 파일에 API 키 입력

# 4. 테스트 실행 (10초)
python -m src.main tests/fixtures/test_epic.json

# ✅ 완료!

---

5. 개발 가이드 (planning_agent_dev_guide.md)

내용:

• Day 1-14까지 단계별 완전 가이드
• 모든 파일의 전체 코드
• LangGraph 노드 구현
• FastAPI 서버 구현
• Docker 컨테이너화
• ANYON 통합
• 트러블슈팅

이런 사람에게 추천:

• ✅ 실제로 개발할 개발자
• ✅ 코드 레벨 구현이 필요한 사람
• ✅ 2주 동안 집중 개발할 사람

주차별 목표:

Week 1:
  Day 1-2: 환경 구축, 데이터 스키마
  Day 3-5: LangGraph 노드 구현
  Day 6-7: 워크플로우 조립, 테스트

Week 2:
  Day 8-10: FastAPI 서비스화, Docker
  Day 11-12: ANYON 백엔드 통합
  Day 13-14: 프론트엔드 UI 통합

---

🚀 지금 바로 시작하는 방법

Option 1: 가장 빠른 방법 (권장)

# 1. Quick Start 문서 열기
open planning_agent_quickstart.md

# 2. 명령어 복사-붙여넣기
# 5분 후 실행 완료!

# 3. 본격 개발은 개발 가이드 참고
open planning_agent_dev_guide.md

Option 2: 체계적인 방법

# 1. 설계 문서로 전체 이해
open planning_agent_design.md

# 2. 통합 전략으로 계획 수립
open planning_agent_integration_strategy.md

# 3. Quick Start로 시작
open planning_agent_quickstart.md

# 4. 개발 가이드로 완성
open planning_agent_dev_guide.md

# 5. KPI 문서로 측정
open planning_agent_kpi.md

---

💡 각 역할별 추천 문서

🎨 CEO / 창업자

1. [통합 전략] - 일정과 비용 확인
2. [KPI 문서] - 성과 측정 방법
3. [설계 문서] - 기술 개요 파악

💻 CTO / 개발자

1. [설계 문서] - 아키텍처 이해
2. [Quick Start] - 즉시 실행
3. [개발 가이드] - 단계별 구현
4. [통합 전략] - 배포 계획

🎨 Designer / PM

1. [통합 전략] - 전체 흐름 이해
2. [설계 문서] - UI 연동 포인트
3. [KPI 문서] - 사용자 경험 지표

---

📝 문서 업데이트 이력

날짜	버전	변경사항
2025-11-11	1.0	초기 문서 세트 완성

---

⚠️ 중요 참고사항

필수 요구사항

• Python 3.11+
• Anthropic API Key
• 2주 개발 시간
• ANYON 기존 시스템 (Epic, Story 모델)

LangSmith 통합 (추적 및 모니터링)

LangSmith란?

• LangChain이 제공하는 LLM 애플리케이션 추적 및 디버깅 도구
• 워크플로우 실행, LLM 호출, 프롬프트/응답을 시각화
• 성능 모니터링 및 비용 분석

설정 방법:

1. LangSmith 계정 생성

   • https://smith.langchain.com 접속
   • 계정 생성 (무료 티어 사용 가능)
   • API 키 발급

2. 환경 변수 설정

   .env 파일에 다음 추가:

   # LangSmith Configuration
   LANGSMITH_API_KEY=your_langsmith_api_key_here
   LANGSMITH_PROJECT=planning-agent
   LANGSMITH_TRACING=true
   LANGSMITH_ENDPOINT=https://api.smith.langchain.com

3. 의존성 설치

   pip install -r requirements.txt
   # langsmith>=0.1.0 이 자동으로 설치됩니다

4. 추적 확인

   • 에이전트 실행 후 https://smith.langchain.com 에서 확인
   • 프로젝트: planning-agent
   • 워크플로우 전체 실행 추적 가능

추적되는 항목:

• ✅ LangGraph 워크플로우 전체 실행
• ✅ 각 노드 실행 (6개 노드)
• ✅ LLM 호출 (프롬프트, 응답, 토큰 사용량)
• ✅ API 요청 (REST API 엔드포인트)
• ✅ 실행 시간 및 비용 분석

테스트 환경에서 비활성화:

# 테스트 실행 시 추적 비활성화 (기본값)
pytest

# 테스트 중에도 추적 활성화 (디버깅용)
LANGSMITH_TRACING=true pytest

비용:

• LangSmith: 무료 티어 (월 5,000 traces)
• 대부분의 개발 및 Beta 운영에 충분

예상 비용

• 개발 단계: $50-100 (LLM API)
• Beta 운영: $10/월 (100명)
• 1,000명: $130/월

팀 역할

• CTO: LangGraph + API 개발 (10-12일)
• Designer: UI 통합 (7-8일)
• CEO: 테스트 + 검증 (5-7일)

---

🎯 성공 체크리스트

Week 1 완료 후

[ ] CLI로 실행 가능
[ ] LangGraph 워크플로우 작동
[ ] 샘플 Epic 처리 성공
[ ] 로그 파일 생성 확인

Week 2 완료 후

[ ] FastAPI 서버 실행
[ ] Docker 컨테이너 빌드
[ ] ANYON 백엔드 통합
[ ] 칸반보드 UI 표시

---

🆘 도움이 필요하면

1. 개발 가이드의 트러블슈팅 섹션 참고
2. Quick Start의 자주 발생하는 문제 확인
3. 통합 전략의 위험 관리 섹션 검토

---

🎉 다음 단계

문서를 모두 읽었다면:

1. ✅ Quick Start로 5분 안에 프로토타입 실행
2. ✅ 개발 가이드로 2주 개발 계획 수립
3. ✅ 팀 미팅에서 통합 전략 공유
4. ✅ 지금 바로 개발 시작! 🚀

---

Good luck! 🎯