AI 코딩 에이전트 효과 높이는 스펙 작성법과 실전 가이드

핵심 요약

좋은 스펙은 "많이"가 아니라 "정확히 필요한 만큼"의 정보로 AI를 조준해 주는 문서다.

고수준 목표 → 구조화된 스펙 → 작게 쪼갠 작업 → 자동·수동 검증 → 스펙 업데이트라는 루프를 돌릴 때 AI 코딩 에이전트가 가장 잘 작동한다.

PRD처럼 섹션을 나누고, 작업은 쪼개고, 테스트와 경계 조건을 스펙에 심어 두는 것이 핵심이다.

AI에게 스펙이 왜 중요한가

AI 코딩 에이전트는 "잘 쓴 스펙"을 만났을 때 비로소 실력을 발휘한다.

거대한 요구사항을 한 번에 던지면, 컨텍스트 한도도 문제지만 모델의 "주의력"이 분산되면서 핵심을 놓치기 쉽다.

반대로 목표가 분명하고, 범위가 적절히 좁혀진 스펙을 주면, 세부 구현·보일러플레이트·계획 elaboration 같은 일을 AI가 알아서 채워 넣어 준다.

이 글의 전체 메시지는 간단하다.
"처음부터 RFC처럼 다 쓰려 하지 말고, AI에게 잘 던져서 같이 만들어라. 그리고 스펙을 프로젝트의 '살아 있는 소스 오브 트루스'로 관리하라."

고수준 비전으로 시작해 스펙을 AI와 함께 확장하기

스펙은 "아주 잘 정리된 상세 문서"가 아니라, "명확한 방향성을 가진 고수준 비전"에서 출발해야 한다.

처음에는 다음 정도면 충분하다.
누가 쓰는지, 어떤 문제를 해결하는지, 핵심 기능은 무엇인지, 성공 기준은 무엇인지.
예: "유저가 할 일을 추가/수정/완료할 수 있고, 영구 저장되며, 모바일에서도 보기 좋고 안전해야 한다."

여기서부터 실제 상세 스펙은 AI에게 맡긴다.
"당신은 소프트웨어 엔지니어다. 위 목표를 만족하는 상세 스펙(spec.md)을 작성해라. 목표, 기능, 제약, 단계별 계획을 포함해라."
이렇게 하면 AI가 개요, 기능 목록, 제안 스택, 데이터 모델, 단계 계획을 만들어준다.

이 초안은 첫 번째 산출물이다.
사람이 검토하면서 잘못된 가정, 과도한 복잡성, 스택 선택 등을 조정하고, 다시 AI에게 "수정된 방향으로 스펙을 업데이트해 달라"고 요청한다.

이 과정을 거치면 스펙은 "처음부터 사람이 혼자 쓴 문서"가 아니라 "사람과 AI가 협업해 만든, 이후 개발의 기준이 되는 문서"가 된다.

가능하다면 코드 편집기에서 '읽기 전용 계획 모드(Plan Mode)'처럼 코드는 건드리지 않고 분석과 계획만 하게 만드는 모드를 사용하면 좋다.
이 모드에서 AI는 기존 코드베이스를 읽고, 설계 검토, 보안·테스트 전략 제안을 하게 하고, 충분히 명확해진 후에야 실제 구현을 시작하게 만든다.

PRD처럼 구조화하고 6가지 핵심 영역을 채우기

스펙은 "긴 메모"가 아니라 "섹션이 명확한 문서"여야 한다.
사람뿐 아니라 모델도 구조화된 텍스트를 훨씬 잘 이해한다.

실무에서 성과가 좋았던 스펙들은 공통적으로 6가지를 포함한다.

첫째, 명령어.
에이전트가 자주 실행할 커맨드를 구체적으로 적는다.
단순히 "테스트는 Jest"가 아니라 npm test, pytest -v 같은 실제 명령과 옵션을 넣는다.

둘째, 테스트 방법.
어떤 테스트 프레임워크를 쓰고, 테스트 파일 위치는 어디이며, "모든 테스트가 통과해야 한다" 같은 기준을 적는다.

셋째, 프로젝트 구조.
src/, tests/, docs/처럼 디렉터리 역할을 명시해서, AI가 파일을 어디에 생성·수정해야 하는지 헷갈리지 않게 한다.

넷째, 코드 스타일.
장황한 설명보다 "진짜 코드 예제" 한 덩어리가 더 효과적이다.
이 예제에 맞춰 함수명, 컴포넌트 구조, 에러 처리 방식 등을 맞추게 한다.

다섯째, Git 워크플로.
브랜치 네이밍 규칙, 커밋 메시지 형식, PR 조건(예: 테스트 통과 필수)을 적으면, 에이전트도 그 규칙에 따라 브랜치·커밋을 제안할 수 있다.

여섯째, 경계(Boundaries).
절대 건드리면 안 되는 디렉터리, 민감 설정, 배포/CI 파일 등을 명시한다.
"비밀 키는 절대 커밋하지 마라" 같은 규칙은 실제로 가장 효과적인 제약 중 하나다.

이 여섯 가지를 적어두면, 스펙은 단순 설명을 넘어 "에이전트가 프로젝트에 참여할 때 지켜야 할 행동 규칙"이 된다.

마지막으로, 이 스펙 문서 자체를 레포에 포함하고, CI나 워크플로와 연결해 "스펙 → 계획 → 작업 → 구현"이라는 단계적 흐름(일종의 spec-driven development)을 만드는 것이 좋다.
각 단계는 검증을 통과해야 다음 단계로 넘어가는 게이트 역할을 한다.

거대한 한 방 프롬프트 대신 작게 나눈 작업과 컨텍스트

모든 요구사항·코드·문서를 한 번에 주는 "한 방 프롬프트"는 성능을 떨어뜨린다.
연구에서도, 지시사항이 많아질수록 각각을 제대로 지키는 비율이 떨어지는 "지시의 저주" 현상이 확인되고 있다.

따라서 "한 번에 모든 걸 시키기"보다 "작고 선명한 과업들을 순서대로 시키기"가 훨씬 낫다.

이를 위해 스펙도 물리적으로 혹은 논리적으로 쪼갠다.
예를 들어 "백엔드 API", "프론트엔드 UI", "인증", "결제" 같은 섹션으로 나누고, 작업할 때는 해당 섹션과 꼭 필요한 글로벌 제약만 AI에게 제공한다.

스펙이 길어졌다면, 먼저 AI에게 "확장 목차 + 한 줄 요약"을 만들게 하면 좋다.
각 섹션의 핵심만 추린 요약을 프롬프트에 상시 두고, 실제 상세 내용은 필요할 때만 해당 부분을 추가로 제공하는 식이다.
이렇게 하면 모델은 전체 구조를 기억하면서도, 실제 컨텍스트는 최소로 유지한다.

도구가 허용한다면, 역할이 다른 서브 에이전트(혹은 "스킬")를 만드는 것도 방법이다.
"DB 설계 전담", "API 구현 전담", "테스트 작성 전담"처럼 스펙의 일부만을 기본 컨텍스트로 가진 별도 에이전트를 두고, 상위 에이전트(오케스트레이터)가 일을 분배하는 식이다.
이렇게 하면 각 에이전트는 작은 맥락에 집중할 수 있고, 병렬 작업도 가능해진다.

하지만 꼭 멀티 에이전트가 아니어도 된다.
사람이 직접 "지금은 데이터베이스 스키마만", "지금은 인증 로직만"이라는 식으로 작업 범위를 좁혀서 프롬프트를 구성해도 효과는 비슷하다.
중요한 것은 매번 "이번 요청의 목표는 단 하나"가 되게 만드는 것이다.

스펙에 품질 가이드와 자기검사 장치를 심어두기

좋은 스펙은 "해야 할 일 리스트"를 넘어서 "어떻게 하면 망하지 않는지"까지 안내해야 한다.

여기서 유용한 것이 세 단계 경계 설정이다.

항상 해도 좋은 것(✅),
먼저 물어봐야 하는 것(⚠️),
절대 하면 안 되는 것(🚫)을 나눠 적는다.

예를 들면 이렇다.
"항상: 테스트를 실행하고 결과를 요약한다."
"먼저 물어보기: DB 스키마 변경, 새로운 라이브러리 추가, CI 설정 수정."
"절대 금지: 비밀 키 커밋, node_modules/ 수정, 실패한 테스트 삭제."

이렇게 하면 AI는 스스로 "이건 내가 바로 해도 되나, 물어봐야 하나, 아예 하면 안 되나"를 구분하는 기준을 갖게 된다.

또 하나 중요한 것은 "자기 검증"을 스펙과 프롬프트에 포함하는 것이다.
예를 들어 구현 요청 끝에 "구현 후, 위 요구사항 목록을 다시 읽고 각 항목이 충족되었는지 체크리스트로 정리하라" 같은 문장을 붙인다.
이렇게 하면 모델이 스스로 빠뜨린 항목을 찾는 확률이 올라간다.

테스트와 리뷰도 스펙 수준에서 설계할 수 있다.
간단한 예시 입력/출력, 최소한의 단위 테스트 시나리오, 또는 별도의 "검증용 에이전트"를 두어 스타일·보안·성능 관점에서 코드 리뷰를 시키는 것도 가능하다.
이때 "이 테스트 파일의 모든 케이스를 통과해야 완료로 간주한다" 같은 성공 조건을 스펙에 명시한다.

마지막으로, 당신만 알고 있는 도메인 지식을 적극적으로 스펙에 녹여야 한다.
특정 라이브러리의 함정, 데이터 모델의 비표준 제약, 실무에서 자주 터지는 엣지 케이스 등은 AI가 스스로 학습하기 어렵다.
"나는 후배에게 이 프로젝트를 맡긴다면 무엇을 미리 알려줄까?"를 떠올리며 그 내용을 스펙에 적어두면, AI는 그만큼 덜 헤맨다.

테스트·반복·스펙 진화: 한 번 쓰고 끝이 아니다

스펙 작성은 시작일 뿐, 실제 가치는 "테스트-피드백-수정" 루프에서 나온다.

기능 하나가 끝날 때마다 바로 테스트를 돌리거나 최소한 수동으로 시나리오를 확인해 본다.
실제 동작이 스펙과 다르면, 단순히 코드를 고치는 데서 끝내지 말고 "왜 이런 오해가 생겼는지"를 기준으로 스펙을 수정한다.
애매하게 적혀 있거나 빠진 부분을 보완하고, 그 변경 내용을 AI에게 알려 "업데이트된 스펙에 맞춰 다시 계획/코드를 조정하라"고 지시한다.

큰 스펙이나 문서가 많을 경우, RAG나 MCP 같은 컨텍스트 관리 도구를 쓰면, 현재 작업에 관련 있는 스펙 조각만 자동으로 가져올 수 있다.
직접 구현한다면, 스펙을 파일 여러 개로 나누고, 키워드 검색으로 필요한 부분만 발췌해 프롬프트에 넣는 간단한 방식부터 시작할 수 있다.

버전 관리는 특히 중요하다.
스펙(SPEC.md)을 코드와 함께 Git에 넣고, 변경 내역을 커밋 메시지로 남기면, 사람과 AI 모두 "언제 어떤 결정이 바뀌었는지"를 추적할 수 있다.
일부 도구는 에이전트가 git diff를 읽고 변경 맥락을 이해하게 하기도 한다.

복수의 에이전트를 병렬로 돌릴 때는 "서로 다른 파일/모듈"을 맡기거나 "한 명은 구현, 한 명은 테스트/리뷰"처럼 역할을 나누면 충돌을 줄일 수 있다.
이때도 결국 기준은 스펙이며, 작업 간 의존성은 스펙의 구조와 계획 단계에서 분명히 적어두어야 한다.

피해야 할 안티 패턴

실제 레포들을 분석해 보면, 대부분의 에이전트 설정 파일은 "너무 막연해서" 실패한다.

"대충 잘 만들어줘", "더 좋게 바꿔줘" 같은 요구는 사람에게도 어렵지만 AI에게는 거의 불가능에 가깝다.
입력, 출력, 제약, 예시를 구체적으로 적지 않으면 원하는 결과를 얻기 힘들다.

또 다른 문제는 "문서 쏟아붓기"다.
수십 페이지의 문서를 그대로 붙여넣으면, 모델은 어디가 중요한지 판단하기 어렵고, 토큰도 낭비된다.
요약, 목차, RAG, 섹션 분리를 통해 "양"보다 "선별된 질"을 제공해야 한다.

가장 위험한 실수는 "사람 검토 없이 AI 결과를 바로 신뢰하는 것"이다.
테스트를 모두 통과했다고 해서, 그 코드가 보안·성능·유지보수 측면에서 안전하다는 보장은 없다.
특히 핵심 로직, 인증·결제, 데이터 삭제 같은 민감한 부분은 반드시 사람이 눈으로 확인해야 한다.

마지막으로 "프로토타입 모드(감으로 빨리 만들어보는 '바이브 코딩')"와 "실제 프로덕션 개발"을 혼동하면 안 된다.
실험 단계에서는 대충 시켜보고 결과를 보며 아이디어를 다듬을 수 있지만, 실제 서비스에 쓰려면 이 글에서 설명한 스펙·테스트·리뷰 체계가 필수다.

요약하면, 좋은 스펙의 체크리스트는 다음과 같다.
구체적인 목표, 6가지 핵심 영역(명령어·테스트·구조·스타일·Git·경계), 적절한 분할, 테스트/자기검사, 사람 검토.
이 다섯 가지가 빠져 있다면 다시 스펙을 점검해야 한다.

인사이트

AI 코딩 에이전트를 잘 쓰는 능력은 "코드를 대신 짜게 하는 기술"이 아니라, "명확하고 실행 가능한 스펙을 설계하고 관리하는 능력"에 가깝다.

실무에서 적용할 수 있는 간단한 흐름은 이렇다.

한 문단짜리 목표와 성공 기준을 적는다.
AI에게 상세 스펙 초안을 쓰게 하고, PRD처럼 섹션을 정리한다.
6가지 핵심 영역과 세 단계 경계를 채운다.
구현은 항상 "작은 작업 단위"로 쪼개서, 해당 섹션만 컨텍스트로 제공한다.
각 단계마다 테스트와 자기검사, 사람 리뷰를 거치고, 필요하면 스펙을 업데이트한다.

이 과정을 몇 번 돌려 보면, "왜 같은 모델인데도 어떤 프로젝트는 잘 되고 어떤 프로젝트는 엉망인지"의 이유가 눈에 보이기 시작한다.
모델의 성능 차이보다 "스펙과 작업 설계의 차이"가 훨씬 큰 영향을 준다는 사실을 체감하게 될 것이다.

AI를 잘 다루고 싶다면, 다음 프로젝트에서 "스펙부터 같이 작성해 본다"는 마음으로 시작해 보는 것을 추천한다.

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