프로그래머를 위한 프롬프트 엔지니어링 플레이북

(addyo.substack.com)

1P by GN⁺ 1일전 | ★ favorite | 댓글 1개

AI 코딩 도우미는 개발자의 생산성을 높여주지만, 그 결과물의 품질은 프롬프트 엔지니어링에 크게 달려있음
효과적인 결과를 얻으려면 풍부한 맥락, 구체적 목표, 예시, 역할 부여, 반복적 개선 등의 규칙을 지켜야 함
디버깅, 리팩토링, 신규 기능 구현 등 주요 개발 작업별로 프롬프트 설계 패턴과 예시를 제공함
좋은 프롬프트는 목적, 언어, 환경, 오류 메시지, 입력/출력 예시 등 구체 정보를 담아야 함
신규 엔지니어도 따라 할 수 있는 프롬프트 설계법으로, 실제 AI 응답 비교와 코멘트가 포함됨

개요: 성공적인 프롬프트 엔지니어링의 중요성

최근 개발자들은 AI 코딩 어시스턴트를 사용해 함수 자동완성, 버그 수정, 전체 모듈 작성까지 작업 흐름을 가속화함
그러나 AI의 응답 품질은 프롬프트 품질에 결정적으로 좌우됨
좋은 프롬프트는 명확하고 창의적인 코드 솔루션을 유도하지만, 모호하거나 부실한 프롬프트는 제한적이고 무의미한 답변으로 이어짐
본 플레이북은 일상적인 개발 작업에 적용할 수 있는 효과적인 프롬프트 설계법을 실용적으로 정리함

효과적인 코드 프롬프트의 기본 원칙

풍부한 맥락 제공: AI는 프로젝트나 의도를 사전에 알지 못하므로, 사용 언어·프레임워크·라이브러리·에러 메시지·코드 목적 등 모든 관련 정보를 명시함
명확한 목표나 질문 제시: “왜 코드가 안 돼?”와 같은 모호한 질의 대신, 원하는 결과와 현재 상황을 명확하게 기술함
복잡한 작업 분할: 대규모 기능 개발 등은 한 번에 모두 요청하지 않고, 작은 단계로 쪼개어 점진적으로 요구함
입출력 예시나 기대 동작 포함: 실제 입력·출력이나 동작 예시를 주면 AI의 이해도가 크게 높아짐(“few-shot prompting”)
역할(페르소나) 활용: “React 시니어 개발자처럼 코드 검토” “성능 전문 지도로 최적화 요청” 등 책임 있는 역할을 부여해 AI의 응답 수준을 끌어올림
회화적 반복 개선: AI의 첫 번째 답변을 바탕으로 추가 요청이나 수정 요구를 통해 점진적으로 원하는 결과에 도달함
코드 일관성 유지: AI가 코드 스타일, 네이밍, 주석을 참고하므로 코드의 일관성과 명확성을 항상 유지함

디버깅을 위한 프롬프트 패턴

체계적 디버깅 프롬프트 설계법

문제 및 증상 명확 서술: 언어, 기능 목적, 기대 동작과 실제 에러 메시지, 코드 스니펫 등 풍부한 정보 제공
단계별·라인별 분석 요청: 논리 오류나 미묘한 버그는 “한 줄씩 변수 추적”이나 부분 코드 설명을 통해 원인을 파악하게 함
최소 재현 코드 활용: 복잡한 대규모 코드 대신, 에러가 발생하는 최소 단위의 코드를 추출해 문제를 집중적으로 진단함
직접적 질문 및 후속 요청: “어디서 버그가 발생하는가?”, “수정된 코드 제공” 등 명확하고 반복 가능한 피드백 요청

예시: 잘못된 프롬프트 vs. 개선된 프롬프트

문제 코드 예시

function mapUsersById(users) {
  const userMap = {};
  for (let i = 0; i <= users.length; i++) {  
    const user = users[i];
    userMap[user.id] = user;
  }
  return userMap;
}
const result = mapUsersById([{ id: 1, name: "Alice" }]);

잘못된 프롬프트:

“왜 mapUsersById 함수가 동작하지 않을까?”

AI의 응답: “배열이 비었거나 user에 id가 없을 수도 있다” 등 모호한 추측 제시
문맥 부족과 불분명성으로 인한 일반적인 조언만 나옴

개선된 프롬프트:

“mapUsersById 함수가 사용자 배열을 id별로 매핑해야 하는데, [ {id: 1, name: "Alice"} ] 입력 시 TypeError: Cannot read property 'id' of undefined 에러 발생. 코드는 다음과 같다: [코드 포함] 기대 결과는 { "1": ... } 이런 현상 원인과 해결책은?”

AI의 응답: 반복문의 조건 (i <= users.length)이 범위를 초과해 마지막 반복에서 undefined가 발생하는 것을 짚어줌, i < users.length로 수정 제안
구체적 맥락, 오류 메시지, 기대 동작 제공으로 정확한 해결책 도출

추가 디버깅 프롬프트 전략

버그 원인 후보 목록화 요청(“TypeError의 가능한 원인?” 등)
코드 동작 논리 직접 설명 후 검토 요청(“내 설명이 맞는지, 문제점을 찾아달라”)
돌발 상황 테스트케이스 요청(“이 함수가 실패할 수 있는 입력 2개만 제안”)
꼼꼼한 코드 리뷰어 역할 부여(“이 코드를 리뷰하며 문제점과 개선사항을 설명”)

리팩토링/최적화를 위한 프롬프트 패턴

명확한 개선 목표 제시

“리팩토링 하라”는 모호하므로, 가독성, 성능, 유지관리성, 코드 중복 제거 등 구체 목표를 명시
코드 전체(또는 필요한 맥락)와 환경, 언어, 프레임워크 버전을 충분히 제공
변경 사항에 대한 설명도 요청(“코드와 개선 포인트를 함께 알려줘”)
“타입스크립트 전문가로서 최신 관례에 맞게” 등 역할 부여로 기대 품질 상향

예시: 리팩토링 프롬프트 비교

원본 코드

(중복 fetch, 효율 낮은 자료 구조 등 문제 포함)

async function getCombinedData(apiClient) {
  // Fetch list of users
  const usersResponse = await apiClient.fetch('/users');
  if (!usersResponse.ok) {
    throw new Error('Failed to fetch users');
  }
  // ... (이하 생략)
}

모호한 프롬프트

“getCombinedData 함수를 리팩토링 하라”

AI가 임의로 병렬 fetch, 에러 메시지 통합 등 변경(요구 사항이 없으므로 행동이 예측 불가)

구체적 목표 명시 프롬프트

“중복 제거, 성능 개선, 두 fetch 병렬화, 에러 메세지 분리, 데이터 결합은 효율적 방식으로 개선하라. 주석과 개선 포인트 설명까지”

AI의 응답: 병렬 fetch, 에러 구분, 효율적 map 자료구조 도입 등 명확히 목표를 반영한 리팩토링 및 상세 설명 제공

추가 리팩토링 팁

단계별 요청(“가독성 개선→알고리듬 최적화” 순차 적용)
다른 접근 방식 요청(“함수형 스타일로도 구현해줘” 등)
코드+설명 방식 요청을 통한 학습과 튜토리얼화
결과 코드에 대한 테스트 추가 요청

신규 기능 구현 프롬프트 패턴

단계별 코드 생성 유도

고수준 설명(어떤 기능을 만들고 싶은지)을 먼저 제시, 이후 단계적으로 세분화
기존 유사 코드, 프로젝트 패턴, 사용 라이브러리 등 작업 환경 맥락 전달
주석이나 TODO를 프롬프트로 활용해 IDE에서 직접 AI의 코딩 흐름 유도
입력/출력 예시나 테스트 케이스를 제공해 명확한 결과 기대치 부여
첫 결과가 미흡하다면, 바로 구체적 개선점 또는 코드 스타일을 추가 명시해 반복 요청

예시: React ProductList 컴포넌트 생성

“ProductList라는 React 함수형 컴포넌트를 만들어라. /api/products에서 상품 배열을 가져와 리스트로 출력하고, 입력창에서 상품명을 입력하면 대소문자 구분 없이 필터링함. 가져오는 과정의 로딩, 에러 처리도 필요.”

AI 응답: useState, useEffect로 데이터 fetch, 입력 처리, 필터링, 에러·로딩 UI 구현 등 포함
만약 프로젝트에서 커스텀 훅을 활용한다면 “useProducts() 훅을 사용하도록 리팩토링하라” 식으로 추가 지시 반복 가능

실무적 프롬프트 고도화 사례

“정렬 기능을 추가해라: A-Z, Z-A 드롭다운이 있어야 함” 등 점진적 기능 확장 요청 가능
구현 코드 흐름을 단계별 쪼개어, 각 단계별로 프롬프트를 달리해 코드 품질과 일관성 유지

결론

AI 코딩 어시스턴트의 잠재력을 최대한 활용하려면, 프롬프트 설계가 핵심 역량임
성공적인 프롬프트를 작성하려면 항상 구체적 맥락, 목적, 예시, 반복적 피드백, 역할 부여를 염두에 두어야 효과적인 결과 도출 가능
AI를 프로젝트 내의 신입 개발자 혹은 코드 리뷰어로 여겨, 원하는 방향으로 상세히 안내하고 점진적으로 퀄리티를 높이는 것이 성공의 비결임

▲

GN⁺ 1일전 [-]

Hacker News 의견

제 경험으로 보면 진짜 프롬프트 엔지니어링 기법은 세 가지뿐이라는 생각임
- In Context Learning(문맥 안에서 예시 제공, 즉 one shot이나 few shot 방식과 zero shot 대비)
- Chain of Thought(단계별로 생각하게 지시)
- Structured output(예를 들어 JSON처럼 출력 형식을 명확히 지정)
  여기에 이 글에서 언급하는 Role Prompting도 추가할 수 있을 듯
  RAG는 모델이 제공된 문맥을 요약하는 방식이라 따로 분류
  결국 나머지는 원하는 것을 명확하고 평이한 언어로 요청하는 방법 요약
- 프롬프트에선 문맥이 가장 중요한 요소임
  예를 들어 Typescript로 시작해서 데이터 사이언스 질문을 하면 제대로 대답 못하는 현상 확인
  Python으로 똑같이 질문하면 훨씬 잘 나옴
  LLM은 아직 도메인 간 지식 이전이 힘들기 때문에 반드시 목적에 맞는 문맥 설정 중요
- Role prompting도 개인적으로 의미 없는 방식이라고 생각
  GPT-3에선 그랬을지 몰라도 대부분의 LLM은 이미 "전문가" 역할을 알고 있음
  "프롬프트 엔지니어링"에 과몰입하는 건 스스로를 속이는 행동이라 생각
  요구사항을 명확히 전달하고 필요하다면 예시 추가, 결과물이나 reasoning trace 확인, 원하는 결과가 안 나오면 조정해서 다시 시도하는 식
  몇 번 시도해도 답이 안 나오면 AI 말고 내 머리로 reasoning 해보는 선택
- 많은 이들이 "한 번에 모든 걸 한 프롬프트에 넣으려고" 하는 시도가 문제라는 의견
  오히려 거대한 요청 한 번에 넣지 말고, 작은 컨텍스트로 나눈 여러 개의 프롬프트로 쪼개고 각기 명확한 구조화된 출력을 서로 연결하는 방법 제안
  프롬프트 하나하나씩 목적과 예시에 집중, 컨텍스트 오버로드 피하기
  그러면 위에서 언급한 3가지 핵심 방법이 자연스럽게 적용
- 3번째 방식(Structured output)과 관련해 저와 동료들이 과학 분야에서 적용 사례 연구
  논문 링크
- 참고로 저희 팀은 prompt engineering보단 fine tuning에 더 많이 의존
  few-shot prompt 방식이 저희 케이스엔 효과가 없었음
저는 프롬프트가 너무 길거나 복잡해지면 오히려 모델의 인지 성능이 떨어지는 느낌을 자주 받음
복잡한 프롬프트가 컨트롤하는 느낌을 줄 수는 있지만, 실제로는 꼭 이점이 아닐 수도 있음
그래서 사용 패턴이 아주 단순하고 미니멀한 프롬프트로 대충 맞추고, 몇 번 반복 수정하는 방향으로 자연스럽게 수렴
- 저도 완전히 같은 방식으로 접근하기 시작한 경험
  1. 꼭 필요한 컨텍스트와 전제사항, 목표만 간략하게 전달
  2. 답변을 확인하고 초기 프롬프트 수정
    이런 방식이 비용 효율에도 좋음
    agent를 썼다가 $30씩 태우고 코드베이스 엉키거나 원래 코드대로 돌아가는 경험이 너무 많았음
    또 AI가 내 프로젝트에 코드 많이 쓰게 두면, 나중에 그 코드가 내 머리에 잘 안 남고 관리도 어려워진다는 점 경고하고 싶음
- 전문가의 용어를 사용해서 프롬프트를 입력하면 성능이 더 좋다는 근거도 있음
  일반적으로 사람들이 일상 언어로 이야기하는 환경은 정확도가 떨어지지만, 특정 전문 분야의 어휘는 더 신뢰성 높은 답으로 연결
  트레이닝 데이터도 이런 분포를 반영
- 저도 비슷한 경험
  그런데 agent 시스템 프롬프트를 보면 엄청 길고 복잡한 경우 많아서 의문 생김
  실제 그런 프롬프트가 어떻게 동작하는지 궁금
  시스템 프롬프트 예시 링크
- 어떤 작업에서는 제 동료가 아주 장황한 프롬프트를 썼음
  통합 과정에서 CRUD operation 추가하고, 실험 삼아 "이걸 <직군> 입장에서 분석" 정도로 정말 짧게 바꿔봄
  결과적으로 양쪽 결과가 거의 비슷했고, 오히려 긴 프롬프트는 일부 문장을 그대로 출력에 다시 쓰는 현상
  결과 자체는 괜찮았으나 결국 모델(gemini 2.5)은 중요한 정보만 뽑아 보고, 나머지 불필요한 부분까지 결과에 녹여버림
  즉, 적어도 이 과제에서는 장황함이 모델의 "사고 방식"에 흥미로운 영향을 주진 못한다는 느낌
- 저도 같은 결론에 도달했지만, AI 연구소에서 제공하는 긴 프롬프트 사용 예시를 어떻게 해석해야 할지 궁금
  Anthropic 시스템 프롬프트 예시
"프롬프트 엔지니어링"이라는 건 따로 존재하지 않는다는 생각
언제부터 제대로 의미 있는 문장을 쓴다고 엔지니어링이 됐는지 의문
"소프트웨어 엔지니어링"보다 더한 일이라 생각
다만 앞으로 이런 것도 직업(프롬프트 엔지니어)으로 뜨고, 문장 쓰는 특별한 능력으로 자리 잡을 가능성은 안타까운 점
- 사실 "제대로 의미 있는 문장"은 수많은 변수에 따라 달라지는 문제
  실제로는 테스트, 관리, 로깅, 버전 관리까지 포함하면 단순 감각이 아닌 엔지니어링이 되는 것
  특정 순서/스타일/문제 재진술 등 구조화 아주 중요
  파라미터가 많은 패밀리 모델 다루는 경우, API 기반 모델은 버전업마다 기존 프롬프트와 호환체크 필요
  이런 체크와 테스트도 프롬프트 엔지니어링 과정
  유행/하이프에 반감하는 태도에 치우치다 본질 간과하는 경우 많다는 의견
- 우리 동네 바리스타가 자기 이름에 커피 엔지니어 붙이면 차라리 믿음이 갈 법
- 알고리즘 중독으로 요즘 소비자들은 문장 다 읽는 능력조차 쇠퇴한 영향
- “프롬프트 엔지니어” 구인 걱정까진 할 필요 없다고 봄
- AI sloperators는 자기 일을 있어 보이게 만드려 기를 씀
제 경험상 LLM이 못 푸는 문제는 아무리 프롬프트 "엔지니어링" 해도 소용 없는 경우 많음
오히려 부분 문제로 쪼갠 뒤 조금씩 진행하게 두는 방법밖에 없음
반대 경험하신 분 있으면 사례 듣고 싶음
- LLM 사용의 중요한 부분은 문제를 적절히 어떻게 쪼갤지 감을 잡는 것
  언제 어떻게 쪼갤지, 언제 그냥 맡길지 감별 능력 필요
  기사에서도 언급했다시피 이런 노하우 중요
  앞으로 코드를 더 뛰어나게 조직화/주석 처리해서 LLM과 상호작용을 개선하는 방법도 많아질 것
  LLM 자체도 점점 이런 방향에서 진화하고, 문제 쪼개는 방법 제안까지 할 수 있을 거로 기대
- 프롬프트 엔지니어링의 목적은 원하는 형식으로, 더 빠르게 좋은 해답을 얻기 위함
  궁극적으로는 모델이 알아서 답해주길 바라지만, 현실적으론 질문 자체도 최적화 필요
프롬프트 작성 시 평소 습관 때문에 자연어로 지시하는 게 여전히 어색하게 느껴짐
뭔가 정확한 인자나 SQL 쿼리처럼 써야 할 것 같은 느낌
채팅하듯이 툴에 말하듯이 지시하는 것도 신기함
그래도 자연어 지시를 이해하는 툴이 된 건 접근성을 극적으로 높였다고 봄
그런데도 여전히 사람에게 말하는 것처럼 프롬프트를 쓰는 내 모습이 좀 우습게 느껴짐
요즘 프롬프트 가이드 같은 게 엄청 많음
근데 실제론 별로 필요 없다는 생각
직접 툴을 써보고 친숙해지고 사용법을 익히면, 어떤 프롬프트가 좋은지 자연스럽게 알게 됨
- 예전 Google이 유행하고 FOMO 열풍 있었던 시절과 비슷
  관련 책을 안 사면 원시인처럼 뒤처진다고 했는데, 실제로는 하루만에 다 습득할 수 있는 간단한 분야라 복잡하게 고민할 필요 없음
- 가이드나 팁 영상이 정말 도움이 되는 사람도 분명 있음
  많은 이들은 스스로 개선할 의지가 없지만, 한 번쯤 가이드나 고수의 영상을 보는 것만으로도 실력 상승
  저 역시 타인의 사용법이나 커뮤니티 경험에서 팁을 매번 배우는 편
  단지 혼자 연습한다고 이런 팁을 얻는 건 한계가 있음
- 예전에 “유저 스토리 작성 가이드”처럼 “As a [role], I want to [task] so I can [objective]” 공식이 있었음
  고수나 초보할 것 없이 대부분이 분명한 요구사항 전달에 도움 필요
  아무리 뛰어난 개발자도 비구조적 요구사항에는 실수하거나 오해 가능
- 남들이 이 툴로 어떻게 생산성 내는지도 참고가 꽤 됨
  내가 놓쳤던 아이디어도 발견
  트라이/에러로 직접 다 해보기 전에 이미 누가 해둔 경험을 조금이라도 배우는 게 더 효율적
  개인적으로 모든 걸 직접 해볼 시간 없는 입장에선, 이런 경험 공유는 정말 고마운 정보
- 눈에 잘 띄지 않는 트릭도 분명히 있음
  예를 들면, 프롬프트에서 “please” 같은 예의 표현은 다 빼도 된다는 경험
한참 전 컴공 대학원 때 프로그래밍 과학(Science of programming) 과목에서 배운 검증 과정을 데이터 엔지니어링 프롬프트 작성에 잘 응용
예를 들어 “input(…)과 전제(…)를 주고 post-condition(…)이 만족하는 spark 코드를 작성하게 요청”
입력, 전제, 결과조건을 명확하게 명시하면 좋은 코드 출력 가능
참고 교재
1. Science of programming, David Gries
2. Verification of concurrent and sequential systems
프롬프트 엔지니어링에 너무 열내는 건 과한 느낌
그냥 코드나 에러를 복사 붙여넣고 plain question 날리면 요즘 모델들은 대부분 알아서 잘 처리
지나치게 꼬아서 쓸 필요 못 느낌
며칠 전 Sergey Brin이 AI 커뮤니티에서 자주 언급되지 않는 사실이라며 “물리적 위협을 하면 모델 성능이 더 좋아진다”고 말함
관련 기사
- 유튜브 “Programmers are also human”에서 프로 vibe 코더가 LLM 명령 끝에 항상 “.. 아니면 감옥 간다”라는 농담 떠올림
- 그래서 Google이 "Don't Be Evil"을 슬쩍 버린 건가 싶음
프롬프트 작성을 "엔지니어링"이라고 부르는 건 엄청 진지하지 못하다는 느낌
- 예전에 프롬프트 "엔지니어링" 유행할 때 들은 재밌는 비유가 있음
  
  프롬프트 엔지니어를 Subway 샌드위치 가게 직원이 "샌드위치 아티스트"라고 부르는 거랑 똑같음
  농담은 농담이고, 엔지니어라는 말은 이미 너무 광범위하게 쓰이다 보니 별 의미 없어짐
  Sandwich Artist info 링크
- 결국 이 논란은 소프트웨어 엔지니어링 얘기 나올 때마다 반복
- 상상력이 그냥 채팅 인터페이스에서 고양이 사진 요청하는 수준에 멈춰서 그러는 걸지도
  실제론 API와 자동화 워크플로우에 쓰이는 프롬프트도 있어서, 그 이상임
- 미국엔 "sales engineer"라는 직함도 있는데, 제 경험상 이 사람들은 자기가 파는 제품이 어떻게 동작하는지 전혀 모르는 경우 많음
- IT는 단어와 그 의미들이 사라지는 곳
  단어가 원래 의미를 가질 필요가 있냐는 생각이 들 정도

답변달기