감독자의 언어

– 좋은 프롬프트는 어떻게 설계하는가?

1. 들어가며

Claude Code의 강의를 제작하면서 설명을 위한 다양한 소스 코드를 생성하고, 변경하고, 테스트 했습니다. AI 이전 시대에는 실습을 위한 코드를 만들기 위해 꽤 많은 시간 고민하고, 수정하는 작업들이 일상이었던 반면 이제는 몇 마디의 프롬프트로 몇 분 안에 원하는 코드, 동작하는 코드, 테스트 케이스를 한번에 통과하는 그런 코드들을 만들게 됩니다. 그럴 때마다 코드를 만드는 사람에서 만들어진 코드를 검증하는 사람이 되었다는 것을 느끼게 되었습니다.
그리고, AI와 협업에서 중요한 것은 생성된 코드를 다양한 관점에서 검증하는 것이 매우 중요하다는 것과 처음 코드를 생성하기 위해 무엇을 고려하고 프롬프트 하는 것이 좋을지에 대한 보편적인 고민은 다시금 해보게 되었습니다.
게시판 예제를 구성하며 다음과 같은 프롬프트를 했습니다.

“게시글에 댓글 기능을 추가해줘.”

결과는 몇 분 만에 나왔습니다. Comment 엔티티가 생기고, Service, Controller, JPA 기반 Repository까지 구성되고, React로 구성한 화면에 댓글 목록도 표시가 되었습니다. 하지만, 결과 화면과 소스를 보면서 무심코 진행한 프롬프트에서 다양한 질문들이 쏟아졌습니다.
‘댓글에 대댓글은 가능한가?’
‘삭제는 소프트 삭제, 아니면 하드 삭제?’
‘작성자만 삭제할 수 있게 된건가? 관리자는?’
‘페이징은 어떻게 되는 것이지?’
이런 여러가지 질문들이 생겼지만 AI는 작업을 진행하면서 그 어느 것도 묻지 않았습니다. 따져보면 저의 프롬프트는 요구사항이 아니라 힌트 수준의 명령이었기 때문에 나온 결과였습니다. 이런 유사한 경험들을 하면서 ‘정밀한 프롬프트’는 실제 무엇을 의미하는 것인지, 어떤 요소들로 구분해 나눌 수 있는지, 어떻게 반복 가능한 절차로 만들 수 있는지 생각해 보게 되었습니다.

2. 프롬프트를 요구사항 명세로

모호한 요구사항은 모호한 시스템을 만듭니다. 요구사항 공학에서는 요구사항의 품질을 명확성(clarity), 완전성(completeness), 검증 가능성(verifiability), 일관성(consistency)의 기준으로 평가합니다. 이 네 가지의 기준은 프롬프트에도 그대로 적용됩니다. 프롬프트 자체가 이미 AI에게 전하는 우리의 요구사항인 것입니다.

다만 차이가 있다면 속도입니다. 사람에게 불완전한 요구사항을 전달하면 사람은 되묻습니다.“대댓글도 필요한가요?”, “삭제는 어떤 방식으로 할까요?”와 같은 질문이 자연스럽게 오가게 됩니다. 이 과정이 바로 요구사항을 다듬는 과정입니다. 그런데 AI는 되묻지 않습니다. 대신 가장 그럴듯한 기본값을 스스로 채워 즉시 결과를 만들어냅니다. 되묻지 않는 다는 것은 곧 요구사항의 빈틈을 감춘다는 의미와 같습니다.

AI가 모호한 프롬프트로 만들어 낸 결과를 보고 되묻는 절차를 최소화 하려면 이 되묻는 절차를 프롬프트 작성 단계로 앞당겨야 합니다. 동료 개발자와 대화로 채우던 빈자리를 AI에게 위임할 때는 요청 시점에 미리 채워야 합니다. 이것이 프롬프트를 단순한 지시문이 아니라 요구사항 명세로 다뤄야 하는 이유입니다.

3. 정밀한 프롬프트를 위한 4가지

정밀한 프롬프트를 위한 고려사항을 4가지로 정리해봤습니다. 각 사항은 독립적이지 않고, 서로를 보완합니다.

• 결과물의 경계
  가장 먼저 정해야 하는 것은 무엇을 만들고 무엇을 만들지 않을지를 명확히 구분하는 것입니다. “댓글 기능”이라는 명령 안에는 대댓글, 좋아요, 신고, 정렬 옵션, 알림 연동까지 얼마든지 다양한 의미를 포함할 수 있습니다. 경계를 정하지 않으면 AI는 스스로 경계를 정합니다. 그리고 그 경계는 대체로 가장 흔한 구현 사례를 따릅니다. 이는 해당 프로젝트의 맥락과 무관하게 결정된 경계이며 실제 요구사항과 다를 확률이 높습니다.
  경계를 명시하는 것은 기능을 줄이는 것이 아닙니다. 이번 프롬프트에서 구현하고자 하는 범위와 다음 프롬프트와의 범위를 나누는 일입니다. 이러한 구분이 있어야 결과물에 대한 검토도 명확해집니다.

• 기존 시스템과의 관계
  두 번째는 이 기능이 이미 존재하는 프로그램의 구조와 어떻게 맞물리는지를 명확히 하는 것입니다. 이 게시판 프로젝트의 인증 방식, 게시글 엔티티의 구조, 기존 API의 응답 형식과 같은 맥락이 이에 해당합니다. AI가 프로젝트 전체를 인덱싱하고 관련 파일을 스스로 찾아내서 분석하는 능력을 가지고 있지만 그 수준은 코드가 어떻게 연결되었는지를 파악하는 정도입니다. 이 프로그램의 설계 의도까지 추론하지는 못합니다.
  따라서 기존 시스템과의 관계를 프롬프트에 정리하는 것은 AI의 탐색 범위를 넓히는 것이 아니라 AI가 잘못된 전제 위에서 결과를 만들어내는 것을 미연에 방지하는 것입니다.

• 위임의 기준
  세 번째는 AI가 스스로 판단해도 되는 영역과 개발자가 직접 지정해야 하는 영역을 구분하는 것입니다. 예를 들어 “삭제 정책은 소프트 삭제로 하고, 페이징 방식은 스스로 판단해서 제안해줘”처럼 위임의 범위를 명시적으로 나누는 것입니다.
  이 구분이 중요한 이유는 이전 글에서 이야기 했던 인지 부채, 의도 부채와 직결되기 때문입니다. 개발자가 반드시 정해야 하는 판단(삭제 정책, 권한 범위 등 비즈니스 규칙과 직결되는 결정)을 AI에게 위임하면 그 결정의 근거가 남지 않은 채 코드에만 남게 됩니다. 반대로 AI가 판단해도 괜찮은 영역(구현 스타일, 내부 메소드 분리 방식 등)까지 개발자가 일일이 지정하면 프롬프트 작성에 많은 시간이 소요됩니다. 위임의 기준을 나누는 일은 결국 어디까지가 감독자의 결정이고, 어디부터가 실행자의 재량인지를 정하는 일입니다.

• 검증 방법
  마지막은 결과를 어떻게 확인할 것인지 요청 시점에 함께 정하는 것입니다. “작성자가 아닌 사용자가 삭제를 시도하면 403이 반환되는지 확인하는 테스트도 함께 만들어줘”와 같이 요청하면 AI는 구현과 동시에 검증 기준을 함께 구성합니다. 검증 방법을 결과물이 나온 이후에 다시 고민하는 것과 미리 요청 단계에서 정의하는 것은 전혀 다른 결과를 만들어 냅니다.

이 네 가지 사항은 기술 부채, 인지 부채, 의도 부채를 예방하는 첫번째 관문이라 할 수 있습니다. 경계와 위임의 기준을 프롬프트 제안 단계에서 명시적으로 정리하면 그 기록 자체가 추후에 참고할 수 있는 구현 의도의 흔적이 됩니다.

4. 프롬프트 재설계 과정

모호한 프롬프트를 재설계했을 때 어떤 차이가 있는지를 보면 다음과 같습니다.

두 프롬프트의 차이는 길이에 있지 않습니다. 위임과 범위의 구분을 명확히 하고 있는 것의 차이입니다. 코드 스타일이나 서비스 계층의 세부 구조처럼 AI에게 맡겨도 괜찮은 영역은 그대로 재량에 남겨두고, 삭제 정책이나 권한 범위, 페이지 크기처럼 비즈니스 규칙과 직결된 부분만 명시적으로 지정했습니다. 이 구분이 있기 때문에 결과를 검토하는 시간이 크게 줄었고 재요청 없이도 다음 단계로 넘어갈 수 있었습니다.

5. 프롬프트 설계 체크리스트

이 경험을 토대로 프롬프트를 작성하기 전에 참고할 수 있는 질문들을 정리해봤습니다.

• 이 요청이 실패할 수 있는 지점은 어디인가?
  (결과가 나온 이후에 발견하게 될 문제를 미리 예상해 봅니다.)

• AI가 스스로 정해도 되는 부분과 내가 반드시 정해야 하는 부분은 무엇인가?
  (비즈니스 규칙과 직결된 부분은 위임하지 않습니다.)

• 새로 구현하려는 기능이 기존 구조와 어떻게 맞물리는지 정리했는가?
  (인증, 데이터 모델 등의 관계를 명시합니다.)

• 결과를 어떻게 검증할지 고민하고 요청에 포함했는가?
  (검증 기준을 결과물과 함께 볼 수 있도록 합니다.)

6. 끝으로

좋은 프롬프트의 핵심은 명확한 경계와 위임의 기록이라고 생각합니다. AI는 최종 결과의 경계를 대신 정해주지 않으며 어떤 결정을 개발자가 내려야 하는지 스스로 판단하지도 못합니다. 이러한 판단은 그 요청을 하는 개발자만의 몫입니다.
결국 감독자의 언어를 훈련한다는 것은 매번 새로운 요청 앞에서 결과물의 경계, 기존 시스템과의 관계, 위임의 기준, 검증 방법이라는 네 가지 질문을 스스로 되새기면서 프롬프트를 만들어 가는 과정입니다.

 Jin