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

게시일: 2026년 1월 14일 | 원문 작성일: 2026년 1월 13일 | 저자: Addy Osmani | 원문 보기

16비트 픽셀아트 커맨드 센터: 개발자가 구조화된 스펙 문서로 AI 에이전트들을 조율하는 장면

핵심 요약

AI 코딩 에이전트에게 효과적인 스펙을 작성하는 방법을 다룬 가이드예요. 핵심 문제는 너무 큰 스펙이 컨텍스트 한계와 어텐션 제약5으로 모델을 압도한다는 거죠.

하이레벨 비전으로 시작 — 간결한 목표를 주고 AI가 세부사항을 확장하게 해요
전문 문서처럼 구조화 — 명령어, 테스팅, 프로젝트 구조, 코드 스타일, Git 워크플로우, 경계선의 6가지 핵심 영역
모듈화된 프롬프트 — 10개 이상의 요구사항을 한꺼번에 주면 준수율이 급격히 떨어져요
자체 검증과 제약 내장 — 3단계 경계 시스템(항상/먼저 물어보기/절대 금지)으로 에이전트 행동을 가이드해요
테스트하고 반복하고 진화시키기 — 스펙은 살아있는 문서로 다뤄야 해요

• • •

문제: 컨텍스트 과부하

개발자들이 AI 에이전트와 작업할 때 흔히 겪는 문제가 있어요. 충분한 컨텍스트를 제공하면서도 실질적인 한계를 넘지 않아야 한다는 거죠. 한 개발자가 말했듯이, “어느 순간 컨텍스트가 너무 커지면 모델이 무너져요.”

해결책은 AI의 강점을 활용하면서 개발자의 감독을 유지하는 5가지 스펙 작성 원칙이에요.

원칙 1: 하이레벨 비전으로 시작하고 AI가 세부사항을 확장하게 하기

핵심 개념은 간결한 제품 브리프로 시작해서 에이전트가 상세한 스펙을 생성하도록 하는 거예요.

왜 이게 효과적인가요?

”LLM 기반 에이전트는 확실한 하이레벨 지시가 주어지면 세부사항을 살을 붙이는 데 뛰어나요.” 이 접근법은 AI의 확장 능력을 활용하면서 인간의 방향성을 보존해요.

실제 구현

1. 초기 프롬프트 예시:

“사용자가 할 일을 추적할 수 있는 웹앱을 만들어줘. 사용자 계정, 데이터베이스, 간단한 UI가 필요해.”

2. 에이전트 결과물:

개요 섹션
기능 목록
기술 스택 제안
데이터 모델
단계별 계획

3. 플랜 모드 워크플로우 (Claude Code 예시):

Shift+Tab으로 플랜 모드 진입
에이전트가 코드베이스를 분석하고 코드 없이 계획만 생성
모호함이 없어질 때까지 계획을 다듬기
플랜 모드 종료 후 실행

지속적 아티팩트로서의 스펙

스펙을 SPEC.md로 저장하고 세션 간에 관련 섹션을 참조하세요. 이렇게 하면 컨텍스트 손실을 줄이고 PRD(제품 요구사항 문서)처럼 모든 정보가 모이는 중심 역할을 해요.

목표 지향적 프레이밍

처음부터 기술적 세부사항에 집중하기보다 이런 것들에 초점을 맞추세요:

사용자 컨텍스트: 누가 이걸 사용하나요?
문제 정의: 어떤 필요를 해결하나요?
성공 기준: 완료 상태는 어떤 모습인가요?

• • •

원칙 2: 전문적인 PRD/SRS1처럼 스펙 구조화하기

핵심 개념은 확립된 문서화 패턴을 따라 명확한 섹션으로 스펙을 조직하는 거예요.

6가지 핵심 영역 (GitHub 분석)

2,500개 이상의 에이전트 설정 파일을 분석한 결과 필수 섹션들이 밝혀졌어요:

섹션	세부 내용
명령어	플래그가 포함된 완전한 실행 명령어: `npm test`, `pytest -v`, `npm run build`
테스팅	프레임워크 유형, 테스트 파일 위치, 커버리지 기대치
프로젝트 구조	디렉토리를 명확히 매핑: “`src/`는 애플리케이션 코드, `tests/`는 유닛 테스트”
코드 스타일	긴 설명보다 작동하는 예시 하나 제공
Git 워크플로우	브랜치 네이밍, 커밋 형식, PR 요구사항
경계선	에이전트가 절대 건드리면 안 되는 것들

예시 템플릿

# Project Spec: Team Task Manager

## Objective
- 작은 팀이 할 일을 관리할 수 있는 웹앱 구축...

## Tech Stack
- React 18+, TypeScript, Vite, Tailwind CSS
- Node.js/Express 백엔드, PostgreSQL, Prisma ORM

## Commands
- 빌드: npm run build
- 테스트: npm test
- 린트: npm run lint --fix

## Project Structure
- src/ - 애플리케이션 소스 코드
- tests/ - 유닛 및 통합 테스트
- docs/ - 문서

## Boundaries
- Always: 커밋 전 테스트 실행
- Ask first: 데이터베이스 스키마 변경
- Never: 시크릿 커밋

3단계 경계 시스템

가장 효과적인 스펙은 단계별 제한을 사용해요:

Always Do (항상 하기): 승인 없이 안전하게 할 수 있는 작업
Ask First (먼저 물어보기): 인간 검토가 필요한 고영향 변경
Never (절대 금지): 하드 스탑, 금지된 작업

GitHub 연구에서 가장 효과적이라고 꼽힌 제약은 “시크릿을 절대 커밋하지 말 것”이었어요.

3단계 경계 시스템 다이어그램: Always do, Ask first, Never — 3단계 경계 시스템: Always do, Ask first, Never

스펙 주도 개발 워크플로우

4단계 게이트로 각 단계에서 검증을 보장해요:

Specify: 하이레벨 사용자 경험 설명 생성
Plan: 기술 아키텍처와 제약 정의
Tasks: 작고 검토 가능한 청크로 분해
Implement: 에이전트가 태스크를 하나씩 실행

스펙 주도 개발 워크플로우 다이어그램: Specify, Plan, Tasks, Implement — 스펙 주도 개발의 4단계 게이트 워크플로우

각 단계에서 검증을 거치기 때문에 한 곳이 무너지면 전체가 무너지는6 불안정한 코드를 방지할 수 있어요.

살아있는 문서 접근법

결정이 바뀔 때마다 스펙을 업데이트하세요. 스펙을 버전 관리하면 프로젝트 전체에서 유일한 정보 출처로 유지할 수 있어요.

• • •

원칙 3: 태스크를 모듈화된 프롬프트로 분해하기

핵심 개념은 모든 걸 한꺼번에 던지는 대신, 한 번에 하나의 태스크에만 집중된 컨텍스트를 제공하는 거예요.

지시의 저주

연구에 따르면 “프롬프트에 지시나 데이터를 쌓으면 쌓을수록 각 항목에 대한 모델의 준수율이 급격히 떨어져요.”

모놀리식 프롬프트 vs 모듈화된 스펙 비교 다이어그램 — 모놀리식 프롬프트 vs 모듈화된 스펙 비교

실용적인 모듈화 전략

확장된 목차 기법:

핵심 포인트와 참조 태그가 있는 계층적 요약을 만드세요. 에이전트는 요약을 참조하면서 전체 세부사항은 별도로 유지해요.

예시 요약:

- 보안: HTTPS 사용, API 키 보호,
입력 검증 (전체 스펙 4.2 참조)

도메인 전문화를 위한 서브에이전트:

다른 영역에 다른 에이전트를 사용하세요:

데이터베이스 설계자 에이전트
API 코더 에이전트
프론트엔드 개발자 에이전트

각각은 관련 스펙 부분만 받아요.

처리량을 위한 병렬 에이전트:

독립적인 태스크에 여러 에이전트를 동시에 실행하세요. 한 에이전트가 기능을 코딩하는 동안 다른 에이전트가 테스트를 작성해요.

단일 에이전트 vs 멀티 에이전트 비교

측면	단일 에이전트	멀티 에이전트
설정 복잡도	단순	높은 오버헤드
컨텍스트 처리	과부하 가능	분산 부하
적합한 경우	중소규모 프로젝트	대규모 코드베이스

구현 패턴:

SPEC_backend.md와 SPEC_frontend.md로 시작하세요. 에이전트에게 해당 태스크에 관련된 스펙을 사용하도록 지시하세요.

컨텍스트 리프레싱

”새로 시작하기: 주요 기능 간 전환 시 컨텍스트를 비우기 위해 새 세션을 시작하세요.” 컨텍스트 윈도우7를 집중시킨 미니 태스크를 만드세요.

• • •

원칙 4: 자체 검증, 제약, 전문성 내장하기

핵심 개념은 품질 관리와 도메인 지식을 스펙에 직접 내장하는 거예요.

자기 검증 패턴

에이전트에게 스펙 요구사항과 출력을 비교하여 검증하도록 지시하세요:

“구현 후, 결과를 스펙과 비교하고 모든 요구사항이 충족되었는지 확인하세요.”

LLM-as-a-Judge2 평가

두 번째 에이전트를 사용해서 첫 번째 에이전트의 작업을 스타일과 아키텍처 가이드라인에 따라 검토하세요. 이렇게 하면 구문 검사를 넘어서는 의미적 평가가 추가돼요.

적합성 테스팅

스펙에서 직접 도출된 언어 독립적 테스트인 적합성 스위트를 구축하세요. API의 경우 구현이 만족해야 하는 예상 입출력 쌍을 포함하세요.

도메인 지식 활용

전문가 인사이트를 직접 인코딩하세요:

알려진 함정과 해결책
라이브러리별 특이사항
회사 표준과 선호도
코드 스타일 예시 (설명이 아닌)

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

스펙 상세도를 태스크 복잡도에 맞추세요. 단순한 태스크에는 단순한 가이드가 필요하고, 복잡한 것에는 상세한 스펙이 필요해요.

품질 관리 루프

스펙이 에이전트에게 권한을 부여하지만 개발자는 최종 필터로 남아요. 생성된 코드가 기술적으로 스펙을 충족하지만 “뭔가 이상하다”면, 스펙을 다듬고 반복하세요.

• • •

원칙 5: 테스트하고, 반복하고, 스펙을 진화시키기

핵심 개념은 스펙 작성을 테스팅과 개선이 포함된 지속적인 사이클로 다루는 거예요.

지속적 테스팅

각 주요 마일스톤 후 테스트를 실행하세요. 테스트가 실패하면 에이전트가 잘못된 가정으로 계속하게 두지 말고 스펙을 업데이트하세요.

스펙 자체를 반복하기

에이전트가 스펙의 갭이나 모호함을 드러내면 스펙 문서를 업데이트하고 명시적으로 에이전트를 재동기화하세요:

“스펙을 다음과 같이 업데이트했습니다… 이에 따라 계획을 조정하세요.”

스펙 개선 루프 다이어그램: 테스트, 피드백, 개선의 순환 — 스펙 개선 루프: 테스트 → 피드백 → 개선의 지속적 순환

컨텍스트 관리 도구

Model Context Protocol(MCP)3을 구현하는 도구들은 현재 태스크 컨텍스트에 기반해서 관련 스펙 섹션을 자동으로 표면화해요. 수동 컨텍스트 관리가 필요 없어지죠.

병렬 실행 고려사항

여러 에이전트를 동시에 실행할 때:

태스크가 정말 독립적인지 확인
에이전트가 같은 파일에 쓰지 않도록 방지
스펙에 의존성을 명확히 기록

버전 관리 베스트 프랙티스

스펙을 코드와 함께 Git에 커밋하세요. 에이전트는 git diff를 통해 버전 히스토리를 조회하여 변경사항을 이해할 수 있어요. 시간에 따른 스펙 진화를 추적하세요.

비용과 성능 최적화

초안에는 저렴한 모델 사용
프리미엄 모델은 복잡한 추론에 예약
유사한 작업은 배치 처리
효과가 줄어드는 시점 대비 토큰 사용량 모니터링

로깅과 디버깅

에이전트 액션과 출력을 로깅하세요. 트레이스를 검토하여 스펙 오해석을 식별하세요. 실제 에이전트 행동에 기반해서 언어를 다듬으세요.

• • •

피해야 할 흔한 함정

모호한 프롬프트: “뭔가 멋진 거 만들어줘”는 실패해요. “React 컴포넌트 테스트를 작성하는 테스트 엔지니어, 이 예시들을 따르고, 소스 코드는 절대 수정하지 않음”은 작동해요.

요약 없는 과도한 컨텍스트: 계층 구조 없이 50페이지를 통째로 던지면 제대로 처리될 리 없어요.

인간 검토 건너뛰기: “다른 사람에게 설명할 수 없는 코드라면 커밋하지 마세요.”

바이브 코딩4과 프로덕션 코드 혼동: 빠른 프로토타이핑과 실제 배포 코드는 달라요. 지금 어떤 모드로 작업 중인지 명확히 인식해야 해요.

치명적 삼중주8 놓치기: 속도(검토하기 어려움), 비결정성(일관성 없는 출력), 비용(코너 커팅 압박)이 위험한 조건을 만들어요. 스펙과 검토 프로세스가 세 가지 모두를 고려해야 해요.

6가지 핵심 영역 누락: 명령어, 테스팅, 구조, 스타일, 워크플로우, 경계선 - 스펙에 이것들이 없으면 에이전트에게 중요한 가이드가 없는 거예요.

• • •

결론

효과적인 AI 에이전트 스펙을 작성하려면 LLM의 특이점에 맞게 조정된 견고한 소프트웨어 엔지니어링 원칙이 필요해요. 5가지 원칙 - 하이레벨로 시작하기, 전문적으로 구조화하기, 포커스 유지하기, 품질 관리 내장하기, 지속적으로 반복하기 - 이 에이전트를 생산적이고 신뢰할 수 있게 유지하는 스펙을 만들어요.

“이 가이드라인을 따르면 AI 에이전트가 큰 컨텍스트에서 ‘무너지거나’ 헛소리로 빠질 가능성이 훨씬 줄어들어요.”

핵심 테이크어웨이

스펙은 살아있는 아티팩트예요, 정적 문서가 아니에요
구조가 길이보다 중요해요
모듈화가 컨텍스트 과부하를 방지해요
도메인 전문성은 스펙에 속해요
지속적 테스팅이 정렬을 검증해요
개발자가 최종 품질 게이트로 남아야 해요

역자 주

PRD/SRS: PRD(Product Requirements Document)는 제품 요구사항 문서로, 제품이 무엇을 해야 하는지를 정의해요. SRS(Software Requirements Specification)는 소프트웨어 요구사항 명세서로, 더 기술적인 세부사항을 포함해요. 둘 다 프로젝트 시작 전에 작성하는 중요한 문서예요. ↩
LLM-as-a-Judge: LLM을 평가자로 사용하는 기법이에요. 코드를 생성하는 AI 에이전트와 별개로, 다른 LLM이 그 결과물을 검토하고 평가하는 방식이죠. 사람이 모든 것을 검토할 수 없을 때 품질 관리 레이어를 추가하는 방법이에요. ↩
Model Context Protocol (MCP): Anthropic이 개발한 오픈 프로토콜로, AI 어시스턴트가 외부 도구와 데이터 소스에 연결할 수 있게 해줘요. 마치 USB가 다양한 기기를 연결하는 표준이 된 것처럼, MCP는 AI가 다양한 컨텍스트 소스에 접근하는 표준을 제공해요. ↩
바이브 코딩 (Vibe Coding): AI와 대화하면서 “느낌”으로 코딩하는 방식을 말해요. 정확한 명세 없이 “이런 느낌으로 해줘”라고 요청하고 결과를 보면서 조정하는 거죠. 프로토타이핑에는 좋지만, 프로덕션 코드에 적용하면 유지보수가 어려운 코드가 될 수 있어요. ↩
어텐션 제약: LLM의 트랜스포머 아키텍처에서 “어텐션(attention)“은 입력 텍스트의 어느 부분에 집중할지를 결정하는 메커니즘이에요. 컨텍스트가 길어지면 각 토큰에 할당되는 어텐션이 분산되어 중요한 정보를 놓치기 쉬워져요. 마치 동시에 너무 많은 것을 신경 쓰면 집중력이 떨어지는 것과 비슷해요. ↩
원문 “house of cards”: 트럼프 카드로 쌓아 올린 구조물처럼, 기초가 약해서 한 부분이 무너지면 전체가 연쇄적으로 무너지는 상황을 의미해요. 단계별 검증 없이 작성된 코드가 이런 특성을 갖기 쉽죠. ↩
컨텍스트 윈도우: LLM이 한 번에 처리할 수 있는 텍스트의 최대 길이예요. 창문(window)을 통해 볼 수 있는 범위가 제한되어 있듯이, 모델도 한 번에 “볼 수 있는” 텍스트 양에 한계가 있어요. 이 윈도우를 넘어가는 정보는 모델이 참조할 수 없어요. ↩
치명적 삼중주 (Lethal Trifecta): 원저자가 사용한 표현으로, AI 코딩에서 특히 위험한 세 가지 요소의 조합을 말해요. 빠른 속도는 검토할 시간을 빼앗고, 비결정성은 같은 프롬프트에도 다른 결과를 낳으며, 비용 압박은 품질 관리를 건너뛰게 만들어요. 셋이 동시에 작용하면 심각한 버그가 프로덕션에 들어갈 위험이 커져요. ↩

저자 소개: Addy Osmani는 Google Chrome 팀의 엔지니어링 리더로, 웹 성능과 개발자 도구 분야에서 널리 알려진 전문가예요.

참고: 이 글은 Addy Osmani가 자신의 블로그에 게시한 아티클을 번역하고 요약한 것입니다.

원문: How to Write a Good Spec for AI Agents - Addy Osmani (2026년 1월 13일)

생성: Claude (Anthropic)

총괄: 존 (디노이저denoiser)