AI 에이전트를 위한 효과적인 스펙 작성 방법 - Addy Osmani

• AI 에이전트 생산성 가장 큰 차이를 만드는 것 → 명확하고 구조화된 SPEC
• 나쁜 SPEC = 모호함 → AI 드리프트, 반복 실패, 컨텍스트 초과
• 좋은 SPEC = 살아있는 문서 (SPEC.md) + 지속 업데이트

좋은 SPEC의 핵심 구성 요소

• 목표 / 비전 (왜 만드는지, 누구를 위한지)
• 기능 목록 + 우선순위
• 기술 스택 (React 18 + TS, Node 20 등 구체적으로)
• 실행 명령어 (npm test, lint, build 등)
• 테스트 기준 (어떤 테스트를 돌려야 성공인지)
• 코드 구조 / 스타일 가이드
• Git 워크플로 (브랜치 규칙, 커밋 메시지)
• 경계 설정 (✅ 항상 / ⚠️ 물어봐 / 🚫 절대 하지 마)

효과적인 시작 프롬프트 패턴

• “Draft a detailed specification for … covering objectives, features, constraints, step-by-step plan”
• Plan Mode 먼저 → AI가 SPEC 초안 작성하게 하기
• 이후 작은 단위 작업으로 쪼개서 지시

실무 팁 (핵심만)

• SPEC.md 별도 파일 유지 → 작업마다 관련 섹션만 넣기
• 모듈화 + 하위 태스크 분리
• 매 작업 후 자동 테스트 + SPEC 준수 여부 확인
• 경계 규칙 3단계 명확히 (Always / Ask / Never)