AI 코딩 도구에 상세한 요구사항을 한 번에 쏟아부으면 어떻게 될까요? 예상과 달리, 더 많은 지시사항이 오히려 성능을 떨어뜨립니다. 연구에 따르면 GPT-4와 Claude조차 여러 요구사항을 동시에 처리할 때 초반 몇 개만 따르고 나머지는 무시하는 경향을 보입니다. 이를 “지시의 저주(curse of instructions)”라고 부르죠.

구글 크롬 엔지니어링 담당 Addy Osmani가 Claude Code와 Gemini CLI 사용 경험을 바탕으로 실용적인 스펙 작성 프레임워크를 발표했습니다. GitHub의 2,500개 이상 프로젝트 분석 데이터를 포함해, AI 에이전트가 집중력을 유지하며 생산적으로 작동하도록 만드는 구체적인 방법을 제시합니다.

출처: How to write a good spec for AI agents – AddyOsmani.com

핵심 원칙 5가지

1. 하이레벨 비전으로 시작해서 AI가 디테일을 채우게 하기

처음부터 모든 걸 상세히 작성하지 마세요. 명확한 목표와 핵심 요구사항만 제시하고, AI에게 상세한 플랜을 작성하게 하는 게 효과적입니다. “작은 팀을 위한 할 일 관리 웹앱 만들기”처럼 하이레벨 설명을 주면, AI가 기능 목록, 기술 스택, 데이터 모델 등을 포함한 구조화된 초안 스펙을 생성합니다.

Claude Code의 Plan Mode처럼 계획 단계와 실행 단계를 분리하는 도구들이 이 접근법을 강제합니다. Plan Mode에서는 AI가 코드베이스를 분석하고 상세 플랜을 만들지만 실제 코드는 작성하지 않습니다. 플랜이 완성되고 검증된 후에야 실행 모드로 전환하죠. 이 스펙 문서(예: SPEC.md)는 세션 간에도 유지되는 “진실의 원천”이 됩니다.

2. PRD처럼 구조화하기: 6가지 핵심 영역

GitHub이 2,500개 이상의 에이전트 설정 파일을 분석한 결과, 가장 효과적인 스펙은 6가지 영역을 커버했습니다:

• 명령어: npm test, pytest -v 같은 실행 가능한 전체 명령어
• 테스팅: 테스트 실행 방법, 프레임워크, 커버리지 기대치
• 프로젝트 구조: 소스 코드와 테스트, 문서의 위치
• 코드 스타일: 설명보다 실제 코드 샘플 하나가 효과적
• Git 워크플로우: 브랜치 명명, 커밋 메시지 형식, PR 요구사항
• 경계선: 절대 건드리면 안 되는 것들 (시크릿, 벤더 디렉토리 등)

특히 경계선은 3단계 시스템으로 구성하는 게 좋습니다:

• ✅ 항상 하기: “커밋 전 항상 테스트 실행”
• ⚠️ 먼저 물어보기: “데이터베이스 스키마 변경은 승인 필요”
• 🚫 절대 금지: “시크릿 절대 커밋 금지” (가장 흔한 제약사항)

3. 작업을 모듈화하고 컨텍스트 나누기

한 번에 하나의 집중된 작업만 주세요. 전체 프로젝트를 한 프롬프트에 몰아넣으면 토큰 한계에 부딪히고 AI가 초점을 잃습니다. 긴 스펙이라면 섹션별로 나누거나, 확장된 목차로 요약본을 만들어 필요할 때만 디테일을 제공하세요.

서브에이전트를 활용하는 방법도 있습니다. 데이터베이스 디자이너 에이전트는 데이터 모델 섹션만, API 코더 에이전트는 엔드포인트 스펙만 받는 식이죠. Anthropic의 Claude Code는 각각 독립적인 컨텍스트 윈도우와 시스템 프롬프트를 가진 서브에이전트를 지원합니다. 병렬 에이전트 실행도 가능한데, 한 에이전트가 코드를 작성하는 동안 다른 에이전트가 테스트를 작성하는 방식입니다.

4. 자체 검증과 전문 지식 주입하기

스펙은 단순한 할 일 목록이 아니라 품질 관리 가이드여야 합니다. AI에게 작업 완료 후 스펙과 비교해 모든 요구사항이 충족됐는지 확인하라고 지시하세요. “LLM-as-a-Judge” 패턴을 사용해 두 번째 에이전트가 첫 번째 에이전트의 결과물을 스펙 대비 검토하게 할 수도 있습니다.

도메인 지식도 적극 포함하세요. “X 라이브러리 Y 버전에 메모리 누수 있으니 Z 우회책 적용”처럼 경험 많은 개발자만 아는 함정들을 명시하면 AI가 흔한 실수를 피할 수 있습니다. API 응답 형식 같은 작은 예시 하나가 긴 설명보다 효과적입니다.

5. 테스트-피드백-개선 반복하기

초기 스펙은 시작점일 뿐입니다. 각 마일스톤마다 테스트를 실행하고, 실패하면 즉시 수정하세요. 스펙이 불완전하거나 불명확하다면 업데이트하고 AI와 다시 동기화합니다. 좋은 테스트 스위트는 AI 에이전트에게 “초능력”을 줍니다. 테스트 실패 시 빠르게 검증하고 반복할 수 있죠.

Git처럼 버전 관리를 활용해 스펙 파일도 함께 추적하세요. AI는 놀랍게도 git diff 읽기에 능숙합니다. GitHub Spec Kit 같은 도구는 스펙 기반 개발을 Git 워크플로우에 통합해, 스펙 업데이트 없이는 머지를 막는 게이트 시스템을 제공합니다.

피해야 할 함정들

GitHub 연구에 따르면 대부분의 실패 사례는 “너무 애매한 스펙” 때문입니다. “멋진 거 만들어줘”나 “더 잘 작동하게 해줘”는 AI에게 아무 단서를 주지 못합니다. 구체적인 입력, 출력, 제약사항을 명시하세요.

또한 AI가 생성한 코드를 무조건 신뢰하지 마세요. Simon Willison의 개인 원칙처럼 “다른 사람에게 설명할 수 없는 코드는 커밋하지 않기”를 실천하세요. 테스트를 통과했다고 해서 안전하고 유지보수 가능한 코드는 아닙니다. AI가 만든 코드는 겉보기엔 견고해 보이지만 테스트하지 않은 엣지 케이스에서 무너질 수 있습니다.

프롬프트 엔지니어링이 핵심 스킬이 되는 시대

AI 코딩 도구가 보편화되면서 “AI에게 어떻게 지시하느냐”가 개발자의 핵심 역량으로 떠오르고 있습니다. 명확한 목적으로 시작해서 AI가 플랜을 확장하게 하고, 진지한 설계 문서처럼 구조화하며, 작은 조각으로 나누고, 함정을 예측하며, 지속적으로 반복하는 것. 이 원칙들을 따르면 AI 에이전트가 거대한 컨텍스트에서 무너지거나 헛소리를 하는 상황을 크게 줄일 수 있습니다.