AI 에이전트를 위한 좋은 스펙 작성법
목차
개요
Google의 소프트웨어 엔지니어 Addy Osmani가 AI 에이전트를 효과적으로 활용하기 위한 스펙 작성법을 공유했다. 핵심 메시지는 명확하다. 명확하고 집중된 스펙이 AI 에이전트의 생산성을 크게 향상시킨다는 것이다.
AI 에이전트와 협업할 때 모호한 지시는 예측 불가능한 결과를 낳는다. 반면 잘 구조화된 스펙은 AI가 전문가처럼 동작하도록 이끈다.
5가지 핵심 원칙
원칙 1: 고수준 비전으로 시작, 세부사항은 AI가 작성
구체적인 목표 설명서로 시작해 AI가 상세 스펙을 작성하도록 한다. Plan Mode를 활용하여 코드 작성 전 읽기 전용 모드로 계획을 수립한다. 스펙은 지속적 참고 자료로 보존하며, SPEC.md 파일로 관리하는 것이 좋다. 목표 중심으로 작성하되 “무엇”과 “왜”에 집중해야 한다.
원칙 2: 전문적 PRD처럼 구조화된 스펙
스펙은 PRD(Product Requirements Document)처럼 체계적으로 구조화해야 한다. 6가지 핵심 영역을 반드시 포함해야 효과적인 스펙이 된다.
원칙 3: 모듈식 프롬프트로 분할 정복
거대한 단일 프롬프트 대신 집중된 작은 작업 단위로 분해한다. “지시사항의 저주”라는 현상이 있다. 요구사항이 많을수록 AI가 모든 요구사항을 따를 확률이 감소한다. 스펙 요약본(TOC)을 작성해 상위 수준 개요를 유지하고, 필요할 때만 관련 섹션만 제공한다.
다중 에이전트를 활용할 때는 백엔드/프론트엔드 전문 에이전트를 분리하는 것이 효과적이다. 각 에이전트에게 해당 스펙 섹션만 제공하면 병렬 처리로 처리량을 증대시킬 수 있다.
원칙 4: 자체 검증, 제약, 전문 지식 포함
AI가 작업을 검증할 수 있도록 가이드를 제공한다. “작업 후 스펙과 비교해 요구사항 충족을 확인하라”는 지시를 포함한다. 적합성 테스트(Conformance Testing)로 YAML 기반 테스트 스위트를 계약서처럼 활용할 수 있다. 도메인 지식도 투입해야 한다. 라이브러리 함정, 아키텍처 패턴, 주의사항을 기재한다. 단, 간단한 작업에는 과도한 스펙을 피해야 한다.
원칙 5: 테스트, 반복, 진화, 도구 활용
마일스톤마다 지속적으로 테스트한다. 스펙이 실패하면 즉시 업데이트한다. RAG(Retrieval-Augmented Generation)와 같은 컨텍스트 관리 도구를 활용하여 필요한 부분만 검색한다. Git에 스펙 파일을 저장해 이력을 추적하는 버전 관리도 중요하다. 병렬 에이전트는 관리 복잡도를 고려해 최대 2-3개로 유지한다.
스펙의 6가지 핵심 영역
효과적인 스펙에는 다음 6가지 영역이 반드시 포함되어야 한다.
| 영역 | 설명 | 예시 |
|---|---|---|
| Commands | 실행 명령어 | npm test, npm run build |
| Testing | 테스트 프레임워크와 실행 방법 | Jest, 커버리지 기대치 |
| Project Structure | 소스 코드, 테스트, 문서 위치 | src/, tests/, docs/ |
| Code Style | 실제 코드 샘플로 스타일 제시 | 명명 규칙, 포맷팅 |
| Git Workflow | 브랜치 명명, 커밋 메시지 형식 | feature/, fix/ 접두사 |
| Boundaries | 건드리면 안 되는 영역 | 레거시 코드, 설정 파일 |
3계층 경계 설정
스펙에서 경계 설정은 3가지 계층으로 구분한다.
Always (항상 해야 할 것)
- 테스트 실행
- 명명 규칙 준수
- 코드 리뷰 전 린트 실행
Ask First (승인 필요)
- DB 스키마 변경
- API 인터페이스 수정
- 의존성 추가
Never (절대 금지)
- 시크릿 커밋
- CI 설정 수정
- 프로덕션 데이터 접근
피해야 할 함정
AI 에이전트와 협업할 때 흔히 저지르는 실수들이 있다.
모호한 프롬프트
“뭔가 멋진 걸 만들어”와 같은 지시는 방향을 제시하지 못한다. 명확한 목표와 제약 조건을 제시해야 한다.
과도한 컨텍스트
50페이지 문서를 한 번에 제공하고 결과를 기대하는 것은 비현실적이다. 필요한 정보만 선별해서 제공해야 한다.
검토 생략
테스트 통과가 올바른 코드를 의미하지는 않는다. AI가 생성한 코드도 반드시 리뷰해야 한다.
프로토타입과 프로덕션 혼동
“Vibe Coding”은 빠르지만 정밀도가 낮다. 프로덕션 코드에는 더 엄격한 스펙이 필요하다.
6가지 영역 누락
Commands, Testing, Structure, Style, Git, Boundaries 중 하나라도 빠지면 AI가 잘못된 가정을 할 수 있다.
스펙 기반 개발 워크플로우
효과적인 AI 협업을 위한 4단계 워크플로우가 있다.
1단계: 스펙화(Specify)
사용자 관점에서 고수준 설명을 작성한다. AI가 이를 바탕으로 상세 스펙을 작성하도록 한다.
2단계: 계획(Plan)
기술 스택, 아키텍처, 제약사항을 정의한다. Plan Mode를 활용해 코드 작성 전에 계획을 수립한다.
3단계: 작업 분해(Tasks)
작은 단위의 검토 가능한 작업으로 분할한다. 각 작업은 독립적으로 검증 가능해야 한다.
4단계: 구현(Implement)
AI가 작업을 순차적으로 진행한다. 각 단계마다 검증을 수행한다.
실제 스펙 구조 예시
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 프로젝트 스펙: 팀 작업 관리 앱
## 목표
- 소팀이 작업을 추적할 수 있는 웹앱 제공
## 기술 스택
- React 18+, TypeScript, Vite, Tailwind CSS
- Node.js/Express, PostgreSQL, Prisma ORM
## Commands
- Build: `npm run build` (TypeScript 컴파일)
- Test: `npm test` (Jest 실행, 커밋 전 필수)
## Boundaries
- Always: 테스트 실행, 명명 규칙 준수
- Ask First: DB 스키마 변경
- Never: 시크릿 커밋, CI 설정 수정
핵심 통찰
너무 거대한 스펙은 AI를 방해한다
모듈식 접근으로 해결해야 한다. 필요한 정보만 선별적으로 제공하면 AI의 집중력이 높아진다.
스펙은 일회용 문서가 아니다
지속적으로 진화하는 살아있는 아티팩트로 관리해야 한다. 프로젝트가 발전함에 따라 스펙도 함께 업데이트한다.
당신이 경험 전문가다
도메인 지식을 스펙에 녹여내야 AI도 전문가처럼 동작한다. AI는 도구일 뿐이며, 방향을 제시하는 것은 개발자의 몫이다.
효과적인 AI 에이전트 스펙은 소프트웨어 엔지니어링 원칙(명확성, 구조, 제약)에 LLM 특성(컨텍스트 한계, 주의 능력)을 고려한 하이브리드 접근법이다. 명확하고 집중된, 반복적으로 개선되는 스펙이 AI 에이전트의 생산성을 극대화한다.