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

• 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에서도 “무엇을 왜 만드는지에 대한 고수준 설명을 주고, 코딩 에이전트가 사용자 경험과 성공 기준 중심으로 상세 사양을 만들도록 한다”는 흐름을 강조

원칙 2: 스펙을 전문적인 PRD(또는 SRS)처럼 구조화

• AI 스펙을 단순한 메모 모음이 아니라, 명확한 섹션을 갖춘 구조화된 문서로 다루는 것이 중요
• PRD나 시스템 설계 문서처럼 포괄적이고 정돈된 형태가, 내용을 문자 그대로 해석하는 AI에게 특히 잘 맞음
• GitHub에서 2,500개 이상의 에이전트 설정 파일을 분석한 결과, 효과적인 스펙에는 공통적으로 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 엔지니어들 역시 <background>, <instructions>, <tools>, <output_format>처럼 명확히 구분된 섹션 구성을 권장

• 스펙을 툴체인에 통합

  • 스펙을 단순 문서가 아니라, 버전 관리와 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와 함께 결정을 내리거나 새로운 사실이 드러날 때마다 계속 업데이트
  • 스펙 기반 워크플로우에서는 스펙이 구현, 테스트, 태스크 분해를 주도하며, 스펙이 검증되기 전에는 다음 단계로 넘어가지 않음
  • 이 스펙은 AI만을 위한 문서가 아니라, 개발자가 전체 흐름을 감독하고 AI의 결과물이 실제 요구사항을 충족하는지 확인하는 핵심 도구

원칙 3: 태스크를 모듈화된 프롬프트와 컨텍스트로 분할

• 하나의 거대한 프롬프트에 모든 것을 담기보다, 한 번에 하나의 태스크에만 집중하도록 컨텍스트를 제공
• 전체 프로젝트의 요구사항·코드·지시를 단일 프롬프트에 담으면, 오히려 혼란을 키우기 쉬움
• 토큰 한계에 걸릴 위험뿐 아니라, “지시의 저주(curse of instructions)” 로 모델의 집중력이 급격히 떨어질 수 있음

• 지시의 저주

  • 연구 결과에 따르면, 프롬프트에 지시나 데이터를 많이 쌓을수록 각 지시를 정확히 따르는 성능이 눈에 띄게 하락
  • GPT-4나 Claude 같은 강력한 모델도, 많은 요구사항을 동시에 만족시키라는 요청에는 어려움을 겪음
  • 예를 들어 10개의 상세 규칙을 불릿으로 주면, 처음 몇 개만 지키고 뒤쪽 규칙은 점점 무시하는 경향이 나타남
  • 더 나은 전략은 반복적 집중: 한 번에 하나의 하위 문제에만 집중시키고, 끝난 뒤 다음 문제로 넘어가는 방식

• 스펙을 단계나 컴포넌트로 분할

  • 스펙 문서가 길거나 다루는 범위가 넓다면, 여러 부분으로 나누는 것을 고려
  • 예: “Backend API Spec”과 “Frontend UI Spec”을 별도 섹션으로 분리
  • 백엔드 작업을 할 때는 프론트엔드 스펙을 항상 함께 줄 필요는 없음
  • 멀티 에이전트 환경에서는 각 영역별로 별도의 에이전트나 하위 프로세스를 둘 수도 있음
  • DigitalOcean AI 가이드에서도 “인증 태스크와 데이터베이스 스키마 변경을 한 번에 섞지 말라”고 경고

• 대규모 스펙을 위한 확장 TOC/요약

  • 에이전트에게 전체 스펙을 요약한 확장 목차(TOC) 를 먼저 작성하게 하는 방식
  • 각 섹션을 몇 가지 핵심 포인트나 키워드로 압축하고, 세부 내용이 있는 위치를 함께 참조
  • 예: “Security: HTTPS 사용, API 키 보호, 입력 검증 구현 (전체 스펙 §4.2 참조)”
  • 이렇게 계층적 요약을 만들어 두면, 프롬프트에는 큰 그림만 유지하고 세부는 필요할 때만 제공 가능
  • 확장 TOC는 일종의 인덱스 역할을 하며, 에이전트가 “아, 보안 섹션이 있구나”를 인지하고 해당 부분을 요청하게 만듦
  • 이런 계층적 요약 방식 은 LLM이 고수준 구조를 유지하는 데 도움이 됨

• 서브에이전트 또는 “스킬” 활용

  • Anthropic이 말하는 서브에이전트(또는 “스킬”)처럼, 역할이 분리된 다중 에이전트 활용 가능
  • 각 서브에이전트는 특정 전문 영역에 맞게 설정되고, 그 영역에 해당하는 스펙 일부만 제공받음
  • 예: Database Designer 서브에이전트는 데이터 모델 섹션만, API Coder 서브에이전트는 API 엔드포인트 스펙만 인지
  • 이렇게 하면 각 에이전트가 더 작은 컨텍스트와 더 또렷한 역할을 가져 정확도 향상과 병렬 작업 이 가능
  • Claude Code는 자체 시스템 프롬프트와 도구를 가진 서브에이전트를 정의하는 기능을 지원

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

  • 여러 에이전트를 동시에 돌리는 방식이 개발자 생산성의 다음 단계로 떠오르고 있음
  • 하나의 에이전트가 끝나길 기다리지 않고, 서로 겹치지 않는 작업에 병렬로 에이전트를 투입
  • Simon Willison은 이를 “병렬 코딩 에이전트를 받아들이는 것” 이라 표현하며, 놀라울 정도로 효과적이지만 정신적으로는 꽤 피곤하다고 언급
  • 핵심은 에이전트들이 서로의 작업을 방해하지 않도록 태스크 범위를 명확히 나누는 것
  • LangGraph나 OpenAI Swarm 같은 오케스트레이션 프레임워크가 이런 조율을 돕고,
  • Chroma 같은 벡터 데이터베이스를 공유 메모리로 쓰면, 중복 프롬프팅 없이 공통 컨텍스트에 접근 가능

• 단일 vs 멀티 에이전트: 언제 사용할 것인가

  측면 단일 에이전트 병렬/멀티 에이전트

  장점	설정이 단순하고 오버헤드가 낮으며, 디버그와 흐름 추적이 쉬움	처리량이 높고, 복잡한 상호의존성 대응과 도메인별 전문화 가능
  단점	대형 프로젝트에서 컨텍스트 과부하, 반복 속도 저하, 단일 장애점	조율 비용 증가, 충돌 가능성, 공유 메모리 필요
  적합한 경우	격리된 모듈, 중·소형 프로젝트, 초기 프로토타이핑	대규모 코드베이스, 코딩·테스트·리뷰 분리, 독립적인 기능 개발
  팁	스펙 요약 활용, 태스크별 컨텍스트 갱신, 세션 자주 리셋	초반에는 2~3개 에이전트로 제한, MCP로 도구 공유, 경계 명확화

• 각 프롬프트를 하나의 태스크/섹션에 집중

  • 복잡한 멀티 에이전트 환경이 없어도, 수동으로 충분히 모듈성을 강제할 수 있음
  • 예: 스펙 작성 후 “Step 1: 데이터베이스 스키마 구현” 단계에서는 스펙의 Database 섹션만 제공
  • 주요 태스크가 바뀔 때마다 컨텍스트를 새로 구성해, 오래되거나 관련 없는 정보로 인한 산만함을 줄임
  • 일부 가이드에서는 주요 기능 전환 시 새 세션을 시작 해 컨텍스트를 정리하라고 권장

• 인라인 지시문과 코드 TODO 활용

  • 코드에 // TODO 주석으로 해야 할 일을 적어두고, 에이전트가 하나씩 채우게 하는 방식
  • 각 TODO가 작은 태스크에 대한 미니 스펙 역할을 함
  • 결과적으로 AI가 “이 스펙 스니펫에 맞춰 이 함수만 구현하라”는 식으로 매우 좁은 범위에 집중하게 됨

원칙 4: 자가 검사, 제약조건, 인간 전문성 내장

• 스펙을 단순히 에이전트의 할 일 목록이 아니라, 품질을 관리하는 가이드로 다루고 자신의 전문성을 적극적으로 반영할 것
• 좋은 스펙은 AI가 어디에서 실수할 수 있는지를 미리 짚고, 그 지점에 가드레일을 세워 둠
• 도메인 지식, 엣지 케이스, 각종 “주의사항”을 담아 AI가 맥락 없는 진공 상태에서 작동하지 않게 함
• 스펙을 AI의 코치이자 심판으로 생각하면 이해가 쉬움: 올바른 접근은 유도하고, 잘못된 행동은 즉시 제동
• GitHub의 2,500개 이상 에이전트 파일 분석 결과, 가장 효과적인 스펙은 단순한 금지 목록이 아니라 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은 견고한 테스트 스위트가 에이전트에게 사실상 슈퍼파워를 준다고 표현
  • 테스트 실패 시 즉각 검증하고 반복할 수 있기 때문
  • 서브에이전트 구성에서는 스펙 기준을 받아 코드 출력을 계속 검증하는 전용 테스트 에이전트 를 둘 수도 있음

• 도메인 지식 반영

  • 스펙에는 경험 있는 개발자나 맥락을 아는 사람만 알고 있는 현실적인 인사이트를 담아야 함
  • 예: 이커머스 에이전트를 만들 때 “products”와 “categories”가 다대다 관계라는 점을 명확히 적어 둠
    • AI가 알아서 추론할 것이라 기대하지 않음
  • 특정 라이브러리가 까다롭다면, 자주 빠지는 함정이나 주의점도 함께 명시
  • 자신의 멘토십을 스펙에 녹여내는 방식
    • 예: “라이브러리 X 사용 시 버전 Y에서 메모리 누수 문제가 있으니 우회책 Z 적용”

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

  • 철저한 스펙이 중요하지만, 전문성의 일부는 언제 단순하게 가야 하는지 아는 데 있음
  • 비교적 단순하고 격리된 작업에는 과도한 스펙이 오히려 혼란을 키울 수 있음
  • 예: “페이지에서 div를 중앙 정렬” 같은 작업에는
    • “솔루션을 간결하게 유지하고, 불필요한 마크업이나 스타일을 추가하지 말 것” 정도면 충분
  • 반대로 “토큰 갱신과 오류 처리가 포함된 OAuth 흐름 구현”처럼 복잡한 작업에는 상세 스펙이 필요
  • 경험적인 기준은 태스크 복잡도에 맞춰 스펙의 밀도를 조절하는 것

• 인간이 최종 품질 필터로 유지

  • 스펙은 에이전트에 권한을 위임하지만, 최종 품질 책임은 개발자에게 있음
  • 에이전트가 기술적으로는 스펙을 충족했더라도, 느낌이나 맥락이 맞지 않으면 자신의 판단을 신뢰
  • 필요하다면 스펙을 다시 정제하거나, 결과물을 직접 손보는 것도 자연스러운 과정
  • Willison은 AI 에이전트와 일하는 것을 “아주 이상한 형태의 관리”이자, “인간 인턴을 관리하는 것과 불편할 정도로 닮아 있다” 고 비유
  • 결국 명확한 지시(스펙), 충분한 컨텍스트, 실행 가능한 피드백을 제공하는 역할은 여전히 인간의 몫

원칙 5: 테스트, 반복, 스펙 진화 (올바른 도구 활용)

• 스펙 작성과 에이전트 구축을 한 번으로 끝나는 작업이 아니라 반복 루프로 인식
  • 빠르게 테스트하고, 피드백을 모으고, 스펙을 다듬고, 도구로 검사를 자동화하는 흐름
• 초기 스펙은 완성본이 아니라, 사이클의 출발점

• 지속적 테스트

  • 모든 구현이 끝날 때까지 기다리지 말고, 주요 마일스톤이나 함수 단위로 테스트 또는 간단한 수동 검사 수행
  • 실패가 발견되면 그대로 진행하지 말고, 먼저 스펙이나 프롬프트를 수정
  • 자동화 테스트가 특히 효과적이며, 테스트가 있다면 에이전트가 npm test 같은 명령을 직접 실행하게 할 수 있음
  • 테스트 실패 결과를 그대로 다음 프롬프트의 입력으로 사용
    • 예: “출력이 X, Y, Z에서 스펙을 충족하지 못했으니 수정하라”
  • 코드 → 테스트 → 수정 → 반복으로 이어지는 에이전틱 루프는 매우 강력한 방식

• 스펙 자체 반복

  • 에이전트가 오해했거나 요구사항 누락이 드러났다면, 문제를 덮지 말고 스펙 문서를 먼저 수정
  • 수정된 스펙을 에이전트와 명시적으로 다시 동기화
    • 예: “스펙을 다음과 같이 업데이트했다. 이 변경을 반영해 계획을 조정하거나 코드를 리팩터링하라”
  • 스펙을 항상 단일 진실의 원천으로 유지
  • 가능하다면 커밋 메시지나 노트로 버전 히스토리를 남겨, 무엇이 왜 바뀌었는지 추적

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

  • AI 에이전트의 컨텍스트와 지식 관리를 돕는 도구 생태계가 빠르게 성장 중
  • RAG(검색 증강 생성) 패턴을 활용하면, 에이전트가 벡터 데이터베이스 같은 지식 베이스에서 필요한 정보만 즉시 가져올 수 있음
  • 스펙이 매우 클 경우, 섹션을 임베딩해 두고 에이전트가 전체를 받는 대신 가장 관련 있는 부분만 검색하게 구성
  • MCP(Model Context Protocol) 기반 프레임워크는 현재 태스크에 맞는 컨텍스트를 자동으로 제공
  • Context7(context7.com) 같은 도구는 작업 중인 내용에 따라 문서에서 관련 스니펫을 자동으로 불러옴

• 신중한 병렬화

  • 일부 개발자는 여러 에이전트 인스턴스를 서로 다른 태스크에 병렬로 실행해 속도를 높임
  • 예: 한 에이전트가 코드 생성, 다른 에이전트가 동시에 테스트 작성
  • 이 방식을 택할 경우, 태스크가 정말로 독립적이거나 명확히 분리되어 있어야 충돌을 피할 수 있음
  • 예: 두 에이전트가 동시에 같은 파일을 수정하지 않도록 제한
  • 관리 부담을 줄이기 위해 초반에는 최대 2~3개 에이전트로 시작하는 것이 현실적

• 버전 관리와 스펙 잠금

  • Git 같은 버전 관리 도구로 에이전트의 작업을 꼼꼼히 추적
  • AI를 활용할수록 좋은 버전 관리 습관의 중요성은 더 커짐
  • 스펙 파일 자체를 리포지토리에 커밋해 변경 이력을 남김
  • 에이전트도 git diff나 blame을 읽고 변경 맥락을 이해할 수 있음
    • 실제로 LLM은 diff 해석에 상당히 능숙
  • 스펙을 리포에 두면 개발자와 AI 모두 프로젝트의 진화를 함께 추적 가능
  • Willison은 모델이 “Git에 맹렬하게 유능하다”고 표현

• 비용과 속도 고려

  • 대형 모델과 긴 컨텍스트를 쓰는 작업은 느리고 비용이 많이 들 수 있음
  • 모델 선택을 전략적으로 분리
    • 초기 초안이나 반복 작업에는 빠르고 저렴한 모델
    • 최종 출력이나 복잡한 추론에는 가장 유능한(비싼) 모델
  • 예: GPT-4나 Claude는 계획 수립과 핵심 단계에, 단순 확장이나 리팩터링은 로컬 모델이나 소형 API 모델에 맡김
  • 테스트 실행 에이전트나 린터 에이전트는 상대적으로 작은 모델로도 충분
  • 컨텍스트 크기도 관리 대상
    • 5k 토큰이면 충분한 작업에 20k 토큰을 넣을 필요는 없음
    • 토큰 수가 많아질수록 효율성이 떨어질 수 있음

• 모든 것을 모니터링하고 로깅할 것

  • 복잡한 에이전트 워크플로우에서는 에이전트의 행동과 출력 로그가 필수
  • 로그를 통해 에이전트가 의도에서 벗어났는지, 오류가 발생했는지 확인 가능
  • 많은 프레임워크가 트레이스 로그를 제공하거나, 단계별 사고 과정을 출력하도록 지원
  • 로그를 살펴보면 스펙이나 지시가 어디서 잘못 해석됐는지 드러남

• 학습과 개선

  • 각 프로젝트를 스펙 작성 역량을 다듬는 학습 기회로 삼기
  • 특정 표현이 반복적으로 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 에이전트가 대규모 컨텍스트에서 방향을 잃거나 헛소리로 빠질 가능성을 눈에 띄게 줄일 수 있음