← 글 목록

코딩 AI에게 일을 맡길 때 프롬프트에 넣을 세 가지

AI와 일하기4분 분량

코딩 AI에게 요청할 때 위치, 증상, 완료 기준을 적고 통과 여부를 확인할 검사를 함께 주면 왜 결과가 나아지는지 공식 문서를 바탕으로 정리했습니다.

코딩 도우미에게 일을 맡길 때 "로그인 버그 고쳐줘"처럼 짧게 적는 경우가 많습니다. 이 글에서는 요청에 무엇을 더 적으면 좋은지, 그리고 일이 끝났는지 확인할 수단을 어떻게 건네는지를 정리합니다. 내용은 Anthropic의 공식 문서(프롬프트 작성 가이드, Claude Code 모범 사례)를 바탕으로 했고, 제가 직접 측정한 결과가 아니라 문서가 권하는 방법을 풀어 쓴 것입니다.

AI는 코드에 없는 정보를 모릅니다

공식 문서는 AI를 "뛰어나지만 우리 팀의 규칙과 작업 방식은 아직 모르는 새 동료"에 빗댑니다. 코드 저장소만 읽어서는 알 수 없는 것이 있습니다. 어떤 증상이 문제인지, 두 가지 방법 중 어느 쪽을 원하는지, 어디까지 만들어 주길 바라는지 같은 것들입니다.

문서가 소개하는 점검 방법도 간단합니다. 요청문을 맥락을 전혀 모르는 동료에게 보여 주고, 그대로 따라 할 수 있는지 물어보는 것입니다. 동료가 헷갈린다면 AI도 헷갈립니다.

위치, 증상, 완료 기준을 적습니다

Claude Code 모범 사례 문서는 파일 이름을 적고, 증상을 설명하고, "고쳐졌다"가 무엇을 뜻하는지 처음부터 말해 두면 수정 요청을 한 번 줄일 수 있다고 설명합니다. 문서에 나온 예시를 우리말로 옮기면 이렇습니다.

이전 이후
로그인 버그 고쳐줘 세션이 만료된 뒤 로그인이 실패한다는 제보가 있다. src/auth/의 토큰 갱신을 보고, 실패를 재현하는 테스트를 먼저 쓴 다음 고쳐라

막연한 요청과 구체적인 요청을 비교한 그림. 구체적인 요청에는 위치, 증상, 완료 기준 세 가지가 들어 있다
구체적인 요청에 들어 있는 세 가지

두 번째 문장에는 세 가지가 들어 있습니다. 위치는 src/auth/의 토큰 갱신이고, 증상은 세션 만료 뒤의 로그인 실패이며, 완료 기준은 실패하는 테스트가 통과하는 것입니다.

같은 문서에는 "이 파일의 패턴을 따라 만들고, 새 라이브러리는 쓰지 말 것"처럼 제약을 적는 예시도 있습니다. 두 방법 중 어느 쪽이든 괜찮은 상황에서 내가 한쪽을 선호한다면, 그 사실은 코드에 적혀 있지 않으니 요청에 적어야 합니다.

왜 그렇게 하라는지도 한 줄 덧붙입니다

프롬프트 가이드는 지시만 던지기보다 그 지시가 왜 필요한지 이유를 붙이라고 권합니다. 이유를 알면 AI가 내 목표에 더 맞게 판단할 수 있다는 설명입니다. "이 함수 이름은 바꾸지 마라"보다 "외부 스크립트가 이 이름을 호출하고 있으니 바꾸지 마라"가 더 쓸모 있습니다.

범위도 마찬가지입니다. 문서에 따르면 AI는 요청을 보수적으로 읽어서 조건을 겨우 만족하는 가장 작은 결과물을 내놓는 경향이 있습니다. 빈 화면 상태, 오류 상태, 저장 흐름까지 원한다면 "여기까지 만들어 달라"고 직접 적어야 합니다. 한편 막연히 "이 파일에서 개선할 점이 뭘까"처럼 탐색하는 질문은 모호해도 괜찮다고 문서는 말합니다. 고칠 대상이 정해졌을 때 구체적으로 쓰라는 이야기입니다.

통과 여부를 알려 주는 검사를 함께 줍니다

모범 사례 문서에서 가장 인상적인 대목은 검사에 관한 것입니다. AI는 결과물이 완성된 것처럼 보이면 멈춥니다. 실제로 맞는지 확인할 방법이 없으면 "그럴듯해 보인다"가 판단의 전부이고, 결국 사람이 테스트 역할을 하게 됩니다.

그래서 통과와 실패가 명확히 나오는 것을 주라고 합니다. 테스트 파일, 빌드의 종료 코드, 린터, 결과를 기준 파일과 비교하는 스크립트, 디자인 시안과 나란히 놓은 화면 캡처가 모두 검사가 됩니다. 검사가 있으면 AI가 수정하고, 실행하고, 실패하면 출력을 읽고 다시 고치는 순환을 스스로 돌릴 수 있습니다.

수정, 검사 실행, 결과 읽기가 이어지고 실패하면 처음으로 돌아가며 통과하면 근거와 함께 보고하는 순환 그림
검사가 있을 때의 순환

가장 간단한 방법은 요청문에 한 줄을 더하는 것입니다. 문서가 드는 예는 "끝나면 인증 테스트를 돌리고, 통과할 때까지 계속해라"입니다. 저장소에 이미 검사 명령이 있다면, 그 명령을 프로젝트 안내 파일(CLAUDE.md)에 적어 두는 것이 가장 쓸모 있는 한 줄이라고도 합니다.

끝났다는 보고를 받을 때는 "모두 통과했다"는 말만 받지 말고, 실행한 명령과 그 출력을 함께 달라고 요청하라고 문서는 권합니다. 출력을 읽는 쪽이 검사를 다시 돌려 보는 것보다 빠르기 때문입니다.

요청하기 전에 확인할 것

정리하면 요청을 보내기 전에 아래 네 가지를 보면 됩니다.

  1. 어느 파일이나 기능인지 적었는가
  2. 증상이나 원하는 결과를 구체적으로 적었는가
  3. 선호하는 방식, 쓰지 말아야 할 것, 원하는 범위를 적었는가
  4. 통과와 실패를 가를 검사를 주었는가

네 가지 모두 사람 동료에게 일을 부탁할 때 챙기는 것과 크게 다르지 않습니다. 코드에 드러나지 않는 맥락을 내가 대신 적어 준다는 점이 핵심입니다. 모든 요청에 이렇게 길게 쓸 필요는 없고, 결과를 되돌리기 번거로운 수정일수록 앞의 네 가지가 값을 한다고 생각합니다.

참고한 자료

  • #AI
  • #프롬프트
  • #코딩 도우미
  • #Claude Code
  • #업무 효율