01. 개요 — Agent로 개발한다는 것
이 프로젝트는 “Claude 같은 coding agent로 소프트웨어를 만들 때, 어디까지 사람이 하고 어디까지 agent가 하는가” 를 정리한 학습 자료다. 방법론(SDD, TDD), 도구(SpecKit), 만들어야 할 문서(PRD, 아키텍처 등)를 Claude Code 사용법과 묶어서 하나의 실전 프로세스로 연결한다.
큰 그림: 세 단계의 진화
AI 코딩 방식은 대략 세 단계로 진화해 왔다.
| 단계 | 이름 | 사람의 역할 | 적합한 상황 |
|---|---|---|---|
| 1 | Vibe coding | ”이거 만들어줘”라고 말하고 결과를 본다 | 프로토타입, 일회성 스크립트, 탐색 |
| 2 | Spec-Driven Development (SDD) | 명세(spec)를 먼저 쓰고 agent가 구현 | 유지보수할 프로덕션 코드 |
| 3 | Agentic engineering | 상세한 명세에 대해 여러 agent를 오케스트레이션하고 감독 | 팀/대규모, 반복 가능한 파이프라인 |
“vibe coding”을 만든 Andrej Karpathy조차 1년 뒤 “그 시대는 끝나가고, 사람의 감독 아래 상세한 명세에 대해 agent를 오케스트레이션하는 agentic engineering의 시대로 들어가고 있다”고 말했다. (Towards Data Science)
핵심 통찰: Vibe coding과 SDD는 경쟁 관계가 아니라 보완 관계다. 탐색·프로토타이핑은 vibe coding으로, 굳히고 출시(harden & ship)하는 것은 SDD로 한다. (InfoWorld)
왜 명세가 다시 중요한가
LLM은 텍스트를 코드로 바꾸는 데 능하다. 그래서 병목이 “코드를 타이핑하는 일”에서 “무엇을 만들지 정확히 정의하는 일” 로 옮겨갔다. 명세가 모호하면 agent는 그 모호함을 그럴듯한 코드로 채워버린다 — 빠르지만 틀린 코드를.
SDD의 본질은 한 가지다: 명세(무엇을, 왜)와 구현(실제 코드)을 분리한다. 명세는 저장소에 두고 코드와 함께 갱신한다. 그러면:
- 사람은 어려운 사고(아키텍처 결정, 요구사항, 트레이드오프)에 집중한다.
- agent는 잘 정의된 의도를 실행 가능한 코드로 옮긴다.
- 코드가 틀리면 코드가 아니라 명세를 고치고 다시 생성한다.
”vibe coding 숙취(hangover)“라는 경고
2025년 9월, 여러 시니어 엔지니어가 AI가 만든 vibe-code로 인한 “development hell”을 호소했다. (dplooy 2025 가이드) 빠르게 만든 코드가 유지보수 불가능한 부채가 된 것이다. SDD는 이 문제에 대한 업계의 대답이다: AI가 만든 코드를 실제로 유지보수할 수 있게 만드는 것.
이 자료를 읽는 순서
- 02-methodologies.md — SDD / TDD가 뭔지, 어떻게 결합하는지
- 03-speckit.md — SDD를 자동화하는 GitHub SpecKit 사용법
- 04-human-vs-agent.md — ⭐ 핵심: 사람 vs agent 경계를 정하는 기준
- 05-documents.md — PRD / 아키텍처 / ADR 등 어떤 문서를 언제 만드나
- 06-claude-workflow.md — 위 전부를 Claude Code로 실행하는 실전 절차
- 07-example-project.md — 예제 프로젝트를 agent와 나눠 만드는 명령어·절차
템플릿은 /templates 에, 채워진 예시는 /examples 에 있다.