AI 에이전트를 위한 좋은 명세 작성 방법

https://addyosmani.com/blog/good-spec/

TL;DR: 명확한 명세를 통해 AI를 과도하게 압도하지 않으면서 필요한 뉘앙스(구조, 스타일, 테스트, 경계 포함)를 충분히 담아 안내하세요. 큰 작업은 하나의 거대한 프롬프트로 유지하기보다 더 작은 작업으로 분할하세요. 먼저 읽기 전용 모드로 계획을 수립한 뒤, 실행하고 지속적으로 반복하세요.

AI 에이전트에 대한 좋은 명세 작성법을 많이 들었지만, 아직 탄탄한 프레임워크를 찾지 못했습니다. RFC에 필적하는 명세를 쓸 수도 있지만, 어느 시점에서는 컨텍스트가 너무 커져서 모델이 무너집니다.

많은 개발자가 이런 좌절을 공유합니다. AI 에이전트에게 방대한 명세를 그대로 던지는 방식은 작동하지 않습니다 — 컨텍스트 윈도 제한과 모델의 “주의력 예산”이 방해가 됩니다. 핵심은 스마트한 명세를 쓰는 것입니다: 에이전트를 명확히 안내하면서 실용적인 컨텍스트 크기 내에 머물고, 프로젝트와 함께 진화하는 문서. 이 가이드는 Claude Code와 Gemini CLI 같은 코딩 에이전트를 사용하며 얻은 모범 사례를, 에이전트를 집중적이고 생산적으로 유지하는 명세 작성 프레임워크로 정리합니다.

이 글에서는 훌륭한 AI 에이전트 명세를 위한 다섯 가지 원칙을 다룹니다. 각 원칙은 굵게 된 요약 문구로 시작합니다.

1. 높은 수준의 비전으로 시작하고, 세부는 AI가 초안을 잡도록 하세요

프로젝트를 간결한 고수준 명세로 시작한 다음, AI가 이를 상세 계획으로 확장하게 하세요.

초기에 과도한 엔지니어링을 하기보다, 명확한 목표 진술과 몇 가지 핵심 요구사항으로 시작하세요. 이를 “제품 브리프”로 간주하고, 에이전트가 더 정교한 명세를 생성하도록 하세요. 이렇게 하면 방향에 대한 통제는 유지하면서, AI의 상세화 강점을 활용할 수 있습니다. 이는 처음부터 매우 구체적인 기술 요구사항을 반드시 충족해야 하는 경우가 아니라면 특히 효과적입니다.

왜 효과적인가: 탄탄한 고수준 지시가 주어지면 LLM 기반 에이전트는 세부를 훌륭히 보완하지만, 주어진 방향에서 벗어나지 않도록 하려면 명확한 임무가 필요합니다. 짧은 개요나 목표 설명을 제공하고 AI에게 전체 명세(예: spec.md)를 생성하도록 요청하면, 에이전트가 참고할 지속적인 레퍼런스를 만들게 됩니다. 에이전트에서는 사전 계획이 더욱 중요합니다 — 먼저 계획을 반복 개선한 뒤, 에이전트에게 코드를 작성하도록 넘기세요. 명세는 여러분과 AI가 함께 만드는 첫 산출물이 됩니다.

실용적 접근: 새 코딩 세션을 다음과 같이 시작하세요. “당신은 AI 소프트웨어 엔지니어입니다. [프로젝트 X]에 대해 목표, 기능, 제약, 단계별 계획을 포함한 상세 명세를 작성하세요.” 초기 프롬프트는 고수준으로 유지하세요 — 예: “사용자가 작업(투두 리스트)을 추적할 수 있는 웹 앱을 구축합니다. 사용자 계정, 데이터베이스, 간단한 UI를 포함합니다.” 에이전트는 개요, 기능 목록, 기술 스택 제안, 데이터 모델 등을 포함한 구조화된 초안 명세로 응답할 수 있습니다. 그러면 이 명세가 여러분과 에이전트 모두가 참조하는 “단일 진실의 원천”이 됩니다. GitHub의 AI 팀은 “명세가 공유된 진실의 원천이 되고… 프로젝트와 함께 진화하는 살아 있는, 실행 가능한 산출물”이 되는 명세 주도 개발(spec-driven development)을 권장합니다. 코드를 작성하기 전에 AI가 만든 명세를 검토하고 개선하세요. 여러분의 비전과 일치하는지 확인하고, 환각이나 엇나간 세부를 바로잡으세요.

Plan Mode로 ‘계획 우선’을 강제하세요: Claude Code 같은 도구는 에이전트를 읽기 전용 작업으로 제한하는 Plan Mode를 제공합니다 — 코드베이스를 분석하고 상세 계획을 만들 수 있지만, 여러분이 준비될 때까지 코드는 작성하지 않습니다. 이는 계획 단계에 이상적입니다: Plan Mode(Claude Code에서 Shift+Tab)로 시작하여, 만들고자 하는 것을 설명하고 에이전트가 기존 코드를 탐색하면서 명세 초안을 작성하도록 하세요. 계획의 모호한 부분을 질문하며 명확히 하도록 요청하세요. 아키텍처, 모범 사례, 보안 위험, 테스트 전략 관점에서 계획을 리뷰하도록 하세요. 목표는 오해의 여지가 없을 때까지 계획을 정제하는 것입니다. 그때에만 Plan Mode를 종료하고 에이전트가 실행하도록 하세요. 이 워크플로우는 명세가 견고해지기 전에 코드 생성으로 곧장 뛰어드는 흔한 함정을 예방합니다.

명세를 컨텍스트로 활용하세요: 승인되면 이 명세를 저장하세요(예: SPEC.md) 그리고 필요할 때 관련 섹션만 에이전트에 제공하세요. 강력한 모델을 사용하는 많은 개발자가 정확히 이렇게 합니다 — 명세 파일을 세션 간에 유지해, 작업을 재개할 때마다 AI를 고정(anchor)합니다. 대화 기록이 길어지거나 에이전트를 재시작해야 할 때 발생할 수 있는 건망증을 완화합니다. 이는 팀에서 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 디렉터리, 프로덕션 설정, 특정 폴더. GitHub 연구에서 “시크릿을 절대 커밋하지 말라”는 단일로는 가장 유용한 제약이었습니다.

스택을 구체적으로: “React 18 + TypeScript, Vite, Tailwind CSS”처럼 버전과 핵심 의존성을 포함해 명확히 쓰세요. 모호한 명세는 모호한 코드를 낳습니다.

일관된 형식 사용: 명확성이 최우선입니다. 많은 개발자가 명세에서 Markdown 헤딩 또는 <background>, <instructions>, <tools>, <output_format> 같은 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은 명세를 엔지니어링 프로세스의 중심으로 만드는 네 단계, 게이트드 워크플로우를 사용합니다. 명세를 작성하고 옆으로 치워두는 대신, 명세가 구현, 체크리스트, 작업 분해를 주도합니다. 여러분의 주된 역할은 조종하고 방향을 제시하는 것이고, 코딩 에이전트가 대부분의 작성 작업을 수행합니다. 각 단계는 특정 역할을 가지며, 현재 작업이 완전히 검증되기 전에는 다음 단계로 이동하지 않습니다:

1. Specify: 무엇을 왜 만드는지에 대한 고수준 설명을 제공하면, 코딩 에이전트가 상세 명세를 생성합니다. 이는 기술 스택이나 앱 설계가 아니라 — 사용자 여정, 경험, 성공의 정의에 관한 것입니다. 누가 사용할지? 어떤 문제를 해결하는지? 어떻게 상호작용할지? 만들고자 하는 사용자 경험을 맵핑하고, 코딩 에이전트가 세부를 살을 붙이게 하세요. 이 명세는 학습과 함께 진화하는 살아 있는 산출물이 됩니다.
2. Plan: 이제 기술적으로 들어갑니다. 원하는 스택, 아키텍처, 제약을 제공하면, 코딩 에이전트가 포괄적인 기술 계획을 생성합니다. 회사 표준 기술이 있다면 여기서 명시하세요. 레거시 시스템 통합이나 컴플라이언스 요구사항이 있다면 모두 포함하세요. 여러 계획 변형을 요청하여 접근을 비교할 수 있습니다. 내부 문서를 제공하면, 에이전트가 여러분의 아키텍처 패턴을 계획에 직접 통합할 수 있습니다.
3. Tasks: 코딩 에이전트가 명세와 계획을 실제 작업으로 분해합니다 — 각기 특정 부분을 해결하는 작은, 리뷰 가능한 청크들. 각 작업은 고립된 상태에서 구현 및 테스트할 수 있어야 하며, 거의 AI 에이전트를 위한 테스트 주도 개발과 같습니다. “인증을 구축” 대신 “이메일 형식을 검증하는 사용자 등록 엔드포인트를 생성” 같은 구체적 작업을 얻습니다.
4. Implement: 코딩 에이전트가 작업을 하나씩(또는 병렬로) 처리합니다. 여러분은 수천 줄의 코드 덤프를 검토하는 대신, 특정 문제를 해결하는 집중된 변경을 검토합니다. 에이전트는 무엇을 만들지(명세), 어떻게 만들지(계획), 무엇을 작업할지(작업)를 알고 있습니다. 결정적은 여러분의 역할은 각 단계에서 검증하는 것입니다: 명세가 원하는 것을 포착했는가? 계획이 제약을 고려했는가? AI가 놓친 엣지 케이스가 있는가? 이 프로세스는 앞으로 나아가기 전에 여러분이 비판하고, 빈틈을 찾고, 방향을 수정할 수 있는 체크포인트를 내장합니다.

이 게이트드 워크플로우는 Willison이 말하는 “하우스 오브 카드 코드” — 검증에 무너지기 쉬운 취약한 AI 출력 — 를 예방합니다. Anthropic의 Skills 시스템은 유사한 패턴을 제공하며, 마크다운 기반의 재사용 가능한 행동을 정의해 에이전트가 호출할 수 있게 합니다. 명세를 이러한 워크플로우에 삽입함으로써, 명세가 검증되기 전에는 에이전트가 진행할 수 없고, 변경사항은 자동으로 작업 분해와 테스트에 전파됩니다.

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

Agent Experience(AX) 설계: 개발자 경험(DX)을 위한 API를 설계하듯, “에이전트 경험”을 위한 명세 설계를 고려하세요. 즉, 깔끔하고 파싱 가능한 포맷: 에이전트가 소비할 모든 API에 대한 OpenAPI 스키마, LLM 소비를 위해 문서를 요약하는 llms.txt, 명시적 타입 정의. Agentic AI Foundation(AAIF)은 MCP(Model Context Protocol) 같은 도구 통합 프로토콜을 표준화하고 있습니다 — 이런 패턴을 따르는 명세는 에이전트가 더 쉽게 소비하고 신뢰성 있게 행동할 수 있습니다.

PRD vs SRS 마인드셋: 확립된 문서 관행을 차용하면 도움이 됩니다. AI 에이전트 명세에서는 종종 이를 하나의 문서로 혼합하게 되지만(위 예시처럼), 양 측면을 모두 다루는 것이 유리합니다. PRD처럼 작성하면 사용자 중심 컨텍스트(“각 기능의 이유”)를 포함해 AI가 잘못된 목표를 최적화하는 것을 막습니다. SRS처럼 확장하면 AI가 실제로 올바른 코드를 생성하는 데 필요한 구체사항(어떤 데이터베이스나 API를 사용할지)을 못 박습니다. 이런 초기 투자 노력은 이후 에이전트와의 오해를 크게 줄여줍니다.

명세를 “살아 있는 문서”로: 작성하고 잊지 마세요. 여러분과 에이전트가 결정을 내리거나 새로운 정보를 발견할 때 명세를 업데이트하세요. AI가 데이터 모델을 변경해야 했거나 기능을 줄이기로 했다면, 이를 명세에 반영해 ‘진실의 원천’을 유지하세요. 버전 관리된 문서로 생각하세요. 명세 주도 워크플로우에서는 명세가 구현, 테스트, 작업 분해를 주도하며, 명세가 검증되기 전에는 코딩으로 넘어가지 않습니다. 이 습관은 여러분이나 에이전트가 잠시 떠났다가 다시 돌아와도 프로젝트의 일관성을 유지하게 합니다. 명세는 AI만을 위한 것이 아니라, 여러분(개발자)이 감독을 유지하고 AI의 작업이 실제 요구사항을 충족하는지 보장하는 데도 도움이 됩니다.

3. 큰 프롬프트 하나가 아닌, 모듈식 프롬프트와 컨텍스트로 작업을 분해하세요

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

숙련된 AI 엔지니어들은 프로젝트 전체(모든 요구사항, 모든 코드, 모든 지시사항)를 단일 프롬프트나 에이전트 메시지에 집어넣는 것이 혼란의 지름길이라는 것을 배웠습니다. 토큰 한계에 부딪힐 위험뿐 아니라, “지시의 저주” — 너무 많은 지시로 어느 것도 잘 따르지 못하는 현상 — 로 인해 모델의 집중력이 흐려집니다. 해결책은 명세와 워크플로우를 모듈식으로 설계해, 한 번에 한 조각만 처리하고 그 조각에 필요한 컨텍스트만 끌어오는 것입니다.

너무 많은 컨텍스트/지시의 저주: 연구는 많은 개발자가 경험적으로 본 바를 확인했습니다. 프롬프트에 지시사항이나 데이터를 많이 쌓을수록, 각 지시를 준수하는 모델 성능이 현저히 떨어집니다. 한 연구는 이를 “지시의 저주”라고 명명하며, GPT-4와 Claude조차 많은 요구사항을 동시에 만족시키려 하면 어려움을 겪는다고 보여줬습니다. 실무적으로, 상세 규칙 10개를 제시하면 AI가 처음 몇 개는 따르다가 나머지는 간과할 수 있습니다. 더 나은 전략은 반복적 집중입니다. 업계 가이드라인은 복잡한 요구사항을 순차적이고 단순한 지시로 분해하는 모범 사례를 제시합니다. AI를 한 서브 문제에 집중시키고, 이를 완료한 뒤 다음으로 이동하세요. 이렇게 하면 품질이 유지되고 오류가 관리 가능합니다.

명세를 단계나 구성요소로 나누기: 명세 문서가 매우 길거나 많은 내용을 다룬다면, 부분적으로 나누는 것을 고려하세요(물리적으로 별도 파일이든, 명확히 구분된 섹션이든). 예를 들어 “백엔드 API 명세” 섹션과 “프론트엔드 UI 명세” 섹션을 둘 수 있습니다. 백엔드 작업 중에는 항상 프론트엔드 명세를 제공할 필요가 없고, 그 반대도 마찬가지입니다. 다중 에이전트 설정을 사용하는 많은 개발자는 각 부분에 대해 별도의 에이전트나 서브 프로세스를 만듭니다 — 예: 한 에이전트는 데이터베이스/스키마, 다른 에이전트는 API 로직, 또 다른 에이전트는 프론트엔드를 담당 — 각자 관련된 명세 조각만 갖고. 단일 에이전트를 쓰더라도, 해당 작업에 필요한 명세 섹션만 프롬프트에 복사해 이 접근을 모사할 수 있습니다. 컨텍스트 오버로드를 피하세요: DigitalOcean AI 가이드가 경고하듯, 인증 작업과 데이터베이스 스키마 변경을 한 번에 섞지 마세요. 각 프롬프트를 현재 목표에 타이트하게 범위 설정하세요.

대형 명세를 위한 확장 TOC/요약: 에이전트에게 명세의 확장된 목차(Table of Contents)를 요약과 함께 만들게 하는 영리한 기법이 있습니다. 이는 각 섹션을 몇 가지 핵심 포인트나 키워드로 응축하고, 세부사항이 어디에 있는지 참조를 붙인 “명세 요약”입니다. 예를 들어, 전체 명세에 “보안 요구사항” 섹션이 500단어로 있다면, 요약은 “보안: HTTPS 사용, API 키 보호, 입력 검증 구현(전체 명세 §4.2 참조)”처럼 만들 수 있습니다. 계획 단계에서 이런 계층적 요약을 만들면, 프롬프트에 유지 가능한 새 깃발이 생기고, 자세한 내용은 필요 시에만 가져옵니다. 이 확장 TOC는 인덱스 역할을 합니다: 에이전트는 이를 참고해 “아, 보안 섹션이 있군, 확인해야겠다”라고 인지하고, 여러분은 그 섹션을 수요 기반으로 제공하면 됩니다. 이는 인간 개발자가 개요를 훑고, 특정 부분을 작업할 때 명세 문서의 해당 페이지로 넘겨 보는 방식과 유사합니다.

이를 구현하려면, 명세를 작성한 뒤 에이전트에게 이렇게 프롬프트하세요: “위 명세를 각 섹션의 핵심 포인트와 참조 태그를 포함한 매우 간결한 개요로 요약하세요.” 결과는 각 섹션에 대해 한두 문장 요약이 붙은 목록일 수 있습니다. 그 요약을 시스템 또는 어시스턴트 메시지에 유지해, 너무 많은 토큰을 소모하지 않고 에이전트의 집중을 안내합니다. 이 계층적 요약 접근법은 LLM이 장기 컨텍스트를 고수준 구조에 집중해 유지하는 데 도움이 되는 것으로 알려져 있습니다. 에이전트는 명세의 “정신적 지도”를 지니게 됩니다.

명세 파트별 ‘서브 에이전트’ 또는 ‘스킬’ 활용: 또 다른 고급 접근은 분야별 전문화를 가진 복수 에이전트(Anthropic이 ‘서브에이전트’라고 부르는 것, 혹은 ‘스킬’)를 사용하는 것입니다. 각 서브에이전트는 특정 전문 영역을 위해 구성되고, 해당 영역의 명세 일부만 전달받습니다. 예를 들어, 데이터 모델 섹션만 아는 데이터베이스 디자이너 서브에이전트와 API 엔드포인트 명세만 아는 API 코더 서브에이전트를 둘 수 있습니다. 메인 에이전트(또는 오케스트레이터)가 작업을 적합한 서브에이전트로 자동 라우팅합니다. 이점은 각 에이전트가 더 작은 컨텍스트 윈도를 다루고 더 집중된 역할을 가져 정확도가 상승하며 독립 작업을 병렬로 처리할 수 있다는 점입니다. Anthropic의 Claude Code는 각 서브에이전트에 고유 시스템 프롬프트와 도구를 설정해 지원합니다. “각 서브에이전트는 특정 목적과 전문 영역을 가지며, 메인 대화와 별도의 컨텍스트 윈도를 사용하고, 그 행동을 안내하는 커스텀 시스템 프롬프트를 갖습니다.” 문서에 설명된 바와 같습니다. 해당 도메인의 작업이 나타나면 Claude는 해당 서브에이전트에 작업을 위임하고, 서브에이전트는 독립적으로 결과를 반환합니다.

처리량을 위한 병렬 에이전트: 여러 에이전트를 동시에 실행하는 것은 개발자 생산성의 “다음 큰 흐름”으로 떠오르고 있습니다. 하나의 에이전트가 끝나기를 기다리기보다, 독립 작업을 위해 병렬 에이전트를 가동하세요. Willison은 이를 “병렬 코딩 에이전트 수용”이라 부르며 “놀라울 정도로 효과적이지만 정신적으로 피로하다”고 말합니다. 핵심은 에이전트들이 서로 간섭하지 않도록 작업 범위를 정의하는 것입니다 — 한 에이전트는 기능을 코딩하고 다른 에이전트는 테스트를 작성하는 식, 또는 분리된 컴포넌트를 동시에 구축. LangGraph나 OpenAI Swarm 같은 오케스트레이션 프레임워크가 에이전트 조정에 도움을 주며, Chroma 같은 벡터 DB를 통한 공유 메모리는 중복 프롬프트 없이 공용 컨텍스트 접근을 가능하게 합니다.

단일 vs 다중 에이전트: 언제 무엇을 쓸지

실무적으로, 서브에이전트나 스킬별 프롬프트는 여러 명세 파일(또는 프롬프트 템플릿)을 유지하는 형태일 수 있습니다 — 예: SPEC_backend.md, SPEC_frontend.md — 그리고 AI에게 “백엔드 작업에는 SPEC_backend를, 프론트엔드 작업에는 SPEC_frontend를 참조해”라고 지시합니다. Cursor/Claude 같은 도구에서는 실제로 각 영역에 서브에이전트를 띄울 수 있습니다. 단일 에이전트 루프보다 설정이 확실히 더 복잡하지만, 인간 개발자의 사고방식을 모사합니다 — 우리는 큰 명세 전체를 머릿속에 넣어두지 않고, 현재 작업에 필요한 부분만 회상하며 전체 아키텍처에 대한 일반 감각을 유지합니다. 주의할 점은 상호의존 관리입니다: 프론트엔드는 백엔드 명세의 API 계약을 알아야 하는 등, 서브에이전트 간 일관성 보장이 필요합니다. 중앙 개요(또는 “아키텍트” 에이전트)가 서브 명세를 참조해 일관성을 유지하도록 돕습니다.

각 프롬프트를 한 작업/섹션에 집중하세요: 고급 다중 에이전트 설정 없이도 모듈성을 수동으로 강제할 수 있습니다. 예를 들어, 명세가 작성된 후 다음 단계가 “1단계: 데이터베이스 스키마 구현”이라면, 에이전트에게 명세의 데이터베이스 섹션만, 그리고 글로벌 제약(예: 기술 스택)만 제공하세요. 에이전트가 이를 처리합니다. 그 다음 “2단계: 인증 기능 구현”에서는 명세의 인증 섹션과 필요 시 스키마의 관련 부분만 제공합니다. 주요 작업마다 컨텍스트를 새로고침함으로써, 모델이 오래되거나 불필요한 정보를 들고 다니며 산만해지는 것을 막습니다. 한 가이드가 제안하듯: “새 세션으로 시작해 주요 기능을 전환할 때 컨텍스트를 정리하세요.” 매번 명세의 핵심 글로벌 규칙(제약 섹션)을 상기시키되, 필요하지 않은 전체 명세는 밀어 넣지 마세요.

인라인 지시와 코드 TODO 활용: 또 다른 모듈성 트릭은 코드나 명세를 대화의 ‘활성 요소’로 사용하는 것입니다. 예를 들어, // TODO 주석으로 해야 할 일을 스캐폴딩하고, 에이전트가 이를 하나씩 채우게 하세요. 각 TODO가 작은 작업을 위한 미니 명세가 됩니다. 이는 AI를 레이저처럼 집중시키며(“이 명세 스니펫에 따라 이 특정 함수를 구현”), 짧은 루프로 반복할 수 있습니다. 전체 체크리스트를 한 번에 주는 대신, AI에게 체크리스트 항목 하나를 완료하도록 하는 방식과 유사합니다.

핵심 결론: 작은, 집중된 컨텍스트가 거대한 프롬프트보다 낫습니다. 이는 품질을 높이고 AI가 한 번에 너무 많은 것을 처리하려다 “압도”되는 것을 막습니다. 모듈로 작업을 구조화하고, 명세 요약이나 서브 명세 에이전트 같은 전략을 사용하면 컨텍스트 크기 제한과 AI의 단기 기억 한계를 우회할 수 있습니다. 잘 설계된 입력은 잘 설계된 함수와 같습니다: 작업에 필요한 입력만 제공하세요.

4. 자기 점검, 제약, 그리고 인간 전문성을 내장하세요

에이전트를 위한 명세는 ‘할 일 목록’에 그치지 않고, 품질 관리 가이드여야 합니다 — 그리고 여러분의 전문성을 과감히 주입하세요.

좋은 명세는 AI가 어디서 실수할지 예측하고 가드레일을 세웁니다. 또한 여러분이 가진 도메인 지식, 엣지 케이스, ‘함정’을 활용해 AI가 진공 상태에서 작동하지 않게 합니다. 명세를 AI의 코치이자 레페리로 생각하세요: 올바른 접근을 권장하고, 반칙을 콜합니다.

세 단계 경계(Three-tier boundaries) 사용: 2,500개+ 에이전트 파일에 대한 GitHub 분석은 단순한 금지 목록보다 세 단계 경계 시스템이 가장 효과적임을 보여줬습니다. 이는 에이전트에게 언제 진행하고, 언제 멈추고, 언제 질문해야 하는지 더 명확히 안내합니다:

• ✅ 항상(Always do): 승인 없이 수행해도 되는 작업. “커밋 전 항상 테스트를 실행.” “스타일 가이드 네이밍을 항상 준수.” “에러는 항상 모니터링 서비스에 로깅.”
• ⚠️ 먼저 질문(Ask first): 인간 승인 필요한 작업. “DB 스키마 변경 전 질문.” “새 의존성 추가 전 질문.” “CI/CD 설정 변경 전 질문.”
• 🚫 절대 금지(Never do): 하드 스톱. “시크릿/키는 절대 커밋하지 말 것.” “node_modules/나 vendor/는 절대 수정하지 말 것.” “실패하는 테스트를 승인 없이 제거하지 말 것.” GitHub 연구에서 “시크릿 커밋 금지”가 단일로는 가장 유용한 제약이었습니다.

이 삼단계 접근은 단순한 규칙 목록보다 더 미묘합니다. 어떤 행동은 항상 안전하고, 어떤 행동은 감독이 필요하며, 어떤 행동은 범주적으로 금지된다는 점을 인정합니다. 에이전트는 “항상(Always)” 항목은 자신 있게 진행하고, “먼저 질문(Ask first)” 항목은 검토 대상으로 표시하며, “절대 금지(Never)” 항목에서는 즉시 중단할 수 있습니다.

자기 검증을 장려하세요: 강력한 패턴 중 하나는 에이전트가 자신의 작업을 명세에 자동으로 대조하도록 하는 것입니다. 도구가 허용한다면, 코드 생성 후 AI가 실행할 수 있는 단위 테스트나 린팅 같은 점검을 통합할 수 있습니다. 하지만 명세/프롬프트 수준에서도 “구현 후 결과를 명세와 비교해 모든 요구사항 충족 여부를 확인하고, 처리되지 않은 명세 항목을 나열하라”처럼 이중 확인을 지시할 수 있습니다. 이는 LLM이 출력물을 명세에 비추어 성찰하도록 만들어 누락을 포착합니다. 프로세스에 내장된 일종의 자기 감사(Self-audit)입니다.

예를 들어 프롬프트에 “(함수를 작성한 뒤 위 요구사항 목록을 검토해 각 항목이 충족되었는지 확인하고, 누락된 항목을 표시하라)”를 덧붙일 수 있습니다. 그러면 모델은 (이상적으로) 코드를 출력한 다음 각 요구사항 충족 여부를 나타내는 짧은 체크리스트를 제공합니다. 이는 여러분이 테스트를 실행하기도 전에 무언가를 잊어버릴 가능성을 줄입니다. 만능은 아니지만 도움이 됩니다.

주관적 점검을 위한 LLM-as-a-Judge: 자동 테스트가 어려운 기준 — 코드 스타일, 가독성, 아키텍처 패턴 준수 — 에 대해서는 “LLM-as-a-Judge”를 고려하세요. 이는 두 번째 에이전트(또는 별도의 프롬프트)가 첫 번째 에이전트의 출력을 명세의 품질 가이드라인에 맞춰 리뷰하는 것입니다. Anthropic 등은 주관적 평가에 이 접근이 효과적이라고 보고했습니다. 예: “이 코드를 우리 스타일 가이드 준수 관점에서 리뷰하고, 위반을 표시하라.” 판정 에이전트가 피드백을 반환하면 이를 반영하거나 재수정을 촉발합니다. 이는 구문 검사 너머의 의미론적 평가 층을 추가합니다.

컨포먼스 테스트: Willison은 컨포먼스 스위트 구축을 옹호합니다 — 언어에 독립적인 테스트(종종 YAML 기반)로, 어떠한 구현도 반드시 통과해야 합니다. 이는 계약처럼 작동합니다. API를 구축한다면, 컨포먼스 스위트가 기대되는 입력/출력을 규정하고, 에이전트의 코드는 모든 케이스를 만족해야 합니다. 이는 임시 단위 테스트보다 더 엄격한데, 명세에서 직접 도출되며 구현 간 재사용할 수 있기 때문입니다. 명세의 성공 기준 섹션에 컨포먼스 기준을 포함하세요(예: “conformance/api-tests.yaml의 모든 케이스를 통과해야 함”).

테스트를 명세에 녹이기: 전통적인 개발에서는 요구사항을 명확히 하기 위해 TDD를 사용하거나 테스트 케이스를 작성하며, 동일한 방식을 AI에도 적용할 수 있습니다. 예를 들어 명세의 성공 기준에 “이 샘플 입력들은 다음 출력들을 산출해야 한다…” 또는 “다음 단위 테스트들이 통과해야 한다.”라고 명시할 수 있습니다. 에이전트는 능력이 있다면 이러한 케이스들을 머릿속으로 시뮬레이션하거나 실제로 실행하도록 프롬프트할 수 있습니다. Simon Willison은 견고한 테스트 스위트를 갖추는 것이 에이전트에게 초능력을 부여하는 것과 같다고 언급했는데, 테스트가 실패할 때 빠르게 검증하고 반복할 수 있기 때문입니다. AI 코딩 맥락에서는 명세에 테스트나 기대 결과에 대한 약간의 의사코드를 작성해두면 에이전트의 구현을 안내할 수 있습니다. 또한 서브에이전트 설정에서 명세의 기준을 받아 “코드 에이전트”의 출력을 지속적으로 검증하는 전용 “테스트 에이전트”를 사용할 수 있습니다.

도메인 지식을 반영하세요: 명세에는 숙련된 개발자나 맥락을 아는 사람만이 알 법한 통찰이 담겨야 합니다. 예를 들어 전자상거래 에이전트를 구축하는데 “products”와 “categories”가 다대다 관계라는 사실을 알고 있다면, 이를 명확히 명시하세요(AI가 알아서 추론할 것이라 가정하지 마세요 — 그렇지 않을 수 있습니다). 특정 라이브러리가 악명 높게 까다롭다면, 피해야 할 함정을 언급하세요. 본질적으로, 여러분의 멘토링을 명세에 녹여 넣는 것입니다. 명세에는 “라이브러리 X를 사용할 경우, 버전 Y에서 메모리 누수 문제가 있으니 주의할 것(대안 Z 적용)” 같은 조언을 포함할 수 있습니다. 이 정도 수준의 세부사항이 평균적인 AI 출력물을 진정으로 견고한 해결책으로 바꾸는데, 이는 여러분이 흔한 함정을 피해 가도록 AI를 이끌었기 때문입니다.

또한 선호나 스타일 가이드라인(예: “React에서는 클래스 컴포넌트보다 함수형 컴포넌트를 사용”)이 있다면 명세에 인코딩하세요. 그러면 AI가 여러분의 스타일을 모방합니다. 많은 엔지니어들은 명세에 작은 예시도 포함합니다. 예: “모든 API 응답은 JSON이어야 합니다. 오류의 경우 {“error”: “message”}.” 간단한 예시를 제공하면, 원하는 정확한 형식에 AI를 고정(anchor)할 수 있습니다.

단순한 작업을 위한 미니멀리즘: 우리는 철저한 명세를 권장하지만, 전문가다운 역량의 한 부분은 언제 단순하게 유지할지 아는 것입니다. 상대적으로 단순하고 고립된 작업에는 지나치게 강압적인 명세가 도움보다 혼란을 줄 수 있습니다. 에이전트에게 직관적인 일을 요청한다면(예: “페이지에서 div를 가운데 정렬”), “해결책을 간결하게 유지하고 불필요한 마크업이나 스타일을 추가하지 마세요.”라고만 말해도 충분합니다. 거기에 전체 PRD는 필요 없습니다. 반대로 복잡한 작업(예: “토큰 갱신과 오류 처리를 포함한 OAuth 플로우를 구현”)에는 그때가 바로 상세 명세를 꺼낼 때입니다. 좋은 경험칙은 작업 복잡도에 맞춰 명세의 상세 수준을 조정하는 것입니다. 어려운 문제를 과소 명세하지 마세요(에이전트가 허우적대거나 엇나갈 수 있습니다). 그러나 사소한 문제를 과다 명세하지도 마세요(에이전트가 얽히거나 불필요한 지시 때문에 컨텍스트를 소모할 수 있습니다).

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

루프에서 책임자는 여전히 여러분입니다: 명세는 에이전트를 강화하지만, 최종 품질 필터는 여러분입니다. 에이전트가 기술적으로는 명세를 충족하지만 느낌이 맞지 않는 결과를 내놓는다면, 여러분의 판단을 신뢰하세요. 명세를 정제하거나 출력을 직접 조정하면 됩니다. AI 에이전트의 장점은 기분이 상하지 않는다는 점입니다 — 설계가 엇나갔다면 “사실 제가 의도한 바와 다릅니다. 명세를 명확히 하고 다시 진행하죠.”라고 말하면 됩니다. 명세는 AI와의 협업 속에서 진화하는 살아 있는 산출물이며, 변경할 수 없는 일회성 계약이 아닙니다.

Simon Willison은 AI 에이전트와 협업하는 일을 “매우 기묘한 형태의 매니지먼트”에 비유했으며, “코딩 에이전트에서 좋은 결과를 얻는 일은 인간 인턴을 관리하는 것과 불편할 정도로 비슷하게 느껴진다”고 농담했습니다. 여러분은 명확한 지시사항(명세)을 제공하고, 필요한 컨텍스트(명세와 관련 데이터)를 갖추게 하며, 실행 가능한 피드백을 제공해야 합니다. 명세가 무대를 마련하지만, 실행 중의 모니터링과 피드백이 핵심입니다. 만약 AI가 “기회만 주면 반드시 편법을 쓰는 괴상한 디지털 인턴”이라면, 여러분이 작성하는 명세와 제약이 그 편법을 막고 작업에 집중하게 만드는 방법입니다.

결실은 이렇습니다: 좋은 명세는 AI에게 무엇을 만들라고 지시하는 데 그치지 않고, 스스로 수정하고 안전한 경계 안에 머물도록 돕습니다. 검증 단계, 제약, 그리고 여러분이 힘들게 얻은 지식을 명세에 녹여 넣으면, 에이전트의 출력이 첫 시도부터 올바를 가능성(적어도 훨씬 더 올바를 가능성)이 크게 높아집니다. 이는 반복 횟수를 줄이고 “도대체 왜 저렇게 했지?”라는 순간들을 줄여줍니다.

5. 사양을 테스트하고, 반복하고, 발전시키세요 (그리고 적절한 도구를 사용하세요)

사양 작성과 에이전트 구축은 반복 루프입니다: 빠르게 테스트하고, 피드백을 모아 사양을 정제하고, 자동화 도구를 활용하세요.

초기 사양은 끝이 아니라 시작입니다. 최고의 결과는 사양과 에이전트의 작업을 지속적으로 검증하며 필요에 따라 조정할 때 나옵니다. 또한 현대 AI 개발자는 CI 파이프라인부터 컨텍스트 관리 유틸리티까지 다양한 도구로 이 과정을 지원합니다.

지속적 테스트: 끝까지 기다리지 말고, 큰 이정표마다 혹은 함수마다 테스트를 실행하거나 최소한 빠른 수동 점검을 하세요. 실패가 보이면, 진행 전에 사양이나 프롬프트를 업데이트하세요. 예를 들어 사양이 “비밀번호는 bcrypt로 해시되어야 한다”고 했는데 에이전트 코드가 평문을 저장한다면—즉시 멈추고 수정하세요(사양/프롬프트에 규칙을 재강조). 자동 테스트가 특히 빛납니다: 테스트를 제공했거나 진행 중에 작성한다면, 작업 후 에이전트가 그것을 실행하도록 하세요. 많은 코딩 에이전트 설정에서는 작업 완료 후 npm test 등의 명령을 수행하게 할 수 있습니다. 결과(실패)는 다음 프롬프트로 되먹임되어 “출력이 X, Y, Z에서 사양을 충족하지 못했으니 수정하라”는 효과를 냅니다. 이런 에이전틱 루프(코드 → 테스트 → 수정 → 반복)는 매우 강력하며 Claude Code나 Copilot Labs 같은 도구가 더 큰 작업을 처리하도록 진화하는 방식입니다. 항상 “완료”의 정의(테스트나 기준)를 정하고 이에 대해 확인하세요.

사양 자체를 반복: 사양이 불완전하거나 모호하다는 것을 발견하면(에이전트가 오해했거나 누락을 깨달았을 때), 사양 문서를 업데이트하세요. 그리고 에이전트를 명시적으로 재동기화하세요: “사양을 다음처럼 업데이트했습니다… 업데이트된 사양에 따라 계획을 조정하거나 코드를 리팩터링하세요.” 이렇게 하면 사양이 단일 진실의 원천으로 남습니다. 일반 개발에서 요구사항 변경을 처리하는 것과 유사하지만, 여기서는 AI 에이전트의 제품 관리자 역할도 수행하는 셈입니다. 가능한 경우 버전 히스토리를 유지하세요(커밋 메시지나 노트라도) — 무엇이 왜 변경되었는지 알 수 있습니다.

컨텍스트·메모리 도구 활용: 에이전트 컨텍스트와 지식을 관리하는 도구 생태계가 성장 중입니다. 예컨대 RAG는 에이전트가 지식베이스(벡터 DB 등)에서 관련 조각을 필요 시 끌어오게 합니다. 사양이 거대하다면 이를 섹션별로 임베드하고, 작업 시점에 가장 관련 있는 부분만 검색·주입하게 할 수 있습니다. MCP(Model Context Protocol)를 구현하는 프레임워크는 현재 작업에 따라 적절한 컨텍스트를 자동 급지합니다. 예로 Context7은 작업 중인 내용에 맞춰 문서에서 관련 컨텍스트 스니펫을 자동 가져올 수 있습니다. 실무적으로는 “결제 처리”를 작업하는 것을 에이전트가 감지하면, 사양/문서의 “결제” 섹션을 프롬프트에 당겨오는 식입니다. 이런 도구를 고려하거나, 간단한 수준(사양 문서 내 검색)으로라도 설정하세요.

신중한 병렬화: 일부 개발자는 독립 작업에 대해 여러 에이전트를 병렬로 돌립니다. 이는 속도를 높일 수 있습니다 — 예를 들어 하나는 코드를 생성하는 동안 다른 하나는 테스트를 작성하거나, 두 기능이 동시에 구축됩니다. 이 방식을 택한다면 충돌을 피하도록 작업이 정말 독립적인지 혹은 명확히 분리되었는지 사양에 명기하세요. 같은 파일을 동시에 쓰지 않도록 합니다. 한 워크플로우 예시는 코드 생성 에이전트와 리뷰 에이전트를 병렬로 돌리거나, 별도 컴포넌트를 구축한 뒤 통합하는 것입니다. 이는 고급 사용이며 관리가 정신적으로 부담될 수 있습니다(Willison은 여러 에이전트 운용이 “놀라울 정도로 효과적이지만 정신적으로 피곤”하다고 고백). 처음엔 2–3개 이하로 시작해 관리 가능성을 확보하세요.

버전 관리와 사양 잠금: Git 등 VCS로 에이전트 변경을 추적하세요. 좋은 버전 관리 습관은 AI 보조가 있을 때 더 중요합니다. 사양 파일 자체를 레포에 커밋하세요. 이렇게 하면 히스토리가 보존될 뿐 아니라, 에이전트가 git diff나 blame을 읽어 변경을 이해할 수도 있습니다(LLM은 diff 읽기에 꽤 능숙합니다). 일부 고급 에이전트 설정은 VCS 히스토리를 질의하여 도입 시점을 확인하도록 합니다 — 놀랍게도 모델은 “Git에 매우 유능”할 수 있습니다. 사양을 레포에 유지하면, 당신과 AI 모두가 진화를 추적할 수 있습니다. GitHub Spec Kit 같은 도구는 사양 주도 개발을 git 워크플로우에 통합합니다 — 예를 들면, 업데이트된 사양을 기준으로 병합을 게이트하거나 사양 항목에서 체크리스트를 생성합니다. 이런 도구 없이도 성공할 수 있지만, 핵심은 사양을 코드처럼 다루며 성실히 유지하는 것입니다.

비용과 속도 고려: 대형 모델과 긴 컨텍스트는 느리고 비용이 큽니다. 실용 팁은 모델 선택과 배칭을 영리하게 하는 것입니다. 초기 초안이나 반복에는 더 저렴하고 빠른 모델을 쓰고, 최종 출력이나 복잡한 추론엔 가장 강력(그리고 비싼) 모델을 예약하세요. 다중 에이전트 사용 시 모두가 최상급일 필요는 없습니다; 테스트 실행 에이전트나 린터 에이전트는 더 작은 모델로 충분합니다. 또한 컨텍스트 크기를 절약하세요: 20k 토큰이 아니라 5k로 충분하다면 그렇게 하세요. 앞서 언급했듯이, 토큰이 많다고 항상 수익이 증가하지는 않습니다.

모니터링과 로깅: 복잡한 에이전트 워크플로우에서는 행동과 출력을 로깅하는 것이 필수입니다. 에이전트가 일탈하거나 오류를 만나는지 로그를 확인하세요. 많은 프레임워크는 트레이스 로그를 제공하거나 단계별 사고를 출력하게 합니다(특히 단계별 사고를 유도하는 프롬프트 사용 시). 로그를 검토하면 사양/지시가 어떻게 오해되었는지 하이라이트됩니다. 일반 프로그램 디버깅과 유사하되, 여기서 “프로그램”은 대화/프롬프트 체인입니다. 이상 징후가 보이면 사양/지시로 돌아가 모호성이 있었는지 확인하세요.

학습과 개선: 각 프로젝트를 통해 사양 작성 기술을 개선하세요. 특정 표현이 AI를 일관되게 혼동시키거나, 사양 섹션을 특정 방식으로 조직하면 준수도가 개선되는지 알게 될 것입니다. 이러한 교훈을 다음 사양에 반영하세요. AI 에이전트 분야는 빠르게 진화하므로 새로운 모범 사례와 도구가 꾸준히 등장합니다. Simon Willison, Andrej Karpathy 등의 블로그를 통해 최신 정보를 따라가고, 실험을 주저하지 마세요.

AI 코딩 에이전트용 사양은 “한 번 쓰고 끝”이 아닙니다. 지시, 검증, 정제의 연속 사이클의 일부입니다. 이 성실함의 보상은 큽니다: 문제를 초기에 잡아 에이전트를 정렬 상태로 유지하면, 뒤늦은 재작성이나 실패를 피할 수 있습니다. 한 AI 엔지니어의 농담처럼, 이런 관행을 쓰면 “인턴 군단”이 당신을 위해 일하는 느낌이 들 수 있지만, 잘 관리해야 합니다. 지속적으로 유지되는 좋은 사양이 바로 그 관리 도구입니다.

일반적인 함정 피하기

마무리 전, 선의의 사양 주도 워크플로우조차 탈선을 부르는 안티패턴을 짚습니다. 2,500+ 에이전트 파일의 GitHub 연구는 뚜렷한 분기를 보여줍니다: “대부분의 에이전트 파일은 지나치게 모호해서 실패합니다.” 피해야 할 실수는 다음과 같습니다.

모호한 프롬프트: “멋진 것을 만들어줘”나 “더 잘 작동하게 해줘”는 에이전트가 고정할 앵커가 없습니다. Baptiste Studer의 말처럼: “모호한 프롬프트는 잘못된 결과를 낳습니다.” 입력, 출력, 제약을 구체화하세요. “당신은 도움을 주는 코딩 어시스턴트입니다”는 통하지 않습니다. “당신은 React 컴포넌트에 대한 테스트를 작성하는 테스트 엔지니어이며, 다음 예시를 따르고, 소스 코드를 절대 수정하지 않습니다”는 통합니다.

요약 없는 장문 컨텍스트 덤프: 50페이지 문서를 프롬프트로 던져 모델이 알아서 하길 기대하는 전략은 거의 실패합니다. 앞서 논의한 위계적 요약(원칙 3)이나 RAG로 관련 정보만 표면화하세요. 컨텍스트 길이는 컨텍스트 품질의 대체물이 아닙니다.

인간 리뷰 생략: Willison의 개인 규칙: “누군가에게 설명할 수 없는 코드는 커밋하지 않는다.” 에이전트가 테스트를 통과한 출력을 냈다고 해서, 그것이 올바르고, 안전하며, 유지보수 가능하다는 뜻은 아닙니다. 중요한 경로는 항상 리뷰하세요. “카드로 지은 집” 은유가 적용됩니다: AI 생성 코드는 견고해 보이지만, 테스트하지 않은 엣지 케이스에서 붕괴할 수 있습니다.

바이브 코딩과 프로덕션 엔지니어링의 혼동: AI로 빠르게 프로토타이핑하는 “바이브 코딩”은 탐색과 폐기형 프로젝트에 훌륭합니다. 그러나 이를 엄격한 사양·테스트·리뷰 없이 프로덕션에 배포하는 것은 문제를 자초합니다. 저는 “바이브 코딩”과 “AI 지원 엔지니어링”을 구분합니다 — 후자는 이 글의 규율을 필요로 합니다. 자신이 어느 모드인지 인지하세요.

“치명적 삼중항” 무시: Willison은 에이전트를 위험하게 만드는 세 속성을 경고합니다: 속도(리뷰 속도를 앞지름), 비결정성(같은 입력, 다른 출력), 비용(검증을 줄이려는 유혹). 당신의 사양과 리뷰 프로세스는 이 셋을 모두 고려해야 합니다. 속도가 검증 능력을 앞서지 않도록 하세요.

여섯 핵심 영역 누락: 사양이 명령어, 테스트, 프로젝트 구조, 코드 스타일, Git 워크플로우, 경계를 다루지 않는다면, 에이전트가 필요로 하는 것을 놓치고 있을 가능성이 큽니다. 섹션 2의 6영역 체크리스트로 에이전트 넘기기 전 최종 점검하세요.

결론

효과적인 AI 코딩 에이전트 사양 작성은 견고한 소프트웨어 엔지니어링 원칙과 LLM 특성에 대한 적응을 결합합니다. 목적의 명확성으로 시작하고, AI가 계획 확장에 도움을 주게 하세요. 사양을 진지한 설계문서처럼 구조화하고—여섯 핵심 영역을 포괄하며—툴체인에 통합해 “실행 가능한 아티팩트”가 되게 하세요. 에이전트의 집중을 유지하려면 한 번에 퍼즐의 한 조각만 급지하세요(거대 사양엔 요약 TOC, 서브 에이전트, 병렬 오케스트레이션 같은 영리한 전술을 고려). “항상/먼저 물어보기/절대 금지”의 3단계 경계, 자기 점검, 적합성 테스트를 포함해—본질적으로 AI가 실패하지 않도록 가르치세요. 그리고 전체 프로세스를 반복적으로 다루세요: 테스트와 피드백으로 사양과 코드를 지속적으로 정제합니다.

이 지침을 따르면, 에이전트가 거대한 컨텍스트에서 “붕괴”하거나 허튼소리로 표류할 가능성이 훨씬 낮아집니다.