코드 작성을 위한 프롬프트 엔지니어링은 작동하는 풀 리퀘스트를 배포하는 에이전트와 프로덕션에서 조용히 무언가를 깨뜨리는 에이전트의 차이다. 우리는 그걸 비싼 대가로 배웠다: 우리 파이프라인의 한 가지 모호한 지시 하나로 인해 누구도 알아차리지 못한 채 54개의 중복된 라이브 페이지가 생성되었다. 요즘에는 16개 에이전트로 구성된 Claude Code 설정이 우리 콘텐츠를 작성, 번역, 발행하고 있으며, 이를 구동하는 프롬프트는 구글 첫 페이지의 50개 템플릿 목록과는 완전히 다르다. 다음은 매일 우리가 작성하는 7가지 패턴이며, 각각 실제 전후 사례를 포함하고 있다.
간단한 답: 좋은 코딩 프롬프트는 하나의 구조를 공유한다. 목표와 "완료"의 정의를 명시하고, 정확한 파일 범위를 지정하고, 편집 전에 계획을 먼저 세우고, 테스트를 넘겨주고, "괜찮아 보인다"는 대신 증거를 요구한다. 이렇게 하면 현대적인 에이전트(Claude Code, Cursor, GitHub Copilot)는 첫 시도에서 검토를 통과하는 코드를 훨씬 더 자주 작성한다. 이를 건너뛰면 자신감 넘치지만 그럴듯한 형편없는 결과물을 얻는다.
7가지 패턴, 우리가 사용하는 순서대로:
- 작업 프레이밍: 목표, 제약, "완료" 조건을 먼저 제시
- 맥락 선택: 파일을 명시하고 나머지는 제외
- 계획 우선: 편집 전에 접근 방식을 제시하도록 강제
- 테스트 우선: 수용 테스트를 프롬프트에 포함
- 디버깅: 오류와 재현 및 예상 결과, 수정 전에 근본 원인 파악
- 리팩토링: 구조를 변경하되 동작은 유지, diff 표시
- 검토: grep으로 확인할 체크리스트와 증거 제시
코드 작성을 위한 프롬프트 엔지니어링 vs. 설정 파일: 무엇이 어디에 가는가
설정 파일과 작업별 프롬프트는 다른 역할을 하며, 둘을 혼동하는 것이 이 분야에서 가장 흔한 실수다. CLAUDE.md나 .cursor/rules 파일은 에이전트가 매 세션마다 읽는 상시 정책이다: 스택, 네이밍 규칙, 테스트 명령어. 프롬프트는 지금 당신이 넘기는 구체적인 작업이다. 지속적인 규칙은 설정에 가고, 작업은 프롬프트에 간다.
대부분의 "코딩 프롬프트" 정리는 이를 혼동하고 거대한 페르소나 프롬프트를 .cursorrules에 붙여넣으라고 말한다. 이는 에이전트가 모든 단일 작업에서 로드하는 설정을 부풀리면서도 앞에 있는 한 가지 작업을 프레임하는 데 여전히 실패한다. 두 가지를 분리하라:
설정 측이 제대로 이루어지길 원한다면 우리는 CLAUDE.md 모범 사례와 Cursor 규칙 가이드에서 깊이 있게 다룬다. 이 문서는 반대쪽이다: 매번 새로 작성하는 프롬프트다. 둘 다 기초를 먼저 원한다면 우리의 광범위한 프롬프트 엔지니어링 가이드에 있다.
코드 작성을 위한 프롬프트 엔지니어링: 매일 사용하는 7가지 패턴
아래의 각 패턴에는 사람들이 실제로 작성하는 약한 버전과 작동하는 코드를 얻는 강한 버전이 있다. 약한 버전에서 강한 버전으로의 전환은 거의 항상 같은 방식이다: 소망을 명세로 바꾼다.
1. 작업 프레이밍: 목표, 제약, "완료"를 명시하라
작업 프레이밍은 에이전트가 한 줄도 건드리기 전에 목표, 제약, "완료"가 무엇인지를 기술하는 것을 의미한다. 에이전트는 당신이 말한 것을 문자 그대로 최적화하므로, 모호한 요청은 모호한 패치를 초래한다. 파일을 명시하고, 원하는 동작, 수용 기준, 변경하지 말아야 할 것들을 명시하라.
이것이 우리에게 54개의 페이지를 안겨준 패턴이다. 우리의 예전 번역 지시는 기본적으로 하나의 소망이었다:
그 안에는 슬러그가 무엇을 할 수 있는지에 대한 아무 말도 없다. 따라서 다시 실행할 때 에이전트는 URL 슬러그를 "개선"했고, 새 슬러그는 새 문서를 의미하므로 같은 포스트에 대해 2개의 라이브 독일어 페이지가 생겼다. 여러 언어와 오래된 포스트에 걸쳐 곱하면 54개의 중복과 중복 콘텐츠 제외의 더미를 얻는다. 해결책은 더 나은 소망이 아니라 명세였다:
강한 프롬프트는 실패 모드를 큰 목소리로 명시한다. 무엇이 일어나면 안 되는지, 그 이유가 무엇인지를 말하는 이 단 하나의 습관이 대부분의 팀이 할 수 있는 가장 가치 있는 변화 중 하나다. 우리는 또한 모든 작업 프롬프트를 명시적인 출력 계약으로 끝낸다("최종 메시지는 단어 수, 검증 점수, 그리고 건드린 파일을 보고해야 한다"). 그래서 에이전트는 무엇을 할지뿐만 아니라 "완료"가 무엇을 산출하는지 안다.
2. 맥락 선택: 파일을 명시하고 나머지는 제외하라
맥락 선택은 에이전트가 grep을 돌아다니며 창을 노이즈로 채우도록 두는 대신, 정확히 어느 파일을 읽고 어느 파일을 그대로 둘 것인지를 명시하는 것을 의미한다. Anthropic 자체 가이드는 그 이유에 대해 명확하다: 맥락 창이 빠르게 차고 채워질수록 품질이 떨어지므로 대부분의 모범 사례는 이를 보호하기 위해 존재한다(Claude Code 모범 사례).
우리는 엄격하게 제한한다. 우리 에이전트 프롬프트의 실제 한 줄은 다음과 같다: "url-mapping.json, pipeline.md, config.json에 쓰지 말고, 스크래치패드 디렉토리 밖의 어떤 파일도 건드리지 마라." 그 한 줄이 사후 정리보다 훨씬 더 많은 실수로 인한 손상을 방지했다. 작업이 정말로 라이브 문서나 추가 도구가 필요할 때, 우리는 에이전트가 올바른 파일에 우연히 부딪히길 기대하는 대신 MCP 서버를 통해 의도적으로 추가한다. 그리고 그 맥락이 저장소 외부에서 온다면 신뢰할 수 없는 것으로 취급하라: 긁어온 페이지를 코딩 에이전트에 붙여넣기 전에 프롬프트 주입 방지에 대한 우리의 주석을 읽어라.
3. 계획 우선: 편집 전에 제시하도록 강제하라
계획 우선 프롬프트는 에이전트가 어떤 것도 편집하기 전에 접근 방식을 당신에게 제시하도록 한다. Claude Code에서 계획 모드는 에이전트가 지나갈 수 있는 정중한 "먼저 생각해"가 아니라 강제되는 읽기 전용 상태이므로 당신이 계획을 승인할 때까지 실제로 쓸 수 없다. 연구 및 계획을 실행과 분리하는 것은 Anthropic이 잘못된 문제를 푸는 것을 피하기 위해 가장 많이 활용하는 단일 관행이다.
작동하는 이유: 계획은 읽기가 저렴하고 수정도 저렴하다. 잘못된 계획을 고치는 데 한 문장이 들고, 잘못된 코드를 고치는 데 검토 사이클이 든다. 이는 모델에 단계별로 추론하도록 요청하는 것과 자연스럽게 짝을 이룬다(연쇄 추론 프롬프트 참고), 그리고 그것은 사소하지 않은 모든 것에 대해 우리가 실행하는 다단계 Claude Code 워크플로우의 척추다.
4. 테스트 우선: 수용 테스트를 프롬프트에 넣어라
테스트 우선 프롬프트는 수용 기준을 프롬프트에 구체적인 입출력으로 넣으므로 에이전트는 그것이 추측한 것이 아니라 당신이 정의한 목표에 대해 코드를 작성한다. 실패하는 테스트를 붙여넣거나 작은 예상 결과 표를 붙여넣고 "테스트를 편집하지 않고 이를 통과하는 코드를 작성하라"고 말하라.
구체적인 예는 형용사를 매길 수 없다. "엣지 케이스를 처리하라"는 희망이다; 4개의 입출력 행은 모델이 실제로 만족할 수 있는 명세이며, 코드가 내려앉으면 즉시 실행할 수 있다.
5. 디버깅: 오류, 재현, 예상, 수정 전 근본 원인
디버깅 프롬프트는 에이전트에게 오류 텍스트, 이를 트리거하는 입력, 예상되는 것을 주고 어떤 수정도 전에 원인을 묻는다. 그걸 건너뛰면 에이전트는 증상을 패치하므로 버그는 단순히 더 조용한 곳으로 이동한다.
"먼저 한 문장으로 원인을 설명하라"는 줄은 실제 작업을 하고 있다. 그것은 모델이 당신이 건전성을 검토할 수 있는 진단에 약속하도록 강제하고, 로직을 절대 보지 않은 수정을 배포하는 대신이다. "try/catch에 숨기지 마라"는 줄은 가장 흔한 탈출구를 닫는다.
6. 리팩토링: 구조를 변경하되 동작은 유지하고 diff를 보여라
리팩토링 프롬프트는 범위를 엄격하게 제한한다: 구조를 변경하되 동작은 완전히 같게 유지하고 diff를 보여라. 울타리가 없으면 에이전트는 당신이 요청하지 않은 것들을 "정리"하고, 중요한 변경 사항을 검토할 능력을 잃는다.
이것은 앞의 설정 대 프롬프트 분할의 반대편이다: 당신의 상시 스타일 규칙은 Cursor 규칙에 살고 있지만, 이 리팩토링의 범위는 프롬프트에 속한다. "다른 것은 아무것도 변경하지 마라"는 표현이 리팩토링을 검토 가능하게 유지한다.
7. 검토: grep으로 확인할 체크리스트와 증거
검토 프롬프트는 에이전트에게 grep으로 확인할 체크리스트를 주고 판정이 아니라 증거를 요구한다. "괜찮아 보인다"는 가치가 없다; 그것이 실행한 명령과 그것이 얻은 출력은 그렇지 않다. Anthropic은 이를 명확히 말한다: 에이전트가 증거(테스트 출력, 명령과 그 결과)를 보여주도록 하라. 증거를 읽는 것이 직접 검증하는 것보다 빠르기 때문이다.
...