코딩 에이전트에게 좋은 프롬프트 쓰기

개요

Casebook은 코딩 에이전트(Claude Code)와 함께 만들었습니다. 같은 에이전트라도 어떤 요청은 한 번에 원하는 결과가 나왔고, 어떤 요청은 같은 화면을 몇 번씩 다시 만들게 했습니다. 이 글에서는 실제로 쓴 프롬프트를 예로 그 차이를 정리합니다.

화면은 구조, 제한, 참고 대상을 함께 적기

문의 화면을 요청할 때는 이렇게 썼습니다.

“섹션 2개와 버튼 1개. 커스텀 UI 말고 Apple 기본 SwiftUI 컴포넌트로. 카테고리 2개, 최대 300자. 기존 ‘내가 올린 사건’ 목록과 같은 레이아웃.”

여기에 쓸 그림 2장을 함께 줬습니다. 구조, 금지할 것, 숫자 제한, 참고할 화면, 에셋이 한 번에 전달돼서 화면이 한 번에 구현됐습니다. 나중에 고친 것은 Mac 입력칸 정렬 하나뿐이었습니다.

반대로 “UI는 앱 분위기와 컨셉에 맞도록”이라고만 쓴 화면은 커스텀 디자인으로 나와서, 구현한 뒤 전부 다시 만들었습니다.

참고: 분위기를 원한다면 범위를 정해 주세요. 예: “Apple 기본 컴포넌트만, 분위기는 그림 한 장 정도. 시안 먼저.”

만들기 전에 빈틈을 묻기

설계를 설명한 뒤 “일단 여기까지 중에서 이상한 거 있어?“라고 물었습니다. 에이전트는 코딩을 시작하기 전에 빈틈 8가지를 짚었고, 그중에는 권한이 필요 이상으로 넓게 열리는 문제도 있었습니다. 모두 미리 정한 덕분에 구현하는 동안 되돌아간 일이 없었습니다.

요청에 이유를 붙이기

“로그인 없이 게임할 수 있으니, 문의도 로그인 없이 할 수 있어야 해”처럼 이유를 함께 말하면, 뒤따르는 작은 결정도 그 목적에 맞춰 빨리 정해집니다. 하루에 보낼 수 있는 편지 수나 오래 쓰지 않은 임시 사용자 정리 규칙이 그랬습니다.

고칠 때는 증상, 바꿀 것, 유지할 것을 말하기

“입력칸이 우측 정렬돼 있어. placeholder 빼고 일반 입력 폼으로. 300자 제한은 그대로.”

무엇이 보이는지, 무엇을 바꿀지, 무엇을 지킬지가 모두 들어 있어서 에이전트가 원인을 바로 찾아 한 번에 고쳤습니다.

형용사 대신 비교 대상을 주기

“개발자가 쓴 느낌이 없어”라는 평가만으로는 고칠 방향이 정해지지 않습니다. “Apple Developer Article을 참고해”처럼 비교할 대상을 함께 주자, 다음 한 번 만에 톤이 맞춰졌습니다. 분량도 “길지 않게” 대신 “3분 이내”처럼 잴 수 있는 기준으로 줬습니다.

기준과 범위는 처음에 정하기

“개발 블로그도 만들까 해. 개선안 보여줄래?“로 시작한 작업은 기준이 하나씩 나중에 더해져서 같은 화면을 세 번 고쳤습니다. 첫 메시지도 마찬가지입니다. 근거 기준과 승인 절차는 처음부터 넣어 좋았지만, 최종 목표와 답변 언어가 빠져 방향을 여러 번 다시 맞췄습니다. 승인 범위가 넓어서 첫 주에만 승인 질문이 20번쯤 오갔습니다.

지금은 첫 메시지를 이런 틀로 씁니다.

역할: visionOS에 특화된 시니어 Apple 개발자
최종 목표: iPhone · iPad · Mac · Apple Vision Pro 앱을 App Store에 출시
답변 형식: 한국어, 3분 이내, 표 활용
승인 범위: 이름 · 구조 · 커밋 · 삭제 · 배포만 묻고, 나머지는 진행 후 보고
첫 작업: 지금 프로젝트의 아키텍처 살펴보기

정리

이어 갈 습관	고칠 습관
요청에 이유 붙이기	방향만 주는 첫 요청
형용사 대신 비교 대상	기준을 나중에 하나씩 더하기
만들기 전에 빈틈 묻기	범위를 빼고 맡기기
결정은 짧게(“11번 빼줘”, “15번 A”)	찾아야 할 정보를 함께 주지 않기