AI에게 코딩 제대로 시키는 법 — 프롬프트를 '스펙'으로 쓰는 5가지

AI에게 코드를 시켰는데 엉뚱한 라이브러리를 끌어오거나, 그럴듯한데 미묘하게 틀린 코드가 나온 적 있을 겁니다. 고치고 되돌리다 보면 차라리 직접 짜는 게 빨랐겠다 싶은 순간이 옵니다. AI를 실무 코딩에 붙여 쓰면서 확인한 건, 문제 대부분이 모델이 아니라 프롬프트에 있다는 점입니다. 이 글을 따라가면 AI 코딩 프롬프트를 '스펙'으로 쓰는 5요소와, 나쁜 프롬프트가 좋은 프롬프트로 바뀌는 예시가 손에 잡힙니다.

1. AI가 자꾸 헛짓하는 이유

AI 코딩 프롬프트를 마법 단어처럼 다루는 경우가 많습니다. "잘 짜줘", "프로처럼"을 붙이면 결과가 좋아질 거라는 기대인데, 실제로 결과를 가르는 건 표현이 아니라 모호함이 얼마나 남아 있느냐입니다. Anthropic 공식 가이드도 프롬프트를 "마법 주문"이 아니라 태스크를 정의하는 명세로 봅니다.

 

가장 잘 맞는 비유는 맥락을 전혀 모르는 똑똑한 신입 직원입니다. 실력은 좋지만 우리 프로젝트 사정을 모르는 사람에게 일을 시킨다고 생각하면 됩니다. 어떤 파일이 있는지, 어떤 규칙을 지켜야 하는지 말해주지 않으면, 능력과 무관하게 자기 방식대로 짜옵니다.

여기서 한 가지 자가 점검이 있습니다. 작성한 프롬프트를 맥락 모르는 동료에게 보여줬을 때 그 사람이 헷갈리면, AI도 헷갈립니다. 실제로 저도 초기엔 "캐시 레이어 붙여줘" 한 줄로 시켰다가, 프로젝트에 없던 라이브러리를 새로 끌어와 짜온 코드를 받고 처음부터 다시 시킨 적이 있습니다. 부족했던 건 모델 성능이 아니라 제가 준 정보였습니다.

 

정리하면 방향은 하나입니다. 코드는 점점 AI가 짜고, 사람은 무엇을 어떻게 만들지 스펙을 쓰고 결과를 리뷰하는 일에 시간을 더 쓰는 흐름입니다. 결국 AI 코딩 프롬프트를 잘 쓴다는 건 스펙을 잘 쓴다는 뜻입니다.

2. AI 코딩 프롬프트 스펙 5요소

모호함을 없애는 스펙은 대략 다섯 조각으로 나뉩니다. 순서대로 채우면 빠진 정보가 눈에 보입니다.

요소	무엇을 담나	한 줄
맥락(context)	관련 파일·구조·목표, 그리고 왜	"이걸 왜 하는지"까지 주면 정확도가 오른다
제약(constraints)	쓸 것/쓰지 말 것 — 라이브러리·패턴·에러 처리	"새 의존성 추가 금지" 한 줄이 헛짓을 막는다
참조(examples)	기존 코드·컨벤션 3~5개 예시	말로 설명하기 힘든 스타일을 코드로 보여준다
검증(verification)	통과 기준 — 테스트·타입체크·확인 명령	AI가 스스로 검증하고 고치게 만든다
형식(format)	원하는 출력 구조·완료 기준	"라우터/서비스 분리" 같은 결과 형태 지정

맥락에는 사실뿐 아니라 이유를 넣는 게 핵심입니다. "세션 기반을 JWT로 통일하려는 것"처럼 목적을 알려주면, AI가 세부 결정에서 방향을 덜 잃습니다. 참조는 few-shot 예시인데, Anthropic 가이드는 예시를 <example> 태그로 감싸 지시와 구분하라고 권합니다.

 

나쁜 프롬프트 → 좋은 프롬프트 예시를 보면 차이가 분명합니다.

❌ 나쁜 프롬프트
로그인 API 만들어줘.

✅ 스펙으로 쓴 프롬프트
[맥락] Express + Prisma 프로젝트. User 모델(email, passwordHash)은 이미 있음.
       이메일/비밀번호 로그인 엔드포인트를 추가한다. 세션 기반을 JWT로 통일하려는 목적.
[제약] bcrypt로 비밀번호 비교, JWT 발급. 기존 errorHandler.ts 패턴을 그대로 따를 것.
       새 라이브러리 추가 금지.
[참조] 회원가입 라우터 src/routes/auth/signup.ts의 구조·네이밍을 따를 것.
[검증] npm test의 auth 스위트와 tsc --noEmit가 모두 통과해야 함.
[형식] 라우터(routes)와 서비스(services)를 분리. 컨트롤러는 얇게.

같은 기능이지만 결과 품질이 갈립니다. 아래 프롬프트는 새 의존성을 끌어올 여지, 에러 처리 방식이 제각각일 여지, 파일 구조가 어긋날 여지를 미리 닫아둡니다.

3. 깔끔하게 시키는 3가지 습관

AI 코딩 프롬프트에 스펙을 채웠으면, 전달 방식에서 오해를 더 줄일 수 있습니다.

 

XML 태그로 구조화합니다. 지시·맥락·예시를 <instructions>, <context>, <example>로 분리하면 AI가 "이건 시키는 말, 저건 참고 자료"를 헷갈리지 않습니다.

<instructions>아래 컨벤션대로 결제 취소 엔드포인트를 추가해라.</instructions>
<context>NestJS + TypeORM. Payment 엔티티에 status 컬럼 있음.</context>
<example>// 기존 결제 승인 핸들러 코드 …</example>

역할을 한 줄로 부여합니다. system 자리에 "You are a senior backend coding assistant" 정도만 넣어도 톤과 행동이 그 방향으로 모입니다.

 

긴 자료는 프롬프트 위쪽에 둡니다. 참조할 파일·문서가 길면, 질문이나 지시보다 앞에 배치하는 편이 낫습니다. Anthropic 가이드 기준 긴 컨텍스트를 앞에 두면 최대 30%까지 성능이 오릅니다.

 

한 가지 주의가 있습니다. Opus 5 같은 최신 모델은 스스로 검증하고 수정하는 성향이 강합니다. 옛 모델용으로 쓰던 "검증 단계를 꼭 추가해라" 같은 지시를 그대로 넣으면 오히려 과검증으로 시간을 잡아먹습니다. 모델이 바뀌면 프롬프트도 손봐야 하는데, 세대별 차이는 Claude Opus 5 정리에서 짚어뒀습니다.

4. 매번 안 적기 + 코드 리뷰

스펙 5요소를 매 프롬프트마다 타이핑하긴 번거롭습니다. 프로젝트 규칙은 CLAUDE.md 같은 규칙 파일에 한 번 정리해 상시 맥락으로 깔아두는 게 낫습니다. 스택·컨벤션·금지 라이브러리를 적어두면, 개별 프롬프트에서는 그때그때 다른 맥락만 채우면 됩니다. 이 파일을 어떻게 쓰는지는 CLAUDE.md 작성법에 단계별로 정리해뒀습니다.

 

그리고 AI가 짠 코드는 리뷰를 건너뛰지 않는 게 안전합니다. 가장 위험한 결과물은 컴파일도 되고 겉보기엔 멀쩡한데 미묘하게 틀린 코드입니다.

증상: 테스트도 통과하고 리뷰에서도 그냥 넘어갔는데, 특정 조건에서만 값이 어긋남.

원인: AI가 프롬프트에 없던 부분을 그럴듯한 관행으로 채워 넣음(예: null 처리·타임존·경계값 가정).

해결: 스펙에 검증 기준을 명시하고, 리뷰 때 "왜 이렇게 짰는지" 근거를 되묻는다. 가정이 깔린 곳을 먼저 본다.

즉 스펙을 잘 쓰면 헛짓이 줄고, 리뷰로 남은 오차를 잡는 구조입니다. 이 둘은 대체재가 아니라 짝입니다.

Q&A — 자주 보는 질문 4개

Q. 프롬프트는 길수록 좋나요?
좋은 AI 코딩 프롬프트의 기준은 길이가 아니라 모호함 제거입니다. 관련 없는 정보를 잔뜩 붙이면 오히려 방향이 흐려집니다. 스펙 5요소에 해당하는 정보만 채우고 나머지는 뺍니다.

Q. 어떤 AI가 코딩을 잘하나요?
작업 성격에 따라 다릅니다. 저는 긴 문맥·리팩토링은 Claude, 빠른 탐색·요약은 Gemini를 병행합니다. 다만 어떤 모델이든 스펙이 부실하면 결과도 부실합니다.

Q. 매번 이렇게 쓰기 귀찮은데요?
반복되는 규칙은 CLAUDE.md 같은 규칙 파일로 빼두고, 프롬프트에는 그때그때 다른 맥락만 적으면 됩니다. 한 번 세팅하면 이후엔 짧아집니다.

Q. AI가 짠 코드, 그대로 믿어도 되나요?
검증과 리뷰를 거치기 전엔 아닙니다. 특히 겉보기에 멀쩡한 코드일수록 가정이 깔린 부분을 확인해야 합니다.

함께 보면 좋은 글

• Claude Code 활용법 정리 — 망치는 습관 3개와 살리는 습관 7개
• Claude Code 서브에이전트 실전 배치 — 역할 분리부터 병렬 3~5개 스윗스팟까지
• 카파시 CLAUDE.md — GitHub 10만 스타 받은 65줄 파일 정리

기준 시점: 2026-08 · 기법은 Anthropic 공식 프롬프트 가이드 기준