AI 코딩 에이전트에게 제대로 프롬프트하는 방법

AI 코딩 에이전트에게 제대로 프롬프트하는 방법

대부분의 개발자가 AI 코딩 에이전트를 사용하는 방식은 이렇습니다. 채팅창을 열고 "설정 페이지에 다크 모드 토글을 추가해 줘" 같은 내용을 입력합니다. 에이전트는 무언가를 만들어냅니다. 어느 정도는 작동하지만, 매끄럽지 않은 부분들이 있습니다. 개발자는 향후 20분 동안 이리저리 오가며 코드를 땜질합니다.

그러고 나서 모델이 별로 좋지 않다고 결론 내립니다.

모델은 괜찮습니다. 문제는 프롬프트입니다.

모호한 프롬프트의 불편한 진실

프롬프트의 모든 모호함은 모델이 당신 없이 내리는 결정입니다. 다크 모드 설정이 세션을 넘어서도 유지되어야 할까요? OS 수준의 설정을 따라야 할까요? 설정은 어디에 저장되나요 — localStorage, 데이터베이스의 사용자 프로필, 아니면 쿠키? 어떤 컴포넌트 라이브러리를 사용 중이고, 그 안에서 테마는 어떻게 작동하나요?

당신은 말해주지 않았습니다. 그래서 모델은 추측합니다. 가끔은 맞게 추측하지만, 종종 틀립니다. 결국 특정 환경에서는 작동하고 다른 환경에서는 고장 나거나, 사용자의 기존 설정을 무시하거나, 올바른 컨텍스트에 연결되지 않아 실제로 아무것도 토글하지 못하는 토글을 얻게 됩니다.

이것은 모델의 품질 문제가 아닙니다. 정보의 문제입니다.

기법: 에이전트가 스스로 프롬프트를 만들게 하라

실제로 효과가 있는 방법이자, 진지하게 AI 기반 개발 워크플로우를 구축하는 팀들이 깨달은 사실은 다음과 같습니다: 모델은 작업을 잘 수행하기 위해 자신이 무엇이 필요한지, 대부분의 개발자가 어떻게 요청해야 하는지 아는 것보다 더 잘 알고 있습니다.

모델은 엄청난 양의 잘 명세된 엔지니어링 작업을 처리해 왔습니다. 완벽한 기능 요청이 어떻게 생겼는지 알고 있습니다. 모호한 버그 리포트에서 일반적으로 어떤 정보가 누락되는지도 압니다. 핵심은 모델에게 어떤 것도 지시하기 전에 무엇이 누락되었는지 말하게 만드는 것입니다.

흐름은 다음과 같습니다:

  1. 목표를 느슨하게 설명합니다 — 에이전트가 문제 공간을 이해할 수 있을 정도로만요.
  2. 제대로 수행하기 위해 무엇이 필요한지 묻습니다 — "이 작업을 잘 완료하려면 어떤 정보가 필요한가요? 어떤 모호한 점을 명확히 해야 할까요? 제가 명시하지 않은 것들 중 무엇을 정해야 할까요?"
  3. 빈틈을 채웁니다 — 에이전트의 질문에 답하고, 요청한 컨텍스트를 제공합니다.
  4. 이제 작업을 지시합니다 — 에이전트의 질문을 프롬프트에 통합하거나, 원래 요청을 완전한 명세서로 다시 작성해 달라고 한 뒤 이를 승인하고 실행합니다.

마지막 단계는 선택적이지만 강력합니다. 에이전트에게 이렇게 요청할 수 있습니다: "나의 답변을 바탕으로 내 원래 요청을 완전한 작업 명세서로 다시 작성해 줘." 돌아오는 답변은 모델 스스로가 잘 실행할 수 있을 만큼 충분히 완벽하다고 판단한 프롬프트입니다. 그런 다음 이 프롬프트를 실제 작업으로 제출합니다.

어떤 이들은 이를 작업 실행을 위한 역 프롬프트 엔지니어링방식(reverse prompt engineering)이라고 부르기 시작했습니다. 처음부터 완벽한 프롬프트를 작성하는 것이 아니라, 완벽한 프롬프트에 무엇이 포함되어야 하는지 모델을 사용해 드러내는 것입니다.

예시 1: 기능 구축하기

설정 페이지에 다크 모드 토글을 추가하고 싶다고 가정해 봅시다. 두 가지 접근 방식이 어떻게 전개되는지 확인해 보겠습니다.

순진한 접근 방식:

"설정 페이지에 다크 모드 토글을 추가해 줘."

에이전트는 하드코딩된 토글 컴포넌트를 만들고, 설정을 컴포넌트 상태에 저장하며(새로고침 시 사라짐), 기존 테마 시스템과 연결하지 않고, 여러분이 이미 사용 중인 CSS 변수나 테마 토큰 대신 인라인 스타일을 사용합니다.

당신은 이를 고치느라 한 시간을 보냅니다.

역 프롬프트 접근 방식:

당신은 같은 문장으로 시작한 다음, 이렇게 묻습니다: "시작하기 전에, 이를 제대로 구현하려면 무엇을 알아야 해? 내가 무엇을 명확히 해야 할까?"

에이전트는 이와 비슷하게 대답할 것입니다:

당신은 이 질문들에 대답합니다. 앱이 next-themes를 사용하고, 설정은 기존의 PATCH /users/me 엔드포인트를 통해 사용자 프로필에 저장되며, 설정 페이지에는 특정 컴포넌트 패턴을 따르는 다른 토글들이 있는 "외관" 섹션이 이미 있다고 말해줍니다.

이제 에이전트는 필요한 것을 얻었습니다. 에이전트가 생성한 구현체는 올바른 테마 제공자에 연결되고, 기존 API를 사용하며, 기존 UI 패턴과 일치하고, OS 설정 폴백을 처리합니다. 어떤 것도 고칠 필요가 없습니다.

결과물의 품질 차이는 결코 작지 않습니다.

예시 2: 버그 수정하기

모호한 프롬프트가 가장 큰 피해를 일으키는 곳이 바로 버그 리포트입니다. 충분한 컨텍스트가 없는 모델은 그저 적당한 코드를 생성하는 데 그치지 않고, 자신만만하게 틀린 코드를 만들어내기 때문입니다.

누군가 다음과 같은 버그를 보고했다고 상상해 보세요: "가끔 로그인 버튼이 작동하지 않습니다."

순진한 접근 방식:

당신은 이를 에이전트에 붙여넣습니다. 에이전트는 인증 코드를 스캔하기 시작하고, 의심스러운 async/await 패턴을 발견하며, 아마 그것이 문제일 것이라 판단하고, 함수를 재작성한 뒤 PR을 엽니다. 버그는 여전히 존재합니다. 에이전트가 변경한 함수는 전혀 관계가 없는 것이었습니다.

역 프롬프트 접근 방식:

당신은 에이전트에게 버그 리포트를 주고 이렇게 묻습니다: "이를 효과적으로 진단하려면 무엇을 알아야 해? 시니어 엔지니어라면 코드를 건드리기 전에 어떤 질문을 할까?"

그것은 다음과 같이 대답합니다:

당신은 버그를 보고한 사람에게 돌아가 답변을 얻습니다: 간헐적이고, 사용자가 페이지에 10분 이상 머물렀을 때만 발생하며, 콘솔 에러는 없지만 네트워크 요청이 아예 시작되지 않습니다. 이젠 완전히 다른 버그가 되었습니다 — async/await 문제가 아니라 토큰 만료 문제이거나 이벤트 핸들러의 오래된 클로저(stale closure)일 가능성이 높습니다.

당신은 에이전트에게 그 정보를 주면, 이제 올바른 곳으로 찾아갑니다. 초기 렌더링에서 인증 토큰을 캡처하여 오래된 의존성을 가진 useCallback을 찾아냅니다. 정확한 수정 한 번, 부수적인 피해는 없습니다.

이것이 효과적인 이유

대부분의 AI 기반 코딩이 협상(여러 라운드에 걸쳐 결과물을 다듬기 위해 오가는 과정)처럼 느껴지는 이유는 초기 프롬프트가 너무 많은 결정을 모델에게 맡기기 때문입니다. 각 수정 라운드는 당신이 명세하지 않아 모델이 임의로 한 추측을 바로잡는 과정입니다.

역 프롬프트는 그 라운드의 대부분을 사전 대화 한 번으로 압축합니다. 모델의 질문은 자신이 스스로 내려야 했을 결정이 무엇인지 정확하게 알려줍니다. 당신이 대신 그 결정을 내립니다. 완전한 정보를 가지고 있었기 때문에 결과물은 처음부터 올바르게 나옵니다.

부차적인 장점도 있습니다: 모델이 묻는 질문들은 일종의 체크리스트입니다. 새로운 설정 추가, 인증 버그 수정, 새 API 연동 등 유사한 작업에 이 기법을 일관되게 사용하면 그 질문들이 눈에 익기 시작합니다. 시간이 지남에 따라 질문받지 않고도 프롬프트에 그러한 세부 사항을 포함하는 방법을 배우게 되며, 기본적인 프롬프트 품질이 향상됩니다.

몇 가지 실용적인 팁

이 기법은 도구 사용과 파일 접근 권한이 있는 에이전트 — Cursor, 에이전트 모드의 GitHub Copilot, Claude 등 — 와 함께 사용할 때 가장 효과적입니다. 당신의 코드베이스를 읽을 수 있는 에이전트는 상황을 모르고 작업하는 에이전트보다 훨씬 더 구체적인 질문을 할 것입니다.

세 단계의 흐름(무엇이 필요한지 묻기 → 정보 제공 → 작업 지시)이 한 단계를 더 추가하는 것은 맞습니다. 작고 명확하게 정의된 작업이라면 과할 수 있습니다. 하지만 여러 파일을 건드리거나, 기존 시스템과 통합하거나, 명료하지 않은 설계 결정이 포함된 작업이라면 곧바로 구현에 뛰어드는 것보다 일관되게 더 나은 결과를 만들어냅니다.

그리고 3단계에서 생성된 명세서는 저장해 둘 가치가 있습니다. 이는 재사용 가능한 템플릿입니다. 다음번에 누군가 사용자 프로필에 유지되는 설정을 추가해야 할 때, 이미 그에 대한 잘 명세된 프롬프트를 갖게 되는 것입니다.

더 큰 관점

대부분의 개발자가 코딩 에이전트에게 프롬프트를 작성하는 방식은 품질을 희생하며 속도에 최적화되어 있습니다. 짧은 문장을 넣고, 그저 그런 결과물을 얻은 뒤, 10분 동안 수정하는 작업을 — 하루에도 수십 번씩 반복합니다.

역 프롬프트 접근 방식은 그 트레이드오프를 뒤집습니다. 모델이 필요한 것을 갖췄는지 확인하는 데 초반에 조금 더 시간을 투자합니다. 그 대가로 결과물은 당신이 실제로 원했던 것에 훨씬 가깝게 나오고, 수정하는 데 단축된 시간을 얻게 됩니다.

어떤 작업에 대한 가장 좋은 프롬프트는 당신이 30초 만에 작성한 것이 아닙니다. 모델이 자신에게 필요하다고 말해주는 프롬프트입니다.

© Melvin Laplanche - All rights reserved.