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

핵심 요약: 구조, 스타일, 테스트, 경계 등 꼭 필요한 수준의 뉘앙스만 담아 명확한 스펙을 작성하세요. AI를 압도하지 않으면서도 충분한 가이드를 제공하는 것이 목표입니다. 하나의 거대한 프롬프트에 모든 것을 담기보다 큰 작업을 작은 단위로 나누세요. 먼저 읽기 전용 모드에서 계획을 세운 뒤, 실행하고 지속적으로 반복 개선하세요.

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

많은 개발자가 이런 좌절감을 공유합니다. 방대한 스펙을 AI 에이전트에 통째로 던져주는 방식은 효과가 없습니다. 컨텍스트 윈도우 한계와 모델의 "주의력 예산"이 걸림돌이 되기 때문입니다. 핵심은 똑똑한 스펙을 작성하는 것입니다. 에이전트에게 명확한 방향을 제시하고, 실용적인 컨텍스트 크기 안에 머물면서, 프로젝트와 함께 진화하는 문서를 만들어야 합니다. 이 가이드는 Claude Code, Gemini CLI 등 코딩 에이전트를 직접 사용하며 축적한 베스트 프랙티스를 정리하여, AI 에이전트를 집중적이고 생산적으로 유지하는 스펙 작성 프레임워크로 구성했습니다.

AI 에이전트 스펙 작성의 5가지 원칙을 다루며, 각 원칙은 굵은 글씨 요약으로 시작합니다.

1. 상위 수준의 비전으로 시작하고, 세부 사항은 AI에게 맡기기

프로젝트를 간결한 상위 수준 스펙으로 시작한 뒤, AI가 이를 상세한 계획으로 확장하도록 하세요.

처음부터 과도하게 설계하지 말고, 명확한 목표 선언과 몇 가지 핵심 요구사항으로 시작하세요. 이를 "프로덕트 브리프"로 취급하고, 에이전트가 여기서 더 정교한 스펙을 생성하도록 합니다. 이렇게 하면 AI의 확장 능력을 활용하면서도 방향성은 직접 통제할 수 있습니다. 단, 처음부터 반드시 충족해야 할 매우 구체적인 기술 요구사항이 이미 있다면 이 방식이 적합하지 않을 수 있습니다.

왜 효과적인가: LLM 기반 에이전트는 확실한 상위 수준 지시가 주어지면 세부 사항을 채우는 데 뛰어나지만, 방향을 잃지 않으려면 명확한 미션이 필요합니다. 짧은 개요나 목표 설명을 제공하고 AI에게 전체 스펙(예: spec.md)을 작성하도록 요청하면, 에이전트가 지속적으로 참조할 수 있는 레퍼런스가 만들어집니다. 에이전트를 활용할 때는 사전 계획이 더욱 중요합니다. 먼저 계획을 반복 수정한 뒤, 에이전트에게 코드 작성을 맡기면 됩니다. 스펙은 여러분과 AI가 함께 만드는 첫 번째 산출물입니다.

실전 접근법: 새로운 코딩 세션을 시작할 때 "당신은 AI 소프트웨어 엔지니어입니다. [프로젝트 X]에 대해 목표, 기능, 제약 조건, 단계별 계획을 포함한 상세 스펙을 작성하세요."라고 프롬프트를 입력합니다. 초기 프롬프트는 상위 수준으로 유지하세요. 예를 들어 "사용자가 할 일을 추적할 수 있는 웹 앱을 만들어줘. 사용자 계정, 데이터베이스, 간단한 UI 포함"과 같이 작성합니다. 에이전트는 개요, 기능 목록, 기술 스택 제안, 데이터 모델 등 구조화된 스펙 초안을 작성합니다. 이 스펙이 여러분과 에이전트 모두가 다시 참조할 수 있는 "단일 진실 공급원(source of truth)"이 됩니다. GitHub AI 팀은 스펙 주도 개발(spec-driven development)을 권장하며, "스펙이 공유된 진실 공급원이 되어… 프로젝트와 함께 진화하는 살아 있는 실행 가능한 산출물"이 된다고 설명합니다. 코드를 작성하기 전에 AI가 만든 스펙을 반드시 검토하고 다듬으세요. 비전에 부합하는지 확인하고, 환각(hallucination)이나 잘못된 세부 사항을 수정합니다.

Plan Mode로 계획 우선 방식 적용하기: Claude Code 같은 도구에는 에이전트를 읽기 전용 작업으로 제한하는 Plan Mode가 있습니다. 에이전트가 코드베이스를 분석하고 상세 계획을 수립할 수 있지만, 준비가 될 때까지 코드를 작성하지 않습니다. 계획 단계에 이상적인 기능입니다. Claude Code에서 Shift+Tab으로 Plan Mode를 시작하고, 만들고자 하는 것을 설명한 뒤, 에이전트가 기존 코드를 탐색하며 스펙 초안을 작성하도록 합니다. 에이전트에게 계획에 대한 질문을 통해 모호한 부분을 명확히 하도록 요청하세요. 아키텍처, 베스트 프랙티스, 보안 리스크, 테스트 전략을 검토하도록 합니다. 목표는 오해의 여지가 없을 때까지 계획을 다듬는 것입니다. 그때서야 Plan Mode를 종료하고 에이전트가 실행하도록 합니다. 이 워크플로는 스펙이 탄탄해지기 전에 코드 생성에 바로 뛰어드는 흔한 실수를 방지합니다.

스펙을 컨텍스트로 활용하기: 승인된 스펙을 저장하고(예: SPEC.md), 필요에 따라 관련 섹션을 에이전트에 제공하세요. 강력한 모델을 사용하는 많은 개발자가 정확히 이 방식을 따릅니다. 스펙 파일이 세션 간에 유지되어, 프로젝트 작업을 재개할 때마다 AI의 기준점이 됩니다. 대화 이력이 너무 길어지거나 에이전트를 재시작해야 할 때 발생하는 망각 문제를 완화할 수 있습니다. 팀에서 PRD(제품 요구사항 문서)를 사용하는 것과 비슷합니다. 사람이든 AI든 누구나 참조하여 방향을 유지할 수 있는 레퍼런스인 셈입니다. 경험 많은 엔지니어들은 "먼저 좋은 문서를 작성하면 모델이 그 입력만으로 구현을 완성할 수도 있다"고 말합니다. 스펙이 바로 그 문서입니다.

목표 중심으로 유지하기: AI 에이전트를 위한 상위 수준 스펙은 "무엇을(what)"과 "왜(why)"에 초점을 맞추되, "어떻게(how)"의 세부 사항은 (적어도 초기에는) 최소화해야 합니다. 사용자 스토리와 인수 기준(acceptance criteria)처럼 생각하세요. 사용자는 누구인가? 무엇이 필요한가? 성공이란 어떤 모습인가? (예: "사용자가 할 일을 추가, 수정, 완료할 수 있어야 하고, 데이터는 영구 저장되며, 앱은 반응형이고 안전해야 한다"). 이렇게 하면 AI의 상세 스펙이 기술적 할 일 목록이 아닌, 사용자 니즈와 결과에 기반하게 됩니다. GitHub Spec Kit 문서에서도 무엇을 만드는지와 왜 만드는지에 대한 상위 수준 설명을 제공하고, 코딩 에이전트가 사용자 경험과 성공 기준에 초점을 맞춘 상세 스펙을 생성하도록 하라고 안내합니다. 이 큰 그림의 비전으로 시작하면, 에이전트가 나중에 코딩에 들어갔을 때 나무만 보고 숲을 놓치는 일을 방지할 수 있습니다.

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

AI 스펙을 산발적인 메모가 아닌, 명확한 섹션이 있는 구조화된 문서(PRD)로 작성하세요.

많은 개발자가 에이전트용 스펙을 기존의 PRD(제품 요구사항 문서)나 시스템 설계 문서처럼 다룹니다. 포괄적이고 체계적이며, "문자 그대로 해석하는" AI가 파싱하기 쉬운 형태로 말입니다. 이 형식적 접근법은 에이전트에게 따를 청사진을 제공하고 모호함을 줄입니다.

6가지 핵심 영역: GitHub이 2,500개 이상의 에이전트 설정 파일을 분석한 결과, 명확한 패턴이 드러났습니다. 가장 효과적인 스펙은 6가지 영역을 다룹니다. 완전성을 위한 체크리스트로 활용하세요:

1. 명령어(Commands): 실행 가능한 명령어를 앞쪽에 배치하세요. 도구 이름만이 아니라 플래그가 포함된 전체 명령어를 적습니다: npm test, pytest -v, npm run build. 에이전트가 이를 수시로 참조하게 됩니다.

2. 테스트: 테스트 실행 방법, 사용하는 프레임워크, 테스트 파일 위치, 커버리지 기대치를 명시합니다.

3. 프로젝트 구조: 소스 코드 위치, 테스트 위치, 문서 위치를 명시합니다. 구체적으로 적으세요: "src/에 애플리케이션 코드, tests/에 유닛 테스트, docs/에 문서."

4. 코드 스타일: 스타일을 설명하는 세 문단보다 실제 코드 스니펫 하나가 더 효과적입니다. 네이밍 컨벤션, 포맷팅 규칙, 좋은 출력 예시를 포함하세요.

5. Git 워크플로: 브랜치 네이밍, 커밋 메시지 형식, PR 요구사항을 명시합니다. 에이전트는 명확히 적어두면 이를 따를 수 있습니다.

6. 경계: 에이전트가 절대 건드리면 안 되는 것—시크릿, vendor 디렉터리, 프로덕션 설정, 특정 폴더. "시크릿을 절대 커밋하지 말 것"은 GitHub 연구에서 가장 자주 등장한 유용한 제약 조건이었습니다.

스택을 구체적으로 명시하기: "React 프로젝트"가 아니라 "React 18 + TypeScript, Vite, Tailwind CSS"라고 쓰세요. 버전과 주요 디펜던시를 포함합니다. 모호한 스펙은 모호한 코드를 낳습니다.

일관된 형식 사용하기: 명확성이 최우선입니다. 많은 개발자가 스펙의 섹션을 구분하기 위해 마크다운 제목이나 XML 유사 태그를 사용합니다. AI 모델이 자유로운 산문보다 잘 구조화된 텍스트를 더 잘 처리하기 때문입니다. 예를 들어 스펙을 다음과 같이 구성할 수 있습니다:

# Project Spec: My team's tasks app

## Objective
- Build a web app for small teams to manage tasks...

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

## Commands
- Build: `npm run build` (compiles TypeScript, outputs to dist/)
- Test: `npm test` (runs Jest, must pass before commits)
- Lint: `npm run lint --fix` (auto-fixes ESLint errors)

## Project Structure
- `src/` – Application source code
- `tests/` – Unit and integration tests
- `docs/` – Documentation

## Boundaries
- ✅ Always: Run tests before commits, follow naming conventions
- ⚠️ Ask first: Database schema changes, adding dependencies
- 🚫 Never: Commit secrets, edit node_modules/, modify CI config

이런 수준의 구조화는 여러분의 사고를 정리할 뿐만 아니라, AI가 필요한 정보를 찾는 데도 도움이 됩니다. Anthropic 엔지니어들도 정확히 이런 이유로 프롬프트를 명확한 섹션(, , , 등)으로 구성하라고 권장합니다. 모델이 어떤 정보가 무엇인지 식별하는 강력한 단서를 얻기 때문입니다. 그리고 "최소한이라고 해서 반드시 짧은 것은 아닙니다." 중요한 내용이라면 스펙에 세부 사항을 담는 것을 주저하지 마세요. 다만 초점은 유지해야 합니다.

스펙을 툴체인에 통합하기: 스펙을 버전 관리와 CI/CD에 연결된 "실행 가능한 산출물"로 취급하세요. GitHub Spec Kit은 스펙을 엔지니어링 프로세스의 중심에 놓는 4단계 게이트 워크플로를 사용합니다. 스펙을 작성한 뒤 치워두는 대신, 스펙이 구현, 체크리스트, 작업 분해를 주도합니다. 여러분의 주된 역할은 방향을 잡는 것이고, 코딩 에이전트가 대부분의 작성을 수행합니다. 각 단계에는 고유한 역할이 있으며, 현재 작업이 완전히 검증되기 전까지 다음 단계로 넘어가지 않습니다:

1. 명세(Specify): 무엇을 만들고 왜 만드는지에 대한 상위 수준 설명을 제공하면, 코딩 에이전트가 상세 스펙을 생성합니다. 기술 스택이나 앱 설계가 아니라, 사용자 여정, 경험, 성공의 모습에 초점을 맞춥니다. 누가 사용할 것인가? 어떤 문제를 해결하는가? 어떻게 상호작용할 것인가? 만들고자 하는 사용자 경험을 그리고, 코딩 에이전트가 세부 사항을 채우도록 한다고 생각하세요. 이 산출물은 새로운 것을 알게 될 때마다 함께 진화하는 살아 있는 문서입니다.

2. 계획(Plan): 이제 기술적 세부 사항을 다룹니다. 원하는 스택, 아키텍처, 제약 조건을 제공하면 코딩 에이전트가 포괄적인 기술 계획을 생성합니다. 회사에서 특정 기술을 표준으로 사용한다면 여기서 명시합니다. 레거시 시스템과의 통합이나 컴플라이언스 요구사항이 있다면 모두 이 단계에 포함합니다. 접근 방식을 비교하기 위해 여러 계획 변형을 요청할 수도 있습니다. 내부 문서를 제공하면 에이전트가 여러분의 아키텍처 패턴을 계획에 직접 통합할 수 있습니다.

3. 작업 분해(Tasks): 코딩 에이전트가 스펙과 계획을 실제 작업으로 분해합니다. 작고, 리뷰 가능하며, 각각 퍼즐의 특정 조각을 해결하는 단위입니다. 각 작업은 독립적으로 구현하고 테스트할 수 있어야 하며, AI 에이전트를 위한 TDD(테스트 주도 개발)와 비슷합니다. "인증 구현"이 아니라 "이메일 형식을 검증하는 사용자 등록 엔드포인트 생성"처럼 구체적인 작업이 나와야 합니다.

4. 구현(Implement): 코딩 에이전트가 작업을 하나씩(또는 병렬로) 처리합니다. 수천 줄의 코드 덤프를 리뷰하는 대신, 특정 문제를 해결하는 집중된 변경 사항을 리뷰합니다. 에이전트는 무엇을 만들어야 하는지(스펙), 어떻게 만들어야 하는지(계획), 무엇을 작업해야 하는지(작업)를 알고 있습니다. 중요한 것은 각 단계에서 여러분이 검증하는 것입니다: 스펙이 원하는 바를 담고 있는가? 계획이 제약 조건을 반영했는가? AI가 놓친 엣지 케이스는 없는가? 이 프로세스에는 비평하고, 빈틈을 찾고, 진행 전에 방향을 수정할 수 있는 체크포인트가 내장되어 있습니다.

이 게이트 워크플로는 Willison이 "카드로 쌓은 집(house of cards) 코드"라고 부르는 것—꼼꼼히 들여다보면 무너지는 취약한 AI 출력—을 방지합니다. Anthropic의 Skills 시스템도 유사한 패턴을 제공하여, 에이전트가 호출하는 재사용 가능한 마크다운 기반 동작을 정의할 수 있습니다. 스펙을 이러한 워크플로에 내장하면, 스펙이 검증되기 전까지 에이전트가 진행할 수 없고, 변경 사항이 작업 분해와 테스트에 자동으로 전파됩니다.

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

에이전트 경험(AX) 설계하기: 개발자 경험(DX)을 고려해 API를 설계하듯, "에이전트 경험"을 고려해 스펙을 설계하세요. 깔끔하고 파싱 가능한 형식을 의미합니다: 에이전트가 사용할 API의 OpenAPI 스키마, LLM 소비용 문서를 요약한 llms.txt 파일, 명시적 타입 정의 등. AAIF(Agentic AI Foundation)는 도구 통합을 위한 MCP(Model Context Protocol) 같은 프로토콜을 표준화하고 있으며, 이런 패턴을 따르는 스펙은 에이전트가 소비하고 안정적으로 동작하기 훨씬 수월합니다.

PRD vs SRS 관점: 기존의 문서 작성 관행을 차용하면 도움이 됩니다. AI 에이전트 스펙에서는 (위에서 설명한 것처럼) 두 가지를 하나의 문서에 통합하는 경우가 많지만, 양쪽을 모두 다루면 효과적입니다. PRD처럼 작성하면 사용자 중심 맥락("각 기능의 이유")을 포함하여 AI가 잘못된 것을 최적화하는 것을 방지합니다. SRS처럼 확장하면 AI가 올바른 코드를 생성하는 데 필요한 구체적인 사항(어떤 데이터베이스나 API를 사용할지 등)을 확정할 수 있습니다. 이 사전 노력이 나중에 에이전트와의 커뮤니케이션 오류를 크게 줄인다는 것을 많은 개발자가 경험으로 확인했습니다.

스펙을 "살아 있는 문서"로 유지하기: 한 번 쓰고 잊지 마세요. 여러분과 에이전트가 결정을 내리거나 새로운 정보를 발견할 때마다 스펙을 업데이트합니다. AI가 데이터 모델을 변경해야 했거나 기능을 제외하기로 결정했다면, 스펙에 반영하여 항상 최신 진실 공급원으로 유지하세요. 버전 관리되는 문서라고 생각하면 됩니다. 스펙 주도 워크플로에서는 스펙이 구현, 테스트, 작업 분해를 주도하며, 스펙이 검증되기 전까지 코딩으로 넘어가지 않습니다. 이 습관은 프로젝트의 일관성을 유지합니다. 특히 여러분이나 에이전트가 작업을 중단했다가 나중에 돌아올 때 중요합니다. 스펙은 AI만을 위한 것이 아닙니다. 개발자인 여러분이 감독을 유지하고, AI의 작업이 실제 요구사항을 충족하는지 확인하는 데에도 도움이 됩니다.

3. 하나의 거대한 프롬프트 대신, 모듈화된 프롬프트와 컨텍스트로 작업 분할하기

분할 정복: 모든 것을 한꺼번에 담은 단일 프롬프트 대신, 한 번에 하나의 집중된 작업을 AI에게 맡기세요.

경험 많은 AI 엔지니어들은 프로젝트 전체(모든 요구사항, 모든 코드, 모든 지시 사항)를 하나의 프롬프트나 에이전트 메시지에 몰아넣는 것이 혼란의 지름길이라는 것을 체험으로 알게 되었습니다. 토큰 한계에 도달할 위험뿐 아니라, "지시의 저주(curse of instructions)"로 인해 모델이 집중력을 잃을 위험도 있습니다. 너무 많은 지시 사항이 주어지면 어느 것도 제대로 따르지 못하는 현상입니다. 해결책은 스펙과 워크플로를 모듈 방식으로 설계하여, 한 번에 하나의 조각을 처리하고 해당 조각에 필요한 컨텍스트만 제공하는 것입니다.

과도한 컨텍스트/지시의 저주: 많은 개발자가 경험적으로 발견한 것을 연구가 확인해 주었습니다. 프롬프트에 지시 사항이나 데이터를 추가할수록, 모델이 각 지시를 준수하는 성능이 크게 떨어집니다. 한 연구는 이를 "지시의 저주"라 명명하며, GPT-4와 Claude조차 여러 요구사항을 동시에 충족하라고 하면 어려움을 겪는다는 것을 보여주었습니다. 실무적으로 말하면, 10개의 상세한 규칙을 제시하면 AI가 처음 몇 개는 따르다가 나머지는 무시하기 시작할 수 있습니다. 더 나은 전략은 반복적 집중입니다. 업계 가이드라인에서도 복잡한 요구사항을 순차적이고 단순한 지시로 분해하는 것을 베스트 프랙티스로 권장합니다. AI를 한 번에 하나의 하위 문제에 집중시키고, 완료된 후 다음으로 넘어가세요. 이렇게 하면 품질이 높아지고 오류도 관리 가능한 수준으로 유지됩니다.

스펙을 단계 또는 컴포넌트로 분할하기: 스펙 문서가 매우 길거나 다루는 범위가 넓다면, 여러 부분으로 나누는 것을 고려하세요(물리적으로 별도 파일로 분리하거나, 명확히 구분된 섹션으로). 예를 들어 "백엔드 API 스펙" 섹션과 "프론트엔드 UI 스펙" 섹션을 따로 둘 수 있습니다. 에이전트가 백엔드 작업을 할 때 프론트엔드 스펙을 제공할 필요가 없고, 반대의 경우도 마찬가지입니다. 멀티 에이전트 설정을 사용하는 개발자들은 각 부분에 별도 에이전트나 하위 프로세스를 배정하기도 합니다. 예를 들어 한 에이전트는 데이터베이스/스키마, 다른 에이전트는 API 로직, 또 다른 에이전트는 프론트엔드를 담당하며, 각각 관련된 스펙 조각만 받습니다. 단일 에이전트를 사용하더라도, 해당 작업에 관련된 스펙 섹션만 프롬프트에 복사하면 이를 흉내 낼 수 있습니다. 컨텍스트 과부하를 피하세요: DigitalOcean AI 가이드에서 경고하듯, 인증 작업과 데이터베이스 스키마 변경을 한 번에 섞지 마세요. 각 프롬프트를 현재 목표에 맞게 단단히 범위를 좁히세요.

대규모 스펙을 위한 확장 목차 / 요약: 유용한 기법 하나는 에이전트에게 스펙의 확장 목차(Extended TOC)와 요약을 작성하도록 하는 것입니다. 이는 각 섹션을 몇 가지 핵심 포인트나 키워드로 압축하고, 세부 사항이 어디에 있는지 참조하는 "스펙 요약"입니다. 예를 들어, 전체 스펙에 500단어 분량의 "보안 요구사항" 섹션이 있다면, 에이전트에게 이를 다음과 같이 요약하도록 할 수 있습니다: "보안: HTTPS 사용, API 키 보호, 입력 검증 구현 (상세 내용은 §4.2 참조)". 계획 단계에서 이런 계층적 요약을 만들면, 프롬프트에 상주할 수 있는 조감도를 얻으면서도 세부 사항은 필요할 때만 불러올 수 있습니다. 이 확장 목차는 인덱스 역할을 합니다. 에이전트가 이를 참조하여 "여기 보안 섹션이 있으니 확인해야겠다"고 판단하고, 그때 해당 섹션을 제공할 수 있습니다. 사람 개발자가 스펙의 개요를 훑어본 뒤, 특정 부분을 작업할 때 해당 페이지를 찾아보는 것과 같은 방식입니다.

이를 구현하려면 스펙 작성 후 에이전트에게 다음과 같이 프롬프트하세요: "위 스펙을 각 섹션의 핵심 포인트와 참조 태그가 포함된 매우 간결한 개요로 요약해줘." 결과로 한두 문장 요약이 포함된 섹션 목록이 나옵니다. 이 요약을 시스템 또는 어시스턴트 메시지에 유지하면, 너무 많은 토큰을 소비하지 않으면서 에이전트의 집중을 유도할 수 있습니다. 이 계층적 요약 접근법은 LLM이 상위 수준 구조에 집중하여 장기적 컨텍스트를 유지하는 데 도움이 되는 것으로 알려져 있습니다. 에이전트가 스펙의 "인지 지도"를 갖고 다니는 셈입니다.

스펙 파트별 서브 에이전트 또는 "스킬" 활용: 또 다른 고급 접근법은 여러 전문 에이전트(Anthropic이 서브 에이전트라 부르거나 "스킬"이라 부를 수 있는 것)를 사용하는 것입니다. 각 서브 에이전트는 특정 전문 영역에 맞게 구성되며, 해당 영역에 관련된 스펙 부분만 제공받습니다. 예를 들어 데이터 모델 섹션만 아는 Database Designer 서브 에이전트와 API 엔드포인트 스펙만 아는 API Coder 서브 에이전트를 둘 수 있습니다. 메인 에이전트(또는 오케스트레이터)가 적절한 서브 에이전트에 자동으로 작업을 라우팅합니다. 장점은 각 에이전트가 더 작은 컨텍스트 윈도우와 더 집중된 역할을 갖게 되어, 정확도가 향상되고 독립적인 작업의 병렬 처리가 가능하다는 것입니다. Anthropic의 Claude Code는 자체 시스템 프롬프트와 도구를 가진 서브 에이전트 정의를 지원합니다. 문서에 따르면 "각 서브 에이전트는 특정 목적과 전문 영역을 가지며, 메인 대화와 별도의 컨텍스트 윈도우를 사용하고, 동작을 안내하는 맞춤형 시스템 프롬프트를 갖습니다." 서브 에이전트의 도메인에 맞는 작업이 발생하면 Claude가 해당 작업을 위임하고, 서브 에이전트가 독립적으로 결과를 반환합니다.

처리량을 위한 병렬 에이전트: 여러 에이전트를 동시에 실행하는 것이 개발 생산성의 "차세대 트렌드"로 부상하고 있습니다. 한 에이전트가 끝나기를 기다린 뒤 다른 작업을 시작하는 대신, 겹치지 않는 작업에 병렬 에이전트를 띄울 수 있습니다. Willison은 이를 "병렬 코딩 에이전트 수용"이라 표현하며, "놀라울 만큼 효과적이지만 정신적으로 지치는" 방식이라고 언급합니다. 핵심은 에이전트끼리 충돌하지 않도록 작업 범위를 설정하는 것입니다. 한 에이전트가 기능을 코딩하는 동안 다른 에이전트가 테스트를 작성하거나, 별도 컴포넌트를 동시에 구축하는 식입니다. LangGraph나 OpenAI Swarm 같은 오케스트레이션 프레임워크가 에이전트 간 조율을 돕고, Chroma 같은 벡터 데이터베이스를 통한 공유 메모리로 중복 프롬프팅 없이 공통 컨텍스트에 접근할 수 있습니다.

단일 에이전트 vs. 멀티 에이전트: 언제 무엇을 선택할까

실제로 서브 에이전트나 스킬별 프롬프트를 사용하는 모습은 다음과 같습니다. 여러 스펙 파일(또는 프롬프트 템플릿)—예를 들어 SPEC_backend.md, SPEC_frontend.md—을 유지하면서, AI에게 "백엔드 작업은 SPEC_backend, 프론트엔드 작업은 SPEC_frontend를 참조하라"고 지시합니다. 또는 Cursor/Claude 같은 도구에서 실제로 각 역할에 서브 에이전트를 띄웁니다. 이 방식은 단일 에이전트 루프보다 설정이 복잡하지만, 사람 개발자가 하는 것과 같습니다. 우리는 대규모 스펙을 머릿속에서 관련 조각으로 구획화합니다. 50페이지 스펙 전체를 한꺼번에 기억하지 않고, 현재 작업에 필요한 부분을 떠올리며 전체 아키텍처는 대략적으로 파악하고 있는 것입니다. 앞서 언급했듯 과제는 상호 의존성 관리입니다. 서브 에이전트들도 여전히 조율해야 합니다(프론트엔드는 백엔드 스펙에서 API 계약을 알아야 합니다). 중앙 개요(또는 "아키텍트" 에이전트)가 하위 스펙을 참조하여 일관성을 보장하면 이 문제를 완화할 수 있습니다.

각 프롬프트를 하나의 작업/섹션에 집중시키기: 복잡한 멀티 에이전트 설정 없이도 수동으로 모듈성을 강제할 수 있습니다. 예를 들어 스펙을 작성한 후 다음 단계로 "Step 1: 데이터베이스 스키마 구현"을 진행합니다. 에이전트에게 스펙의 데이터베이스 섹션만, 그리고 기술 스택 같은 글로벌 제약 조건을 함께 제공합니다. 에이전트가 이를 처리합니다. 그런 다음 Step 2로 "이제 인증 기능을 구현하라"고 하면서, 인증 섹션과 필요한 경우 관련 스키마 부분을 제공합니다. 주요 작업마다 컨텍스트를 갱신하면, 모델이 주의를 분산시킬 수 있는 오래되거나 무관한 정보를 끌고 다니지 않게 됩니다. 한 가이드에서 제안하듯 "새로 시작하세요: 주요 기능 전환 시 새 세션을 열어 컨텍스트를 초기화"하면 됩니다. 매번 스펙의 제약 조건 섹션에서 핵심 글로벌 규칙을 상기시킬 수 있지만, 전부 필요하지 않다면 스펙 전체를 밀어 넣지 마세요.

인라인 지시문과 코드 TODO 활용: 또 다른 모듈화 기법은 코드나 스펙을 대화의 능동적인 부분으로 활용하는 것입니다. 예를 들어 코드에 // TODO 주석으로 해야 할 작업을 기술하고, 에이전트가 하나씩 채우도록 합니다. 각 TODO는 작은 작업에 대한 미니 스펙 역할을 합니다. 이렇게 하면 AI의 집중도가 극대화되고("이 스펙 스니펫에 따라 이 특정 함수를 구현하라"), 긴밀한 루프로 반복 작업이 가능합니다. 전체 체크리스트를 한꺼번에 주는 대신, 체크리스트 항목 하나씩 완료하도록 하는 것과 같습니다.

핵심은 이렇습니다: 작고 집중된 컨텍스트가 하나의 거대한 프롬프트보다 낫습니다. 품질이 향상되고, 한꺼번에 너무 많은 것으로 AI가 "압도"당하는 것을 방지합니다. 베스트 프랙티스를 정리하면, 모델에 "하나의 작업 집중"과 "관련 정보만" 제공하고, 모든 곳에 모든 것을 쏟아붓지 말라는 것입니다. 작업을 모듈로 구조화하고—스펙 요약이나 하위 스펙 에이전트 같은 전략을 활용하면—컨텍스트 크기 제한과 AI의 단기 기억 한계를 효과적으로 우회할 수 있습니다. 잘 먹인 AI는 잘 설계된 함수와 같습니다: 현재 작업에 필요한 입력만 제공하세요.

4. 자체 점검, 제약 조건, 그리고 사람의 전문성 내장하기

스펙을 에이전트의 할 일 목록에 그치지 않고, 품질 관리 가이드로도 활용하세요. 그리고 여러분의 전문성을 주입하는 것을 주저하지 마세요.

좋은 AI 에이전트 스펙은 AI가 실수할 수 있는 지점을 예측하고 가드레일을 설정합니다. 또한 여러분이 아는 것(도메인 지식, 엣지 케이스, "함정")을 활용하여 AI가 진공 상태에서 작동하지 않도록 합니다. 스펙을 AI의 코치이자 심판으로 생각하세요: 올바른 접근법을 독려하고, 반칙을 짚어내야 합니다.

3단계 경계 체계 활용: GitHub의 2,500개 이상 에이전트 파일 분석에 따르면, 가장 효과적인 스펙은 단순한 금지 목록이 아니라 3단계 경계 체계를 사용합니다. 에이전트에게 진행해도 될 때, 멈춰야 할 때, 완전히 중단해야 할 때를 더 명확히 안내할 수 있습니다:

✅ 항상 수행: 에이전트가 묻지 않고 실행해야 하는 동작입니다. "커밋 전에 항상 테스트를 실행할 것." "항상 스타일 가이드의 네이밍 컨벤션을 따를 것." "항상 모니터링 서비스에 오류를 기록할 것."

⚠️ 먼저 확인: 사람의 승인이 필요한 동작입니다. "데이터베이스 스키마 변경 전에 확인 받을 것." "새 디펜던시 추가 전에 확인 받을 것." "CI/CD 설정 변경 전에 확인 받을 것." 이 단계는 괜찮을 수 있지만 사람의 확인이 필요한 고영향 변경을 포착합니다.

🚫 절대 금지: 완전 차단입니다. "시크릿이나 API 키를 절대 커밋하지 말 것." "node_modules/나 vendor/를 절대 수정하지 말 것." "명시적 승인 없이 실패하는 테스트를 절대 삭제하지 말 것." "시크릿을 절대 커밋하지 말 것"은 연구에서 가장 자주 등장한 유용한 제약 조건이었습니다.

이 3단계 접근법은 단순한 규칙 나열보다 훨씬 섬세합니다. 어떤 동작은 항상 안전하고, 어떤 것은 감독이 필요하며, 어떤 것은 절대 허용되지 않는다는 것을 인정합니다. 에이전트는 "항상" 항목은 자신 있게 진행하고, "먼저 확인" 항목은 리뷰를 위해 플래그하며, "절대 금지" 항목은 즉시 중단합니다.

자체 검증 유도하기: 강력한 패턴 하나는 에이전트가 스펙과 대조하여 자신의 결과물을 자동으로 검증하도록 하는 것입니다. 도구가 지원한다면 AI가 코드 생성 후 실행할 수 있는 유닛 테스트나 린팅 같은 검사를 통합할 수 있습니다. 하지만 스펙/프롬프트 수준에서도 AI에게 이중 검사를 지시할 수 있습니다. 예를 들어 "구현 완료 후, 결과를 스펙과 비교하고 모든 요구사항이 충족되었는지 확인하라. 미반영된 스펙 항목을 나열하라"고 지시합니다. 이렇게 하면 LLM이 스펙 대비 자신의 출력을 되돌아보게 되어 누락을 포착할 수 있습니다. 프로세스에 자체 감사를 내장하는 형태입니다.

예를 들어 프롬프트에 이렇게 추가할 수 있습니다: "(함수 작성 후, 위의 요구사항 목록을 검토하고 각각이 충족되었는지 확인하며, 누락된 것은 표시하라)." 모델이 코드를 출력한 뒤, 각 요구사항의 충족 여부를 나타내는 짧은 체크리스트를 함께 출력합니다. 테스트를 실행하기 전에 누락을 줄이는 효과가 있습니다. 완벽하지는 않지만 확실히 도움이 됩니다.

주관적 검사를 위한 LLM-as-a-Judge: 자동 테스트가 어려운 기준—코드 스타일, 가독성, 아키텍처 패턴 준수 등—에는 "LLM-as-a-Judge"를 고려해 보세요. 두 번째 에이전트(또는 별도 프롬프트)가 첫 번째 에이전트의 출력을 스펙의 품질 가이드라인과 대조하여 리뷰하는 방식입니다. Anthropic을 비롯한 여러 곳에서 주관적 평가에 효과적이라고 확인했습니다. "이 코드가 스타일 가이드를 준수하는지 리뷰하라. 위반 사항을 표시하라"고 프롬프트합니다. 리뷰 에이전트가 반환한 피드백은 반영되거나 수정 작업을 촉발합니다. 구문 검사를 넘어 의미론적 평가 레이어를 추가하는 셈입니다.

적합성 테스트(Conformance Testing): Willison은 적합성 테스트 스위트 구축을 권장합니다. 모든 구현이 반드시 통과해야 하는, 언어에 독립적인 테스트(주로 YAML 기반)입니다. 일종의 계약서 역할입니다. API를 구축한다면, 적합성 스위트가 예상 입력/출력을 명시하고 에이전트의 코드가 모든 케이스를 만족해야 합니다. 이는 임시 유닛 테스트보다 엄격한데, 스펙에서 직접 도출되며 여러 구현에 재사용할 수 있기 때문입니다. 스펙의 성공 기준 섹션에 적합성 기준을 포함하세요(예: "conformance/api-tests.yaml의 모든 케이스를 통과해야 함").

스펙에 테스트 전략 반영하기: 가능하다면 스펙과 프롬프트 흐름에 테스트 계획이나 실제 테스트를 포함하세요. 전통적 개발에서 TDD를 사용하거나 테스트 케이스를 작성해 요구사항을 명확히 하듯, AI에게도 같은 방법을 적용할 수 있습니다. 예를 들어 스펙의 성공 기준에 "이 샘플 입력은 이 출력을 생성해야 한다…" 또는 "다음 유닛 테스트가 통과해야 한다"라고 명시합니다. 에이전트에게 해당 케이스를 머릿속으로 검토하거나, 실행 기능이 있다면 실제로 실행하도록 프롬프트할 수 있습니다. Simon Willison은 탄탄한 테스트 스위트가 에이전트에게 초능력을 부여하는 것과 같다고 강조했습니다. 테스트가 실패하면 빠르게 검증하고 반복할 수 있기 때문입니다. AI 코딩 맥락에서, 스펙에 테스트용 의사 코드나 예상 결과를 조금 작성하면 에이전트의 구현을 효과적으로 유도할 수 있습니다. 추가로 서브 에이전트 설정에서 스펙의 기준을 가져와 "코드 에이전트"의 출력을 지속적으로 검증하는 전용 "테스트 에이전트"를 활용할 수도 있습니다.

도메인 지식 반영하기: 스펙에는 경험 많은 개발자나 맥락을 아는 사람만이 알 수 있는 통찰을 담아야 합니다. 예를 들어 전자상거래 에이전트를 구축하면서 "상품"과 "카테고리"가 다대다(many-to-many) 관계라는 것을 안다면, 이를 명확히 기술하세요(AI가 추론할 것이라 가정하지 마세요—추론하지 못할 수 있습니다). 특정 라이브러리가 까다롭기로 유명하다면, 피해야 할 함정을 언급하세요. 본질적으로, 스펙에 여러분의 멘토링을 쏟아넣는 것입니다. "라이브러리 X 사용 시, 버전 Y의 메모리 누수 이슈에 주의(해결 방법 Z 적용)"과 같은 조언을 담을 수 있습니다. 이런 수준의 세부 사항이 평범한 AI 출력을 진정으로 견고한 솔루션으로 바꿔줍니다. AI를 흔한 함정에서 미리 벗어나게 해주기 때문입니다.

또한 선호 사항이나 스타일 가이드라인(예: "React에서 클래스 컴포넌트 대신 함수형 컴포넌트 사용")이 있다면 스펙에 명시하세요. AI가 여러분의 스타일을 따르게 됩니다. 많은 엔지니어가 스펙에 작은 예시도 포함합니다. 예를 들어 "모든 API 응답은 JSON 형식이어야 한다. 예: 에러의 경우 {"error": "message"}." 짧은 예시 하나로 AI를 원하는 정확한 형식에 고정시킬 수 있습니다.

단순한 작업에는 미니멀하게: 꼼꼼한 스펙을 권장하지만, 언제 간결하게 갈지 아는 것도 전문성의 일부입니다. 비교적 단순하고 독립적인 작업이라면, 지나치게 상세한 스펙이 오히려 혼란을 줄 수 있습니다. 에이전트에게 간단한 작업(예: "페이지에서 div를 가운데 정렬해줘")을 요청한다면, "솔루션을 간결하게 유지하고 불필요한 마크업이나 스타일을 추가하지 말 것"이라고만 하면 충분합니다. 전체 PRD가 필요 없습니다. 반대로 복잡한 작업(예: "토큰 갱신과 에러 처리를 포함한 OAuth 플로 구현")이라면 상세한 스펙을 활용해야 합니다. 경험 법칙은 이렇습니다: 작업 복잡도에 맞춰 스펙의 상세도를 조절하세요. 어려운 문제를 과소 명세하면 에이전트가 헤매거나 궤도를 벗어나고, 사소한 문제를 과잉 명세하면 에이전트가 불필요한 지시에 얽히거나 컨텍스트를 낭비합니다.

필요 시 AI의 "페르소나" 유지하기: 때로는 스펙의 일부로 에이전트의 행동 방식이나 응답 스타일을 정의해야 합니다. 특히 에이전트가 사용자와 상호작용하는 경우 그렇습니다. 예를 들어 고객 지원 에이전트를 구축한다면, "친절하고 전문적인 어조를 사용할 것", "답을 모르면 추측하지 말고, 명확히 하기 위해 질문하거나 후속 조치를 제안할 것" 같은 가이드라인을 포함할 수 있습니다. 이런 규칙(보통 시스템 프롬프트에 포함)은 AI의 출력을 기대에 맞게 유지하는 데 도움이 됩니다. 본질적으로 AI 동작에 대한 스펙 항목입니다. 일관성을 유지하고, 긴 세션에서 필요하면 상기시키세요(LLM은 고삐를 놓으면 시간이 지나며 스타일이 "흘러갈" 수 있습니다).

여러분이 루프 안의 최종 결정자입니다: 스펙은 에이전트에게 힘을 실어주지만, 최종 품질 필터는 여러분입니다. 에이전트가 기술적으로 스펙을 충족하는 결과물을 만들었지만 뭔가 맞지 않는다면, 여러분의 판단을 믿으세요. 스펙을 수정하거나 출력을 직접 조정하면 됩니다. AI 에이전트의 좋은 점은 기분이 상하지 않는다는 것입니다. 결과물이 방향에서 벗어났다면 "사실 의도한 바가 아니야, 스펙을 명확히 하고 다시 해보자"라고 말하면 됩니다. 스펙은 AI와의 협업에서 살아 있는 산출물이지, 한 번 쓰면 바꿀 수 없는 계약이 아닙니다.

Simon Willison은 AI 에이전트와 일하는 것을 "아주 기묘한 형태의 관리"에 비유하며, 심지어 "코딩 에이전트에서 좋은 결과를 얻는 것이 사람 인턴을 관리하는 것과 불편할 정도로 비슷하다"고 말했습니다. 명확한 지시(스펙)를 제공하고, 필요한 맥락(스펙과 관련 데이터)을 갖추게 하고, 실행 가능한 피드백을 줘야 합니다. 스펙이 무대를 세우지만, 실행 중 모니터링과 피드백이 핵심입니다. AI가 "기회만 주면 분명 편법을 쓸 기묘한 디지털 인턴"이라면, 여러분이 작성하는 스펙과 제약 조건이 바로 그 편법을 방지하고 올바른 작업에 집중하게 하는 수단입니다.

좋은 스펙의 보상은 이렇습니다: AI에게 무엇을 만들라고 지시할 뿐 아니라, AI가 스스로 수정하고 안전한 경계 안에 머물도록 돕습니다. 검증 단계, 제약 조건, 그리고 여러분이 어렵게 쌓은 지식을 스펙에 녹여 넣으면, 에이전트의 출력이 첫 시도에 정확할 확률(또는 적어도 정확에 훨씬 가까울 확률)이 크게 높아집니다. 반복 횟수가 줄고, "도대체 왜 이렇게 한 거지?" 하는 순간도 줄어듭니다.

5. 테스트, 반복, 스펙 진화 (그리고 적절한 도구 활용)

스펙 작성과 에이전트 활용을 반복적 순환으로 생각하세요: 일찍 테스트하고, 피드백을 수집하고, 스펙을 다듬고, 도구로 검사를 자동화하세요.

초기 스펙은 끝이 아니라 순환의 시작입니다. 최상의 결과는 에이전트의 작업을 스펙과 지속적으로 대조 검증하고 그에 맞춰 조정할 때 나옵니다. 또한 현대의 AI 개발자들은 이 과정을 지원하기 위해 다양한 도구(CI 파이프라인부터 컨텍스트 관리 유틸리티까지)를 활용합니다.

지속적 테스트: 에이전트가 스펙을 충족했는지 마지막에 확인하지 마세요. 주요 마일스톤마다, 심지어 함수 하나가 끝날 때마다 테스트를 실행하거나 최소한 빠른 수동 검사를 수행하세요. 실패하는 것이 있으면, 다음으로 진행하기 전에 스펙이나 프롬프트를 업데이트합니다. 예를 들어 스펙에 "비밀번호는 bcrypt로 해시해야 한다"고 명시했는데 에이전트의 코드가 평문을 저장한다면—즉시 멈추고 수정하세요(그리고 스펙이나 프롬프트에 해당 규칙을 다시 상기시킵니다). 자동 테스트가 여기서 빛을 발합니다: 테스트를 제공했거나 작업 중에 작성했다면, 에이전트가 실행하도록 하세요. 많은 코딩 에이전트 환경에서 작업 완료 후 npm test 등을 실행할 수 있습니다. 결과(실패)가 다음 프롬프트에 피드백되어, 에이전트에게 "출력이 X, Y, Z에서 스펙을 충족하지 못한다—수정하라"고 알려줍니다. 이런 에이전트 루프(코딩 → 테스트 → 수정 → 반복)는 매우 강력하며, Claude Code나 Copilot Labs 같은 도구가 더 큰 작업을 처리하기 위해 진화하고 있는 방식입니다. "완료"가 무엇인지(테스트나 기준을 통해) 항상 정의하고 확인하세요.

스펙 자체를 반복하기: 스펙이 불완전하거나 모호했음을 발견하면(에이전트가 의도를 잘못 이해했거나, 누락된 요구사항을 발견했거나), 스펙 문서를 업데이트하세요. 그런 다음 에이전트에게 새 스펙을 명시적으로 동기화합니다: "스펙을 다음과 같이 업데이트했다… 업데이트된 스펙에 따라 계획을 조정하거나 코드를 리팩터링하라." 이렇게 하면 스펙이 단일 진실 공급원으로 유지됩니다. 일반적인 개발에서 변경되는 요구사항을 처리하는 것과 비슷하지만, 이 경우 여러분이 AI 에이전트의 프로덕트 매니저이기도 합니다. 가능하면 버전 이력을 유지하세요(커밋 메시지나 메모라도). 무엇이 왜 바뀌었는지 추적할 수 있습니다.

컨텍스트 관리와 메모리 도구 활용: AI 에이전트의 컨텍스트와 지식 관리를 돕는 도구 생태계가 성장하고 있습니다. 예를 들어 RAG(검색 증강 생성, Retrieval-Augmented Generation)은 에이전트가 지식 베이스(벡터 데이터베이스 등)에서 관련 데이터 조각을 실시간으로 가져오는 패턴입니다. 스펙이 방대하다면 섹션을 임베딩하고, 전체를 항상 제공하는 대신 에이전트가 필요할 때 가장 관련 있는 부분을 검색하도록 할 수 있습니다. MCP(Model Context Protocol)를 구현하는 프레임워크도 있어, 현재 작업에 따라 올바른 컨텍스트를 모델에 자동으로 제공합니다. 한 예로 Context7(context7.com)은 현재 작업 내용에 기반해 관련 컨텍스트 스니펫을 문서에서 자동으로 가져옵니다. 실제로 에이전트가 "결제 처리"를 작업 중임을 감지하면, 스펙이나 문서의 "결제" 섹션을 프롬프트에 자동으로 끌어오는 식입니다. 이런 도구를 활용하거나, 기초적인 버전(스펙 문서 내 간단한 검색 기능 등)이라도 구축하는 것을 고려해 보세요.

병렬화는 신중하게: 일부 개발자는 (앞서 서브 에이전트에서 언급했듯) 여러 에이전트 인스턴스를 서로 다른 작업에 병렬로 실행합니다. 개발 속도를 높일 수 있습니다. 예를 들어 한 에이전트가 코드를 생성하는 동안 다른 에이전트가 동시에 테스트를 작성하거나, 두 기능을 동시에 구축하는 식입니다. 이 방식을 쓸 때는 작업이 진정으로 독립적이거나 명확히 분리되어 충돌을 피할 수 있는지 확인하세요(스펙에 의존성을 명시해야 합니다). 예를 들어 두 에이전트가 동시에 같은 파일에 쓰게 하면 안 됩니다. 하나의 워크플로로는 한 에이전트가 코드를 생성하고 다른 에이전트가 병렬로 리뷰하거나, 별도 컴포넌트를 각각 만든 뒤 나중에 통합하는 방식이 있습니다. 이는 고급 활용법이며, Willison도 인정했듯 복수 에이전트를 운영하는 것은 놀라울 만큼 효과적이지만 정신적으로 지칩니다. 관리 가능한 수준을 유지하려면 최대 2~3개 에이전트로 시작하세요.

버전 관리와 스펙 잠금: Git이나 사용하는 버전 관리 시스템으로 에이전트의 작업을 추적하세요. 좋은 버전 관리 습관은 AI 지원 개발에서 더욱 중요합니다. 스펙 파일 자체를 리포지토리에 커밋하세요. 이력이 보존될 뿐만 아니라, 에이전트가 git diff나 blame을 사용해 변경 사항을 파악할 수도 있습니다(LLM은 diff를 상당히 잘 읽습니다). 일부 고급 에이전트 설정에서는 에이전트가 VCS 이력을 조회하여 무언가가 도입된 시점을 확인할 수 있습니다. 놀랍게도 모델은 "Git에 맹렬하게 능숙"합니다. 스펙을 리포지토리에 보관하면 여러분과 AI 모두 진화 과정을 추적할 수 있습니다. 앞서 언급한 GitHub Spec Kit 같은 도구는 스펙 주도 개발을 git 워크플로에 통합합니다. 예를 들어 업데이트된 스펙에 맞춰 머지를 게이트하거나, 스펙 항목에서 체크리스트를 자동 생성합니다. 이런 도구가 없어도 성공할 수 있지만, 핵심은 스펙을 코드처럼 다루고 성실하게 관리하라는 것입니다.

비용과 속도 고려: 대형 모델과 긴 컨텍스트로 작업하면 느리고 비용이 많이 들 수 있습니다. 실용적인 팁은 모델 선택과 배칭을 전략적으로 하는 것입니다. 초기 초안이나 반복 작업에는 저렴하거나 빠른 모델을 쓰고, 최종 출력이나 복잡한 추론에는 가장 강력한(비싼) 모델을 배정하세요. 일부 개발자는 계획과 핵심 단계에 GPT-4나 Claude를 쓰지만, 간단한 확장이나 리팩터링은 로컬 모델이나 소형 API 모델에 맡깁니다. 멀티 에이전트 사용 시 모두 최상위 모델일 필요는 없습니다. 테스트 실행 에이전트나 린터 에이전트는 소형 모델로 충분할 수 있습니다. 또한 컨텍스트 크기를 조절하세요: 5,000 토큰이면 충분한데 20,000 토큰을 넣지 마세요. 앞서 논의했듯 토큰이 많다고 반드시 좋은 것은 아닙니다.

모든 것을 모니터링하고 로깅하기: 복잡한 에이전트 워크플로에서는 에이전트의 행동과 출력을 로깅하는 것이 필수입니다. 로그를 확인하여 에이전트가 궤도를 벗어나거나 오류를 만나는지 살펴보세요. 많은 프레임워크가 트레이스 로그를 제공하거나, 단계별 사고(chain-of-thought)를 출력하도록 프롬프트할 수 있습니다(특히 step-by-step으로 생각하도록 지시했을 때). 이 로그를 검토하면 스펙이나 지시가 잘못 해석된 지점을 파악할 수 있습니다. 프로그램을 디버깅하는 것과 다르지 않습니다—다만 "프로그램"이 대화/프롬프트 체인이라는 점만 다릅니다. 이상한 결과가 나오면, 스펙/지시로 돌아가 모호한 부분이 없었는지 확인하세요.

학습하고 개선하기: 마지막으로, 각 프로젝트를 스펙 작성 역량을 다듬는 학습 기회로 삼으세요. 특정 표현이 일관되게 AI를 혼란스럽게 한다거나, 스펙 섹션을 특정 방식으로 구성하면 준수율이 높아진다는 것을 발견할 수 있습니다. 이런 교훈을 다음 스펙에 반영하세요. AI 에이전트 분야는 빠르게 진화하고 있어, 새로운 베스트 프랙티스(와 도구)가 끊임없이 등장합니다. Simon Willison, Andrej Karpathy 등의 블로그를 통해 최신 동향을 파악하고, 실험을 두려워하지 마세요.

AI 에이전트를 위한 스펙은 "한 번 쓰면 끝"이 아닙니다. 지시하고, 검증하고, 다듬는 지속적 순환의 일부입니다. 이 성실함의 보상은 큽니다: 문제를 일찍 포착하고 에이전트를 올바른 방향으로 유지함으로써, 나중에 발생할 비용 큰 재작업이나 장애를 피할 수 있습니다. 한 AI 엔지니어가 말했듯, 이런 실천법을 적용하면 "인턴 군단"이 일해주는 느낌이 들지만, 잘 관리해야 합니다. 지속적으로 유지되는 좋은 스펙이 바로 여러분의 관리 도구입니다.

흔한 실수 피하기

마무리하기 전에, 의도가 좋은 스펙 주도 워크플로도 탈선시킬 수 있는 안티 패턴을 짚어볼 필요가 있습니다. GitHub의 2,500개 이상 에이전트 파일 분석은 극명한 차이를 보여줍니다: "대부분의 에이전트 파일이 실패하는 이유는 너무 모호하기 때문입니다." 피해야 할 실수들은 다음과 같습니다:

모호한 프롬프트: "멋진 걸 만들어줘"나 "더 잘 작동하게 해줘"는 에이전트에게 기준점을 전혀 주지 못합니다. Baptiste Studer의 말처럼 "모호한 프롬프트는 잘못된 결과를 낳습니다." 입력, 출력, 제약 조건을 구체적으로 명시하세요. "당신은 도움이 되는 코딩 어시스턴트입니다"는 효과가 없습니다. "당신은 React 컴포넌트의 테스트를 작성하는 테스트 엔지니어입니다. 이 예시들을 따르며, 소스 코드는 절대 수정하지 않습니다"라고 해야 효과가 있습니다.

요약 없는 과도한 컨텍스트: 50페이지 분량의 문서를 프롬프트에 통째로 넣고 모델이 알아서 파악하기를 바라는 것은 대부분 실패합니다. 원칙 3에서 논의한 계층적 요약이나 RAG를 활용해 관련 내용만 노출하세요. 컨텍스트의 길이는 컨텍스트의 품질을 대체하지 못합니다.

사람의 리뷰 건너뛰기: Willison은 개인 원칙이 있습니다: "다른 사람에게 설명할 수 없는 코드는 커밋하지 않는다." 에이전트가 만든 결과물이 테스트를 통과했다고 해서 올바르고, 안전하고, 유지보수 가능하다는 의미는 아닙니다. 핵심 코드 경로는 반드시 리뷰하세요. "카드로 쌓은 집" 비유가 적용됩니다: AI 생성 코드는 견고해 보이지만 테스트하지 않은 엣지 케이스에서 무너질 수 있습니다.

바이브 코딩과 프로덕션 엔지니어링 혼동: AI를 활용한 빠른 프로토타이핑("바이브 코딩")은 탐색이나 일회성 프로젝트에 훌륭합니다. 하지만 그 코드를 엄격한 스펙, 테스트, 리뷰 없이 프로덕션에 배포하면 문제를 자초하는 것입니다. "바이브 코딩"과 "AI 지원 엔지니어링"은 구분해야 합니다. 후자에는 이 가이드에서 설명하는 규율이 필요합니다. 현재 어떤 모드에 있는지 인지하세요.

"치명적 삼박자" 무시: Willison은 AI 에이전트를 위험하게 만드는 세 가지 특성을 경고합니다: 속도(리뷰할 수 있는 것보다 빠르게 작동), 비결정성(같은 입력에 다른 출력), 비용(검증을 생략하도록 유혹). 스펙과 리뷰 프로세스는 이 세 가지를 모두 감안해야 합니다. 속도가 검증 능력을 앞지르지 않도록 하세요.

6가지 핵심 영역 누락: 스펙이 명령어, 테스트, 프로젝트 구조, 코드 스타일, git 워크플로, 경계를 다루지 않는다면, 에이전트에게 필요한 무언가를 빠뜨리고 있을 가능성이 높습니다. 에이전트에게 넘기기 전에 섹션 2의 6가지 영역 체크리스트로 점검하세요.

결론

AI 코딩 에이전트를 위한 효과적인 스펙 작성에는 탄탄한 소프트웨어 엔지니어링 원칙과 LLM 특성에 대한 적응이 함께 필요합니다. 목적의 명확성으로 시작하고, AI가 계획을 확장하도록 하세요. 스펙을 진지한 설계 문서처럼 구조화하여—6가지 핵심 영역을 다루고 툴체인에 통합하여—단순한 산문이 아닌 실행 가능한 산출물로 만드세요. 한 번에 퍼즐 한 조각만 제공하여 에이전트의 집중력을 유지하세요(대규모 스펙에는 요약 목차, 서브 에이전트, 병렬 오케스트레이션 같은 전략을 고려합니다). 3단계 경계(항상/먼저 확인/절대 금지), 자체 점검, 적합성 테스트를 포함하여 실수를 예방하세요—본질적으로 AI에게 실패하지 않는 방법을 가르치는 것입니다. 그리고 전체 과정을 반복적으로 다루세요: 테스트와 피드백으로 스펙과 코드를 지속적으로 다듬습니다.

이 가이드라인을 따르면, AI 에이전트가 큰 컨텍스트에서 "무너지거나" 엉뚱한 방향으로 빠질 가능성이 훨씬 줄어들 것입니다.

즐거운 스펙 작성 되세요!

이 글의 포맷팅에는 Gemini, 이미지 생성에는 Nano Banana Pro가 사용되었습니다

O'Reilly에서 새로운 AI 지원 엔지니어링 도서를 출간하게 되어 기쁩니다. 관심 있으시면 도서 사이트에서 무료 팁을 확인하실 수 있습니다.