프로젝트 계획서 작성 가이드

개요

캡스톤 프로젝트 계획서는 8주차(2026-04-21) 중간고사 대체 발표의 핵심 산출물이다. 이 가이드는 계획서의 일관성과 구체성을 확보하기 위한 작성 지침과 템플릿을 제공한다.

제출 위치: capstone/projects/[학번]/proposal.md (GitHub PR) 제출 마감: 2026-04-20 23:59 (8주차 강의 전날) 분량: 4–6페이지 (약 2,000–3,000 단어) 발표 시간: 15분 발표 + 5분 Q&A

평가 기준 (중간 프로젝트 20%)

항목	배점	설명
문제 정의의 명확성	4점	왜 이 문제인가, 왜 에이전틱 접근이 필요한가
시스템 설계의 구체성	6점	에이전트 구성, 아티팩트, 파이프라인 구조
수업 기법 적용	4점	1–7주차 학습 내용과의 명시적 연결
실현 가능성	3점	13–16주차 일정 내 완성 가능성
발표 품질	3점	명확한 전달, Q&A 대응

작성 원칙

구체적 > 일반적: “LLM을 사용하여 코드를 개선한다” ❌ → “GPT-5.1 Sonnet으로 pytest 실패 로그를 분석하여 fix 패치를 생성한다” ✓
숫자로 성공 기준: “잘 작동한다” ❌ → “테스트 커버리지 80% 이상, 평균 루프 횟수 5회 이하” ✓
수업 기법 명시적 매핑: 사용할 기법과 해당 주차를 명시 (예: “Week 5 Context Rot 방지”, “Week 6 CLAUDE.md 튜닝”)
위험을 솔직하게: 실패 가능성이 있는 부분을 숨기지 말고 완화 전략과 함께 기술
다이어그램 1개 이상: 에이전트 파이프라인 또는 데이터 흐름을 시각화

계획서 템플릿

아래 템플릿을 복사하여 capstone/projects/[학번]/proposal.md로 저장하고 작성한다.

---
title: "[프로젝트 제목]"
student_id: "2023xxxx"
student_name: "홍길동"
submitted: "2026-04-20"
---

# [프로젝트 제목]

**한 줄 요약**: (에이전트 시스템이 해결하는 문제를 한 문장으로)

**학번 / 이름**: 2023xxxx / 홍길동
**GitHub 저장소**: https://github.com/...

---

## 1. 문제 정의

### 1.1 현재 상황
(어떤 작업이 현재 얼마나 비효율적인지, 수작업/반복작업 현황 기술)

### 1.2 왜 에이전틱 접근인가
(단순 스크립트나 단일 LLM 호출이 아닌 에이전트 시스템이 필요한 이유.
Week 1 HITL/HOTL 관점, Week 4 루프 패러다임 관점에서 논증)

### 1.3 목표 사용자 / 사용 맥락
(누가, 언제, 어떻게 이 시스템을 사용하는가)

---

## 2. 제안 시스템 설계

### 2.1 에이전트 구성

| 에이전트 | 역할 | 입력 아티팩트 | 출력 아티팩트 | 사용 모델 |
|----------|------|--------------|--------------|----------|
| Planner  | 요구사항 파싱 | user prompt | spec.md | Opus |
| Coder    | 구현 | spec.md, code | diff, PR | Sonnet |
| QA       | 검증 | PR, tests | review.md | Sonnet |

### 2.2 파이프라인 아키텍처

(다이어그램 또는 ASCII art로 파이프라인 시각화)

User Input → Planner → Coder (Ralph Loop) → QA Gate → Human Approval → Deploy

### 2.3 MCP 도구 / 외부 연동

- GitHub MCP — PR 생성/리뷰
- Filesystem MCP — 로컬 파일 수정
- (추가)

### 2.4 상태 추적 / 핸드오프

(에이전트 간 어떤 파일/JSON 구조로 핸드오프하는가 — Week 5/7 참조)

---

## 3. 기술 스택

| 범주 | 선택 | 근거 |
|------|------|------|
| LLM | Claude Opus 4.6 (Planner), Sonnet 4.6 (Coder) | 비용/품질 균형 (Week 5 참조) |
| 프레임워크 | Claude Code + Custom Agents | .claude/agents/ 디렉토리 활용 |
| 언어 | Python 3.12 | 팀 표준 |
| 테스트 | pytest | CI 통합 용이 |
| 배포 | GitHub Actions | 무료 + 간단 |

---

## 4. 수업 기법 적용 매핑

각 주차에서 배운 기법 중 **실제로 적용할** 항목을 명시한다. "들어봤다"가 아닌 "이 프로젝트에서 이렇게 쓴다"로 작성.

| 주차 | 기법 | 적용 방식 |
|------|------|----------|
| Week 1 | HOTL 거버넌스 | 배포 단계에서 사람 승인 게이트 |
| Week 3 | MCP 서버 | GitHub API 호출을 MCP로 캡슐화 |
| Week 4 | Ralph Loop | Coder 에이전트의 테스트-실패-재시도 |
| Week 5 | Context Rot 방지 | fix_plan.md + claude-progress.txt 상태 파일 |
| Week 6 | CLAUDE.md 튜닝 | 프로젝트별 제약 작성 (예: "secret을 코드에 넣지 말라") |
| Week 7 | 게이트드 파이프라인 | QA 실패 시 3회 재시도 후 사람 에스컬레이션 |

---

## 5. 개발 일정

| 주차 | 마일스톤 | 산출물 |
|------|---------|--------|
| Week 13 | Planner + Coder 스켈레톤 | design.md, 초기 코드 |
| Week 14 | Ralph Loop 통합, QA 에이전트 | 파이프라인 동작 데모 |
| Week 15 | 시스템 통합, E2E 테스트 | report.md, links.md (슬라이드 URL) |
| Week 16 | 최종 발표, 데모 | links.md (데모 영상 URL), 최종 제출 |

---

## 6. 성공 기준

| 지표 | 목표 | 측정 방법 |
|------|------|----------|
| 기능 정확도 | 80% 이상 | 테스트 케이스 통과율 |
| 평균 루프 횟수 | 5회 이하 | 로그 분석 |
| 토큰 비용 / 태스크 | $0.50 이하 | API 청구 로그 |
| E2E 응답 시간 | 2분 이하 | 벤치마크 |

---

## 7. 위험 요소와 대응

| 위험 | 영향도 | 대응 전략 |
|------|-------|----------|
| LLM 환각으로 존재하지 않는 API 호출 | 높음 | QA 게이트에서 테스트 강제 (Week 7) |
| 토큰 비용 폭발 | 중간 | 모델 티어 라우팅 (Haiku 탐색, Sonnet 구현) |
| 외부 API 장애 | 낮음 | Mock 백업 경로 준비 |

---

## 8. 참고자료

- (수업 주차 링크, 논문, 블로그 등)

작성 팁

자주 하는 실수 (피하라)

X “AI로 코드를 자동 생성하는 시스템” — 너무 추상적
O “pytest 실패 로그를 입력받아 수정 커밋을 생성하는 에이전트” — 구체적 입출력
X “Claude를 사용한다”
O “Planner는 Opus 4.6 (--effort high), Coder는 Sonnet 4.6 (--effort medium)”
X “좋은 결과를 낼 것이다”
O “테스트 커버리지 80% 이상, 평균 수정 1.5회 내 수렴”

Agentic 시스템이어야 한다

다음 특징이 최소 3개 이상 있어야 캡스톤 프로젝트로 인정:

에이전트가 루프 안에서 반복한다 (Ralph Loop)
다단계 파이프라인이 있다 (Planner → Coder → QA 등)
도구 사용이 있다 (파일 시스템, 셸, 외부 API)
자율 의사결정이 있다 (사람이 매 스텝 개입하지 않음)
상태 추적 파일로 컨텍스트를 관리한다
검증 게이트가 있다 (테스트, QA, 사람 승인)

발표 구성 (15분)

시간	섹션
2분	문제 정의 (§1)
5분	시스템 설계 (§2) — 다이어그램 중심
3분	수업 기법 매핑 (§4) — 왜 이 주차들이 필요한가
2분	일정과 성공 기준 (§5–6)
3분	위험과 대응 (§7)

FAQ

Q. 주제를 아직 정하지 못했다. A. Week 13 프로젝트 아이디어를 참고하라. 5가지 예시 주제가 있다.

Q. 기존 오픈소스 도구(예: sdlc-toolkit)를 확장해도 되나? A. 가능. 단, 무엇을 추가/변경했는지 명확히 기술해야 한다. 단순 재사용은 불인정.

Q. 모델을 로컬(Ollama)로 돌려도 되나? A. 가능. Week 10–11의 오픈소스 모델 배포 내용과 연결된다.

Q. GitHub 저장소는 private인가 public인가? A. Public 권장 (동료 평가 용이). Private이면 교수와 조교를 collaborator로 초대해야 한다.