이 기사에서 얻을 수 있는 것

• AI 에이전트로부터 좋은 코드를 이끌어내는 「지시 설계의 5원칙」 개요
• 실제로 Docker 환경에서 검증한 「좋은 지시 vs 나쁜 지시」의 정량 데이터
• 3대 도구 (Claude Code / Cursor / GitHub Copilot)의 설정 파일 활용법
• 바로 사용할 수 있는 프로젝트 설정 파일 샘플

대상 독자

• AI 코딩 도구를 사용하기 시작했지만, 원하는 결과가 나오지 않는 분
• 「무엇을 지시해야 할지 모르겠다」고 느끼는 분
• 지시의 질을 정량적으로 평가하고 싶은 분

「지시의 질」로 정말 코드가 변하는가? — 검증해 보았다

「AI에게 주는 지시가 중요하다」는 말을 자주 듣지만, 정말로 그럴까? 필자는 이를 Docker 환경에서 실제로 검증했습니다.

검증 방법

Next.js 14 (App Router) + TypeScript + Prisma + PostgreSQL 환경을 Docker Compose로 구축하고, 동일한 「로그인 기능」을 2가지 패턴의 지시로 구현했습니다. 47개의 자동 테스트로 품질 차이를 정량적으로 비교했습니다.

검증 결과

나쁜 지시: 「로그인 기능을 만들어줘」

아무것도 지정하지 않으면 다음과 같은 코드가 생성됩니다:

// ❌ 나쁜 지시로부터 생성되는 코드
const handleSubmit = async (e: any) => { // any 타입
e.preventDefault()
...

좋은 지시: 기술 스택 + 요구사항 + 제약 사항 명시

Next.js 14 (App Router) 프로젝트에서, 이메일+비밀번호를 통한 로그인 기능을 구현해 주세요.
요구사항:
- Credentials Provider를 통한 이메일+비밀번호 인증
...

정량 비교 데이터

결론: 지시의 구체성이 생성된 코드의 품질을 모든 관점에서 향상시킨다. 이는 감각이 아니라 수치로 증명할 수 있는 사실입니다.

지시 설계의 5원칙

이 검증 결과에 기반하여, AI 에이전트로부터 확실하게 좋은 코드를 이끌어내는 5원칙을 소개합니다.

원칙 1: 컨텍스트 제공 — 「전제 조건」을 생략하지 말 것

AI 에이전트에 대한 가장 큰 실패는 「당연히 알고 있겠지」라며 전제 조건을 생략하는 것입니다.

제공해야 할 정보

실천: 프로젝트 설정 파일 활용

각 도구에는 「프로젝트 문맥 (Context)」을 상시 제공하는 메커니즘이 있습니다:

설정 파일 예시 (Next.js용):

# Stack
- Next.js 14+ (App Router), TypeScript strict
- Tailwind CSS + shadcn/ui, Prisma + PostgreSQL
...

원칙 2: 제약 사항 명시 — 「하지 말아야 할 것」을 전달할 것

AI 에이전트는 친절함 때문에 「불필요한 일」을 하기 쉽습니다. 앞선 검증에서 지시가 없었을 때 any 타입이나 인라인 스타일이 사용된 것이 그 증거입니다.

효과적인 제약 사항 작성법:

제약 사항:

• any 타입을 사용하지 말 것 (unknown으로 설정하고 타입을 좁힐 것)
• 새로운 라이브러리를 추가하지 말 것
  ...

제약 사항은 "규칙"이 아니라 "가드레일 (Guardrail)"로서 기능합니다. AI의 과도한 친절을 방지하는 것입니다.

원칙 3: 출력 형식 지정 — "어떻게 응답받고 싶은가"를 정의하기

동일한 "로그인 폼"이라도 출력 형식을 어떻게 지정하느냐에 따라 결과가 달라집니다:

출력 형식:
- 폼 컴포넌트: app/login/page.tsx
- 검증 스키마 (Validation Schema): src/schemas/login.ts (export const loginSchema)
...

포인트는 파일 경로, export 명, 타입 시그니처 (Type Signature) 까지 지정하는 것입니다. 모호함을 제로로 만듭니다.

원칙 4: 단계적 태스크 분해 — 큰 작업을 작게 나누기

"로그인 기능을 만들어줘"는 하나의 커다란 태스크입니다. 다음과 같이 분해하면 정밀도가 높아집니다:

Step 1: src/schemas/login.ts に Zod 스키마 생성
Step 2: app/login/actions.ts に Server Action 생성
Step 3: app/login/page.tsx に 폼 UI 생성
...

각 단계의 출력이 다음 단계의 입력이 되도록 설계하는 것이 요령입니다.

원칙 5: 피드백 루프 — "확인 $\rightarrow$ 수정" 사이클 돌리기

한 번에 완벽한 코드는 나오지 않습니다. 하지만 피드백의 질을 높임으로써, 2~3회의 반복 (Iteration)을 통해 완성도를 높일 수 있습니다:

피드백 예시:
"loginAction의 반환값에 error가 포함되지 않는 경우가 있음. 
try-catch의 catch 절에서 return { data: null, error: "..." }를 반환해주길 바람"

나쁜 피드백: "뭔가 작동하지 않음"

좋은 피드백: "XX 파일의 YY 행에서 ZZ 타입이 기대되지만 AA 타입이 반환되고 있음"

요약: 5원칙 목록

더 자세히 알고 싶은 분들께

본 기사는 5원칙의 개요를 다루고 있지만, 각 원칙의 상세한 실전 방법과 10종류의 템플릿(신규 기능 구현, 버그 수정, 리팩토링, 테스트 생성, 보안 리뷰 등)을 포함한 완전판은 유료 Book으로 공개하고 있습니다.

📚 AI 에이전트를 위한 지시 설계 완전 가이드 (¥500)

• 5원칙의 상세 해설 + 도구별 최적화 패턴
• 복사 붙여넣기가 가능한 템플릿 10종
• 실패 패턴과 개선 사례의 상세 해설

또한, 템플릿을 즉시 사용하고 싶은 분들을 위해 50개 이상의 템플릿을 정리한 세트도 준비되어 있습니다:

🛠️ The AI Coding Prompt Toolkit ($5)

• 50개 이상의 프롬프트 템플릿 (PDF + Markdown)
• 5개 카테고리: 프로젝트 설정, 기능 구현, 버그 수정, 테스트, 리팩토링

이 기사가 도움이 되었다면, 좋아요👍를 부탁드립니다. 질문이나 감상은 댓글창을 환영합니다.

#AIAgent #AI개발 #개발효율화 #프롬프트엔지니어링

Discussion