(번역) AI 에이전트를 위한 좋은 스펙 작성법

January 29, 2026

원문 : How to write a good spec for AI agents

TL;DR: AI를 압도하지 않으면서도 충분히 세밀한 지침(구조, 스타일, 테스트, 경계 조건 등을 포함)을 담아 명확한 스펙을 작성하는 것을 목표로 하세요. 큰 작업을 하나의 거대한 프롬프트로 처리하기보다는 작은 작업 단위로 나누는 것이 좋습니다. 먼저 읽기 전용 모드에서 계획을 세운 뒤, 실행하고 지속적으로 반복 개선하세요.

“AI 에이전트를 위한 좋은 스펙 작성에 대해 많이 들었지만, 아직 제대로 된 프레임워크를 찾지는 못했습니다. RFC에 맞먹는 스펙을 쓸 수도 있겠지만, 어느 순간 컨텍스트가 너무 커져서 모델이 제대로 작동하지 않게 됩니다.”

많은 개발자들이 이와 같은 좌절을 겪고 있습니다. 단순히 방대한 스펙을 AI 에이전트에게 던져주는 방식은 효과적이지 않습니다. 컨텍스트 윈도우의 한계와 모델의 ‘주의력 예산(attention budget)’이 이를 방해하기 때문입니다. 핵심은 스마트한 스펙을 작성하는 것입니다. 즉, 에이전트를 명확하게 안내하면서도 실용적인 컨텍스트 크기를 유지하고, 프로젝트와 함께 진화할 수 있는 문서를 만드는 것입니다. 이 가이드는 Claude Code, Gemini CLI 등 코딩 에이전트를 사용하며 얻은 베스트 프랙티스를 바탕으로, AI 에이전트를 집중력 있고 생산적으로 유지하는 스펙 작성 프레임워크를 제시합니다.

이 글에서는 훌륭한 AI 에이전트 스펙을 위한 다섯 가지 원칙을 다루며, 각 원칙은 굵은 핵심 요약으로 시작합니다.

1. 상위 수준의 비전부터 시작하고, 세부 사항은 AI가 초안을 작성하도록 하세요

프로젝트는 간결한 상위 수준 스펙으로 시작한 뒤, AI가 이를 구체화하여 상세 계획까지 작성하도록 하세요.

처음부터 과도하게 설계하려 하지 말고, 명확한 목표 설명과 몇 가지 핵심 요구사항으로 시작하세요. 이를 “제품 브리프”처럼 다루고, 에이전트가 이를 바탕으로 더 정교한 스펙을 생성하게 하세요. 이렇게 하면 방향성은 여러분이 통제하면서, 세부 확장은 AI의 강점을 활용할 수 있습니다. 다만, 처음부터 반드시 충족해야 할 매우 구체적인 기술 요구사항이 이미 있다면 예외일 수 있습니다.

이 방식이 효과적인 이유

LLM 기반 에이전트는 명확한 상위 지침이 주어졌을 때 세부 사항을 구체화하는 데 매우 뛰어나지만, 분명한 미션이 없으면 쉽게 방향을 잃습니다. 짧은 개요나 목표 설명을 제공하고, AI에게 전체 스펙(예: spec.md)을 작성하도록 요청하면, 에이전트가 계속 참조할 수 있는 지속적인 기준점을 만들 수 있습니다. 에이전트를 사용할수록 사전 계획의 중요성은 더 커집니다. 먼저 계획을 반복 개선한 뒤, 에이전트에게 코드를 작성하도록 넘길 수 있기 때문입니다. 이때 스펙은 여러분과 AI가 함께 만드는 첫 번째 산출물이 됩니다.

실무적인 접근법

새로운 코딩 세션을 시작할 때 이렇게 프롬프트를 써보세요. “당신은 AI 소프트웨어 엔지니어입니다. [프로젝트 X]에 대해 목표, 기능, 제약 조건, 단계별 계획을 모두 포함한 상세 스펙을 작성하세요.” 초기 프롬프트는 반드시 상위 수준에서 시작합니다. 예를 들면, “사용자가 할 일을 추적할 수 있는 웹 앱을 만드세요(할 일 목록), 사용자 계정, 데이터베이스, 간단한 UI 포함”처럼 프로젝트 목표만 간단히 제시합니다. 이 프롬프트에 대해 에이전트는 개요, 기능 목록, 기술 스택 제안, 데이터 모델 등 구조화된 초안 스펙으로 응답할 수 있습니다. 이렇게 작성된 스펙은 여러분과 AI 모두가 계속해서 참고하는 “단일 진실의 원천(source of truth)”이 됩니다. GitHub의 AI 팀은 스펙 주도 개발을 지지하며, “스펙은 프로젝트와 함께 발전하는 공유된 소스이며, 살아있는 실행 산출물이다”라고 강조합니다. 코드로 들어가기 전에 AI가 작성한 스펙을 반드시 검토하고, 여러분의 비전과 맞는지 확인하며 환각이나 방향이 어긋난 부분은 수정하세요.

계획 우선 방식을 적용하려면 Plan Mode를 사용하세요

Claude Code와 같은 도구에는 에이전트를 읽기 전용으로 제한하는 Plan Mode가 있습니다. 이 모드에서는 에이전트가 코드베이스를 분석하고 상세 계획을 작성할 수는 있지만, 코드 작성은 할 수 없습니다. 계획 단계에 매우 적합합니다. Plan Mode(Claude Code에서는 Shift+Tab)를 켜고 만들고 싶은 것을 설명하면, 에이전트가 기존 코드를 탐색하며 스펙을 작성합니다. 이 과정에서 모호한 부분에 대해 질문하도록 요청하세요. 아키텍처, 모범 사례, 보안 위험, 테스트 전략을 검토하게 하세요. 오해의 여지가 없을 때까지 계획을 다듬는 것이 목표입니다. 그다음에야 Plan Mode를 종료하고 에이전트가 실행하도록 허용하세요. 이 워크플로우는 스펙이 충분히 다듬어지기 전에 곧바로 코드 생성을 시작하는 흔한 실수를 방지합니다.

스펙을 컨텍스트로 활용하세요

승인된 스펙은 SPEC.md 같은 파일로 저장하고, 필요할 때마다 관련 섹션을 에이전트에게 제공하세요. 강력한 모델을 사용하는 많은 개발자들이 이 방식을 씁니다. 스펙 파일은 세션 간에도 유지되며, 작업을 재개할 때마다 AI가 기준점을 잃지 않도록 잡아줍니다. 이는 대화 기록이 길어지거나 에이전트를 재시작해야 할 때 발생하는 ‘망각’을 완화합니다. 팀에서 PRD를 사용하는 것과 유사하게, 인간과 AI 모두가 참고할 수 있는 문서입니다. 한 엔지니어의 말처럼, “먼저 좋은 문서를 작성하면, 모델은 그 입력만으로도 구현을 만들어낼 수 있다”는 경우가 많습니다. 그 문서가 바로 스펙입니다.

목표 중심으로 유지하세요

AI 에이전트를 위한 상위 수준 스펙은 초기에는 ‘어떻게’보다 ‘무엇’과 ‘왜’에 집중해야 합니다. 사용자 스토리와 수용 기준을 떠올려 보세요. 누가 사용하는가? 무엇이 필요한가? 성공의 기준은 무엇인가? (예: “사용자는 할 일을 추가, 수정, 완료할 수 있어야 하며, 데이터는 영구 저장되고 앱은 반응형이며 안전해야 한다”). 이렇게 하면 AI가 단순한 기술적 할 일 목록이 아니라 사용자와 결과에 기반해 상세 스펙을 작성하게 됩니다. GitHub Spec Kit 문서에서도 “무엇을 왜 만드는지에 대한 상위 수준의 설명을 제공하고, 사용자 경험과 성공 기준에 초점을 맞춘 상세 스펙은 코딩 에이전트가 생성하게 하라”라고 권장합니다. 이 큰 그림이 이후 코딩 단계에서 나무만 보고 숲을 보지 못하는 실수를 방지하게 해 줍니다.

2. 전문적인 PRD(또는 SRS)처럼 스펙을 구조화하세요

AI 스펙을 정리되지 않은 메모가 아니라, 명확한 섹션을 가진 구조화된 문서(PRD)로 다루세요.

많은 개발자들이 에이전트용 스펙을 전통적인 제품 요구사항 문서(PRD)나 시스템 설계 문서처럼 다룹니다. 즉, 포괄적이고 체계적이며, ‘문자 그대로 해석하는’ AI가 이해하기 쉬운 형태로 작성합니다. 이러한 형식은 에이전트에게 명확한 청사진을 제공하고 모호성을 줄여 줍니다.

여섯 가지 핵심 영역

GitHub가 2,500개 이상의 에이전트 설정 파일을 분석한 결과, 가장 효과적인 스펙에는 공통적으로 여섯 가지 영역이 포함되어 있었습니다. 다음 체크리스트를 완성도 점검용으로 사용하세요.

1. 명령어(Commands)

단순한 도구 이름이 아니라, 플래그까지 포함한 실제 실행 명령어를 앞부분에 배치하세요. (예: npm test, pytest -v, npm run build) 에이전트는 이를 지속적으로 참조합니다.

2. 테스트(Testing)

테스트 실행 방법, 사용하는 프레임워크, 테스트 파일 위치, 커버리지 기대치 등을 명시하세요.

3. 프로젝트 구조(Project structure)

소스 코드, 테스트, 문서의 위치를 명확히 하세요. (예: “src/는 애플리케이션 코드, tests/는 단위 테스트, docs/는 문서”)

4. 코드 스타일(Code style)

스타일을 설명하는 문단 세 개보다, 실제 코드 예제 하나가 훨씬 효과적입니다. 명명 규칙, 포맷팅 규칙, 좋은 출력 예시를 포함하세요.

5. Git 워크플로우(Git workflow)

브랜치 명명 규칙, 커밋 메시지 형식, PR 요구사항 등을 명시하면 에이전트가 그대로 따를 수 있습니다.

6. 작업 경계(Boundaries)

에이전트가 절대 건드려서는 안 되는 것들을 명확히 하세요. (예: 비밀 정보, vendor 디렉터리, 프로덕션 설정, 특정 폴더 등) 가장 흔하면서도 유용한 제약 조건은 “비밀 정보 절대 커밋 금지”였습니다.

기술 스택은 구체적으로 명시하세요

“리액트 프로젝트”가 아니라 “타입스크립트, Vite, Tailwind CSS를 사용하는 리액트 18”처럼 작성하세요. 버전과 핵심 의존성을 포함하세요. 모호한 스펙은 모호한 코드를 낳습니다.

일관된 형식을 사용하세요

명확성이 가장 중요합니다. 많은 개발자들이 마크다운 헤딩이나 XML 유사 태그를 사용해 섹션을 구분합니다. AI 모델은 자유 형식 텍스트보다 구조화된 텍스트를 더 잘 처리합니다. 예를 들면 다음과 같습니다.

# 프로젝트 스펙: 팀 전용 할 일 관리 앱

## 목표
- 소규모 팀이 작업을 관리할 수 있는 웹 앱을 구축합니다.

## 기술 스택
- React 18+, TypeScript, Vite, Tailwind CSS
- Node.js/Express, PostgreSQL, Prisma ORM

## 커맨드
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint --fix`

## 프로젝트 구조
- `src/` – 애플리케이션 코드
- `tests/` – 테스트
- `docs/` – 문서

## 작업 경계
- ✅ 항상: 커밋 전 테스트 실행
- ⚠️ 먼저 문의: DB 스키마 변경
- 🚫 절대 금지: 비밀 정보 커밋

이러한 수준의 체계화는 명확한 사고를 돕는 동시에 AI가 정보를 찾는 데도 도움이 됩니다. 엔트로픽 엔지니어들 또한 프롬프트를 <배경>, <지침>, <도구>, <출력 포맷>처럼 구분하라고 권장합니다. 이는 모델에게 정보의 성격을 명확히 알려 주기 때문입니다. “최소한”은 “짧음”과 동일하지 않습니다. 중요한 디테일이라면 충분히 포함하되, 핵심에 집중하세요.

스펙을 툴체인에 통합하세요

스펙을 버전 관리와 CI/CD에 연결된 “실행 가능한 산출물”로 다루세요. GitHub Spec Kit은 스펙을 엔지니어링 프로세스의 중심에 두는 4단계 게이트 워크플로우를 제안합니다. 스펙을 작성한 후 방치하는 대신, 스펙이 구현, 체크리스트, 작업 분할을 주도합니다. 여러분의 주요 역할은 방향을 제시하는 것이고, 코딩 에이전트가 대부분의 작성 작업을 수행합니다. 각 단계는 특정 임무를 가지며, 현재 작업이 완전히 검증이 끝나야 다음으로 넘어갑니다.

1. 스펙(Specify)

무엇을 만들고자 하는지, 그리고 왜 만드는지에 대한 고수준 설명을 제공하세요. 코딩 에이전트는 이러한 정보를 바탕으로 상세한 스펙을 생성합니다. 이 단계에서 중요한 것은 기술 스택이나 구체적 디자인이 아니라, 사용자 여정, 경험, 성공의 기준 등입니다. 누가 이 제품을 사용할 것인지, 어떤 문제를 해결하는지, 사용자가 어떻게 상호작용하는지와 같은 항목을 명확히 기술하세요. 사용자가 경험하게 될 전반적인 그림을 그리고, 세부사항의 구체화는 에이전트에게 맡기세요. 이러한 스펙은 프로젝트가 진행됨에 따라 살아 움직이며 진화하는 문서가 됩니다.

2. 계획(Plan)

이제 기술적인 단계입니다. 원하는 기술 스택, 아키텍처, 그리고 제약 사항을 명시하세요. 코딩 에이전트가 이러한 내용을 바탕으로 전체적인 기술 계획을 수립합니다. 회사에서 표준으로 삼는 기술, 레거시 시스템과의 통합, 컴플라이언스 요구사항 등도 모두 포함하세요. 여러 가지 접근 방식을 비교하거나 대안 계획안을 요청할 수도 있습니다. 내부 문서를 제공한다면, 에이전트가 해당 아키텍처 패턴을 직접 계획에 반영할 수 있습니다.

3. 작업(Tasks)

코딩 에이전트는 스펙과 계획을 바탕으로 실제 작업 단위로 쪼갭니다. 각 작업은 작고 검토가 가능해야 하며, 전체 퍼즐의 특정 조각을 해결하는 것처럼 분리되어야 합니다. 각 작업은 독립적으로 구현 및 테스트할 수 있어야 하며, “인증 기능 구현”과 같이 모호한 것보다 “이메일 형식을 검증하는 회원가입 엔드포인트 구현”과 같은 구체적인 단위가 되어야 합니다.

4. 구현(Implement)

코딩 에이전트는 작업 단위를 하나씩 또는 병렬로 처리합니다. 수천 줄짜리 코드 덤프 대신, 각 작업별로 집중된 변경사항을 검토하게 됩니다. 에이전트는 “무엇”(스펙), “어떻게”(계획), “무엇을 해야 하는지”(작업)에 대한 정보를 모두 인지합니다. 그리고 무엇보다도, 각 단계에서 사용자(사람)의 검토와 피드백을 거쳐 다음 단계로 넘어가게 해야 합니다. 스펙이 적합한지, 계획이 제약사항을 반영하는지, AI가 놓친 엣지케이스가 없는지 등을 검증하세요. 이러한 프로세스는 체크포인트를 통해 사용자가 비판적 시각으로 빈틈을 발견하고, 피드백을 반영하여 방향을 수정할 수 있게 합니다.

이러한 단계적 워크플로우는 Willison이 말한 “기초가 부실하여 무너지기 쉬운(house of cards) 코드”, 즉, 겉보기엔 그럴듯하지만 검증 앞에서 무너지는 취약한 AI 산출물을 방지합니다. 엔트로픽의 Skills 시스템도 비슷한 패턴을 제공하며, 에이전트가 호출하는 재사용 가능한 마크다운 기반 동작을 정의할 수 있게 해 줍니다. 이 워크플로우에 스펙을 내장하면, 스펙이 검증되기 전까지 에이전트가 다음 단계로 진행할 수 없고, 변경 사항이 작업 분해와 테스트에 자동으로 전파되도록 할 수 있습니다.

agents.md를 통한 특화된 페르소나 고려

GitHub Copilot 같은 도구에서는 agents.md 파일을 만들어 특화된 에이전트 페르소나를 정의할 수 있습니다. 예를 들어 기술 문서를 담당하는 @docs-agent, QA를 위한 @test-agent, 코드 리뷰를 위한 @security-agent 같은 식입니다. 각 파일은 해당 페르소나의 행동, 명령, 경계를 정의하는 집중된 스펙 역할을 합니다. 이는 범용 에이전트 하나를 쓰는 대신, 작업별로 다른 에이전트를 사용하고 싶을 때 특히 유용합니다.

에이전트 경험(AX)을 위한 설계

개발자 경험(DX)을 위해 API를 설계하듯이, 에이전트 경험(AX)을 위한 스펙 설계도 고려할 필요가 있습니다. 이는 에이전트가 파싱하기 쉬운 깔끔한 형식을 의미합니다. 에이전트가 소비할 API를 위한 OpenAPI 스키마, LLM 소비를 위해 문서를 요약한 llms.txt 파일, 그리고 명시적인 타입 정의 등이 여기에 포함됩니다. Agentic AI Foundation(AAIF)은 도구 통합을 위한 MCP(Model Context Protocol) 같은 프로토콜을 표준화하고 있는데, 이런 패턴을 따르는 스펙은 에이전트가 더 신뢰성 있게 이해하고 행동할 수 있습니다.

PRD vs SRS 사고방식

기존 문서화 관행을 차용하는 것도 도움이 됩니다. AI 에이전트 스펙에서는 보통 이 둘을 하나의 문서로 섞어 쓰게 되지만, 두 관점을 모두 다루는 것이 효과적입니다. PRD처럼 작성하면 “각 기능의 왜(why)” 같은 사용자 중심 맥락을 포함하게 되어 AI가 엉뚱한 최적화를 하지 않게 됩니다. 여기에 SRS처럼 세부 사항을 확장하면, AI가 올바른 코드를 생성하는 데 필요한 구체적인 정보(어떤 데이터베이스나 API를 쓰는지 등)를 확실히 전달할 수 있습니다. 개발자들은 이러한 초기 노력이 이후 에이전트와의 오해를 대폭 줄여 준다는 것을 경험적으로 알고 있습니다.

스펙을 “살아 있는 문서”로 유지하기

스펙을 한 번 쓰고 끝내지 마세요. 사용자와 에이전트가 결정을 내리거나 새로운 정보를 발견할 때마다 스펙을 업데이트해야 합니다. AI가 데이터 모델을 변경했거나 기능을 하나 제거하기로 했다면, 이를 스펙에 반영하여 단일 진실의 원천으로 유지해야 합니다. 이를 버전 관리되는 문서라고 생각하시면 됩니다. 스펙 주도 워크플로우에서는 스펙이 구현, 테스트, 작업 분해를 이끌며, 스펙이 검증되기 전에는 코딩으로 넘어가지 않습니다. 이 습관은 프로젝트의 일관성을 유지하는 데 큰 도움이 되며, 나중에 다시 돌아왔을 때도 맥락을 잃지 않게 해 줍니다. 스펙은 AI만을 위한 것이 아니라, 개발자인 사용자가 전체를 조망하고 AI의 결과물이 실제 요구사항을 충족하는지 확인하는 데도 도움이 됩니다.

3. 하나의 큰 프롬프트가 아니라, 작업을 모듈화 된 프롬프트와 컨텍스트로 나누세요

분할 정복 방식으로 접근하세요. 모든 것을 한 번에 담은 거대한 프롬프트 대신, AI에게 한 번에 하나의 명확한 작업만 맡기세요.

경험 많은 AI 엔지니어들은 프로젝트 전체(모든 요구사항, 모든 코드, 모든 지침)를 하나의 프롬프트나 에이전트 메시지에 억지로 넣으려는 시도가 혼란을 부르는 지름길이라는 것을 이미 알고 있습니다. 토큰 제한에 걸릴 위험이 있을 뿐 아니라, 너무 많은 지시가 한꺼번에 주어질 때 모델이 초점을 잃는 이른바 “지시 사항의 저주(curse of instructions)”에 빠질 위험도 있습니다. 이 저주는 지침이 많을수록 오히려 그 어느 것도 제대로 따르지 못하게 되는 현상을 의미합니다. 해결책은 스펙과 워크플로우를 모듈형으로 설계하여, 한 번에 하나의 조각만 다루고 그 조각에 필요한 컨텍스트만 불러오는 것입니다.

컨텍스트와 지시가 너무 많을 때의 저주

연구 결과는 많은 개발자들이 경험적으로 느껴왔던 사실을 확인해 주었습니다. 프롬프트에 더 많은 지시나 데이터를 쌓아 올릴수록, 모델이 각 지시를 충실히 따르는 성능은 급격히 떨어집니다. 한 연구에서는 이를 “지시 사항의 저주”라고 명명했으며, GPT-4나 Claude조차도 동시에 많은 요구사항을 만족시키는 데 어려움을 겪는다는 점을 보여주었습니다. 실무적으로 보면, 10개의 상세한 규칙을 불릿 포인트로 제시하면 AI는 처음 몇 개는 따르다가 나머지는 놓치기 시작할 수 있습니다. 더 나은 전략은 반복적 집중입니다. 업계 가이드라인에서는 복잡한 요구사항을 순차적이고 단순한 지시로 분해하는 것을 모범 사례로 권장합니다. AI를 한 번에 하나의 하위 문제에만 집중하게 하고, 그것이 끝나면 다음으로 넘어가세요. 이렇게 하면 품질을 높게 유지하면서 오류를 관리하기 쉬워집니다.

스펙을 단계나 컴포넌트로 나누세요

스펙 문서가 매우 길거나 다루는 범위가 넓다면, 이를 여러 부분으로 나누는 것을 고려해 보세요(물리적으로 파일을 분리하거나, 명확히 구분된 섹션으로 나누는 방식입니다). 예를 들어 “백엔드 API 스펙” 섹션과 “프런트엔드 UI 스펙” 섹션을 따로 둘 수 있습니다. 백엔드를 작업할 때마다 프런트엔드 스펙을 항상 AI에게 제공할 필요는 없고, 그 반대도 마찬가지입니다. 다중 에이전트 구성을 사용하는 많은 개발자들은 데이터베이스/스키마, API 로직, 프런트엔드처럼 각 부분마다 별도의 에이전트나 하위 프로세스를 만들기도 합니다. 단일 에이전트를 사용하더라도, 해당 작업에 필요한 스펙 섹션만 프롬프트에 복사해 넣는 방식으로 이를 흉내 낼 수 있습니다. 컨텍스트 과부하를 피하세요. DigitalOcean AI 가이드가 경고하듯, 인증 작업과 데이터베이스 스키마 변경을 한 번에 섞지 마세요. 각 프롬프트는 현재 목표에 딱 맞게 범위를 좁혀야 합니다.

대규모 스펙을 위한 확장된 목차 / 요약

유용한 기법 중 하나는 에이전트에게 스펙 전체에 대한 요약이 포함된 확장된 목차(Table of Contents)를 만들게 하는 것입니다. 이는 각 섹션을 몇 가지 핵심 포인트나 키워드로 압축하고, 상세 내용이 있는 위치를 참조로 남기는 “스펙 요약”에 해당합니다. 예를 들어 전체 스펙에 500 단어 분량의 “보안 요구사항” 섹션이 있다면, 이를 “보안: HTTPS 사용, API 키 보호, 입력 검증 구현(전체 스펙 §4.2 참조)” 정도로 요약할 수 있습니다. 계획 단계에서 이런 계층적 요약을 만들어 두면, 세부 사항은 필요할 때만 불러오고 전체 구조를 조망할 수 있는 정보를 프롬프트에 유지할 수 있습니다. 이 확장된 목차는 일종의 인덱스 역할을 합니다. 에이전트는 이를 보고 “아, 보안 섹션이 있구나”라고 인식하고, 필요할 때 해당 부분을 요청할 수 있습니다. 이는 사람이 스펙 문서의 개요를 훑은 뒤, 특정 작업을 할 때 관련 페이지를 찾아보는 방식과 유사합니다.

이를 구현하려면, 스펙을 작성한 뒤 에이전트에게 다음과 같이 요청할 수 있습니다. “위 스펙을 각 섹션의 핵심 포인트와 참조 태그를 포함한 매우 간결한 개요로 요약해 주세요.” 그 결과는 각 섹션마다 한두 문장의 요약이 붙은 목록이 될 것입니다. 이 요약은 시스템 메시지나 어시스턴트 메시지에 유지하여, 토큰을 과도하게 소모하지 않으면서도 에이전트의 초점을 안내하는 역할을 하게 할 수 있습니다. 이런 계층적 요약 접근 방식은 LLM이 상위 구조에 집중함으로써 장기 컨텍스트를 유지하는 데 도움이 되는 것으로 알려져 있습니다. 에이전트는 스펙에 대한 “정신적 지도”를 갖게 됩니다.

스펙의 각 부분을 위한 서브 에이전트 또는 “스킬” 활용하기

또 다른 고급 접근 방식은 여러 개의 전문화된 에이전트를 사용하는 것입니다(엔트로픽에서는 이를 서브에이전트라고 부르며, “skills”라고 부를 수도 있습니다). 각 서브에이전트는 특정 전문 영역을 위해 설정되고, 그 영역에 해당하는 스펙 부분만을 전달받습니다. 예를 들어 데이터 모델 섹션만 알고 있는 데이터베이스 디자이너 서브에이전트와, API 엔드포인트 스펙만 아는 API 코더 서브에이전트를 둘 수 있습니다. 메인 에이전트(또는 오케스트레이터)는 작업을 적절한 서브에이전트로 자동으로 라우팅 할 수 있습니다. 이렇게 하면 각 에이전트가 다뤄야 할 컨텍스트 창이 작아지고 역할이 명확해져 정확도가 높아지며, 독립적인 작업을 병렬로 진행할 수 있습니다. 엔트로픽의 Claude Code는 각 서브에이전트에 자체 시스템 프롬프트와 도구를 부여하는 방식으로 이를 지원합니다. 그들의 문서에 따르면, “각 서브에이전트는 특정 목적과 전문 영역을 가지며, 메인 대화와 분리된 자체 컨텍스트 창을 사용하고, 행동을 안내하는 맞춤형 시스템 프롬프트를 가진다”라고 설명합니다. 특정 작업이 서브에이전트의 도메인과 일치하면, Claude는 해당 작업을 서브에이전트에 위임하고 독립적인 결과를 받아옵니다.

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

여러 에이전트를 동시에 실행하는 방식은 개발자 생산성의 “다음 큰 흐름”으로 떠오르고 있습니다. 하나의 에이전트가 작업을 끝낼 때까지 기다리는 대신, 겹치지 않는 작업을 위해 병렬 에이전트를 띄울 수 있습니다. Willison은 이를 “병렬 코딩 에이전트 활용”이라고 표현하며, “정신적으로는 지치지만, 놀랄 만큼 효과적”이라고 말합니다. 핵심은 에이전트들이 서로 작업을 침범하지 않도록 범위를 잘 나누는 것입니다. 예를 들어 한 에이전트는 기능을 구현하고, 다른 하나는 테스트를 작성하거나, 서로 다른 컴포넌트를 동시에 구축할 수 있습니다. LangGraph나 OpenAI Swarm 같은 오케스트레이션 프레임워크는 이러한 에이전트들을 조율하는 데 도움을 주며, Chroma 같은 벡터 데이터베이스를 통한 공유 메모리는 중복 프롬프트 없이 공통 컨텍스트에 접근할 수 있게 해 줍니다.

단일 에이전트 vs. 다중 에이전트: 언제 무엇을 쓸 것인가

실무에서 서브에이전트나 스킬별 프롬프트를 사용하는 방식은 다음과 같을 수 있습니다. 예를 들어 SPECbackend.md, SPECfrontend.md처럼 여러 개의 스펙 파일(또는 프롬프트 템플릿)을 유지하고, AI에게 “백엔드 작업은 SPECbackend를 참조하고, 프런트엔드 작업은 SPECfrontend를 참조하세요”라고 지시하는 것입니다. 또는 Cursor나 Claude 같은 도구에서 실제로 각 부분마다 서브에이전트를 띄울 수도 있습니다. 이는 단일 에이전트 루프보다 설정이 확실히 복잡하지만, 인간 개발자가 하는 방식과 유사합니다. 우리는 50페이지짜리 스펙 전체를 한 번에 머릿속에 담고 작업하지 않습니다. 필요한 부분만 떠올리고, 전체 아키텍처에 대한 대략적인 감각만 유지합니다. 문제는 상호 의존성을 관리하는 것입니다. 프런트엔드는 백엔드 스펙의 API 계약을 알아야 하는 것처럼, 서브에이전트들 역시 조율이 필요합니다. 중앙 집중식 개요(또는 “아키텍트” 에이전트)가 하위 스펙들을 참조하며 일관성을 유지하는 데 도움이 될 수 있습니다.

각 프롬프트를 하나의 작업이나 섹션에 집중시키세요

화려한 다중 에이전트 구성이 없어도, 수동으로 모듈성을 강제할 수 있습니다. 예를 들어 스펙을 작성한 다음, 다음 단계로 “1단계: 데이터베이스 스키마 구현”을 진행할 수 있습니다. 이때 스펙의 데이터베이스 섹션과 기술 스택 같은 전역 제약만 AI에게 제공합니다. 에이전트가 이를 처리합니다. 그다음 “2단계: 인증 기능 구현”으로 넘어가면서, 인증 섹션과 필요하다면 관련 스키마 부분만 제공합니다. 이렇게 주요 작업마다 컨텍스트를 새로 구성하면, 모델이 불필요하거나 오래된 정보에 방해받지 않게 할 수 있습니다. 한 가이드에서는 “주요 기능을 전환할 때는 새 세션을 시작해 컨텍스트를 초기화하라”라고 제안합니다. 중요한 전역 규칙(스펙의 제약 섹션 등)은 매번 상기시킬 수 있지만, 필요하지 않은 전체 스펙을 모두 밀어 넣을 필요는 없습니다.

인라인 지시와 코드 TODO 활용하기

또 다른 모듈화 기법은 코드나 스펙 자체를 대화의 일부로 사용하는 것입니다. 예를 들어 코드에 // TODO 주석을 달아 무엇을 구현해야 하는지 설명하고, 에이전트가 이를 하나씩 채우게 할 수 있습니다. 각 TODO는 작은 작업을 위한 미니 스펙 역할을 합니다. 이렇게 하면 AI는 “이 스펙 조각에 따라 이 특정 함수를 구현하라”는 식으로 매우 명확한 목표에 집중할 수 있고, 짧은 반복 루프로 작업을 진행할 수 있습니다. 이는 전체 체크리스트를 한 번에 주는 대신, 한 항목씩 완료하게 하는 것과 유사합니다.

결론은 간단합니다

하나의 거대한 프롬프트보다 작고 집중된 컨텍스트가 더 낫습니다. 이는 품질을 향상하고, AI가 한꺼번에 너무 많은 정보에 “압도”되지 않도록 도와줍니다. 한 모범 사례 요약에서 말하듯, 모델에는 “하나의 작업에 집중”하게 하고 “관련 정보만 제공”하며, 모든 것을 한꺼번에 던져 넣는 일을 피하세요. 작업을 모듈로 나누고, 스펙 요약이나 서브 스펙 에이전트 같은 전략을 사용하면 컨텍스트 크기 제한과 AI의 단기 기억 한계를 우회할 수 있습니다. 잘 먹여진 AI는 잘 설계된 함수와 같습니다. 현재 작업에 필요한 입력만 제공하세요.

4. 자체 점검, 제약, 그리고 사람의 전문성을 스펙에 포함하세요

스펙을 단순히 에이전트를 위한 할 일 목록이 아니라, 품질 관리를 위한 가이드로 만드세요. 그리고 여러분 자신의 전문성을 주저 없이 주입하세요.

AI 에이전트를 위한 좋은 스펙은 AI가 어디에서 실수할 수 있는지를 미리 예상하고, 이를 막기 위한 가드레일을 설정합니다. 또한 여러분이 알고 있는 것들(도메인 지식, 엣지 케이스, “함정들”)을 활용해 AI가 진공 상태에서 작업하지 않도록 합니다. 스펙을 AI를 위한 코치이자 심판이라고 생각해 보세요. 올바른 접근을 장려하고, 반칙을 지적하는 역할을 해야 합니다.

3단계 경계(boundary) 시스템을 사용하세요

GitHub에서 2,500개 이상의 에이전트 파일을 분석한 결과, 가장 효과적인 스펙들은 단순한 “하지 말 것” 목록 대신 3단계 경계 시스템을 사용하고 있었습니다. 이 방식은 에이전트에게 언제 진행해야 하는지, 언제 멈춰서 물어봐야 하는지, 언제 완전히 중단해야 하는지를 더 명확히 안내합니다.

✅ 항상 해야 할 것(Always do)

에이전트가 질문 없이 수행해야 하는 작업입니다. “커밋 전에 항상 테스트를 실행할 것.”, “스타일 가이드의 명명 규칙을 항상 따를 것.”, “에러는 항상 모니터링 서비스에 로그로 남길 것.”

⚠️ 먼저 물어볼 것(Ask first)

다음은 승인이 필요한 작업입니다. “데이터베이스 스키마를 수정하기 전에 물어볼 것.”, “새로운 의존성을 추가하기 전에 물어볼 것.”, “CI/CD 설정을 변경하기 전에 물어볼 것.”. 이 단계는 문제는 없을 수도 있지만, 영향 범위가 큰 변경 사항을 사람이 한 번 더 확인하도록 해 줍니다.

🚫 절대 하지 말 것(Never do)

명확한 금지 사항입니다. “비밀 정보이나 API 키를 절대 커밋하지 말 것.”, “node_modules/나 vendor/를 절대 수정하지 말 것.”, “명시적인 승인 없이 실패하는 테스트를 제거하지 말 것.”. 연구에서 가장 흔하면서도 유용한 제약 조건은 바로 “비밀 정보를 커밋하지 말 것”이었습니다.

이 3단계 접근 방식은 단순한 규칙 목록보다 훨씬 정교합니다. 어떤 행동은 항상 안전하고, 어떤 행동은 감독이 필요하며, 어떤 행동은 절대 허용되지 않는다는 점을 인정하기 때문입니다. 에이전트는 “항상” 항목에 대해서는 자신 있게 진행하고, “먼저 물어볼 것” 항목은 검토 대상으로 표시하며, “절대 하지 말 것” 항목에서는 즉시 중단할 수 있습니다.

자체 검증을 장려하세요

강력한 패턴 중 하나는 에이전트가 자신의 작업을 스펙에 비추어 스스로 검증하도록 만드는 것입니다. 도구가 허용한다면, 코드 생성 후 유닛 테스트나 린트 같은 체크를 실행하도록 통합할 수 있습니다. 하지만 스펙이나 프롬프트 수준에서도 AI에게 재확인을 지시할 수 있습니다. 예를 들어 “구현이 끝난 뒤, 결과를 스펙과 비교하고 모든 요구사항이 충족되었는지 확인하세요. 충족되지 않은 스펙 항목이 있다면 나열하세요.” 와 같은 방식입니다. 이는 LLM이 자신의 결과물을 스펙과 비교하며 되돌아보도록 만들어, 누락 사항을 잡아내는 데 도움이 됩니다. 프로세스에 내장된 일종의 자기 감사(self-audit)입니다.

예를 들어 프롬프트 끝에 다음과 같이 덧붙일 수 있습니다. “(함수를 작성한 후, 위 요구사항 목록을 검토하고 각 항목이 충족되었는지 확인하며, 누락된 항목이 있다면 표시하세요.)” 그러면 모델은 코드 출력 뒤에 각 요구사항 충족 여부를 표시한 간단한 체크리스트를 덧붙일 가능성이 큽니다. 이는 테스트를 실행하기 전 단계에서 무언가를 놓칠 확률을 줄여 줍니다. 완벽한 해결책은 아니지만, 분명 도움이 됩니다.

주관적 검사를 위한 LLM-as-a-Judge

자동으로 테스트하기 어려운 기준들(코드 스타일, 가독성, 아키텍처 패턴 준수 여부)에 대해서는 “LLM-as-a-Judge” 접근 방식을 고려해 보세요. 이는 두 번째 에이전트(또는 별도의 프롬프트)를 사용해 첫 번째 에이전트의 결과물을 스펙의 품질 가이드라인에 따라 검토하게 하는 방식입니다. 엔트로픽을 비롯한 여러 곳에서 이 방식이 주관적 평가에 효과적이라는 점을 확인했습니다. 예를 들어 다음과 같이 요청할 수 있습니다. “이 코드를 스타일 가이드 준수 여부 기준으로 리뷰하고, 위반 사항을 표시해 주세요.” 심사 역할의 에이전트는 피드백을 반환하고, 이는 반영되거나 수정 작업을 촉발합니다. 이는 단순한 문법 검사를 넘어서는 의미적 평가 계층을 추가합니다.

적합성(conformance) 테스트

Simon Willison은 적합성 테스트 스위트를 만드는 것을 권장합니다. 이는 언어에 독립적인 테스트(종종 YAML 기반)로, 어떤 구현이든 반드시 통과해야 하는 계약과 같습니다. 예를 들어 API를 만든다면, 적합성 테스트는 기대 입력과 출력 값을 명시하고, 에이전트가 작성한 코드는 모든 케이스를 만족해야 합니다. 이는 스펙에서 직접 파생되며 여러 구현에서 재사용될 수 있기 때문에, 즉흥적인 유닛 테스트보다 훨씬 엄격합니다. 스펙의 성공 기준(Success) 섹션에 이러한 적합성 기준을 포함시키세요(예: “conformance/api-tests.yaml에 정의된 모든 케이스를 통과해야 함”).

스펙에 테스트를 적극 활용하세요

가능하다면 테스트 계획이나 실제 테스트 자체를 스펙과 프롬프트 흐름에 포함시키세요. 전통적인 개발에서는 TDD나 테스트 케이스 작성을 통해 요구사항을 명확히 하듯, AI와의 작업에서도 동일한 접근을 취할 수 있습니다. 예를 들어 스펙의 성공 기준에 “이 입력값들은 다음과 같은 출력값을 만들어야 한다” 또는 “다음 유닛 테스트들이 통과되어야 한다”라고 명시할 수 있습니다. 에이전트는 이를 머릿속으로 시뮬레이션하거나, 실행 능력이 있다면 실제로 실행할 수 있습니다. Simon Willison은 견고한 테스트 스위트를 갖추는 것이 에이전트에게 초능력을 주는 것과 같다고 언급했습니다. 테스트가 실패하면 빠르게 검증하고 반복할 수 있기 때문입니다. AI 코딩 맥락에서는 스펙에 테스트용 의사 코드나 기대 결과를 조금만 적어두어도 구현 방향을 크게 안내할 수 있습니다. 또한 서브에이전트 구조에서 전용 “테스트 에이전트”를 두어, 스펙 기준에 따라 “코드 에이전트”의 출력을 지속적으로 검증하게 할 수도 있습니다.

도메인 지식을 적극 반영하세요

스펙에는 숙련된 개발자나 맥락을 아는 사람만이 알 수 있는 인사이트가 반영되어야 합니다. 예를 들어 이커머스 에이전트를 만든다면, “상품(products)과 카테고리(categories)는 다대다 관계”라는 사실을 명확히 적어 두세요. AI가 이를 스스로 추론할 것이라고 기대하지 마세요. 그렇지 않을 수 있습니다. 특정 라이브러리가 악명 높은 함정을 가지고 있다면, 피해야 할 점을 명시하세요. 본질적으로, 여러분의 멘토링을 스펙에 적극 반영하는 것입니다. 스펙에는 “라이브러리 X를 사용할 경우, Y 버전에서 메모리 누수 문제가 있으므로 Z 워크어라운드를 적용할 것” 같은 조언이 포함될 수 있습니다. 이런 수준의 디테일이 있어야 평범한 AI 출력이 정말로 견고한 결과물로 바뀝니다. 이는 AI를 흔한 함정에서 벗어나게 안내하기 때문입니다.

또한 선호 사항이나 스타일 가이드(예: “리액트에서는 클래스 컴포넌트보다 함수형 컴포넌트를 사용할 것”)가 있다면 이를 스펙에 명시하세요. 그러면 AI는 여러분의 스타일을 모방하게 됩니다. 많은 엔지니어들은 스펙에 작은 예시도 포함합니다. 예를 들어 “모든 API 응답은 JSON이어야 한다. 예: { “error”: “message” }” 와 같이 적으면, AI는 정확히 원하는 형식에 고정됩니다.

단순한 작업에는 미니멀리즘을

우리는 철저한 스펙을 권장하지만, 언제 단순하게 유지해야 하는지를 아는 것 또한 전문성의 일부입니다. 비교적 단순하고 고립된 작업의 경우, 과도한 스펙은 도움이 되기보다 혼란을 줄 수 있습니다. 예를 들어 “페이지 중앙에 div를 정렬하라” 같은 요청이라면, “해결책은 간결하게 유지하고 불필요한 마크업이나 스타일을 추가하지 말 것”정도로 충분할 수 있습니다. 이 경우 전체 PRD는 필요하지 않습니다. 반대로 “토큰 갱신과 에러 처리를 포함한 OAuth 플로우를 구현하라” 같은 복잡한 작업에서는 상세한 스펙이 반드시 필요합니다. 좋은 원칙은 작업 복잡도에 맞게 스펙의 디테일을 조절하는 것입니다. 어려운 문제를 과소하게 스펙화하면 AI는 헤매거나 엉뚱한 방향으로 갈 것이고, 사소한 문제를 과도하게 스펙화하면 AI는 불필요한 지시로 얽힐 수 있습니다.

필요하다면 AI의 “페르소나”를 유지하세요

때로는 스펙의 일부가 에이전트의 행동 방식이나 말투를 정의하는 것이기도 합니다. 특히 사용자와 상호작용하는 에이전트를 만들 때 그렇습니다. 예를 들어 고객 지원 에이전트를 만든다면, “친절하고 전문적인 톤을 사용할 것”, “답을 모를 경우 추측하지 말고, 명확히 묻거나 후속 조치를 제안할 것”과 같은 가이드라인을 포함할 수 있습니다. 이런 규칙들은 보통 시스템 프롬프트에 포함되며, AI의 출력이 기대치에 맞도록 유지해 줍니다. 이는 AI 행동에 대한 스펙 항목이라고 볼 수 있습니다. 긴 세션에서는 스타일이 흐트러질 수 있으므로(LLM은 시간이 지나면 톤이 변하기도 합니다), 필요할 때 다시 상기시켜 주세요.

당신은 여전히 루프 안의 의사결정자입니다

스펙은 에이전트에게 권한을 부여하지만, 최종 품질 필터는 여전히 여러분입니다. 에이전트가 기술적으로는 스펙을 충족했지만 뭔가 어색하게 느껴진다면, 여러분의 판단을 믿으세요. 스펙을 다듬거나 결과물을 직접 조정하면 됩니다. AI 에이전트의 장점은 감정이 없다는 것입니다. 결과가 마음에 들지 않으면 “이건 내가 의도한 게 아니에요. 스펙을 명확히 하고 다시 해봅시다.”라고 말하면 됩니다. 스펙은 AI와의 협업 과정에서 계속 진화하는 산출물이지, 한 번 쓰고 끝나는 계약서가 아닙니다.

Simon Willison은 AI 에이전트와 함께 일하는 것을 “아주 이상한 형태의 관리”라고 농담 섞어 표현했고, “코딩 에이전트에게서 좋은 결과를 끌어내는 것이 인간 인턴을 관리하는 것과 불편할 정도로 비슷하다”고 말하기도 했습니다. 명확한 지시를 제공하고(스펙), 필요한 컨텍스트를 주며(스펙과 관련 데이터), 실행 중에 실행 가능한 피드백을 주어야 합니다. 스펙이 무대를 설정하지만, 실행 중의 모니터링과 피드백이 핵심입니다. AI가 “기회만 주면 반드시 부정행위를 할 이상한 디지털 인턴”이라면, 여러분이 작성한 스펙과 제약 조건이 바로 그 부정행위를 막고 작업에 집중하게 만드는 장치입니다.

결과적으로 얻는 이점은 이것입니다

좋은 스펙은 AI에게 무엇을 만들지 지시할 뿐만 아니라, 스스로 수정하고 안전한 경계 안에 머물도록 돕습니다. 검증 단계, 제약 조건, 그리고 여러분이 쌓아온 지식을 스펙에 녹여 넣으면, 에이전트의 결과물이 첫 시도부터 정확할 가능성(혹은 최소한 훨씬 정확할 가능성)이 크게 높아집니다. 이는 반복 횟수를 줄이고, “도대체 왜 이런 걸 만든 거지?”라는 순간을 현저히 줄여 줍니다.

5. 스펙을 테스트하고, 반복 개선하며, 진화시키기 (그리고 올바른 도구 사용하기)

스펙 작성과 에이전트 구축은 반복적인 루프라고 생각하시면 됩니다. 즉, 초기에 테스트하고, 피드백을 수집하며, 스펙을 개선하고, 이를 자동화해 줄 도구를 활용하는 과정입니다.

초기 스펙은 끝이 아니라 사이클의 시작입니다. 가장 좋은 결과는 에이전트의 작업을 스펙에 지속적으로 대조해 검증하고, 필요할 때마다 스펙을 조정할 때 나옵니다. 또한 현대적인 AI 개발자들은 CI 파이프라인부터 컨텍스트 관리 도구까지, 다양한 도구를 활용해 이 과정을 지원합니다.

지속적인 테스트

에이전트가 스펙을 충족했는지 마지막까지 기다리지 마세요. 각 주요 마일스톤, 혹은 함수 하나를 완성할 때마다 테스트를 실행하거나 최소한 빠른 수동 점검 하세요. 문제가 발견되면, 그대로 진행하지 말고 즉시 스펙이나 프롬프트를 수정해야 합니다. 예를 들어 스펙에 “비밀번호는 반드시 bcrypt로 해시해야 한다”라고 되어 있는데, 에이전트가 평문으로 저장하고 있다면, 즉시 중단하고 해당 규칙을 다시 강조해야 합니다. 여기서 자동화된 테스트의 가치가 드러납니다. 테스트를 제공했거나 작성해 두었다면, 에이전트가 직접 실행하도록 하세요. 많은 코딩 에이전트 환경에서는 작업 완료 후 npm test 같은 명령을 실행하게 할 수 있습니다. 테스트 실패 결과는 다음 프롬프트로 다시 전달되어 “X, Y, Z에서 스펙을 충족하지 못했다. 수정하라”는 신호가 됩니다. 이러한 에이전틱 루프(코드 → 테스트 → 수정 → 반복)는 매우 강력하며, Claude Code나 Copilot Labs 같은 도구들이 점점 더 큰 작업을 처리할 수 있게 진화하는 방식이기도 합니다. 항상 “완료”의 기준을 테스트나 명확한 기준으로 정의하고, 실제로 충족됐는지 확인하세요.

스펙 자체를 반복 개선하기

에이전트가 무언가를 오해했거나, 요구사항을 빠뜨렸다는 사실을 깨달았다면, 스펙 문서 자체를 수정하세요. 그리고 반드시 에이전트에게 이를 명시적으로 다시 동기화해야 합니다. (예: “스펙을 다음과 같이 업데이트했습니다. 업데이트된 스펙을 기준으로 계획을 수정하거나 코드를 리팩터링하세요.”) 이렇게 하면 스펙이 단일 진실의 원천(single source of truth) 으로 유지됩니다. 일반적인 개발에서 요구사항 변경을 다루는 방식과 동일하지만, 여기서는 여러분이 AI 에이전트의 프로덕트 매니저 역할까지 수행하는 셈입니다. 가능하다면 변경 이력을 남기세요(커밋 메시지나 간단한 메모만으로도 충분합니다). 무엇이, 왜 바뀌었는지를 알 수 있어야 합니다.

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

AI 에이전트의 컨텍스트와 지식을 관리하기 위한 도구 생태계는 빠르게 성장하고 있습니다. 대표적인 패턴이 RAG(Retrieval-Augmented Generation) 입니다. 이는 에이전트가 필요할 때 벡터 데이터베이스 같은 지식 저장소에서 관련 정보를 가져오는 방식입니다. 스펙이 매우 크다면, 전체를 항상 제공하는 대신, 섹션별로 임베딩해 두고 필요한 부분만 검색해 쓰도록 할 수 있습니다. 또한 MCP(Model Context Protocol) 를 구현한 프레임워크들도 있는데, 이는 현재 작업에 맞는 컨텍스트를 자동으로 모델에 공급해 줍니다. 예시로 Context7(context7.com)은 작업 중인 주제에 따라 관련 컨텍스트 조각을 자동으로 가져옵니다. 실제로는 에이전트가 “결제 처리” 작업을 감지하고, 스펙이나 문서의 “결제” 섹션을 프롬프트에 포함시키는 식입니다. 완전한 도구를 쓰지 않더라도, 스펙 문서 내 검색 같은 간단한 방식으로도 비슷한 효과를 낼 수 있습니다.

병렬화는 신중하게

여러 에이전트를 병렬로 실행하는 개발자들도 있습니다. 예를 들어 한 에이전트는 코드를 작성하고, 다른 에이전트는 동시에 테스트를 작성하는 방식입니다. 잘만 하면 개발 속도가 크게 빨라집니다. 다만 작업이 정말로 독립적이거나 명확히 분리되어 있어야 합니다. 스펙에는 의존성을 분명히 명시해야 합니다. 예를 들어 두 에이전트가 동시에 같은 파일을 수정하게 해서는 안 됩니다. 일반적인 패턴은 한 에이전트가 코드를 작성하고, 다른 에이전트가 병렬로 리뷰를 수행하거나, 서로 다른 컴포넌트를 만든 뒤 나중에 통합하는 방식입니다. 이는 고급 활용법이며, 관리 난이도가 높습니다. Willison도 여러 에이전트를 동시에 운영하는 것이 “놀라울 정도로 효과적이지만 정신적으로 매우 피곤하다”고 말했습니다. 관리 가능한 수준을 유지하려면 2~3개 정도로 시작하는 것이 좋습니다.

버전 관리와 스펙 잠금

버전 관리와 스펙 잠금: Git 또는 그에 상응하는 버전 관리 시스템을 반드시 활용하세요. AI 보조 작업 환경에서는 좋은 버전 관리 습관이 더욱 중요합니다. 스펙 파일 자체를 저장소에 커밋하고, 변경 이력을 유지하세요. 이렇게 하면 히스토리를 보존할 수 있을 뿐만 아니라, 에이전트가 git diff나 git blame 등을 통해 스펙의 변화를 추적하거나, 왜 특정 내용이 추가되었는지 파악할 수 있습니다. 예를 들어, 대형 LLM들은 diff를 읽고 사유를 파악하는 데 매우 능숙합니다. 일부 고급 환경에서는 에이전트가 VCS 히스토리 자체에 질문을 던져서, “이 사양이 언제, 왜 추가되었지?”를 직접 답할 수 있습니다. 의외로 최신 모델들은 git 사용에 꽤 능숙합니다. 스펙을 레포에 두면, 여러분과 AI 모두가 같은 소스에서 발전 과정을 추적할 수 있습니다. 앞서 언급한 GitHub Spec Kit처럼, 스펙 기반 개발을 git workflow에 통합하는 도구도 있습니다. 예를 들어 스펙이 누락된 머지를 막거나, 스펙 항목으로 체크리스트를 자동 생성하는 기능 등입니다. 물론 이런 도구가 반드시 필요한 것은 아니지만, 요점은 스펙을 코드처럼 신중히 관리해야 한다는 것입니다.

비용과 속도 고려

대형 모델과 긴 컨텍스트는 느리고 비용이 많이 듭니다. 따라서 모델 선택과 배치 전략을 현명하게 가져가야 합니다. 초기 초안이나 반복 작업에는 저렴하고 빠른 모델을 쓰고, 최종 결과나 복잡한 추론이 필요한 단계에서만 고성능 모델을 쓰는 것이 좋습니다. 일부 개발자들은 GPT-4나 Claude를 계획 수립이나 핵심 단계에 사용하고, 단순한 리팩터링이나 확장 작업은 로컬 모델이나 소형 API 모델로 처리합니다. 여러 에이전트를 쓴다면, 테스트 실행용이나 린트 전용 에이전트는 굳이 최상급 모델일 필요가 없습니다. 또한 컨텍스트 크기도 필요 이상으로 키우지 마세요. 5천 토큰으로 충분하다면 2만 토큰을 입력하지 마세요. 토큰이 많을수록 항상 좋은 것은 아닙니다.

모든 것을 모니터링하고 로그로 남기기

복잡한 에이전트 워크플로우에서는 에이전트의 행동과 출력 로그를 남기는 것이 필수입니다. 로그를 보면 에이전트가 어디서 벗어났는지, 어떤 오류를 겪었는지 알 수 있습니다. 많은 프레임워크가 트레이스 로그를 제공하거나, 단계별 사고 과정을 출력하도록 설정할 수 있습니다. 이런 로그를 검토하다 보면, 스펙이나 지시가 어디서 모호했는지도 드러납니다. 이는 프로그램 디버깅과 매우 비슷합니다. 다만 여기서 “프로그램”은 코드가 아니라 프롬프트 체인입니다. 이상한 일이 발생하면 스펙/지침으로 돌아가 모호한 부분이 있었는지 확인하세요.

배우고 개선하기

마지막으로, 각 프로젝트를 스펙 작성 능력을 개선하는 학습 기회로 삼으세요. 특정 표현이 계속 AI를 헷갈리게 만든다든지, 스펙 구조를 이렇게 짜면 더 잘 따르는 것 같다는 패턴이 보일 것입니다. 이런 교훈을 다음 스펙에 반영하세요. AI 에이전트 분야는 빠르게 진화하고 있으므로, Simon Willison, Andrej Karpathy 같은 사람들의 블로그를 통해 최신 사례를 따라가고, 실험을 두려워하지 마세요.

AI 에이전트를 위한 스펙은 “한 번 쓰고 끝”이 아닙니다. 지시 → 검증 → 개선의 지속적인 사이클입니다. 이 과정을 성실히 유지하면, 나중에 값비싼 재작업이나 실패를 피할 수 있습니다. 한 AI 엔지니어의 말처럼, 이는 “인턴 군단을 거느리는 것”과 비슷하지만, 잘 관리해야만 성과가 납니다. 지속적으로 관리되는 좋은 스펙이 바로 그 관리 도구입니다.

흔히 저지르는 실수 피하기

마무리하기 전에, 스펙 기반 워크플로우를 망치는 안티패턴들을 짚고 가는 것이 중요합니다. 2,500개 이상의 에이전트 파일을 분석한 GitHub 연구에 따르면, 가장 큰 실패 원인은 분명했습니다. “대부분의 에이전트 파일은 너무 모호해서 실패한다.” 피해야 할 실수는 다음과 같습니다.

모호한 프롬프트

“뭔가 멋진 걸 만들어줘”, “더 잘 작동하게 해 줘” 같은 요청은 에이전트가 붙잡을 기준이 없습니다. Baptiste Studer의 말처럼, “모호한 프롬프트는 잘못된 결과를 낳습니다.” 입력, 출력, 제약 조건을 명확히 하세요. “당신은 유용한 코딩 어시스턴트입니다”는 아무 의미가 없습니다. “당신은 리액트 컴포넌트를 위한 테스트를 작성하며, 이 예시들을 따르고, 소스 코드는 절대 수정하지 않는 테스트 엔지니어입니다”처럼 구체적이어야 합니다.

요약 없는 과도한 컨텍스트

문서 50페이지를 그대로 던져주고 모델이 알아서 하길 기대하는 것은 거의 실패합니다. 계층적 요약이나 RAG를 사용해 관련된 것만 제공하세요. 컨텍스트 길이는 품질을 대체하지 못합니다.

사람의 리뷰 생략

Willison의 개인 규칙은 이렇습니다. “나는 다른 사람에게 설명할 수 없는 코드는 커밋하지 않는다.” 테스트를 통과했다고 해서 코드가 안전하거나 유지보수 가능하다는 보장은 없습니다. 핵심 로직은 반드시 직접 리뷰하세요. AI 코드에는 ‘카드로 쌓은 집’ 같은 취약성이 숨어 있을 수 있습니다. AI가 생성한 코드는 견고해 보일 수 있지만, 테스트하지 않은 경계 사례에서 무너질 수 있습니다.

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

AI로 빠르게 프로토타이핑하는 “바이브 코딩”은 탐색 단계에서는 훌륭합니다. 하지만 엄격한 스펙, 테스트, 리뷰 없이 이를 바로 프로덕션에 올리는 것은 위험합니다. “AI 보조 엔지니어링”은 이 가이드에서 설명한 규율을 요구합니다. 지금 어느 모드에 있는지 스스로 인식해야 합니다.

‘치명적인 삼위일체’ 무시

Willison은 AI 에이전트를 위험하게 만드는 세 가지를 경고합니다. 속도(검토보다 빠름), 비결정성(같은 입력, 다른 출력), 비용(검증을 건너뛰게 부추김). 스펙과 리뷰 프로세스는 이 세 가지를 모두 고려해야 합니다. 속도가 검증 능력을 앞서게 두지 마세요.

여섯 가지 핵심 영역 누락

스펙에 명령, 테스트, 프로젝트 구조, 코드 스타일, Git 워크플로우, 경계 규칙이 포함되어 있지 않다면, 에이전트가 필요로 하는 무언가가 빠져 있을 가능성이 큽니다. 2번 섹션의 여섯 영역 체크리스트를 최종 점검용으로 활용하세요.

결론

AI 코딩 에이전트를 위한 효과적인 스펙 작성은 탄탄한 소프트웨어 엔지니어링 원칙에 LLM의 특성을 고려한 적응이 결합된 작업입니다. 명확한 목적에서 시작하고, 세부 계획은 AI가 확장하도록 하세요. 여섯 가지 핵심 영역을 포함한 진지한 설계 문서 형태로 스펙을 구조화하고, 이를 툴체인에 통합해 단순한 글이 아닌 실행 가능한 산출물로 만드세요. 한 번에 하나의 문제에만 집중하도록 컨텍스트를 관리하고, 3단계(항상 / 먼저 묻기 / 절대 안 됨) 경계, 자체 검증, 적합성 테스트를 통해 실패하지 않는 방법을 AI에게 가르치세요. 그리고 이 모든 과정을 반복적이고 진화하는 사이클로 다루세요. 테스트와 피드백을 활용해 스펙과 TODO를 지속적으로 개선하세요.

이 가이드라인을 따르면, AI 에이전트가 큰 컨텍스트에서 무너지거나 엉뚱한 방향으로 흘러갈 가능성은 크게 줄어들 것입니다.

행복한 스펙 작성 되세요!

이 글은 Gemini를 사용해 포맷되었으며, 이미지는 Nano Banana Pro로 생성되었습니다.

O’Reilly와 함께 새로운 AI 보조 엔지니어링 도서를 출간하게 되어 매우 기쁩니다. 관심 있으시다면 도서 사이트에서 무료로 제공되는 여러 팁들도 확인하실 수 있습니다.

🚀 한국어로 된 프런트엔드 아티클을 빠르게 받아보고 싶다면 Korean FE Article(https://kofearticle.substack.com/)을 구독해주세요!