“RFC 수준의 완벽한 스펙을 써봤는데, 어느 순간 컨텍스트가 너무 커지면서 모델이 망가졌어요.”
많은 개발자가 이 경험을 공유합니다. AI 에이전트에게 방대한 스펙을 통째로 던지면 잘 작동할 것 같지만, 실제로는 그 반대입니다. O’Reilly에 기고한 구글 Chrome 엔지니어링 디렉터 Addy Osmani는 GitHub이 2,500개 이상의 에이전트 설정 파일을 분석한 결과를 토대로, AI 코딩 에이전트 스펙 작성의 핵심 원칙을 정리했습니다. 결론은 명확합니다. “대부분의 에이전트 파일은 너무 모호하기 때문에 실패한다.”
출처: How to Write a Good Spec for AI Agents – O’Reilly Radar
스펙이 실패하는 두 가지 함정
첫 번째 함정은 모호함입니다. “유용한 코딩 어시스턴트처럼 행동해”는 작동하지 않습니다. “React 컴포넌트 테스트를 작성하는 테스트 엔지니어이며, 소스 코드는 절대 수정하지 않는다”처럼 역할과 제약을 명확히 해야 합니다.
두 번째 함정은 과부하입니다. 한 연구에서 ‘Curse of Instructions(지시의 저주)’라고 명명한 현상인데, 지시사항이 많아질수록 모델이 앞 몇 가지만 따르고 나머지를 흘려버리는 경향이 확인됐습니다. 50페이지짜리 문서를 통째로 넣는 것은 품질 개선이 아니라 오히려 역효과입니다.
성공하는 스펙의 6가지 핵심 영역
GitHub 분석에서 효과적인 스펙에는 공통된 구조가 있었습니다. 6가지 영역을 체크리스트로 사용할 수 있습니다.
- Commands: 도구 이름이 아닌 실제 명령어 전체 —
npm test,pytest -v처럼 - Testing: 어떤 프레임워크를 쓰고, 테스트 파일이 어디 있으며, 커버리지 기준은 무엇인지
- Project structure:
src/는 애플리케이션 코드,tests/는 단위 테스트처럼 명시적으로 - Code style: 스타일을 설명하는 세 문단보다 실제 코드 한 줄이 낫습니다
- Git workflow: 브랜치 네이밍, 커밋 메시지 형식, PR 요건
- Boundaries: 에이전트가 절대 건드리면 안 되는 것들 — “시크릿 절대 커밋 금지”가 2,500개 파일 중 가장 많이 등장한 제약이었습니다
3계층 경계 설정이 핵심
단순한 금지 목록보다 훨씬 효과적인 구조가 있습니다. 에이전트에게 “진행 / 확인 후 진행 / 절대 금지” 세 단계로 경계를 알려주는 방식입니다.
- ✅ Always: 묻지 않고 해도 되는 것 — “커밋 전 항상 테스트 실행”
- ⚠️ Ask first: 사람 승인이 필요한 것 — “데이터베이스 스키마 변경 전 확인”
- 🚫 Never: 절대 불가 — “시크릿이나 API 키 절대 커밋 금지”
이 구조는 에이전트가 안전하게 진행할 수 있는 영역과 멈춰야 할 영역을 명확히 구분해 줍니다. 단순한 규칙 목록과는 달리, 에이전트가 상황에 맞는 판단을 할 수 있게 됩니다.
큰 스펙은 잘게 나눠야 합니다
스펙이 클수록 한 번에 다 넣으려 하면 안 됩니다. Osmani가 권장하는 방법은 스펙을 SPEC_backend.md, SPEC_frontend.md처럼 분리하고, 백엔드 작업 시에는 백엔드 스펙만, 프론트엔드 작업 시에는 프론트엔드 스펙만 제공하는 것입니다. 각 작업마다 필요한 컨텍스트만 주는 거죠.
또 하나의 실용적인 방법은 Plan Mode 활용입니다. Claude Code에서는 Shift+Tab으로 활성화할 수 있는 이 모드에서 에이전트가 코드베이스를 분석하고 계획을 수립하지만, 실제 코드는 작성하지 않습니다. 계획이 충분히 정교해진 후에만 실행 모드로 전환하는 방식으로, 코드 생성 전에 스펙이 확실히 검증됩니다.
스펙은 한 번 쓰고 끝나는 문서가 아닙니다. 에이전트가 잘못 이해하거나 요구사항이 바뀔 때마다 업데이트하며, Git으로 버전을 관리하면 에이전트도 히스토리를 참고할 수 있습니다. Osmani는 이를 “팀의 PRD처럼 모두가(사람이든 AI든) 참조하는 단일 진실 공급원”으로 표현합니다.
원문에는 다중 에이전트 병렬 실행 방법, 서브에이전트 구성, LLM-as-a-Judge를 이용한 품질 검증 방법 등 더 심화된 내용도 다룹니다.
답글 남기기