🎱 AI에게 '시니어 엔지니어'처럼 지시할 수 있는, 저장해 둘 만한 프롬프트 8가지!
🧰 Claude Code나 Codex 같은 모델에게 단순히 "로그인 기능을 만들어줘"라는 한 문장만 던져주는 것은 마치 인테리어 전문가에게 "거실을 예쁘게 꾸며줘"라고 말하고 나가는 것과 비슷합니다. AI는 추측에 의존할 수밖에 없고, 잘못된 추측은 관련 없는 파일들을 여기저기 수정하게 만들고, 결국 돌아와서는 사용자가 하나하나 정리해야 하는 상황이 발생합니다. 제가 사용하는 방법은 "무엇부터 해야 하는지, 무엇을 하지 말아야 하는지, 최종적으로 무엇을 돌려받아야 하는지"를 프롬프트에 명확히 규정하는 것입니다. 이렇게 하면 같은 모델이라도 결과물의 수준 차이가 크게 달라집니다. 아래 8가지 내용은 제가 상황별로 정리한 것이며, 양쪽 모두 사용할 수 있습니다. 대괄호([]) 안의 내용을 본인의 상황에 맞게 바꿔서 사용하시면 됩니다.
온라인 오류 발생 시, 원인을 찾지 못하고 있을 때: AI에게 바로 코드를 수정하게 하지 말고, 먼저 병을 정확히 진단하도록 강제해야 합니다:
"이것은 운영 환경에서 발생하는 에러와 관련 코드입니다: [붙여넣기]. 어떤 파일도 수정하지 마세요. 다음 순서대로 알려주세요: 이 코드의 원래 목적은 무엇이었는지, 오류가 발생했을 때 실제로 무슨 일이 일어났는지, 당신이 판단하는 근본적인 원인과 그 근거, 그리고 동일한 문제가 발생할 수 있는 경계 조건(boundary case)에는 어떤 것들이 있는지. 제가 근본 원인을 확인한 후에만 수정 방안을 제시하고, 이 수정 사항이 제대로 작동했는지 검증할 수 있는 명령어 또는 테스트 케이스를 함께 첨부해 주세요."
이렇게 작성하면 AI가 원인 분석을 잘못했을 경우 즉시 알아차릴 수 있으며, 세 개의 파일을 수정하고 롤백(rollback)하는 번거로움을 피할 수 있습니다.
낯선 저장소(repository)를 맡았을 때, 첫 번째 임무는 지도를 그려달라고 하는 것입니다. 성급하게 코드를 건드리지 마세요:
"제가 이 프로젝트를 새로 인계받았습니다. 먼저 전체 코드를 읽고, 몇 문단에 걸쳐 전체 구조, 핵심 모듈, 그리고 하나의 요청이 데이터를 어떻게 흐르는지(data flow)를 명확히 설명해 주세요. 그 후 발견한 문제점들을 목록으로 작성해 주세요: 구조가 혼란스러운 부분, 중복 코드, 잠재적인 성능 병목 지점(performance bottleneck), 향후 유지보수가 어려울 수 있는 부분. 각 항목에는 파일명과 줄 번호(line number)를 명시하고, 심각도 순서대로 정렬해 주세요. 이 단계에서는 보고서만 작성하고 코드는 수정하지 마세요."
보고서를 바탕으로 리팩토링을 결정했을 때 가장 두려운 것은 기능이 조용히 변하는 것입니다. 따라서 '행동의 불변성(behavior invariance)'을 필수 조건으로 명시해야 합니다:
"위 보고서에 따라 [모듈명]을 리팩토링해 주세요. 외부 동작과 인터페이스는 완전히 변경되지 않아야 합니다. 작업을 시작하기 전에, 현재 행동을 모두 커버할 수 있는 테스트 코드를 먼저 작성하여 실행하고 모든 것이 통과하는지 확인한 후, 리팩토링을 진행해 주세요. 리팩토링이 완료된 후에는 동일한 테스트 묶음을 다시 실행해 주세요. 마지막으로 새로운 디렉토리 구조, 각 모듈의 현재 책임 범위, 그리고 전체 변경 목록을 완벽하게 정리해서 제공해 주세요."
테스트 코드를 먼저 작성하는 과정은 마치 이사 전에 가구 하나하나 사진을 찍어두고, 이사 후에 사진과 대조하며 빠진 것이 없는지 확인하는 것과 같습니다. 빠진 부분이 있으면 한눈에 알 수 있습니다.
코드는 돌아가지만 느릴 때, 성능 엔지니어 역할을 맡기고 숫자로 말하게 하세요:
"이 코드가 [구체적인 시나리오, 예: 목록 항목이 1만 개를 초과할 때]에서 눈에 띄게 느려집니다: [붙여넣기]. 실행 속도, 메모리 점유율, 데이터 증가에 따른 성능 세 가지 관점에서 병목 지점을 찾아주세요. 비효율적인 반복문이나 쿼리, 불필요한 중복 렌더링 또는 계산을 포함합니다. 각 문제점마다 왜 느린지, 얼마나 빨라질 것으로 예상되는지를 설명하고, 개선된 코드를 제시해 주세요. 수익성(impact)이 큰 순서대로 정렬하도록 요청하는 것은 가장 가치 있는 부분부터 수정하게 하여 하루 종일 시간을 낭비하지 않게 하기 위함입니다."
프론트엔드 컴포넌트를 작성할 때, AI는 기본적으로 '보기 좋은 스크린샷' 버전만 제출합니다. 로딩 중(loading), 오류 발생(error), 데이터 없음(empty data) 같은 상황들은 자주 누락되므로 하나하나 명시해야 합니다:
"[React/Vue]를 사용하여 재사용 가능한 [컴포넌트명] 컴포넌트를 작성해 주세요. 반드시 로딩 중, 로드 실패, 빈 데이터, 초장문 텍스트 등 여러 상태를 처리할 수 있어야 하며, 모바일과 데스크톱 모두에서 정상적으로 표시되어야 합니다. 키보드 조작 및 스크린 리더(screen reader) 지원도 필수입니다. 먼저 props 설계와 그 이유를 제시하고, 구현 코드를 작성하며, 마지막으로 사용 예시 2~3개를 첨부해 주세요."
기존 시스템에 트래픽을 감당해야 할 기능을 추가할 때 (예: 메시지 알림 또는 순위표), 디자인과 구현을 두 단계로 나누어 받게 하세요:
"기존 시스템에 [기능]을 추가하려고 합니다. 예상되는 [일간 활성 사용자 수(DAU) 또는 초당 요청량]입니다. 먼저 설계도를 제시해 주세요: 컴포넌트 분할 방법, 데이터 흐름 방식, API 정의, 테이블 구조 변경점, 캐시를 어느 계층에 배치하고 언제 만료시킬지. 제가 설계를 확인한 후에만, 실제로 배포 가능한 최소 기능 버전(Minimum Viable Product)만 구현하고, 당장 사용하지 않는 확장 지점은 주석 처리하여 남겨두세요."
제로베이스에서 새로운 제품을 만들 때는 역시 아키텍트 역할을 맡기세요. Claude Code에서는 Shift+Tab을 눌러 Plan Mode로 전환할 수 있습니다. 이 모드에서는 파일을 읽고 계획만 세우며, 승인하기 전까지는 어떤 파일도 수정하지 않습니다. 다음 상황에 활용하세요:
"저는 [제품 한 문장 설명]을 만들려고 합니다. 목표는 실제 사용자가 사용할 수 있는 최소 버전이며, 향후 사용자 증가에 대응할 수 있도록 확장 가능해야 합니다. 먼저 시스템 아키텍처, 디렉토리 구조, 데이터베이스 테이블 설계, API 목록, 프론트엔드 페이지 구조를 제시해 주세요. 제가 이 계획을 확인한 후에만 전체 코드를 작성해 주세요."
Plan Mode 사용법: https://t.co/H0AhURb4LD
작업량이 클 때는 AI가 여러 역할을 맡아 스스로 단점을 찾아내게 하세요:
"다음부터 네가 네 가지 역할로 순차적으로 작업해라: 아키텍트가 먼저 설계를 제시하고, 엔지니어가 그 설계에 따라 코드를 작성하며, 검토자가 버그, 보안 취약점, 그리고 설계와 맞지 않는 부분을 항목별로 지적하고, 최적화자가 검토 의견을 바탕으로 최종본을 수정해라. 각 역할의 결과물을 따로 목록으로 제시해야 하며, 특히 검토자는 최소 5가지의 구체적인 문제점을 제기해야 한다."
더 철저하게 작업하려면 Claude Code에서 /agents를 사용하여 검토자만 별도의 서브 에이전트(sub-agent)로 만들 수 있습니다. 설정 파일은 .claude/agents/에 저장합니다. 이 에이전트는 독립적인 컨텍스트를 가지므로, 코드를 작성하는 과정의 사고방식에 영향을 받지 않고 문제점을 지적할 수 있습니다.
서브 에이전트 문서: https://t.co/r4JVkREUb5
오늘 당장 할 수 있는 한 가지는 가장 자주 사용하는 2~3가지 규칙(예: "코드 수정 전 원인과 계획 먼저 설명하기", "리팩토링 시 테스트 케이스 보강 필수")을 골라 프로젝트 루트 디렉터리의 설명 파일에 작성하는 것입니다. Claude는 CLAUDE.md를 읽고, Codex는 AGENTS.md를 읽게 합니다. 한 번 작성해 두면 이후 작업 시작 시마다 자동으로 적용되어 매번 붙여넣을 필요가 없습니다.
CLAUDE.md: https://t.co/BTp4MPL6lu
AGENTS.md: https://t.co/KfKWi48gwJ