AI 에이전트를 위한 스마트 스펙 작성법

ai development prompt-engineering

2026년 01월 20일

AI 코딩 에이전트에게 방대한 스펙을 한꺼번에 던지면 제대로 작동하지 않습니다. 핵심은 스마트 스펙 작성에 있습니다. GitHub의 2,500개 이상 에이전트 설정 파일 분석 결과와 실전 경험을 바탕으로 효과적인 스펙 작성 방법을 정리했습니다.

TL;DR

적절한 수준의 세부 정보(구조, 스타일, 테스트, 경계 등)를 포함하는 명확한 명세를 작성할 것
큰 작업은 한 덩어리 프롬프트 대신 작은 단위로 분해하는 방식 권장
계획은 읽기 전용 모드로 먼저 수립한 후 실행하고 지속적으로 개선

핵심 원칙: 스마트 스펙 작성

단순히 방대한 스펙을 AI 에이전트에 던지는 방식은 실패하며, 컨텍스트 윈도우 제한과 모델의 주의 예산(attention budget)에 부딪힙니다.

“스마트 스펙”이란 에이전트를 명확히 안내하고, 실용적인 컨텍스트 크기 내에 유지하며, 프로젝트와 함께 진화하는 문서입니다.

원칙 1: 큰그림을 먼저 주고, 세부는 AI가 초안 작성

과도하게 처음부터 다 설계하려 하기보다, 먼저 목표 진술과 몇 가지 핵심 요구사항만 또렷하게 잡고 시작합니다. 이 초기 스펙을 “제품 브리프”처럼 두고, 에이전트가 이를 바탕으로 상세 스펙을 확장 작성하도록 맡기는 방식입니다.

LLM 기반 에이전트는 고수준 지시가 분명할 때 세부를 잘 채우지만, 미션이 흐리면 쉽게 딴길로 새는 특성을 보입니다. 그래서 핵심은, 에이전트가 방황하지 않도록 처음에 명확한 미션을 박아두는 것입니다.

Plan Mode 활용

Claude Code의 Plan Mode는 에이전트를 읽기 전용으로 묶어두고, 코드베이스 분석과 상세 계획 수립만 하게 만드는 모드입니다.

Shift+Tab으로 Plan Mode에 들어간 뒤 “무엇을 만들고 싶은지”를 설명하면, 에이전트가 기존 코드를 훑으면서 스펙 초안을 작성
이때 계획에 대해 아키텍처, 모범 사례, 보안 위험, 테스트 전략까지 함께 점검하도록 요구
계획이 오해의 여지 없이 충분히 정제될 때까지는 Plan Mode를 유지하고, 그다음에야 실행 단계 진입

스펙을 컨텍스트로 활용

확정된 스펙은 SPEC.md 같은 파일로 저장하고, 작업할 때 필요한 섹션만 골라 에이전트에 다시 제공합니다.

스펙 파일이 세션 사이에 남아 있기 때문에, 프로젝트를 다시 시작할 때도 AI를 같은 기준점에 고정시키는 역할
대화 히스토리가 길어지거나 에이전트를 재시작할 때 생기는 망각을 줄이는 데 도움이 됨
팀에서 PRD(제품 요구사항 문서)를 공유 기준으로 쓰듯, 인간이든 AI든 모두가 참조하는 “단일 기준 문서” 역할

목표 지향적 유지

고수준 스펙은 처음부터 구현 방법을 다 적기보다 what/why에 집중하고, 구체적인 how는 뒤로 미루는 구성이 적합합니다.

사용자 스토리와 수락 기준처럼 구성: “사용자는 누구인가? / 무엇이 필요한가? / 성공의 모습은?”
GitHub Spec Kit에서도 “무엇을 왜 만드는지에 대한 고수준 설명을 주고, 코딩 에이전트가 사용자 경험과 성공 기준 중심으로 상세 사양을 만들도록 한다”는 흐름을 강조

원칙 2: 스펙을 전문적인 PRD(또는 SRS)처럼 구조화

AI 스펙을 단순한 메모 모음이 아니라, 명확한 섹션을 갖춘 구조화된 문서로 다루는 것이 중요합니다. PRD나 시스템 설계 문서처럼 포괄적이고 정돈된 형태가, 내용을 문자 그대로 해석하는 AI에게 특히 잘 맞습니다.

6가지 핵심 영역

GitHub에서 2,500개 이상의 에이전트 설정 파일을 분석한 결과, 효과적인 스펙에는 공통적으로 6가지 핵심 영역이 포함됩니다.

Commands: 실행 가능한 명령어를 문서 앞부분에 배치. 도구 이름만 적는 것이 아니라, 플래그까지 포함된 전체 명령어 명시 (npm test, pytest -v, npm run build)
Testing: 테스트 실행 방법, 사용하는 프레임워크, 테스트 파일 위치, 기대하는 커버리지 수준을 구체적으로 명시
Project Structure: 소스 코드, 테스트, 문서의 위치를 명확히 구분. 예: “src/는 애플리케이션 코드, tests/는 단위 테스트, docs/는 문서용”
Code Style: 스타일을 장황하게 설명하는 것보다 실제 코드 스니펫 하나가 훨씬 효과적. 네이밍 규칙, 포매팅 기준, 바람직한 출력 예시를 함께 제시
Git Workflow: 브랜치 네이밍 규칙, 커밋 메시지 형식, PR 요구사항을 명시하면 에이전트도 그 흐름을 따름
Boundaries: 에이전트가 절대 건드리면 안 되는 영역을 분명히 지정. 시크릿, vendor 디렉토리, 프로덕션 설정, 특정 폴더 등. GitHub 연구에서 “절대 시크릿을 커밋하지 말 것”이 가장 자주 등장한 유용한 제약으로 확인됨

스택에 대해 구체적으로 명시

“React 프로젝트”처럼 뭉뚱그리지 말고, “React 18 + TypeScript + Vite + Tailwind CSS”처럼 구체적으로 적는 것이 중요합니다. 버전과 주요 의존성을 함께 적어야 하며, 모호한 스펙은 결국 모호한 코드를 낳습니다.

일관된 형식 사용

명확성이 가장 중요하며, 많은 개발자가 Markdown 헤딩이나 XML과 유사한 태그로 섹션을 구분합니다. AI 모델은 자유로운 산문보다 잘 구조화된 텍스트를 훨씬 안정적으로 처리합니다.

Anthropic 엔지니어들 역시 <background>, <instructions>, <tools>, <output_format>처럼 명확히 구분된 섹션 구성을 권장합니다.

스펙을 툴체인에 통합

스펙을 단순 문서가 아니라, 버전 관리와 CI/CD에 연결된 “실행 가능한 아티팩트”로 취급합니다.

GitHub Spec Kit는 스펙을 엔지니어링 프로세스의 중심에 두는 4단계 게이트 워크플로우를 사용합니다:

Specify: 무엇을 왜 만드는지에 대한 고수준 설명을 제공하고, 코딩 에이전트가 상세 사양을 생성
Plan: 원하는 스택, 아키텍처, 제약조건을 포함한 기술적 계획을 수립
Tasks: 스펙과 계획을 실제 작업 단위로 쪼개고, 각각을 테스트 가능한 크기로 분해
Implement: 코딩 에이전트가 태스크를 하나씩, 또는 병렬로 처리

살아있는 문서로 유지

스펙은 한 번 작성하고 끝내는 문서가 아니라, AI와 함께 결정을 내리거나 새로운 사실이 드러날 때마다 계속 업데이트합니다.

스펙 기반 워크플로우에서는 스펙이 구현, 테스트, 태스크 분해를 주도하며, 스펙이 검증되기 전에는 다음 단계로 넘어가지 않습니다.

원칙 3: 태스크를 모듈화된 프롬프트와 컨텍스트로 분할

하나의 거대한 프롬프트에 모든 것을 담기보다, 한 번에 하나의 태스크에만 집중하도록 컨텍스트를 제공합니다. 전체 프로젝트의 요구사항·코드·지시를 단일 프롬프트에 담으면, 오히려 혼란을 키우기 쉬움.

토큰 한계에 걸릴 위험뿐 아니라, “지시의 저주(curse of instructions)“로 모델의 집중력이 급격히 떨어질 수 있습니다.

지시의 저주

연구 결과에 따르면, 프롬프트에 지시나 데이터를 많이 쌓을수록 각 지시를 정확히 따르는 성능이 눈에 띄게 하락합니다.

GPT-4나 Claude 같은 강력한 모델도, 많은 요구사항을 동시에 만족시키라는 요청에는 어려움을 겪습니다. 예를 들어 10개의 상세 규칙을 불릿으로 주면, 처음 몇 개만 지키고 뒤쪽 규칙은 점점 무시하는 경향이 나타납니다.

더 나은 전략은 반복적 집중: 한 번에 하나의 하위 문제에만 집중시키고, 끝난 뒤 다음 문제로 넘어가는 방식입니다.

스펙을 단계나 컴포넌트로 분할

스펙 문서가 길거나 다루는 범위가 넓다면, 여러 부분으로 나누는 것을 고려합니다.

예: “Backend API Spec”과 “Frontend UI Spec”을 별도 섹션으로 분리
백엔드 작업을 할 때는 프론트엔드 스펙을 항상 함께 줄 필요는 없음
멀티 에이전트 환경에서는 각 영역별로 별도의 에이전트나 하위 프로세스를 둘 수도 있음

대규모 스펙을 위한 확장 TOC/요약

에이전트에게 전체 스펙을 요약한 확장 목차(TOC)를 먼저 작성하게 하는 방식입니다.

각 섹션을 몇 가지 핵심 포인트나 키워드로 압축하고, 세부 내용이 있는 위치를 함께 참조
예: “Security: HTTPS 사용, API 키 보호, 입력 검증 구현 (전체 스펙 §4.2 참조)”
이렇게 계층적 요약을 만들어 두면, 프롬프트에는 큰 그림만 유지하고 세부는 필요할 때만 제공 가능

서브에이전트 또는 “스킬” 활용

Anthropic이 말하는 서브에이전트(또는 “스킬”)처럼, 역할이 분리된 다중 에이전트활용 가능합니다.

각 서브에이전트는 특정 전문 영역에 맞게 설정되고, 그 영역에 해당하는 스펙 일부만 제공받음
예: Database Designer 서브에이전트는 데이터 모델 섹션만, API Coder 서브에이전트는 API 엔드포인트 스펙만 인지
이렇게 하면 각 에이전트가 더 작은 컨텍스트와 더 또렷한 역할을 가져 정확도 향상과 병렬 작업이 가능

단일 vs 멀티 에이전트: 언제 사용할 것인가

측면	단일 에이전트	병렬/멀티 에이전트
장점	설정이 단순하고 오버헤드가 낮으며, 디버그와 흐름 추적이 쉬움	처리량이 높고, 복잡한 상호의존성 대응과 도메인별 전문화 가능
단점	대형 프로젝트에서 컨텍스트 과부하, 반복 속도 저하, 단일 장애점	조율 비용 증가, 충돌 가능성, 공유 메모리 필요
적합한 경우	격리된 모듈, 중·소형 프로젝트, 초기 프로토타이핑	대규모 코드베이스, 코딩·테스트·리뷰 분리, 독립적인 기능 개발
팁	스펙 요약 활용, 태스크별 컨텍스트 갱신, 세션 자주 리셋	초반에는 2~3개 에이전트로 제한, MCP로 도구 공유, 경계 명확화

각 프롬프트를 하나의 태스크/섹션에 집중

복잡한 멀티 에이전트 환경이 없어도, 수동으로 충분히 모듈성을 강제할 수 있습니다.

예: 스펙 작성 후 “Step 1: 데이터베이스 스키마 구현” 단계에서는 스펙의 Database 섹션만 제공
주요 태스크가 바뀔 때마다 컨텍스트를 새로 구성해, 오래되거나 관련 없는 정보로 인한 산만함을 줄임
일부 가이드에서는 주요 기능 전환 시 새 세션을 시작해 컨텍스트를 정리하라고 권장

원칙 4: 자가 검사, 제약조건, 인간 전문성 내장

스펙을 단순히 에이전트의 할 일 목록이 아니라, 품질을 관리하는 가이드로 다루고 자신의 전문성을 적극적으로 반영할 것.

좋은 스펙은 AI가 어디에서 실수할 수 있는지를 미리 짚고, 그 지점에 가드레일을 세워 둡니다. 도메인 지식, 엣지 케이스, 각종 “주의사항”을 담아 AI가 맥락 없는 진공 상태에서 작동하지 않게 합니다.

3단계 경계 시스템

GitHub의 2,500개 이상 에이전트 파일 분석 결과, 가장 효과적인 스펙은 단순한 금지 목록이 아니라 3단계 경계 시스템을 사용합니다.

에이전트가 언제 그대로 진행해도 되는지, 언제 멈춰서 물어야 하는지, 언제 완전히 중단해야 하는지를 명확히 알려줍니다.

✅ Always do (항상 수행): 묻지 않고 수행해야 하는 작업들
- 예: “커밋 전 항상 테스트 실행”, “스타일 가이드의 네이밍 컨벤션 항상 준수”, “오류는 항상 모니터링 서비스에 로깅”
⚠️ Ask first (먼저 물을 것): 인간의 승인이 필요한 작업들
- 예: “데이터베이스 스키마 수정 전 물을 것”, “새 의존성 추가 전 물을 것”, “CI/CD 설정 변경 전 물을 것”
- 기술적으로 가능할 수는 있지만, 영향 범위가 커서 사람의 판단이 필요한 변경을 여기서 걸러냄
🚫 Never do (절대 금지): 명확한 하드 스톱 영역
- 예: “시크릿이나 API 키 절대 커밋 금지”, “node_modules/나 vendor/ 절대 편집 금지”, “명시적 승인 없이 실패하는 테스트 제거 금지”
- 연구에서도 “절대 시크릿을 커밋하지 말 것”이 가장 자주 등장한 유용한 제약으로 확인됨

자가 검증 장려

에이전트가 스펙에 비춰 스스로 결과를 점검하도록 유도합니다.

도구가 허용된다면, 코드 생성 후 단위 테스트나 린팅을 직접 실행하도록 워크플로우에 포함
프롬프트 수준에서도 재확인 지시 가능
- 예: “구현 후 결과를 스펙과 비교해 모든 요구사항을 충족하는지 확인하고, 미충족 항목이 있으면 나열하라”
LLM이 자신의 출력을 스펙과 대조하도록 만들어 누락을 줄이는 효과

적합성 테스트

Willison은 적합성 스위트(conformance suite)구축을 권장합니다.

언어에 의존하지 않는 테스트(종종 YAML 기반)로, 모든 구현이 반드시 통과해야 하는 계약 역할
API를 만드는 경우, 적합성 스위트가 예상 입력과 출력을 정의하고 에이전트가 만든 코드는 이를 모두 만족해야 함
스펙의 Success 섹션에 “conformance/api-tests.yaml의 모든 케이스 통과 필수”처럼 기준을 명시

도메인 지식 반영

스펙에는 경험 있는 개발자나 맥락을 아는 사람만 알고 있는 현실적인 인사이트를 담아야 합니다.

예: 이커머스 에이전트를 만들 때 “products”와 “categories”가 다대다 관계라는 점을 명확히 적어 둠
- AI가 알아서 추론할 것이라 기대하지 않음
특정 라이브러리가 까다롭다면, 자주 빠지는 함정이나 주의점도 함께 명시
자신의 멘토십을 스펙에 녹여내는 방식
- 예: “라이브러리 X 사용 시 버전 Y에서 메모리 누수 문제가 있으니 우회책 Z 적용”

간단한 태스크에는 미니멀리즘

철저한 스펙이 중요하지만, 전문성의 일부는 언제 단순하게 가야 하는지아는 데 있습니다.

비교적 단순하고 격리된 작업에는 과도한 스펙이 오히려 혼란을 키울 수 있음
예: “페이지에서 div를 중앙 정렬” 같은 작업에는 “솔루션을 간결하게 유지하고, 불필요한 마크업이나 스타일을 추가하지 말 것” 정도면 충분
반대로 “토큰 갱신과 오류 처리가 포함된 OAuth 흐름 구현”처럼 복잡한 작업에는 상세 스펙이 필요

원칙 5: 테스트, 반복, 스펙 진화 (올바른 도구 활용)

스펙 작성과 에이전트 구축을 한 번으로 끝나는 작업이 아니라 반복 루프로 인식합니다. 빠르게 테스트하고, 피드백을 모으고, 스펙을 다듬고, 도구로 검사를 자동화하는 흐름입니다.

지속적 테스트

모든 구현이 끝날 때까지 기다리지 말고, 주요 마일스톤이나 함수 단위로 테스트 또는 간단한 수동 검사 수행합니다.

실패가 발견되면 그대로 진행하지 말고, 먼저 스펙이나 프롬프트를 수정
자동화 테스트가 특히 효과적이며, 테스트가 있다면 에이전트가 npm test같은 명령을 직접 실행하게 할 수 있음
테스트 실패 결과를 그대로 다음 프롬프트의 입력으로 사용
- 예: “출력이 X, Y, Z에서 스펙을 충족하지 못했으니 수정하라”
코드 → 테스트 → 수정 → 반복으로 이어지는 에이전틱 루프는 매우 강력한 방식

스펙 자체 반복

에이전트가 오해했거나 요구사항 누락이 드러났다면, 문제를 덮지 말고 스펙 문서를 먼저 수정합니다.

수정된 스펙을 에이전트와 명시적으로 다시 동기화
- 예: “스펙을 다음과 같이 업데이트했다. 이 변경을 반영해 계획을 조정하거나 코드를 리팩터링하라”
스펙을 항상 단일 진실의 원천으로 유지
가능하다면 커밋 메시지나 노트로 버전 히스토리를 남겨, 무엇이 왜 바뀌었는지 추적

컨텍스트 관리 및 메모리 도구 활용

AI 에이전트의 컨텍스트와 지식 관리를 돕는 도구 생태계가 빠르게 성장 중입니다.

RAG(검색 증강 생성)패턴을 활용하면, 에이전트가 벡터 데이터베이스 같은 지식 베이스에서 필요한 정보만 즉시 가져올 수 있음
스펙이 매우 클 경우, 섹션을 임베딩해 두고 에이전트가 전체를 받는 대신 가장 관련 있는 부분만 검색하게 구성
MCP(Model Context Protocol)기반 프레임워크는 현재 태스크에 맞는 컨텍스트를 자동으로 제공

버전 관리와 스펙 잠금

Git 같은 버전 관리 도구로 에이전트의 작업을 꼼꼼히 추적합니다.

AI를 활용할수록 좋은 버전 관리 습관의 중요성은 더 커짐
스펙 파일 자체를 리포지토리에 커밋해 변경 이력을 남김
에이전트도 git diff나 blame을 읽고 변경 맥락을 이해할 수 있음
- 실제로 LLM은 diff 해석에 상당히 능숙
스펙을 리포에 두면 개발자와 AI 모두 프로젝트의 진화를 함께 추적 가능

비용과 속도 고려

대형 모델과 긴 컨텍스트를 쓰는 작업은 느리고 비용이 많이 들 수 있음.

모델 선택을 전략적으로 분리
- 초기 초안이나 반복 작업에는 빠르고 저렴한 모델
- 최종 출력이나 복잡한 추론에는 가장 유능한(비싼) 모델
예: GPT-4나 Claude는 계획 수립과 핵심 단계에, 단순 확장이나 리팩터링은 로컬 모델이나 소형 API 모델에 맡김
컨텍스트 크기도 관리 대상
- 5k 토큰이면 충분한 작업에 20k 토큰을 넣을 필요는 없음
- 토큰 수가 많아질수록 효율성이 떨어질 수 있음

흔히 저지르는 실수를 피하기

GitHub의 2,500개 이상 에이전트 파일을 분석한 결과, 실패의 가장 큰 원인은 스펙과 지시가 지나치게 모호함입니다.

모호한 프롬프트

“멋진 것 만들어줘”, “더 잘 작동하게 해줘” 같은 요청은 에이전트에게 판단 기준 자체가 없음.

입력, 출력, 제약조건을 가능한 한 구체적으로 명시해야 함
“당신은 도움이 되는 코딩 어시스턴트입니다” 같은 일반적인 역할 지정은 거의 효과 없음
반대로 “당신은 React 컴포넌트 테스트를 작성하는 테스트 엔지니어이며, 이 예시를 따르고 소스 코드는 절대 수정하지 않는다”처럼 역할·범위·제약을 함께 지정하면 훨씬 잘 작동

요약 없는 과도한 컨텍스트

50페이지 문서를 그대로 프롬프트에 덤프하고 모델이 알아서 이해하길 기대하는 방식은 대부분 실패합니다.

계층적 요약이나 RAG를 활용해 지금 태스크와 직접 관련된 내용만 드러내는 것이 필요
컨텍스트 길이를 늘리는 것은 컨텍스트의 품질 부족을 대신해 주지 못함

인간 검토 건너뛰기

Willison의 개인 원칙: “다른 사람에게 설명할 수 없는 코드는 커밋하지 않는다”.

에이전트가 테스트를 통과하는 무언가를 만들었다고 해서, 그 코드가 곧바로 정확하고 안전하며 유지보수 가능하다는 뜻은 아님
특히 중요한 코드 경로는 항상 사람이 직접 검토
AI 생성 코드는 겉보기엔 탄탄해 보여도, 테스트되지 않은 엣지 케이스에서 무너질 수 있다는 점에서 “카드로 만든 집” 비유가 잘 맞음

바이브 코딩과 프로덕션 엔지니어링 혼동

AI를 활용한 빠른 프로토타이핑, 이른바 “바이브 코딩”은 탐색 단계나 일회성 프로젝트에 적합합니다.

엄격한 스펙, 테스트, 검토 없이 그 결과물을 그대로 프로덕션에 배포하면 문제 발생 가능성 큼
“바이브 코딩”과 “AI 지원 엔지니어링”은 분명히 구분해야 하며, 후자는 이 가이드에서 설명한 규율과 절차가 필요
지금 어떤 모드로 작업하고 있는지 스스로 인식하는 것이 중요

“치명적 삼중주” 무시

Willison이 경고하는, AI 에이전트를 위험하게 만드는 세 가지 속성:

속도: 사람이 검토할 수 있는 속도보다 빠르게 결과를 생성
비결정성: 같은 입력에도 실행마다 다른 출력
비용: 검증을 충분히 하기보다 편법을 쓰도록 유도

스펙과 검토 프로세스는 이 세 가지를 모두 전제로 설계돼야 합니다. 특히 속도가 검증 능력을 앞지르지 않도록 의식적인 제어 필요합니다.

핵심요약

고수준 비전 먼저: 목표와 핵심 요구사항만 명확히 제시하고, AI가 세부를 확장하도록 함
구조화된 스펙: 6가지 핵심 영역(Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries)을 포함한 전문적인 문서로 작성
모듈화된 태스크: 거대한 프롬프트 대신 작은 단위로 분할하여 “지시의 저주”를 피함
3단계 경계 시스템: Always do / Ask first / Never do로 명확한 가드레일 설정
반복과 진화: 스펙을 고정된 결과물이 아니라 테스트와 피드백을 통해 지속적으로 개선
도메인 지식 반영: 경험에서 나온 인사이트와 주의사항을 스펙에 명시적으로 포함

이 가이드라인을 따르면, AI 에이전트가 대규모 컨텍스트에서 방향을 잃거나 헛소리로 빠질 가능성을 눈에 띄게 줄일 수 있습니다.