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

핵심 요약

AI 에이전트에게는 "많이"가 아니라 "똑똑하게" 쓴 스펙이 필요합니다.

명확한 목적, 구조화된 문서, 작은 단위 작업, 자기검사와 인간 검토, 지속적인 수정이 좋은 스펙의 핵심입니다.

이 글은 사람 대신 일하는 "디지털 인턴"을 잘 관리하기 위한 스펙 작성 기술이라고 생각하면 이해가 쉽습니다.

1. AI 스펙의 목적: 모델을 "덜 헤매게" 만드는 설계도

AI에게 주는 스펙은 인간 동료에게 전달하는 설계 문서와 비슷하지만, 몇 가지 중요한 차이가 있습니다.

모델은 긴 문서를 모두 정확히 기억하지 못하고, 동시에 너무 많은 요구사항이 들어오면 점점 더 많이 놓칩니다. 그래서 "상세하지만 과하지 않고", "구조화되어 있으며", "작업 단위로 쪼개진" 스펙이 필요합니다.

좋은 스펙의 목표는 단순합니다. 모델이 엉뚱한 방향으로 질주하거나, 중간에 요구사항을 잊어버리거나, 코드만 잔뜩 생성하고 실제 요구와 어긋나는 일을 최소화하는 것입니다.

이때 스펙은 단순한 요구 목록이 아니라, 프로젝트의 공통 언어이자 "진짜 소스 오브 트루스(source of truth)" 역할을 해야 합니다. 사람과 AI가 모두 참조하는 단일 기준점이 될수록, 프로젝트의 일관성이 높아집니다.

2. 먼저 큰 그림: 고수준 목표를 적고, 세부는 AI가 초안을 쓰게 만들기

스펙을 처음부터 끝까지 인간이 완벽히 써 내려가려 하면, 금방 RFC 수준으로 부풀고 모델에게도 과부하가 걸립니다.

더 효과적인 방식은 "제품 기획서" 수준의 고수준 설명으로 출발해, 세부 계획은 AI에게 초안을 쓰게 하는 것입니다. 예를 들어 "소규모 팀을 위한 할 일 관리 웹앱: 계정, DB, 간단한 UI 필요" 정도만 명확히 적고, 나머지는 AI에게 "목표, 기능, 제약, 단계별 계획을 포함한 상세 스펙 초안을 작성하라"고 요청합니다.

이렇게 생성한 스펙 초안은 첫 번째 산출물입니다. 이후 사람은 이 문서를 검토하며 기능, 아키텍처, 보안, 테스트 전략 등을 수정해 나갑니다. 이 단계에서 충분히 토론하고 수정해 두면, 실제 코드 생성 단계에서 엉뚱한 구현이 나올 위험이 크게 줄어듭니다.

가능하다면 "코드는 아직 건드리지 말고, 기존 코드베이스를 읽고 계획만 세우는 모드"를 활용해 스펙과 계획을 먼저 고도화한 후에 실행 모드로 넘어가는 것이 좋습니다. 이렇게 하면 모델이 코드부터 마구 생성하는 흔한 사고를 막을 수 있습니다.

3. 좋은 스펙의 형식: PRD + SRS처럼 구조화된 문서로 만들기

AI에게 주는 스펙은 자유로운 메모가 아니라, PRD(제품 요구사항 문서)나 SRS(소프트웨어 요구사항 명세)처럼 구조가 명확한 문서일 때 효과가 큽니다.

GitHub의 실제 사례 분석에 따르면, 잘 작동하는 스펙에는 공통된 여섯 영역이 있습니다. 명령, 테스트 방법, 프로젝트 구조, 코드 스타일, Git/브랜치 전략, 그리고 "절대 건드리면 안 되는 경계"입니다. 이 여섯 가지가 빠지면, AI는 빌드/테스트 방법을 추측하거나, 디렉터리를 잘못 건드리거나, 스타일이 제각각인 코드를 만들어 내기 쉽습니다.

예를 들어 명령 부분에서는 단순히 "테스트 있음"이 아니라 npm test, pytest -v 같은 실제 명령을 명시해야 합니다. 구조 부분에서는 src/, tests/, docs/와 같이 디렉터리 역할을 분명히 나누고, 스타일은 실제 코드 예시 하나로 보여주는 편이 훨씬 잘 전달됩니다.

이 문서는 보통 마크다운으로 작성하고, 제목과 섹션을 명확히 나눕니다. "프로젝트 개요, 기술 스택, 명령, 구조, 스타일, Git 규칙, 경계"처럼 일관된 형식을 따르면 모델이 정보를 찾고 이해하기 쉬워집니다. 중요한 점은 "간단하게 보이지만 필요한 곳에는 충분히 구체적"이어야 한다는 것입니다.

4. 스펙은 "살아있는 문서": 버전 관리와 단계별 워크플로

스펙은 한 번 쓰고 끝나는 문서가 아니라, 코드와 함께 계속 업데이트되는 살아있는 아티팩트여야 합니다.

많은 팀은 스펙을 Git에 커밋하고, 기능 변경이나 설계 변경이 있으면 스펙부터 업데이트합니다. 이 방식은 "문서와 구현이 어긋나기 시작한 뒤, 아무도 문서를 믿지 않게 되는 상황"을 막아줍니다. AI에게도, 사람에게도 스펙이 진짜 기준점으로 남게 됩니다.

실무에서는 스펙 중심으로 작업 단계를 나누는 것이 좋습니다. 먼저 사용자 관점에서 무엇을 만들지 정의하고(목적, 페르소나, 사용자 여정), 다음에 기술 스택과 아키텍처, 제약 조건을 정리한 기술 계획을 작성하고, 그 다음 이 계획을 작은 작업 단위(예: "회원가입 엔드포인트 구현" 수준)로 쪼갠 뒤, 마지막에 구현 단계로 들어가는 식입니다.

각 단계마다 "이제 다음 단계로 넘어가도 되는가?"를 확인하는 게이트를 두면, AI가 불완전한 계획을 바탕으로 코드를 양산하는 "하우스 오브 카드" 상황을 크게 줄일 수 있습니다.

5. 한 번에 다 시키지 말기: 작은 작업, 작은 컨텍스트

모델에게 모든 요구사항과 전체 코드와 긴 문서를 한 번에 던지면, 이론적으로는 "모든 정보를 안다"가 되지만 실제로는 성능이 떨어집니다.

연구와 실무 모두, 많은 지침을 한 번에 주면 모델이 뒤쪽 지침을 잘 따르지 못하는 현상을 보여줍니다. 즉, 10개의 상세 규칙을 한 번에 전달하면 앞 몇 개에만 충실하고 나머지는 점점 잊어버리기 쉽습니다.

그래서 좋은 전략은 "분할 정복"입니다. 스펙이 길다면, 백엔드 API, 프론트엔드 UI, 인증, 데이터 모델 등으로 논리적으로 나누고, 각 작업에서는 해당 부분만 컨텍스트로 공급합니다. 예를 들어 DB 스키마를 만드는 단계에서는 DB 섹션과 전역 제약만 제공하고, UI 세부 스펙은 잠시 빼두는 식입니다.

큰 스펙을 다뤄야 한다면, 먼저 스펙를 기반으로 섹션별 요약과 확장 목차를 만들게 한 뒤, 이 요약만 상시 컨텍스트에 유지하고 필요할 때 해당 섹션 전문을 추가로 보여주는 패턴도 유용합니다. 이렇게 하면 모델은 "전체 구조의 지도"를 가지고 있으면서도, 실제 작업 시에는 필요한 부분만 자세히 보는 사람 개발자와 비슷한 방식으로 일할 수 있습니다.

6. 단일 에이전트 vs 다중 에이전트: 언제 나눠서 시킬 것인가

모든 일을 한 에이전트에게 맡길 수도 있고, 역할을 나눠 여러 에이전트에 분배할 수도 있습니다.

단일 에이전트는 설정이 단순하고 디버깅이 쉽습니다. 작은 프로젝트, 독립적인 모듈, 초기 프로토타입에는 이 방식이 충분합니다. 다만 프로젝트가 커질수록 컨텍스트가 과부하되고, 한 모델이 모든 영역을 동시에 기억해야 해서 품질이 떨어질 수 있습니다.

반대로 다중 에이전트는 역할을 쪼개어 효율을 높입니다. 예를 들어 "백엔드 설계 에이전트", "프론트엔드 구현 에이전트", "테스트 작성 에이전트", "보안 리뷰 에이전트"처럼 전문화해서 각자에게 해당 스펙 부분만 주면, 각 에이전트는 더 작은 문맥 안에서 일할 수 있습니다. 동시에 서로 다른 부분을 병렬로 진행하는 것도 가능합니다.

다만 이 경우에는 조율이 중요합니다. 서로 같은 파일을 수정하지 않도록 경계를 정하고, API 계약이나 데이터 모델 같은 공유 컨텍스트는 명확히 정의해 두어야 합니다. 필요하다면 "아키텍트 역할"을 하는 상위 에이전트를 두어 각 하위 에이전트의 결과를 검토하고 일관성을 확인하게 할 수 있습니다.

7. 경계와 규칙: Always / Ask / Never 삼단계로 통제하기

AI에게 "하지 말 것"만 잔뜩 나열해 두면, 실제로 어디까지는 자유롭게 해도 되는지 알기 어렵습니다.

GitHub의 많은 프로젝트를 분석한 결과, 가장 효과적인 방식은 행동을 세 구획으로 나누는 것이었습니다. 항상 해도 되는 것, 하기 전에 반드시 물어봐야 하는 것, 절대 해서는 안 되는 것입니다.

예를 들어 "항상 실행" 영역에는 테스트 실행, 스타일 가이드 준수, 에러 로깅 같은 규칙이 들어갈 수 있습니다. "물어보기" 영역에는 DB 스키마 변경, 새 외부 의존성 추가, CI 설정 변경 같은 고위험 작업이 들어갑니다. "절대 금지" 영역에서는 비밀키 커밋, node_modules/ 수정, 실패한 테스트 삭제 등이 대표적입니다.

이 삼단계 구조는 모델에게 행동 기준을 훨씬 더 명확하게 제공합니다. 안전한 일은 스스로 처리하게 하고, 사람 확인이 필요한 지점에서는 질문을 유도하며, 정말 위험한 행동은 아예 시도하지 않도록 막는 식입니다.

8. 자기검사, 테스트, 그리고 "AI 심판" 활용하기

좋은 스펙은 단지 "이렇게 해라"로 끝나지 않고, "제대로 했는지 확인하는 방법"까지 포함합니다.

가장 단순한 수준에서는, 모델에게 작업 후 스스로 스펙을 다시 훑어보고 어떤 요구사항을 충족했는지, 어떤 항목이 미흡한지 목록으로 적게 할 수 있습니다. 이 자체가 일종의 자기검사 루프입니다.

테스트 관점에서는, 스펙에 미리 입력/출력 예시나 필수 통과 테스트 조건을 적어둘 수 있습니다. 코드가 만들어진 뒤, 모델이 이 테스트를 실제로 실행하거나, 최소한 "머릿속 시뮬레이션"을 통해 요구사항 충족 여부를 점검하게 할 수 있습니다. 별도의 "테스트 전담 에이전트"를 두어 코드 에이전트가 만든 결과를 끊임없이 검증하게 만드는 패턴도 있습니다.

더 나아가, 다른 모델이나 별도 인스턴스를 "심판(LLM-as-a-judge)"으로 사용해 스타일, 가독성, 아키텍처 준수 여부를 평가하게 할 수 있습니다. 예를 들어 "이 코드는 우리 스타일 가이드에 맞는지, 어긴 부분은 어디인지 평가하라"고 요청해 2차 검토를 맡기는 방식입니다. 이중, 삼중의 검사 레이어를 쌓을수록 "겉보기에는 돌아가지만 사실 엉망인 코드"를 줄일 수 있습니다.

9. 사람의 전문성을 스펙에 녹여넣기

AI는 일반적인 패턴에는 강하지만, 프로젝트나 도메인 특유의 함정에는 취약합니다. 이 부분은 사람의 경험을 통해 보완해야 합니다.

예를 들어 특정 외부 API의 이상한 버그, 특정 라이브러리의 메모리 이슈, 실제 비즈니스에서 자주 발생하는 경계 케이스 같은 것들은 스펙에 명시적으로 담는 것이 좋습니다. "이 경우에는 이렇게 하지 말고, 이런 우회 방법을 쓰라"와 같은 주석은 AI에게 매우 큰 힌트가 됩니다.

또한 팀의 선호 스타일이나 철학도 적어 두어야 합니다. React에서 함수형 컴포넌트를 우선한다든지, API 오류 응답 형식을 특정 JSON 구조로 통일한다든지, 예시를 하나만 보여주어도 모델은 이를 기준으로 삼습니다. 짧은 예제 코드와 함께 "우리가 원하는 방식"을 시각적으로 보여주는 것이 문장 열 줄보다 더 강력할 때가 많습니다.

중요한 것은 이 문서를 "AI만을 위한 것"으로 보지 않는 것입니다. 이 스펙은 동시에 후임 개발자를 위한 온보딩 자료이기도 하고, 미래의 나 자신을 위한 기억 보관소이기도 합니다. AI와 사람 모두에게 유용한 형태가 가장 이상적입니다.

10. 반복과 도구: 스펙도 테스트하고 리팩터링하라

스펙 역시 코드처럼 "한 번에 완벽하게" 나오는 경우는 드뭅니다. 사용해 보면서 계속 개선해야 합니다.

AI가 스펙을 오해했다면, 그건 종종 스펙이 애매했기 때문이기도 합니다. 이런 경우 "모델이 왜 이렇게 행동했는지"를 추적하고, 그 원인을 스펙 표현 수정으로 되돌려야 합니다. 좋은 팀은 이런 깨달음을 다음 프로젝트 스펙에도 재사용 가능한 패턴으로 축적합니다.

긴 스펙을 다루기 위해 RAG(검색 기반 컨텍스트 주입), MCP(모델 컨텍스트 프로토콜)나 유사한 도구를 활용해 "지금 하는 작업에 필요한 부분만 자동으로 불러오기" 같은 구조를 만드는 것도 점점 중요해지고 있습니다. 큰 한 개의 프롬프트보다, 잘 관리된 지식 베이스 + 검색 조합이 더 안정적입니다.

마지막으로, 모델 비용과 속도를 항상 의식해야 합니다. 계획 수립, 아키텍처 논의 등 복잡한 추론이 필요한 부분은 강력한 모델을, 간단한 변환이나 반복 작업은 더 작은 모델을 쓰는 식으로 나누면 비용 효율이 좋아집니다. 여러 에이전트를 돌릴수록 로그와 히스토리를 꼼꼼히 남기고, 이상 행동이 보이면 "프롬프트와 스펙을 디버깅한다"는 관점으로 접근하는 것이 좋습니다.

인사이트

AI 에이전트는 뛰어난 실력을 가진 동시에, 규칙을 대충 이해하고도 자신 있게 행동하는 "디지털 인턴"에 가깝습니다.

이 인턴에게 필요한 것은 막연한 "잘 부탁해요"가 아니라, 명확한 역할 정의, 구조화된 스펙, 구체적인 경계, 자동·수동 검사의 조합, 그리고 꾸준한 피드백입니다.

실무에서 바로 적용할 수 있는 최소 세 가지를 정리하면 이렇습니다. 먼저, 새로운 기능을 시작할 때마다 "한 페이지짜리 고수준 스펙"을 먼저 쓰고, AI에게 상세 스펙 초안을 만들게 한 뒤 사람 눈으로 반드시 리뷰합니다. 다음으로, 프로젝트 루트에 SPEC.md를 두고 명령, 테스트 방법, 구조, 스타일, Git 규칙, 경계를 모두 명시한 후, 모든 세션에서 이 파일을 기본 컨텍스트로 참조합니다. 마지막으로, 큰 작업은 무조건 작은 단위로 쪼개고, 각 단위마다 "해야 할 일 + 필요한 스펙 조각 + 완료 기준(테스트나 체크리스트)"를 명시한 뒤 진행합니다.

이 세 가지만 실천해도, "모델에 길게 설명했는데도 계속 엉뚱한 코드를 만드는" 상황이 크게 줄어듭니다. 이후에는 각 팀과 프로젝트에 맞게 스펙 양과 형식을 실험하며, 자신만의 AI 스펙 작성 스타일을 만들어 가면 됩니다.

출처 및 참고 : AddyOsmani.com - How to write a good spec for AI agents