🤖 AI 에이전트 스펙, 제대로 쓰는 방법이 따로 있다고요?

 

AI 에이전트 스펙 문서, 제대로 쓰는 법이 따로 있다고요? 🤖

AI 코딩 에이전트 써보신 적 있으신가요? Claude Code나 GitHub Copilot, Cursor 같은 도구를 쓰다 보면 한 번쯤은 이런 상황을 경험하게 되더라구요. 분명히 내가 원하는 걸 다 설명했는데, AI는 전혀 엉뚱한 코드를 만들어내는 거예요. 이 답답함, 공감하시는 분들 꽤 많으실 것 같아요.

그런데 재밌는 건, 이게 AI가 멍청해서가 아니라는 점이에요. 핵심 원인은 따로 있습니다. 우리가 AI에게 주는 지시서, 즉 스펙(Spec) 문서를 제대로 작성하지 않기 때문이에요.

2026년 현재, Gartner에 따르면 전체 기업 애플리케이션의 40%가 올해 말까지 AI 에이전트를 통합할 것으로 전망됩니다. 2025년 5% 미만이었던 걸 감안하면 단 1년 만에 8배 이상 증가하는 셈이죠. KB라이프, LG전자, SK이노베이션, 아모레퍼시픽, 이마트까지 국내 주요 기업들도 이미 에이전틱 AI 도입에 본격적으로 나서고 있어요. 이제 AI 에이전트에게 어떻게 지시하느냐, 즉 스펙을 어떻게 작성하느냐가 개발자와 기획자 모두에게 핵심 역량이 됐습니다. 오늘은 O'Reilly Addy Osmani의 연구와 GitHub의 실제 분석 데이터를 바탕으로 AI 에이전트 스펙 작성의 5가지 핵심 원칙을 정리해 드릴게요.

AI한테 스펙이 왜 필요한 건가요?

스펙(Specification) 문서는 원래 소프트웨어 개발에서 "이걸 만들어야 해"를 정의하는 설계서입니다. PRD(제품 요구사항 문서)라고도 하죠.

그런데 AI 에이전트 시대에 들어서면서 이 스펙의 개념이 완전히 달라졌어요. AI 에이전트는 지시를 글자 그대로 따릅니다. 사람처럼 "아, 이런 맥락이겠지"라고 알아서 추론하는 능력이 아직은 제한적이에요. 그러니 스펙이 모호하면 AI는 제멋대로 해석하고 엉뚱한 결과를 만들어냅니다.

GitHub에서 실제 에이전트 설정 파일 2,500개 이상을 분석한 결과, 스펙을 살아있는 문서로 관리하는 팀이 그렇지 않은 팀에 비해 훨씬 일관된 결과물을 만들어냈다고 해요. 스펙 작성 능력 자체가 새로운 직무 스킬이 된 거예요.

원칙 1 — 처음엔 큰 그림만, 세부 내용은 AI가 채운다

많은 분들이 처음부터 아주 상세한 요구사항을 AI에게 넘기려 하는데요, 역설적으로 너무 상세한 스펙은 AI를 오히려 혼란스럽게 만들 수 있어요.

좋은 방법은 이렇습니다. 먼저 목표와 핵심 요구사항만 담은 간결한 고수준 스펙을 만들고, 그다음에 AI가 그것을 구체화하도록 시키는 거예요. 예를 들어 "팀원들이 할 일을 관리하는 웹앱을 만들어. 계정 기능, DB, 간단한 UI 포함"이라고 주면 AI가 기술 스택 제안, 데이터 모델, 기능 목록 등을 스스로 확장해서 상세 스펙을 만들어 줍니다.

이렇게 만들어진 스펙 파일(SPEC.md)을 버전 관리 시스템에 저장해두면 이후 작업의 나침반이 됩니다. Claude Code의 Plan Mode를 활용하는 것도 좋은 방법이에요. 이 기능은 AI를 읽기 전용 모드로 제한해서 코드를 짜기 전에 먼저 계획서를 만들게 하거든요. 계획이 완성된 다음에야 실행에 들어가는 방식이라 "일단 코드부터 짜고 보자"는 함정을 막아줍니다.

AI 에이전트에게 스펙은 인간 팀원에게 주는 PRD와 같습니다. 처음에 제대로 된 방향을 잡아주는 게 나중에 수십 번의 수정보다 훨씬 중요해요.

원칙 2 — 스펙에는 반드시 6가지 영역이 들어가야 한다

그렇다면 좋은 스펙에는 무엇이 들어가야 할까요? GitHub 연구에서 밝혀진 효과적인 AI 에이전트 스펙의 6가지 핵심 영역이 있습니다.

첫째, 명령어(Commands)예요. "npm test"나 "pytest -v" 같이 실제로 실행 가능한 명령어를 처음부터 포함해야 해요. AI는 이 명령어를 수시로 참고합니다.

둘째, 테스트(Testing)입니다. 어떤 테스트 프레임워크를 쓰는지, 테스트 파일은 어디에 있는지, 커버리지 기준은 무엇인지 명확히 써줘야 해요.

셋째, 프로젝트 구조(Project Structure)입니다. "src/ 폴더는 앱 코드, tests/ 폴더는 단위 테스트"처럼 어디에 무엇이 있는지 명시해야 AI가 헤매지 않아요.

넷째, 코드 스타일(Code Style)이에요. 세 문단짜리 설명보다 실제 코드 예시 하나가 훨씬 효과적입니다. 네이밍 규칙이나 포맷 규칙도 여기에 넣어요.

다섯째, 깃 워크플로우(Git Workflow)입니다. 브랜치 이름 형식, 커밋 메시지 규칙, PR 요건을 명시하면 AI가 그대로 따라요.

여섯째, 경계선(Boundaries)입니다. "비밀 키는 절대 커밋하지 않는다", "node_modules는 절대 수정하지 않는다" 같은 금지 사항이에요. GitHub 연구에서 가장 많이 등장한 유용한 제약이 바로 "절대 비밀번호를 커밋하지 않는다"였다고 하더라구요.

원칙 3 — 한 번에 모든 걸 요구하지 말고, 작게 쪼개라

AI 에이전트에 대한 가장 흔한 오해가 "다 넣을수록 좋다"는 생각이에요. 실제로는 정반대입니다.

"지시의 저주(Curse of Instructions)"라는 연구 결과가 있는데요, 프롬프트에 요구사항이 많아질수록 AI가 각 항목을 충실히 지키는 비율이 급격히 떨어진다고 해요. GPT-4나 Claude 같은 최상위 모델도 동시에 너무 많은 조건을 만족시키는 건 어렵다는 거죠.

그래서 실무에서 검증된 방법은 스펙을 단계별로 나누고, 각 단계마다 관련 스펙 섹션만 AI에게 제공하는 겁니다. 예를 들어 1단계에서는 "데이터베이스 스키마 구현"만 시키고, 2단계에서 "인증 기능 구현"을 요청하는 식이에요. 작업 간에 불필요한 정보는 걷어내고 필요한 컨텍스트만 넘기는 거죠.

복잡한 프로젝트에서는 여러 서브 에이전트를 활용하는 것도 효과적입니다. 백엔드 담당 에이전트, 프론트엔드 담당 에이전트를 따로 두고 각각 관련 스펙만 제공하면 집중도와 품질이 모두 올라갑니다. 국내에서도 실제 현장 개발자들이 "에이전트 코딩은 인지적 부담을 줄이고 핵심 설계에 집중할 수 있게 해준다"고 평가하고 있을 정도예요.

원칙 4 — 스펙에 자기 점검 장치와 경계선을 심어라

좋은 스펙은 AI가 무엇을 해야 하는지뿐만 아니라, 어떻게 스스로 점검해야 하는지도 알려줘야 합니다.

효과적인 방법이 바로 "3단계 경계선(Three-Tier Boundary)" 구조예요.

항상 해라(Always Do) 단계에서는 테스트를 통과하면 반드시 커밋한다, 명명 규칙을 항상 따른다 같은 내용을 넣어요. 먼저 물어봐라(Ask First) 단계에서는 데이터베이스 스키마를 바꾸기 전에 확인한다, 새 의존성 추가 전에 검토한다 같은 내용이 들어가고요. 절대 하지 마라(Never Do) 단계에는 비밀키 커밋 금지, vendor 디렉토리 수정 금지 같은 절대적인 제약이 들어갑니다.

이 구조를 쓰면 AI가 스스로 행동 기준을 판단할 수 있어요. 단순한 금지 목록보다 훨씬 정교하게 작동합니다. 또 여러분이 가진 도메인 지식도 스펙에 적극 담아야 해요. "라이브러리 X의 Y 버전에는 메모리 누수 버그가 있으니 Z 방식으로 우회하라"처럼 경험에서 나온 조언을 넣으면, AI가 흔히 빠지는 함정을 미리 피할 수 있거든요.

원칙 5 — 스펙은 끝이 아니라 시작이다, 계속 진화시켜라

많은 분들이 스펙을 한 번 쓰고 잊어버리는 실수를 합니다. AI 에이전트와의 협업에서 스펙은 살아있는 문서여야 해요.

각 주요 단계가 끝날 때마다 테스트를 돌리고 결과를 확인하는 습관이 중요해요. AI 결과물이 스펙과 어긋나면 스펙을 업데이트하고 AI에게 "스펙이 이렇게 바뀌었어, 여기에 맞춰 다시 조정해줘"라고 알려주는 거죠.

대규모 언어 모델의 특성상, 컨텍스트 창이 길어질수록 주의력이 분산됩니다. 그래서 새로운 주요 기능으로 넘어갈 때는 대화를 새로 시작하고 핵심 스펙만 다시 넘겨주는 방식이 효과적이에요. 깃(Git)으로 스펙 파일 자체를 버전 관리하는 것도 좋습니다. 언제 어떤 이유로 스펙이 바뀌었는지 히스토리를 남기면 나중에 프로젝트 방향을 추적하기 훨씬 쉬워지거든요.

결국 AI 에이전트와의 협업은 인턴 개발자를 관리하는 것과 비슷해요. 명확한 지시, 충분한 컨텍스트, 지속적인 피드백이 있어야 좋은 결과가 나옵니다. 스펙은 그 모든 과정의 공통 기반입니다.

이것만은 피하세요 — 자주 하는 실수 모음

마지막으로 현장에서 자주 발생하는 실수들을 짚어드릴게요.

"멋진 걸 만들어줘"처럼 막연한 지시는 절대 금물이에요. AI는 구체적인 입력, 출력, 제약조건이 있어야 제대로 동작합니다. 50페이지짜리 문서를 통째로 넣고 "알아서 해"라고 하면 성능이 급격히 떨어지니 요약과 섹션 분리가 필수예요.

AI가 생성한 코드를 검토 없이 바로 서비스에 올리는 것도 위험합니다. 테스트를 통과해도 엣지 케이스에서 무너질 수 있어요. 실제로 국내외에서 에이전트 기능 일부만 부정확해도 전체 프로세스가 무너질 수 있다는 경고가 이어지고 있어요. 사람이 검토할 수 없는 코드는 서비스에 올리지 않는다는 원칙을 지켜야 합니다.

그리고 빠른 프로토타이핑(바이브 코딩)과 프로덕션 엔지니어링을 혼동하지 마세요. AI로 빠르게 실험하는 건 좋지만, 그 결과물을 실서비스에 그대로 올리려면 오늘 설명한 수준의 스펙과 검토 과정이 반드시 필요합니다.

마무리

AI 에이전트 스펙 작성은 단순한 문서 작업이 아닙니다. 높은 수준의 비전을 잡고, 스펙을 PRD처럼 구조화하고, 작업을 작게 쪼개고, 자기 점검 장치를 심고, 계속 반복하며 진화시키는 과정이에요. 이 다섯 가지 원칙만 지켜도 AI 에이전트와의 협업에서 훨씬 좋은 결과를 얻을 수 있습니다.

AI 코딩 에이전트를 쓰고 있다면, 오늘부터 SPEC.md 파일 하나를 만들어 시작해보세요. 처음엔 3줄짜리 메모라도 괜찮아요. 그게 쌓이면 여러분의 AI 인턴이 훨씬 똑똑하게 일하기 시작할 거예요. 스펙은 AI와 나 사이의 약속이고, 그 약속이 명확할수록 결과물도 달라집니다.