AI 에이전트가 자꾸 헛소리한다고요? 상위 1% 개발자의 'AI 기획서(Spec)' 작성법 5가지

안녕하세요! 오늘도 AI와 씨름하며 머리를 쥐어뜯고 계신가요? 분명히 하라는 대로 시킨 것 같은데, AI가 갑자기 안드로메다로 가는 코드를 짜오거나 "너무 복잡해서 못 하겠어요"라며 뻗어버릴 때... 솔직히 저도 처음엔 모니터 부술 뻔했습니다. 하지만 문제는 AI의 지능이 아니라, 우리가 주는 '기획서(Spec)'에 있었다는 사실! 오늘은 Claude Code나 Gemini CLI 같은 에이전트들을 내 손발처럼 부릴 수 있는 마법의 기획서 작성법을 탈탈 털어드릴게요.

📌 에디터의 3줄 요약

• AI에게 처음부터 완벽한 문서를 주려 하지 말고, 비전만 던져서 AI가 초안을 잡게 하세요.
• 6가지 핵심 영역(명령어, 테스트, 구조 등)을 포함한 구조화된 PRD 형식을 갖추세요.
• 거대한 작업은 잘게 쪼개고, '항상 할 것/물어볼 것/절대 금지'의 3단계 경계를 설정하세요.

1. 비전은 크게, 디테일은 AI에게 맡기기

여러분, 처음부터 RFC 문서 수준의 완벽한 기획서를 쓰려고 진 빼지 마세요. 우리 AI 친구들은 살 붙이는 능력이 기가 막히거든요. 먼저 고수준의 목표만 던져주고, AI더러 구체적인 기획서(spec.md)를 짜오라고 시키는 게 훨씬 효율적입니다.

1. 비전 공유: "사용자 계정과 DB가 있는 할 일 관리 웹앱을 만들 거야"라고 가볍게 시작하세요.
2. Plan Mode 활용: Claude Code 같은 도구의 '계획 모드'를 켜고 AI가 기존 코드를 분석하며 상세 계획을 짜게 하세요.
3. 살아있는 문서: AI가 뽑아준 초안을 검토하며 수정하면, 그게 바로 우리 둘만의 '단일 진실 공급원(Source of Truth)'이 됩니다.

2. 프로답게! 구조화된 PRD 작성하기

AI는 의외로 '각 잡힌' 문서를 좋아합니다. 깃허브(GitHub)의 분석에 따르면, 가장 효과적인 AI 기획서는 아래 6가지 영역을 포함한다고 해요. 이걸 표로 정리해 봤으니 체크리스트로 활용해 보세요!

항목	포함 내용
명령어(Commands)	npm test, build 등 실제 실행 가능한 커맨드
테스트(Testing)	테스트 프레임워크 정보 및 커버리지 기대치
구조(Structure)	소스 코드, 테스트, 문서가 들어갈 폴더 경로
스타일(Style)	네이밍 규칙, 선호하는 코드 패턴 (예: 함수형 컴포넌트)
Git 워크플로우	브랜치 이름 규칙 및 커밋 메시지 형식
경계(Boundaries)	절대 건드리면 안 되는 설정이나 비밀번호 규칙

3. '지시사항의 저주'를 피하는 법: 모듈화

혹시 AI한테 10가지 규칙을 한 번에 주셨나요? 그러면 AI는 앞부분 몇 개만 듣고 뒷부분은 까먹어버립니다. 이걸 '지시사항의 저주'라고 하죠. 똑똑하게 일하려면 작업을 잘게 쪼개야 합니다.

단계별 해결책 (Step-by-Step)

1. 기획서 분리:
   백엔드 기획서와 프론트엔드 기획서를 따로 관리하세요.
2. 필요한 정보만 제공:
   DB 작업을 할 때는 UI 기획서는 잠시 빼두세요. AI의 집중력을 아껴줘야 합니다.
3. 세션 초기화:
   큰 기능 하나가 끝났다면 새로운 세션을 시작해서 이전의 '찌꺼기' 문맥을 지워주는 게 상책입니다.

4. AI 에이전트의 '가드레일' 설정하기

AI는 시키는 대로만 하는 인턴과 같습니다. 사고 치지 않게 3단계 경계를 딱 정해주세요. 이건 진짜 꿀팁이니까 꼭 메모하세요!

• ✅ 항상 할 것: "커밋 전에는 무조건 테스트를 돌려라."
• ⚠️ 물어볼 것: "DB 스키마를 바꿀 때는 나한테 먼저 확인 받아라."
• 🚫 절대 금지: "API 키는 절대 코드에 하드코딩하지 마라."

5. 테스트하고, 수정하고, 진화하라

기획서는 한 번 쓰고 끝나는 종이 쪼가리가 아닙니다. 프로젝트가 진행되면서 AI와 함께 계속 업데이트해야 해요. AI가 짠 코드가 맘에 안 든다면? 코드를 고치라고 화내지 말고, 기획서의 설명이 부족하진 않았는지 먼저 확인해 보세요. 기획서를 수정하고 다시 던져주는 게 훨씬 빠릅니다.

❓ AI가 기획서를 읽고도 자꾸 무시하면 어쩌죠? ▼

💡 그건 기획서가 너무 길어서 '맥락'을 놓쳤을 확률이 높아요! 기획서 상단에 핵심 요약(TOC)을 넣거나, 현재 작업에 꼭 필요한 부분만 발췌해서 프롬프트에 넣어보세요.

❓ 기획서 양식은 어떤 파일 형식이 제일 좋나요? ▼

💡 마크다운(.md) 형식이 가장 무난하고 AI가 이해하기 좋습니다. 구조를 나눌 때 #, ## 같은 헤딩과 리스트를 적극 활용하세요.

❓ 여러 명의 AI 에이전트를 동시에 써도 될까요? ▼

💡 네! 한 명은 코드 담당, 한 명은 테스트 담당으로 역할을 나누면 효율이 극대화됩니다. 단, 서로 작업이 꼬이지 않게 기획서로 범위를 명확히 갈라줘야 해요.

자, 이제 AI를 제대로 부려먹을 준비가 되셨나요? 처음에는 조금 귀찮아도 기획서 한 장 잘 써두면, AI가 여러분의 야근을 대신해 줄 거예요. 여러분의 코딩 파트너가 진짜 '에이스'가 되는 그날까지, 파이팅입니다! 궁금한 점은 언제든 댓글 남겨주세요~ 😊

---

이 글은 정보 제공 목적이며 실제 AI 모델의 성능은 프롬프트의 품질과 도구의 업데이트 상황에 따라 다를 수 있습니다.