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

> Clean Markdown view of GeekNews topic #25949. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=25949](https://news.hada.io/topic?id=25949)
- GeekNews Markdown: [https://news.hada.io/topic/25949.md](https://news.hada.io/topic/25949.md)
- Type: news
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-01-19T10:02:02+09:00
- Updated: 2026-01-19T10:02:02+09:00
- Original source: [addyosmani.com](https://addyosmani.com/blog/good-spec/)
- Points: 110
- Comments: 3

## Summary

AI 코딩 에이전트의 성능은 방대한 지시보다 **스마트한 스펙 작성**에 달려 있습니다. 명확한 목표와 6가지 핵심 영역(Commands·Testing·Structure·Style·Workflow·Boundaries)을 포함한 구조화된 명세가 에이전트를 안정적으로 이끌어주며, 대규모 작업은 작은 태스크로 분할해 컨텍스트를 최소화해야 합니다. 또한 **3단계 경계(Always/Ask first/Never)** 와 자가 검증, 테스트 루프를 내장해 스펙을 지속적으로 진화시키는 것이 스펙 기반 개발의 핵심입니다.

## Topic Body

- AI 코딩 에이전트에게 방대한 스펙을 한꺼번에 던지면 제대로 작동하지 않으며, 핵심은 **스마트 스펙 작성**에 있음  
- 고수준 비전을 먼저 제시하고 AI가 세부 계획을 확장하도록 한 뒤, **Plan Mode**에서 읽기 전용으로 계획을 검토하고 코드 작성 단계로 전환하는 방식 권장  
- GitHub의 2,500개 이상 에이전트 설정 파일 분석 결과, 효과적인 스펙은 **Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries** 6가지 핵심 영역을 포함하는 것  
- 대규모 작업은 하나의 거대한 프롬프트 대신 **모듈화된 작은 태스크**로 분할하고, 해당 태스크에 필요한 컨텍스트만 제공해야 품질 저하 방지 가능  
- 스펙에 **3단계 경계(Always/Ask first/Never)**, 자가 검증, 적합성 테스트를 내장하고 지속적으로 테스트·반복·진화시키는 것이 **스펙 기반 개발 워크플로우**의 핵심  
  
---  
  
### TL;DR  
- **적절한 수준의 세부 정보(구조, 스타일, 테스트, 경계 등)** 를 포함하는 **명확한 명세를 작성**할 것  
- 큰 작업은 한 덩어리 프롬프트 대신 **작은 단위로 분해**하는 방식 권장  
- 계획은 **읽기 전용 모드**로 먼저 수립한 후 **실행하고 지속적으로 개선**  
  
### 핵심 원칙: 스마트 스펙 작성  
- 단순히 방대한 스펙을 AI 에이전트에 던지는 방식은 실패하며, **컨텍스트 윈도우 제한**과 모델의 **주의 예산(attention budget)** 에 부딪힘  
- **“스마트 스펙”** 이란 에이전트를 명확히 안내하고, 실용적인 컨텍스트 크기 내에 유지하며, 프로젝트와 함께 **진화하는 문서**  
- Claude Code, Gemini CLI 같은 코딩 에이전트 사용 경험에서 뽑은 원칙을 **프레임워크** 형태로 정리함   
  
### 원칙 1: 큰그림을 먼저 주고, 세부는 AI가 초안 작성  
- 과도하게 처음부터 다 설계하려 하기보다, 먼저 **목표 진술**과 몇 가지 핵심 요구사항만 또렷하게 잡고 시작  
- 이 초기 스펙을 **“제품 브리프”** 처럼 두고, 에이전트가 이를 바탕으로 **상세 스펙**을 확장 작성하도록 맡기는 방식  
- LLM 기반 에이전트는 고수준 지시가 분명할 때 세부를 잘 채우지만, 미션이 흐리면 쉽게 딴길로 새는 특성을 보임  
- 그래서 핵심은, 에이전트가 방황하지 않도록 처음에 **명확한 미션**을 박아두는 것  
- ## Plan Mode 활용  
  - Claude Code의 **Plan Mode**는 에이전트를 읽기 전용으로 묶어두고, 코드베이스 분석과 상세 계획 수립만 하게 만드는 모드  
  - Shift+Tab으로 Plan Mode에 들어간 뒤 “무엇을 만들고 싶은지”를 설명하면, 에이전트가 기존 코드를 훑으면서 스펙 초안을 작성  
  - 이때 계획에 대해 아키텍처, 모범 사례, 보안 위험, 테스트 전략까지 함께 점검하도록 요구할 수 있음  
  - 계획이 **오해의 여지 없이** 충분히 정제될 때까지는 Plan Mode를 유지하고, 그다음에야 Plan Mode를 종료하고 실행 단계 진입   
- ## 스펙을 컨텍스트로 활용  
  - 확정된 스펙은 **SPEC.md** 같은 파일로 저장하고, 작업할 때 필요한 섹션만 골라 에이전트에 다시 제공  
  - 스펙 파일이 세션 사이에 남아 있기 때문에, 프로젝트를 다시 시작할 때도 AI를 같은 기준점에 **고정**시키는 역할을 함  
  - 대화 히스토리가 길어지거나 에이전트를 재시작할 때 생기는 **망각**을 줄이는 데 도움이 됨  
  - 팀에서 PRD(제품 요구사항 문서)를 공유 기준으로 쓰듯, 인간이든 AI든 모두가 참조하는 “단일 기준 문서” 역할을 맡게 됨  
- ## 목표 지향적 유지  
  - 고수준 스펙은 처음부터 구현 방법을 다 적기보다 **what/why**에 집중하고, 구체적인 **how**는 뒤로 미루는 구성이 적합  
  - 사용자 스토리와 수락 기준처럼 구성: “사용자는 누구인가? / 무엇이 필요한가? / 성공의 모습은?”  
  - [GitHub Spec Kit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)에서도 “무엇을 왜 만드는지에 대한 고수준 설명을 주고, 코딩 에이전트가 사용자 경험과 성공 기준 중심으로 상세 사양을 만들도록 한다”는 흐름을 강조  
  
### 원칙 2: 스펙을 전문적인 PRD(또는 SRS)처럼 구조화  
- AI 스펙을 단순한 메모 모음이 아니라, **명확한 섹션을 갖춘 구조화된 문서**로 다루는 것이 중요  
- PRD나 시스템 설계 문서처럼 포괄적이고 정돈된 형태가, 내용을 **문자 그대로 해석하는 AI**에게 특히 잘 맞음  
- [GitHub에서 2,500개 이상의 에이전트 설정 파일을 분석](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)한 결과, 효과적인 스펙에는 공통적으로 **6가지 핵심 영역**이 포함됨  
  - ## 1. Commands  
    - 실행 가능한 명령어를 문서 앞부분에 배치  
    - 도구 이름만 적는 것이 아니라, 플래그까지 포함된 전체 명령어 명시: `npm test`, `pytest -v`, `npm run build`  
  - ## 2. Testing  
    - 테스트 실행 방법, 사용하는 프레임워크, 테스트 파일 위치, 기대하는 커버리지 수준을 구체적으로 명시  
  - ## 3. Project Structure  
    - 소스 코드, 테스트, 문서의 위치를 명확히 구분  
    - 예: "`src/`는 애플리케이션 코드, `tests/`는 단위 테스트, `docs/`는 문서용"  
  - ## 4. Code Style  
    - 스타일을 장황하게 설명하는 것보다 **실제 코드 스니펫 하나**가 훨씬 효과적  
    - 네이밍 규칙, 포매팅 기준, 바람직한 출력 예시를 함께 제시  
  - ## 5. Git Workflow  
    - 브랜치 네이밍 규칙, 커밋 메시지 형식, PR 요구사항을 명시하면 에이전트도 그 흐름을 따름  
  - ## 6. Boundaries  
    - 에이전트가 절대 건드리면 안 되는 영역을 분명히 지정  
    - 시크릿, vendor 디렉토리, 프로덕션 설정, 특정 폴더 등  
    - GitHub 연구에서 **“절대 시크릿을 커밋하지 말 것”** 이 가장 자주 등장한 유용한 제약으로 확인됨  
- ## 스택에 대해 구체적으로 명시  
  - “React 프로젝트”처럼 뭉뚱그리지 말고, **“React 18 + TypeScript + Vite + Tailwind CSS”** 처럼 구체적으로 적는 것이 중요  
  - 버전과 주요 의존성을 함께 적어야 하며, 모호한 스펙은 결국 모호한 코드를 낳음  
- ## 일관된 형식 사용  
  - 명확성이 가장 중요하며, 많은 개발자가 Markdown 헤딩이나 XML과 유사한 태그로 섹션을 구분  
  - AI 모델은 자유로운 산문보다 **잘 구조화된 텍스트**를 훨씬 안정적으로 처리  
  - Anthropic 엔지니어들 [역시 `&lt;background&gt;`, `&lt;instructions&gt;`, `&lt;tools&gt;`, `<output_format>`처럼 **명확히 구분된 섹션 구성**을 권장](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)  
- ## 스펙을 툴체인에 통합  
  - 스펙을 단순 문서가 아니라, 버전 관리와 CI/CD에 연결된 **“실행 가능한 아티팩트”** 로 취급  
  - GitHub Spec Kit는 스펙을 엔지니어링 프로세스의 중심에 두는 **4단계 게이트 워크플로우**를 사용  
    - **Specify**: 무엇을 왜 만드는지에 대한 고수준 설명을 제공하고, 코딩 에이전트가 상세 사양을 생성  
    - **Plan**: 원하는 스택, 아키텍처, 제약조건을 포함한 기술적 계획을 수립  
    - **Tasks**: 스펙과 계획을 실제 작업 단위로 쪼개고, 각각을 테스트 가능한 크기로 분해  
    - **Implement**: 코딩 에이전트가 태스크를 하나씩, 또는 병렬로 처리  
- ## agents.md를 통한 전문화된 페르소나  
  - GitHub Copilot 같은 도구에서는 **전문화된 에이전트 페르소나**를 정의할 수 있음  
  - @docs-agent(기술 문서), @test-agent(QA), @security-agent(코드 리뷰) 같은 역할 분리 가능  
  - 각 agents.md 파일은 해당 페르소나의 행동 방식, 명령어, 경계를 담은 집중된 스펙 역할을 수행  
- ## Agent Experience(AX) 설계  
  - API를 개발자 경험(DX)에 맞게 설계하듯, 스펙 역시 **에이전트 경험(AX)** 을 고려해 설계 필요  
  - 깔끔하고 파싱하기 쉬운 형식이 중요  
    - 에이전트가 사용할 API의 OpenAPI 스키마  
    - LLM 소비를 위한 문서 요약(llms.txt)  
    - 명시적인 타입 정의  
  - MCP(Model Context Protocol) 같은 표준을 따르는 스펙일수록, 에이전트가 더 안정적으로 이해하고 동작  
- ## 살아있는 문서로 유지  
  - 스펙은 한 번 작성하고 끝내는 문서가 아니라, AI와 함께 결정을 내리거나 새로운 사실이 드러날 때마다 **계속 업데이트**  
  - [스펙 기반 워크플로우](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)에서는 스펙이 구현, 테스트, 태스크 분해를 주도하며, 스펙이 검증되기 전에는 다음 단계로 넘어가지 않음  
  - 이 스펙은 AI만을 위한 문서가 아니라, 개발자가 전체 흐름을 감독하고 AI의 결과물이 실제 요구사항을 충족하는지 확인하는 핵심 도구  
  
### 원칙 3: 태스크를 모듈화된 프롬프트와 컨텍스트로 분할  
- 하나의 거대한 프롬프트에 모든 것을 담기보다, **한 번에 하나의 태스크에만 집중**하도록 컨텍스트를 제공  
- 전체 프로젝트의 요구사항·코드·지시를 단일 프롬프트에 담으면, 오히려 혼란을 키우기 쉬움  
- 토큰 한계에 걸릴 위험뿐 아니라, **“[지시의 저주(curse of instructions)](https://maxpool.dev/research-papers/curse_of_instructions_report.html)”** 로 모델의 집중력이 급격히 떨어질 수 있음  
- ## 지시의 저주  
  - 연구 결과에 따르면, 프롬프트에 지시나 데이터를 많이 쌓을수록 각 지시를 정확히 따르는 성능이 [**눈에 띄게 하락**](https://openreview.net/pdf/848f1332e941771aa491f036f6350af2effe0513.pdf)  
  - GPT-4나 Claude 같은 강력한 모델도, 많은 요구사항을 동시에 만족시키라는 요청에는 어려움을 겪음  
  - 예를 들어 10개의 상세 규칙을 불릿으로 주면, 처음 몇 개만 지키고 뒤쪽 규칙은 점점 무시하는 경향이 나타남  
  - 더 나은 전략은 **반복적 집중**: 한 번에 하나의 하위 문제에만 집중시키고, 끝난 뒤 다음 문제로 넘어가는 방식  
- ## 스펙을 단계나 컴포넌트로 분할  
  - 스펙 문서가 길거나 다루는 범위가 넓다면, 여러 부분으로 나누는 것을 고려  
  - 예: “Backend API Spec”과 “Frontend UI Spec”을 별도 섹션으로 분리  
  - 백엔드 작업을 할 때는 프론트엔드 스펙을 항상 함께 줄 필요는 없음  
  - 멀티 에이전트 환경에서는 각 영역별로 별도의 에이전트나 하위 프로세스를 둘 수도 있음  
  - [DigitalOcean AI 가이드](https://docs.digitalocean.com/products/gradient-ai-platform/concepts/context-management/)에서도 “인증 태스크와 데이터베이스 스키마 변경을 한 번에 섞지 말라”고 경고  
- ## 대규모 스펙을 위한 확장 TOC/요약  
  - 에이전트에게 전체 스펙을 요약한 **확장 목차(TOC)** 를 먼저 작성하게 하는 방식  
  - 각 섹션을 몇 가지 핵심 포인트나 키워드로 압축하고, 세부 내용이 있는 위치를 함께 참조  
  - 예: “Security: HTTPS 사용, API 키 보호, 입력 검증 구현 (전체 스펙 §4.2 참조)”  
  - 이렇게 계층적 요약을 만들어 두면, 프롬프트에는 큰 그림만 유지하고 세부는 필요할 때만 제공 가능  
  - 확장 TOC는 일종의 인덱스 역할을 하며, 에이전트가 “아, 보안 섹션이 있구나”를 인지하고 해당 부분을 요청하게 만듦  
  - 이런 **[계층적 요약 방식](https://addyo.substack.com/p/context-engineering-bringing-engineering)** 은 LLM이 고수준 구조를 유지하는 데 도움이 됨  
- ## 서브에이전트 또는 “스킬” 활용  
  - Anthropic이 말하는 서브에이전트(또는 “스킬”)처럼, **역할이 분리된 다중 에이전트** 활용 가능  
  - 각 서브에이전트는 특정 전문 영역에 맞게 설정되고, 그 영역에 해당하는 스펙 일부만 제공받음  
  - 예: Database Designer 서브에이전트는 데이터 모델 섹션만, API Coder 서브에이전트는 API 엔드포인트 스펙만 인지  
  - 이렇게 하면 각 에이전트가 더 작은 컨텍스트와 더 또렷한 역할을 가져 [**정확도 향상과 병렬 작업**](https://10xdevelopers.dev/structured/claude-code-with-subagents/) 이 가능  
  - Claude Code는 자체 시스템 프롬프트와 도구를 가진 서브에이전트를 정의하는 기능을 지원  
- ## 처리량을 위한 병렬 에이전트  
  - 여러 에이전트를 동시에 돌리는 방식이 **개발자 생산성의 다음 단계**로 떠오르고 있음  
  - 하나의 에이전트가 끝나길 기다리지 않고, 서로 겹치지 않는 작업에 병렬로 에이전트를 투입  
  - Simon Willison은 이를 [“병렬 코딩 에이전트를 받아들이는 것”](https://simonwillison.net/2025/Oct/7/vibe-engineering/) 이라 표현하며, **놀라울 정도로 효과적이지만 정신적으로는 꽤 피곤**하다고 언급  
  - 핵심은 에이전트들이 서로의 작업을 방해하지 않도록 태스크 범위를 명확히 나누는 것  
  - LangGraph나 OpenAI Swarm 같은 오케스트레이션 프레임워크가 이런 조율을 돕고,  
  - Chroma 같은 벡터 데이터베이스를 공유 메모리로 쓰면, 중복 프롬프팅 없이 공통 컨텍스트에 접근 가능  
- ## 단일 vs 멀티 에이전트: 언제 사용할 것인가  
  | 측면 | 단일 에이전트 | 병렬/멀티 에이전트 |  
  | --- | --- | --- |  
  | **장점** | 설정이 단순하고 오버헤드가 낮으며, 디버그와 흐름 추적이 쉬움 | 처리량이 높고, 복잡한 상호의존성 대응과 도메인별 전문화 가능 |  
  | **단점** | 대형 프로젝트에서 컨텍스트 과부하, 반복 속도 저하, 단일 장애점 | 조율 비용 증가, 충돌 가능성, 공유 메모리 필요 |  
  | **적합한 경우** | 격리된 모듈, 중·소형 프로젝트, 초기 프로토타이핑 | 대규모 코드베이스, 코딩·테스트·리뷰 분리, 독립적인 기능 개발 |  
  | **팁** | 스펙 요약 활용, 태스크별 컨텍스트 갱신, 세션 자주 리셋 | 초반에는 2~3개 에이전트로 제한, MCP로 도구 공유, 경계 명확화 |  
- ## 각 프롬프트를 하나의 태스크/섹션에 집중  
  - 복잡한 멀티 에이전트 환경이 없어도, 수동으로 충분히 모듈성을 강제할 수 있음  
  - 예: 스펙 작성 후 “Step 1: 데이터베이스 스키마 구현” 단계에서는 스펙의 Database 섹션만 제공  
  - 주요 태스크가 바뀔 때마다 컨텍스트를 새로 구성해, 오래되거나 관련 없는 정보로 인한 산만함을 줄임  
  - 일부 가이드에서는 주요 기능 전환 시 [**새 세션을 시작**](https://docs.digitalocean.com/products/gradient-ai-platform/concepts/context-management/) 해 컨텍스트를 정리하라고 권장  
- ## 인라인 지시문과 코드 TODO 활용  
  - 코드에 `// TODO` 주석으로 해야 할 일을 적어두고, 에이전트가 하나씩 채우게 하는 방식  
  - 각 TODO가 작은 태스크에 대한 **미니 스펙** 역할을 함  
  - 결과적으로 AI가 “이 스펙 스니펫에 맞춰 이 함수만 구현하라”는 식으로 매우 좁은 범위에 집중하게 됨  
  
### 원칙 4: 자가 검사, 제약조건, 인간 전문성 내장  
- 스펙을 단순히 에이전트의 할 일 목록이 아니라, **품질을 관리하는 가이드**로 다루고 자신의 전문성을 적극적으로 반영할 것  
- 좋은 스펙은 AI가 어디에서 실수할 수 있는지를 미리 짚고, 그 지점에 **가드레일**을 세워 둠  
- 도메인 지식, 엣지 케이스, 각종 “주의사항”을 담아 AI가 맥락 없는 진공 상태에서 작동하지 않게 함  
- 스펙을 AI의 **코치이자 심판**으로 생각하면 이해가 쉬움: 올바른 접근은 유도하고, 잘못된 행동은 즉시 제동  
- [GitHub의 2,500개 이상 에이전트 파일 분석 결과](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/), 가장 효과적인 스펙은 단순한 금지 목록이 아니라 **3단계 경계 시스템**을 사용  
  - 에이전트가 언제 그대로 진행해도 되는지, 언제 멈춰서 물어야 하는지, 언제 완전히 중단해야 하는지를 명확히 알려줌  
  - ## ✅ Always do (항상 수행)  
    - 묻지 않고 수행해야 하는 작업들  
    - 예: “커밋 전 항상 테스트 실행”, “스타일 가이드의 네이밍 컨벤션 항상 준수”, “오류는 항상 모니터링 서비스에 로깅”  
  - ## ⚠️ Ask first (먼저 물을 것)  
    - 인간의 승인이 필요한 작업들  
    - 예: “데이터베이스 스키마 수정 전 물을 것”, “새 의존성 추가 전 물을 것”, “CI/CD 설정 변경 전 물을 것”  
    - 기술적으로 가능할 수는 있지만, 영향 범위가 커서 **사람의 판단이 필요한 변경**을 여기서 걸러냄  
  - ## 🚫 Never do (절대 금지)  
    - 명확한 하드 스톱 영역  
    - 예: “시크릿이나 API 키 절대 커밋 금지”, “node_modules/나 vendor/ 절대 편집 금지”, “명시적 승인 없이 실패하는 테스트 제거 금지”  
    - 연구에서도 **“절대 시크릿을 커밋하지 말 것”** 이 가장 자주 등장한 유용한 제약으로 확인됨  
- ## 자가 검증 장려  
  - 에이전트가 스펙에 비춰 스스로 **결과를 점검**하도록 유도  
  - 도구가 허용된다면, 코드 생성 후 단위 테스트나 린팅을 직접 실행하도록 워크플로우에 포함  
  - 프롬프트 수준에서도 재확인 지시 가능  
    - 예: “구현 후 결과를 스펙과 비교해 모든 요구사항을 충족하는지 확인하고, 미충족 항목이 있으면 나열하라”  
  - LLM이 자신의 출력을 스펙과 대조하도록 만들어 누락을 줄이는 효과  
- ## 주관적 검사를 위한 LLM-as-a-Judge  
  - 코드 스타일, 가독성, 아키텍처 패턴 준수처럼 자동화하기 어려운 기준에는 **LLM-as-a-Judge** 접근 활용  
  - 두 번째 에이전트(또는 별도 프롬프트)가 첫 번째 에이전트의 출력을 스펙의 품질 기준에 맞춰 검토  
  - 예: “이 코드가 우리 스타일 가이드를 준수하는지 검토하고, 위반 사항을 표시하라”  
  - 심판 역할의 에이전트가 피드백을 돌려주고, 이를 반영하거나 수정의 계기로 사용  
- ## 적합성 테스트  
  - Willison은 **적합성 스위트(conformance suite)** 구축을 권장  
  - 언어에 의존하지 않는 테스트(종종 YAML 기반)로, 모든 구현이 반드시 통과해야 하는 계약 역할  
  - API를 만드는 경우, 적합성 스위트가 예상 입력과 출력을 정의하고 에이전트가 만든 코드는 이를 모두 만족해야 함  
  - 스펙의 Success 섹션에 “conformance/api-tests.yaml의 모든 케이스 통과 필수”처럼 기준을 명시  
- ## 스펙에 테스트 활용  
  - 가능하다면 스펙과 프롬프트 흐름에 **테스트 계획이나 실제 테스트**를 직접 포함  
  - TDD처럼 테스트 케이스로 요구사항을 분명히 함  
    - 예: Success Criteria에 “이 샘플 입력은 반드시 이 출력을 생성해야 한다”  
  - Willison은 [견고한 테스트 스위트](https://simonwillison.net/2025/Oct/7/vibe-engineering/)가 에이전트에게 사실상 **슈퍼파워**를 준다고 표현  
  - 테스트 실패 시 즉각 검증하고 반복할 수 있기 때문  
  - 서브에이전트 구성에서는 스펙 기준을 받아 코드 출력을 계속 검증하는 전용 [**테스트 에이전트**](https://10xdevelopers.dev/structured/claude-code-with-subagents/) 를 둘 수도 있음  
- ## 도메인 지식 반영  
  - 스펙에는 경험 있는 개발자나 맥락을 아는 사람만 알고 있는 **현실적인 인사이트**를 담아야 함  
  - 예: 이커머스 에이전트를 만들 때 “products”와 “categories”가 다대다 관계라는 점을 명확히 적어 둠  
    - AI가 알아서 추론할 것이라 기대하지 않음  
  - 특정 라이브러리가 까다롭다면, 자주 빠지는 함정이나 주의점도 함께 명시  
  - 자신의 **멘토십**을 스펙에 녹여내는 방식  
    - 예: “라이브러리 X 사용 시 버전 Y에서 메모리 누수 문제가 있으니 우회책 Z 적용”  
- ## 간단한 태스크에는 미니멀리즘  
  - 철저한 스펙이 중요하지만, 전문성의 일부는 **언제 단순하게 가야 하는지** 아는 데 있음  
  - 비교적 단순하고 격리된 작업에는 과도한 스펙이 오히려 혼란을 키울 수 있음  
  - 예: “페이지에서 div를 중앙 정렬” 같은 작업에는  
    - “솔루션을 간결하게 유지하고, 불필요한 마크업이나 스타일을 추가하지 말 것” 정도면 충분  
  - 반대로 “토큰 갱신과 오류 처리가 포함된 OAuth 흐름 구현”처럼 복잡한 작업에는 상세 스펙이 필요  
  - 경험적인 기준은 **태스크 복잡도에 맞춰 스펙의 밀도를 조절하는 것**  
- ## 인간이 최종 품질 필터로 유지  
  - 스펙은 에이전트에 권한을 위임하지만, **최종 품질 책임은 개발자에게 있음**  
  - 에이전트가 기술적으로는 스펙을 충족했더라도, 느낌이나 맥락이 맞지 않으면 자신의 판단을 신뢰  
  - 필요하다면 스펙을 다시 정제하거나, 결과물을 직접 손보는 것도 자연스러운 과정  
  - Willison은 AI 에이전트와 일하는 것을 “아주 이상한 형태의 관리”이자, [“인간 인턴을 관리하는 것과 **불편할 정도로 닮아 있다**”](https://simonwillison.net/2025/Oct/7/vibe-engineering/) 고 비유  
  - 결국 명확한 지시(스펙), 충분한 컨텍스트, 실행 가능한 피드백을 제공하는 역할은 여전히 인간의 몫  
  
### 원칙 5: 테스트, 반복, 스펙 진화 (올바른 도구 활용)  
- 스펙 작성과 에이전트 구축을 한 번으로 끝나는 작업이 아니라 **반복 루프**로 인식  
  - 빠르게 테스트하고, 피드백을 모으고, 스펙을 다듬고, 도구로 검사를 자동화하는 흐름  
- 초기 스펙은 완성본이 아니라, **사이클의 출발점**  
- ## 지속적 테스트  
  - 모든 구현이 끝날 때까지 기다리지 말고, 주요 마일스톤이나 함수 단위로 테스트 또는 간단한 수동 검사 수행  
  - 실패가 발견되면 그대로 진행하지 말고, 먼저 스펙이나 프롬프트를 수정  
  - 자동화 테스트가 특히 효과적이며, 테스트가 있다면 에이전트가 `npm test` 같은 명령을 직접 실행하게 할 수 있음  
  - 테스트 실패 결과를 그대로 다음 프롬프트의 입력으로 사용  
    - 예: “출력이 X, Y, Z에서 스펙을 충족하지 못했으니 수정하라”  
  - 코드 → 테스트 → 수정 → 반복으로 이어지는 **에이전틱 루프**는 매우 강력한 방식  
- ## 스펙 자체 반복  
  - 에이전트가 오해했거나 요구사항 누락이 드러났다면, 문제를 덮지 말고 **스펙 문서를 먼저 수정**  
  - 수정된 스펙을 에이전트와 명시적으로 다시 동기화  
    - 예: “스펙을 다음과 같이 업데이트했다. 이 변경을 반영해 계획을 조정하거나 코드를 리팩터링하라”  
  - 스펙을 항상 **단일 진실의 원천**으로 유지  
  - 가능하다면 커밋 메시지나 노트로 버전 히스토리를 남겨, 무엇이 왜 바뀌었는지 추적  
- ## 컨텍스트 관리 및 메모리 도구 활용  
  - AI 에이전트의 컨텍스트와 지식 관리를 돕는 **도구 생태계**가 빠르게 성장 중  
  - **RAG(검색 증강 생성)** 패턴을 활용하면, 에이전트가 벡터 데이터베이스 같은 지식 베이스에서 필요한 정보만 즉시 가져올 수 있음  
  - 스펙이 매우 클 경우, 섹션을 임베딩해 두고 에이전트가 전체를 받는 대신 가장 관련 있는 부분만 검색하게 구성  
  - **MCP(Model Context Protocol)** 기반 프레임워크는 현재 태스크에 맞는 컨텍스트를 자동으로 제공  
  - [Context7(context7.com)](https://docs.digitalocean.com/products/gradient-ai-platform/concepts/context-management/) 같은 도구는 작업 중인 내용에 따라 문서에서 관련 스니펫을 자동으로 불러옴  
- ## 신중한 병렬화  
  - 일부 개발자는 여러 에이전트 인스턴스를 **서로 다른 태스크에 병렬로 실행**해 속도를 높임  
  - 예: 한 에이전트가 코드 생성, 다른 에이전트가 동시에 테스트 작성  
  - 이 방식을 택할 경우, 태스크가 정말로 독립적이거나 명확히 분리되어 있어야 충돌을 피할 수 있음  
  - 예: 두 에이전트가 동시에 같은 파일을 수정하지 않도록 제한  
  - 관리 부담을 줄이기 위해 초반에는 **최대 2~3개 에이전트**로 시작하는 것이 현실적  
- ## 버전 관리와 스펙 잠금  
  - Git 같은 버전 관리 도구로 에이전트의 작업을 꼼꼼히 추적  
  - AI를 활용할수록 [좋은 버전 관리 습관](https://simonwillison.net/2025/Oct/7/vibe-engineering/)의 중요성은 더 커짐  
  - 스펙 파일 자체를 리포지토리에 커밋해 변경 이력을 남김  
  - 에이전트도 git diff나 blame을 읽고 변경 맥락을 이해할 수 있음  
    - 실제로 LLM은 diff 해석에 상당히 능숙  
  - 스펙을 리포에 두면 개발자와 AI 모두 프로젝트의 진화를 함께 추적 가능  
  - Willison은 모델이 “Git에 맹렬하게 유능하다”고 표현  
- ## 비용과 속도 고려  
  - 대형 모델과 긴 컨텍스트를 쓰는 작업은 **느리고 비용이 많이 들 수 있음**  
  - 모델 선택을 전략적으로 분리  
    - 초기 초안이나 반복 작업에는 빠르고 저렴한 모델  
    - 최종 출력이나 복잡한 추론에는 가장 유능한(비싼) 모델  
  - 예: GPT-4나 Claude는 계획 수립과 핵심 단계에, 단순 확장이나 리팩터링은 로컬 모델이나 소형 API 모델에 맡김  
  - 테스트 실행 에이전트나 린터 에이전트는 상대적으로 작은 모델로도 충분  
  - 컨텍스트 크기도 관리 대상  
    - 5k 토큰이면 충분한 작업에 20k 토큰을 넣을 필요는 없음  
    - [토큰 수가 많아질수록 효율성이 떨어질 수 있음](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)  
- ## 모든 것을 모니터링하고 로깅할 것  
  - 복잡한 에이전트 워크플로우에서는 에이전트의 **행동과 출력 로그**가 필수  
  - 로그를 통해 에이전트가 의도에서 벗어났는지, 오류가 발생했는지 확인 가능  
  - 많은 프레임워크가 트레이스 로그를 제공하거나, 단계별 사고 과정을 출력하도록 지원  
  - 로그를 살펴보면 스펙이나 지시가 **어디서 잘못 해석됐는지** 드러남  
- ## 학습과 개선  
  - 각 프로젝트를 스펙 작성 역량을 다듬는 **학습 기회**로 삼기  
  - 특정 표현이 반복적으로 AI를 헷갈리게 하는지, 어떤 스펙 구조가 더 잘 지켜지는지 관찰 가능  
  - 이런 교훈을 다음 스펙에 적극 반영  
  - AI 에이전트 분야는 빠르게 진화 중이며, 새로운 도구와 모범 사례가 계속 등장  
  
### 흔히 저지르는 실수를 피하기  
- GitHub의 2,500개 이상 에이전트 파일을 분석한 결과, 실패의 가장 큰 원인은 **스펙과 지시가 지나치게 모호함**  
- ## 모호한 프롬프트  
  - “멋진 것 만들어줘”, “더 잘 작동하게 해줘” 같은 요청은 에이전트에게 **판단 기준 자체가 없음**  
  - 입력, 출력, 제약조건을 가능한 한 구체적으로 명시해야 함  
  - “당신은 도움이 되는 코딩 어시스턴트입니다” 같은 일반적인 역할 지정은 거의 효과 없음  
  - 반대로 “당신은 React 컴포넌트 테스트를 작성하는 테스트 엔지니어이며, 이 예시를 따르고 소스 코드는 절대 수정하지 않는다”처럼 **역할·범위·제약을 함께 지정**하면 훨씬 잘 작동  
- ## 요약 없는 과도한 컨텍스트  
  - 50페이지 문서를 그대로 프롬프트에 덤프하고 모델이 알아서 이해하길 기대하는 방식은 대부분 실패  
  - **계층적 요약**이나 RAG를 활용해 지금 태스크와 직접 관련된 내용만 드러내는 것이 필요  
  - 컨텍스트 길이를 늘리는 것은 컨텍스트의 **품질 부족을 대신해 주지 못함**  
- ## 인간 검토 건너뛰기  
  - Willison의 개인 원칙: “다른 사람에게 설명할 수 없는 코드는 커밋하지 않는다”  
  - 에이전트가 테스트를 통과하는 무언가를 만들었다고 해서, 그 코드가 곧바로 정확하고 안전하며 유지보수 가능하다는 뜻은 아님  
  - 특히 **중요한 코드 경로**는 항상 사람이 직접 검토  
  - AI 생성 코드는 겉보기엔 탄탄해 보여도, 테스트되지 않은 엣지 케이스에서 무너질 수 있다는 점에서 “카드로 만든 집” 비유가 잘 맞음  
- ## 바이브 코딩과 프로덕션 엔지니어링 혼동  
  - AI를 활용한 빠른 프로토타이핑, 이른바 “바이브 코딩”은 탐색 단계나 일회성 프로젝트에 적합  
  - 엄격한 스펙, 테스트, 검토 없이 그 결과물을 그대로 프로덕션에 배포하면 문제 발생 가능성 큼  
  - “바이브 코딩”과 “AI 지원 엔지니어링”은 분명히 구분해야 하며, 후자는 이 가이드에서 설명한 **규율과 절차**가 필요  
  - 지금 어떤 모드로 작업하고 있는지 스스로 인식하는 것이 중요  
- ## “치명적 삼중주” 무시  
  - Willison이 경고하는, AI 에이전트를 위험하게 만드는 세 가지 속성  
    - **속도**: 사람이 검토할 수 있는 속도보다 빠르게 결과를 생성  
    - **비결정성**: 같은 입력에도 실행마다 다른 출력  
    - **비용**: 검증을 충분히 하기보다 편법을 쓰도록 유도  
  - 스펙과 검토 프로세스는 이 세 가지를 모두 전제로 설계돼야 함  
  - 특히 속도가 검증 능력을 앞지르지 않도록 의식적인 제어 필요  
- ## 6가지 핵심 영역 누락  
  - 스펙이 Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries를 다루지 않으면, 에이전트가 작업에 필요한 중요한 정보를 놓치기 쉬움  
  - 에이전트에게 넘기기 전에 **6가지 영역 체크리스트**로 한 번 더 점검하는 것이 안전  
  
### 결론  
  
- AI 코딩 에이전트를 위한 효과적인 스펙 작성은 **탄탄한 소프트웨어 엔지니어링 원칙**과 LLM의 특성을 이해하고 이에 맞게 조정하는 접근이 함께 필요  
- 모든 것은 목적을 또렷하게 잡는 것에서 시작하며, 그 위에서 AI가 계획과 세부를 확장하도록 역할을 분담  
- 스펙은 메모가 아니라 **진지한 설계 문서**로 다뤄야 하며, 6가지 핵심 영역을 포함하고 툴체인과 연결된 **실행 가능한 아티팩트**로 취급  
- 한 번에 모든 것을 주기보다, 작업 단위별로 나눠 제공해 에이전트의 집중을 유지  
  (요약 TOC, 서브에이전트, 병렬 오케스트레이션은 대규모 스펙을 다루기 위한 실질적인 수단)  
- **3단계 경계(Always / Ask first / Never)**, 자가 검사, 적합성 테스트를 통해 AI가 빠지기 쉬운 함정을 미리 차단  
- 스펙과 구현을 고정된 결과물이 아니라 **반복 과정**으로 다루고, 테스트와 피드백을 통해 스펙과 코드를 함께 계속 다듬어 나가는 것이 핵심  
- 이 가이드라인을 따르면, AI 에이전트가 대규모 컨텍스트에서 방향을 잃거나 헛소리로 빠질 가능성을 **눈에 띄게 줄일 수 있음**

## Comments



### Comment 49671

- Author: gomjellie
- Created: 2026-01-22T11:27:26+09:00
- Points: 1

AI 번역이긴 하지만 한글 번역본이 있어서 링크 공유드립니다.   
  
https://rosetta.page/post/번역-ai-에이전트를-위한-좋은-스펙-작성법-R2eE5

### Comment 49494

- Author: qor0923
- Created: 2026-01-20T08:50:39+09:00
- Points: 1

감사합니다.

### Comment 49478

- Author: googol
- Created: 2026-01-19T16:19:54+09:00
- Points: 1

개인적으로 SDD(Specs Driven Development)로 프로젝트를 개발 했을 때, 처음에는 확실한 생산성 향상을 느꼈지만 아직 모든 코드를 스펙 기반으로 작성할 수 없고 직접 수정이 필요할 때마다 코드와 스펙을 같이 업데이트 해야 하기 때문에 오히려 생산성이 저하되는 경험을 했습니다.