개발자를 위한 AI 프롬프트 엔지니어링: 기획 요구사항을 설계와 구현 요청으로 바꾸는 4단계

AI 코딩 도구에 기획서 문장을 그대로 붙여 넣으면, 모델은 빠진 정보를 스스로 가정해 채운 뒤 코드를 만든다. 그 가정이 팀의 의도와 다르면 결과물 전체를 다시 만들어야 한다. Anthropic의 Prompting best practices 문서는 모델을 "맥락을 모르는 유능한 신입 동료"처럼 대하고, 원하는 결과와 제약을 구체적으로 적으라고 안내한다. 이 글은 그 원칙을 개발 흐름에 맞춰 요구사항 분해 → 설계 선택지 비교 → 범위를 제한한 구현 요청 → 결과 검증 네 단계의 프롬프트 템플릿으로 바꿔 정리한다.

공식 가이드의 원칙을 개발 프롬프트에 대응시키기

문서는 긴 입력(약 2만 토큰 이상)을 다룰 때 질문을 프롬프트 끝에 두면 복잡한 다중 문서 입력에서 응답 품질이 테스트상 최대 30%까지 좋아질 수 있다고 적고 있다. 에러 로그나 API 스펙을 통째로 붙이는 디버깅 요청에서 특히 의미가 있다.

1단계: 기획 문장을 질문과 가정으로 분해하기

"회원은 자기 주문 내역을 볼 수 있다" 같은 기획 문장에는 권한 범위, 페이지네이션, 취소 주문 포함 여부 같은 결정이 빠져 있다. 구현을 요청하기 전에 이 빈칸을 먼저 드러내게 한다.

<requirement>
회원은 마이페이지에서 자신의 주문 내역을 최근 순으로 볼 수 있다.
</requirement>

<task>
위 요구사항을 구현하기 전에 다음 세 가지를 목록으로 정리해 줘. 코드는 아직 쓰지 마.
1. 입력 / 출력 / 권한 / 예외 흐름별로 결정되지 않은 질문
2. 질문에 답이 없을 때 네가 적용할 기본 가정
3. 가정이 틀리면 영향을 받는 화면이나 API
</task>

나온 질문 목록은 기획자와 확인하고, 확정된 답을 다음 단계의 <context>에 그대로 붙인다. 이 과정을 거치면 모델이 임의로 채운 가정이 코드 깊숙이 들어가는 일을 막을 수 있다.

2단계: 설계 선택지를 두세 개로 비교하게 하기

설계 단계에서는 정답 하나를 요구하기보다 선택지와 장단점, 추천 이유를 함께 받는다. 출력 형식을 고정하면 팀 리뷰 문서에 그대로 옮기기도 쉽다.

<context>
- 스택: Next.js App Router, PostgreSQL, Prisma
- 확정된 요구사항: (1단계에서 확정한 답을 붙인다)
- 예상 데이터량: 회원당 주문 최대 수천 건
</context>

<task>
주문 내역 조회 API의 설계 선택지를 2~3개 제시해 줘.
각 선택지마다 다음 형식을 지켜:
<option name="...">
  <summary>한 줄 요약</summary>
  <pros>장점</pros>
  <cons>단점과 운영 리스크</cons>
</option>
마지막에 <recommendation>으로 추천안과 이유를 적어 줘.
</task>

3단계: 수정 범위와 제약을 명시해 구현 요청하기

구현 요청에서는 수정해도 되는 파일과 건드리면 안 되는 범위를 적는다. 공식 문서는 모델이 요청하지 않은 파일·추상화·설정 옵션을 덧붙이는 과잉 설계 경향이 있을 때 "요청된 변경만 하라"는 지시를 넣으라고 안내하고, 에이전트형 코딩에서는 열어 보지 않은 코드에 대해 추측하지 말라는 지시를 예로 든다. 두 지시를 템플릿에 기본으로 넣는다.

<files>
src/app/api/orders/route.ts       (수정 대상)
src/lib/orders/repository.ts      (수정 대상)
src/lib/auth/session.ts           (읽기만, 수정 금지)
</files>

<constraints>
- 기존 함수 시그니처는 바꾸지 않는다. 다른 화면이 같은 함수를 쓰기 때문이다.
- 새 npm 패키지를 추가하지 않는다. 보안 검토 기간이 길기 때문이다.
- 요청한 변경만 한다. 주변 코드 정리나 추가 옵션은 넣지 않는다.
- 답하기 전에 위 파일을 먼저 읽고, 읽지 않은 코드에 대해 추측하지 않는다.
</constraints>

<task>
2단계 추천안(커서 기반 페이지네이션)으로 주문 내역 조회 API를 구현해 줘.
완료 조건: 본인 주문만 반환, 한 번에 20건, 다음 페이지 커서 포함.
</task>

같은 요청을 모호하게 쓸 때와 구체적으로 쓸 때

4단계: 결과를 검증하고 템플릿을 팀 자산으로 남기기

공식 문서는 프롬프트 체이닝의 대표 패턴으로 초안 생성 → 기준에 따른 검토 → 검토 결과를 반영한 수정의 자기 교정 흐름을 소개한다. 개발에서는 다음 순서로 옮길 수 있다.

1. 3단계 템플릿으로 구현 초안을 받는다.
2. 새 대화에서 diff와 함께 "권한 누락, 경계값, 기존 시그니처 변경 여부를 기준으로 검토해 문제 목록만 적어 줘"라고 요청한다.
3. 문제 목록을 근거로 수정을 요청하고, 테스트를 실행해 통과 여부를 확인한다.

검증된 템플릿은 저장소의 docs/prompts/나 도구별 규칙 파일에 넣어 팀이 같은 형식을 쓰게 한다. Cursor를 쓴다면 Cursor Rules 작성법 글처럼 수동 호출 규칙으로 등록할 수 있고, 생성된 코드의 테스트 절차는 AI 생성 코드 테스트 워크플로우 글, 리뷰 기준은 AI 생성 코드 리뷰 규칙 글과 맞춰 두면 프롬프트·테스트·리뷰가 같은 기준으로 움직인다.