{"content_id":"vduimuvis9","slug":"claude-code-prompt-six-principles-and-templates","locale":"ko","schema_type":"HowTo","category":"tutorial","category_name":"튜토리얼","title":"Claude Code 결과물의 완성도를 높이는 프롬프트 6원칙","summary":"Claude Code에 단순히 코드를 만들어 달라고 요청하는 대신 배경, 출력 계약, 예외 처리, 검증 기준을 구조화해 전달하는 방법을 설명합니다. 신규 에이전트 개발, 기능 추가, 오류 수정에 바로 적용할 수 있는 프롬프트 템플릿도 제공합니다.","sponsorship_disclosure":null,"author":{"name":"인조이스 편집팀","url":"https://injoys.com/ko/about"},"key_points":["1. 작업을 시작하기 전에 사용자 배경, 해결할 문제, 성공 기준, 기술적 제약을 한 문서로 정리합니다.","2. 결과물의 파일 구조와 데이터 형식, 허용 범위, 완료 조건을 구체적인 출력 계약으로 지정합니다.","3. 외부 API 실패, 빈 결과, 중복 데이터, 인증 오류 등 예상 가능한 예외와 대응 정책을 정의합니다.","4. 계획 검토, 최소 기능 구현, 자동 테스트, 기능 확장의 순서로 작업을 나누고 단계마다 결과를 확인합니다.","5. 모호한 재작업 요청 대신 실패 사례와 측정 가능한 개선 목표를 제공하고 최종 인수 조건으로 검증합니다."],"content_markdown":"Claude Code와 같은 코딩 에이전트는 코드 한 조각만 생성하는 도구가 아니라 저장소를 탐색하고, 여러 파일을 수정하며, 테스트와 명령을 실행할 수 있는 작업 환경이다. 따라서 결과물의 품질은 문장이 얼마나 그럴듯한가보다 **작업 범위와 검증 방법을 얼마나 명확히 정의했는가**에 크게 좌우된다.\n\n좋은 프롬프트는 긴 설명문이 아니라 실행 가능한 작업 명세다. 무엇을 만들지뿐 아니라 왜 필요한지, 어떤 조건을 지켜야 하는지, 실패를 어떻게 처리할지, 무엇을 통과하면 완료인지까지 전달해야 한다.\n\n## 먼저 구분할 것: 프롬프트와 실행 환경\n\n바이브 코딩은 자연어로 의도를 전달하고 AI 에이전트가 구현을 맡는 협업 방식이다. 그러나 자연어로 요청했다는 사실이 코드의 정확성이나 운영 안정성을 보장하지는 않는다.\n\nClaude Code 작업에는 다음 요소가 함께 작용한다.\n\n| 요소 | 역할 | 프롬프트에서 확인할 내용 |\n|---|---|---|\n| 사용자 요청 | 목표와 변경 범위를 전달 | 목적, 우선순위, 금지 사항 |\n| 저장소 문맥 | 기존 구조와 규칙을 제공 | 프레임워크, 실행 명령, 관련 파일 |\n| `CLAUDE.md` | 반복해서 적용할 프로젝트 지침을 제공 | 코딩 규칙, 테스트 방법, 디렉터리 관례 |\n| 도구 권한 | 파일 수정과 명령 실행의 허용 범위를 통제 | 실행해도 되는 명령과 사전 확인이 필요한 작업 |\n| 외부 연결 | API, 데이터베이스, MCP 서버 등에 접근 | 인증 방식, 신뢰 경계, 실패 정책 |\n| 검증 절차 | 결과가 요구사항을 충족하는지 판정 | 테스트, 정적 분석, 수동 확인 항목 |\n\n프롬프트만 잘 작성해도 모든 문제가 해결되는 것은 아니다. 예를 들어 Claude Code가 예약 실행 코드를 만들 수는 있지만, 컴퓨터가 꺼져 있을 때도 작업을 실행하려면 별도의 서버, CI 서비스 또는 운영체제 스케줄러가 필요하다. 이메일 전송 역시 실제 공급자의 인증 정보와 발송 권한이 없으면 완성할 수 없다.\n\n## 원칙 1. 배경·목적·제약을 먼저 설명한다\n\n`뉴스 수집 에이전트 만들어 줘`처럼 결과물 이름만 제시하면 에이전트는 사용자, 데이터 출처, 실행 환경과 성공 기준을 추측해야 한다. 같은 뉴스 수집기라도 사업 개발 담당자, 투자자, 대학 신문 편집자가 필요로 하는 출처와 분류 기준은 다르다.\n\n### 불충분한 요청\n\n```text\nAI 뉴스 수집 에이전트를 만들어 줘.\n```\n\n### 개선한 요청\n\n```text\n나는 IT 스타트업의 사업 개발 담당자다.\n매일 업무 시작 전에 AI, 클라우드, 핀테크 분야에서\n사업 제휴나 제품 전략에 영향을 줄 뉴스를 빠르게 확인하려고 한다.\n\n목표:\n- 지정한 키워드별로 최신 기사 후보를 수집한다.\n- URL이 같은 기사와 제목이 유사한 중복 기사를 제거한다.\n- 3개월 안에 제품 또는 제휴 의사결정이 필요한지를 기준으로\n  영향도를 높음, 보통, 낮음으로 분류한다.\n- 결과를 한국어 이메일 브리핑으로 만든다.\n\n제약:\n- 현재 저장소의 Python 버전과 패키지 관리 방식을 유지한다.\n- 새 라이브러리를 추가하기 전 필요성과 대안을 설명한다.\n- API 키와 이메일 비밀번호를 코드나 로그에 기록하지 않는다.\n- 실제 메일 발송 전에는 미리보기 파일만 생성한다.\n\n먼저 저장소 구조와 실행 방법을 조사한 뒤 구현 계획을 제안해 줘.\n모르는 환경 정보는 추측하지 말고 질문 목록으로 정리해 줘.\n```\n\n좋은 배경 정보에는 다음 네 가지가 들어간다.\n\n1. **사용자와 이용 상황:** 누가, 언제, 어떤 의사결정에 사용하는가\n2. **목표:** 코드 작성 자체가 아니라 해결해야 할 문제는 무엇인가\n3. **제약:** 유지해야 할 기술, 보안 규칙, 비용 또는 시간 한도는 무엇인가\n4. **비목표:** 이번 변경에서 명시적으로 제외할 기능은 무엇인가\n\n비목표를 적으면 범위가 무한히 커지는 것을 막을 수 있다. 예를 들어 `이번 단계에서는 예약 실행과 실제 이메일 발송은 제외한다`고 정하면 수집과 분류 로직부터 안정적으로 검증할 수 있다.\n\n## 원칙 2. 원하는 출력 형식을 출력 계약으로 만든다\n\n`메일로 보기 좋게 보내 줘`는 사람마다 다르게 해석된다. 출력 형식은 예시만 보여 주기보다 필수 필드, 허용 값, 누락 처리, 정렬 순서를 함께 정의해야 한다.\n\n```text\n이메일 제목:\n[뉴스 브리핑] {YYYY-MM-DD} 오늘의 핵심 뉴스\n\n본문의 기사 형식:\n1. {제목}\n요약: {한국어 1~2문장}\n영향도: {높음|보통|낮음}\n판정 이유: {1문장}\n출처: {매체명}\n링크: {원문 URL}\n\n정렬 규칙:\n1. 영향도 높은 순서\n2. 영향도가 같으면 게시 시각이 최신인 순서\n\n하단 통계:\n- 전체 기사 수\n- 영향도별 기사 수\n- 검색 결과가 없었던 키워드\n\n제약:\n- 요약에서 원문에 없는 수치나 주장을 만들지 않는다.\n- 날짜를 확인할 수 없으면 날짜를 추정하지 않고 '확인 불가'로 표시한다.\n- 링크가 없는 항목은 최종 브리핑에서 제외한다.\n```\n\n프로그램 간에 결과를 전달해야 한다면 사람이 읽는 예시와 함께 JSON 스키마 또는 타입 정의를 요구하는 것이 좋다.\n\n```json\n{\n  \"title\": \"string\",\n  \"summary\": \"string\",\n  \"impact\": \"high | medium | low\",\n  \"reason\": \"string\",\n  \"source\": \"string\",\n  \"url\": \"absolute URL\",\n  \"published_at\": \"ISO 8601 string | null\"\n}\n```\n\n출력 계약에는 형식뿐 아니라 의미도 포함된다. `impact: high`가 무엇을 뜻하는지 판정 기준이 없다면 JSON 문법은 정확해도 분류 결과는 일관되지 않을 수 있다.\n\n## 원칙 3. 예외 상황과 복구 정책을 명시한다\n\n운영 코드의 완성도는 정상 경로보다 실패 경로에서 드러난다. 프롬프트에는 예상 가능한 실패, 재시도 가능 여부, 사용자에게 알릴 조건, 기록하면 안 되는 정보를 함께 적어야 한다.\n\n| 예외 상황 | 권장 정책 예시 |\n|---|---|\n| 검색 결과 없음 | 해당 키워드를 건너뛰고 최종 통계에 기록 |\n| 일시적인 네트워크 오류 | 일정 간격으로 제한된 횟수만 재시도 |\n| 인증 실패 | 재시도하지 말고 즉시 중단한 뒤 설정 확인 안내 |\n| API 사용량 제한 | 응답의 대기 지침을 존중하고 무한 재시도 금지 |\n| 중복 기사 | 정규화한 URL과 제목 유사도 기준으로 제거 |\n| 형식이 잘못된 데이터 | 원본을 보존하고 해당 항목만 격리 |\n| 메일 발송 실패 | 재시도 후에도 실패하면 대체 알림 또는 실패 상태 기록 |\n| 부분 성공 | 성공한 결과와 실패한 항목을 구분해 보고 |\n\n다음처럼 정책을 구체적으로 요청할 수 있다.\n\n```text\n네트워크 시간 초과는 재시도 가능한 오류로 처리해 줘.\n재시도 사이에는 대기 시간을 두고, 최대 횟수를 넘으면 해당 출처만 실패 처리해 줘.\n인증 오류와 잘못된 요청은 반복해도 해결되지 않으므로 즉시 중단해 줘.\n\n모든 오류 로그에는 시각, 작업 단계, 출처, 오류 유형을 남기되\nAPI 키, 이메일 주소 전체, 인증 헤더, 기사 본문 전문은 기록하지 마.\n프로세스 종료 상태로 전체 성공, 부분 성공, 전체 실패를 구분해 줘.\n```\n\n`세 번 재시도`나 `5초 대기` 같은 값은 보편적인 정답이 아니다. 외부 서비스의 공식 제한, 작업의 긴급성, 중복 실행 위험에 따라 프로젝트에서 결정해야 한다. 결제나 메시지 발송처럼 부작용이 있는 작업은 멱등성 보장 없이 자동 재시도하면 중복 처리될 수 있다.\n\n## 원칙 4. 계획·최소 구현·검증 순서로 점진 개발한다\n\n여러 외부 서비스와 자동 실행을 한 번에 연결하면 오류 원인을 분리하기 어렵다. 구현을 작은 검증 단위로 나누면 각 단계의 입력과 출력을 확인할 수 있다.\n\n### 권장 진행 순서\n\n1. 저장소 구조, 관련 파일, 실행 명령을 조사한다.\n2. 코드 변경 전에 계획과 영향을 받을 파일을 제시하게 한다.\n3. 하나의 키워드와 고정된 샘플 데이터로 수집 기능을 구현한다.\n4. 중복 제거와 영향도 분류를 각각 테스트한다.\n5. 이메일은 실제 발송 대신 로컬 미리보기로 검증한다.\n6. 테스트가 통과한 뒤 실제 공급자 연동과 예약 실행을 추가한다.\n\n첫 요청은 다음과 같이 제한할 수 있다.\n\n```text\n지금은 1단계만 수행해 줘.\n저장소를 조사하고 다음 내용을 보고해 줘.\n- 현재 애플리케이션의 진입점\n- 관련 모듈과 테스트 파일\n- 사용하는 패키지 관리 및 테스트 명령\n- 변경이 필요할 것으로 예상되는 파일\n- 구현 전에 결정해야 할 질문\n\n아직 파일은 수정하지 마.\n```\n\n계획을 검토한 다음에는 변경 범위를 좁혀 구현한다.\n\n```text\n승인한 계획 중 뉴스 수집과 중복 제거만 구현해 줘.\n분류, 이메일 발송, 예약 실행은 추가하지 마.\n고정된 테스트 데이터로 실행할 수 있게 하고,\n수정한 파일과 실행한 테스트 결과를 마지막에 요약해 줘.\n```\n\nClaude Code 환경에서 계획 전용 모드를 사용할 수 있다면 탐색과 설계 단계에서 활용할 수 있다. 다만 계획이 그럴듯하다는 사실은 구현이 정확하다는 뜻이 아니므로 실제 테스트와 코드 검토가 뒤따라야 한다.\n\n## 원칙 5. 피드백을 실패 사례와 수치로 전달한다\n\n`결과가 별로다`, `성능이 느리다`, `분류가 틀렸다`는 수정 방향을 결정하기 어렵다. 현재 상태, 기대 상태, 재현 입력, 허용 가능한 변화 범위를 전달해야 한다.\n\n### 길이 수정 요청\n\n```text\n현재 이메일 본문은 약 3,000자로 생성된다.\n모바일에서 빠르게 읽을 수 있도록 500자 이내로 줄이고 싶다.\n각 기사 요약을 1~2문장으로 제한하고 판정 이유는 유지해 줘.\n원문 URL은 제목에 연결하고 별도 링크 줄은 제거해 줘.\n하단 통계는 유지해 줘.\n```\n\n### 분류 기준 수정 요청\n\n```text\n테스트 데이터 10건 중 8건이 '높음'으로 분류됐다.\n장기적인 기술 전망이나 일반 제품 소개는 '낮음'으로 분류해 줘.\n3개월 안에 가격, 제품 로드맵, 규제 대응 또는 제휴 결정을 바꿔야 하는\n구체적인 근거가 있을 때만 '높음'으로 분류해 줘.\n\n첨부한 사례에서 A와 B는 높음, C는 낮음이 정답이다.\n분류 규칙을 수정하고 이 사례들을 회귀 테스트로 추가해 줘.\n```\n\n### 성능 수정 요청\n\n```text\n동일한 샘플 입력의 평균 실행 시간이 현재 약 45초다.\n목표는 같은 환경에서 30초 이내다.\n먼저 단계별 시간을 측정해 병목을 보여 줘.\n결과의 정확도와 오류 처리를 제거하지 말고,\n개선 대안의 효과와 위험을 비교한 뒤 가장 작은 변경부터 적용해 줘.\n```\n\n성능 수치는 측정 환경과 입력 데이터가 같을 때만 비교할 수 있다. 한 번의 실행 결과만으로 개선됐다고 판단하지 말고 측정 방법, 표본, 캐시 상태를 함께 고정해야 한다.\n\n## 원칙 6. 작업 유형별 프롬프트 템플릿을 사용한다\n\n### 새 에이전트 생성 템플릿\n\n```text\n[역할과 상황]\n나는 {직업/역할}이며 {문제 상황}을 해결하려고 한다.\n이 결과는 {사용자 또는 후속 시스템}이 사용한다.\n\n[목표]\n{달성해야 할 결과와 성공 기준}\n\n[실행 트리거]\n{수동 실행, 이벤트, 예약 시각 등}\n\n[입력]\n- 데이터 출처: {파일/API/데이터베이스}\n- 필수 필드: {필드 목록}\n- 인증 방식: {환경 변수 또는 비밀 관리 방식}\n\n[처리 로직]\n1. {단계 1}\n2. {단계 2}\n3. {단계 3}\n\n[출력 계약]\n{파일 형식, 스키마, 템플릿, 정렬과 누락 규칙}\n\n[예외 처리]\n{빈 결과, 시간 초과, 인증 오류, 부분 실패 정책}\n\n[제약과 비목표]\n- 유지해야 할 기술: {항목}\n- 금지 사항: {항목}\n- 이번 작업에서 제외할 기능: {항목}\n\n[검증]\n- 통과해야 할 테스트: {항목}\n- 완료 보고에 포함할 내용: 변경 파일, 실행 명령, 테스트 결과, 남은 위험\n\n먼저 저장소를 조사하고 구현 계획을 제시해 줘.\n모르는 정보는 추측하지 말고 질문해 줘.\n```\n\n### 기존 기능 추가 템플릿\n\n```text\n기존 {에이전트 또는 모듈 이름}에 {새 기능}을 추가해 줘.\n새 기능은 {기존 단계 A} 다음, {기존 단계 B} 전에 실행돼야 한다.\n\n세부 로직:\n- {조건과 처리 규칙}\n- {입출력 형식}\n- {실패 시 동작}\n\n유지 조건:\n- 기존 공개 인터페이스와 설정 형식을 바꾸지 않는다.\n- 기존 테스트를 모두 유지한다.\n- 관련 없는 파일은 수정하지 않는다.\n\n먼저 영향 범위와 회귀 위험을 설명하고,\n기존 동작을 보존하는 테스트를 추가한 뒤 구현해 줘.\n```\n\n### 오류 수정 템플릿\n\n```text\n다음 오류를 재현하고 근본 원인을 수정해 줘.\n\n오류 메시지 전체:\n{비밀 정보와 개인정보를 제거한 오류 메시지 및 스택 추적}\n\n발생 조건:\n- 실행 명령: {명령}\n- 입력: {최소 재현 입력}\n- 환경: {운영체제, 런타임, 관련 버전}\n- 발생 시점: {어떤 단계인지}\n\n기대 동작:\n{정상이라면 나타나야 할 결과}\n\n실제 동작:\n{현재 관찰되는 결과}\n\n요청:\n1. 먼저 오류를 재현한다.\n2. 증거를 바탕으로 원인을 설명한다.\n3. 가장 작은 범위로 수정한다.\n4. 같은 오류를 막는 회귀 테스트를 추가한다.\n5. 실행한 테스트와 남은 위험을 보고한다.\n```\n\n오류 메시지를 붙여 넣을 때는 API 키, 세션 토큰, 고객 데이터, 내부 주소와 같은 민감 정보를 제거해야 한다.\n\n## 완성 예시: 뉴스 브리핑 에이전트 요청\n\n다음 예시는 여섯 원칙을 하나의 요청에 결합한 형태다.\n\n```text\n나는 SaaS 스타트업의 사업 개발 담당자다.\nAI, 클라우드, 핀테크 시장 변화 중 3개월 안에 제품이나 제휴 결정을\n바꿀 수 있는 뉴스만 매일 확인하고 싶다.\n\n현재 저장소를 조사해 뉴스 브리핑 도구를 설계해 줘.\n첫 단계에서는 샘플 JSON을 읽어 중복을 제거하고 영향도를 분류한 뒤\nHTML 미리보기 파일을 만드는 기능까지만 구현한다.\n웹 검색, 실제 메일 발송, 예약 실행은 이번 단계에서 제외한다.\n\n입력 필드:\n- title, url, source, published_at, body\n\n처리 규칙:\n- 정규화한 URL이 같으면 중복으로 본다.\n- URL이 다르더라도 제목이 유사한 경우 중복 후보로 표시한다.\n- 3개월 안에 가격, 규제 대응, 제품 로드맵 또는 제휴 판단에\n  구체적인 변화가 필요한 기사만 영향도 '높음'으로 분류한다.\n- 근거가 부족하면 높은 등급을 추측하지 않는다.\n\n출력:\n- 제목, 1~2문장 요약, 영향도, 판정 이유, 출처, URL을 표시한다.\n- 영향도 높은 순서로 정렬한다.\n- 전체 건수, 중복 제거 건수, 등급별 건수를 하단에 표시한다.\n\n예외 처리:\n- 필수 필드가 없는 항목은 제외하지 말고 별도 오류 목록에 기록한다.\n- 잘못된 날짜는 추정하지 않고 null로 유지한다.\n- 로그에 기사 본문 전체나 인증 정보를 남기지 않는다.\n\n검증:\n- 정상 입력, 빈 입력, 중복 URL, 잘못된 날짜, 필수 필드 누락을 테스트한다.\n- 기존 테스트가 있다면 모두 통과해야 한다.\n\n작업 순서:\n1. 저장소 구조와 관련 파일을 조사한다.\n2. 수정할 파일과 테스트 계획을 제시한다.\n3. 내가 계획을 확인하기 전에는 코드를 변경하지 않는다.\n4. 승인 후 최소 기능을 구현하고 테스트 결과를 보고한다.\n```\n\n이 요청은 필요한 기능을 모두 한 번에 운영 환경에 배포하라고 요구하지 않는다. 범위가 제한되어 있고, 출력 의미와 실패 처리, 테스트 항목이 함께 정의되어 있어 결과를 판정하기 쉽다.\n\n## 프롬프트만으로 놓치기 쉬운 완성도 기준\n\n많은 바이브 코딩 안내는 더 자세한 지시를 작성하는 데 집중한다. 하지만 실제 완성도를 좌우하는 추가 요소는 **검증 가능성, 변경 통제, 관찰 가능성, 보안 경계**다.\n\n### 1. 인수 조건을 테스트로 바꾼다\n\n`잘 작동하게 해 줘` 대신 입력과 기대 출력을 짝으로 제공한다. 중요한 분류 사례는 회귀 테스트로 남겨 다음 변경에서도 결과가 유지되는지 확인한다.\n\n### 2. 에이전트의 자기평가를 최종 증거로 사용하지 않는다\n\n에이전트가 `완료했다`고 말하는 것과 테스트가 통과한 것은 다르다. 실행한 명령, 테스트 결과, 변경 파일, 미해결 위험을 보고하게 하고 사람이 diff를 검토해야 한다.\n\n### 3. 권한과 비밀 정보를 최소화한다\n\n필요하지 않은 디렉터리, 운영 데이터베이스, 배포 자격 증명까지 한꺼번에 제공하지 않는다. API 키는 프롬프트나 저장소에 직접 넣지 말고 환경 변수나 승인된 비밀 관리 시스템을 사용한다. 출처를 알 수 없는 MCP 서버나 스크립트에는 민감한 저장소 접근 권한을 주지 않는다.\n\n### 4. 관찰 가능한 코드를 요구한다\n\n자동화 작업에는 단계별 상태, 구조화된 오류, 실행 시간, 처리 건수처럼 장애 원인을 찾는 데 필요한 정보를 남긴다. 반면 인증 정보와 개인정보는 로그에서 제거한다.\n\n### 5. 변경을 되돌릴 수 있게 만든다\n\n관련 없는 리팩터링과 기능 추가를 한 변경에 섞지 않는다. 작은 단위로 diff를 검토하고 버전 관리에 기록하면 잘못된 변경을 분리해 되돌리기 쉽다.\n\n## Claude Code 프로젝트 운영 팁\n\n- 반복되는 프로젝트 규칙은 `CLAUDE.md`에 짧고 구체적으로 기록한다.\n- 빌드, 테스트, 린트 명령은 실제로 실행 가능한 형태로 제공한다.\n- 비밀 정보, 일회성 오류 로그, 긴 참고 문서를 `CLAUDE.md`에 넣지 않는다.\n- 대규모 변경 전에는 관련 파일과 의존 관계를 먼저 조사하게 한다.\n- 새 패키지를 추가할 때는 필요성, 라이선스, 유지보수 위험을 검토한다.\n- 위험한 삭제, 배포, 데이터 변경 명령은 자동 승인하지 않는다.\n- 외부 API나 MCP를 연결하기 전 데이터가 어디로 전송되는지 확인한다.\n- 완료 시 변경 파일, 실행 명령, 테스트 결과와 남은 제한을 요약하게 한다.\n\n## 제출 전 체크리스트\n\n- [ ] 사용자와 사용 상황이 설명되어 있는가\n- [ ] 목표와 비목표가 분리되어 있는가\n- [ ] 기존 기술과 변경 금지 범위가 명시되어 있는가\n- [ ] 입력 데이터와 출력 형식이 정의되어 있는가\n- [ ] 분류 값과 상태 값의 의미가 설명되어 있는가\n- [ ] 빈 결과, 인증 실패, 시간 초과, 부분 실패 정책이 있는가\n- [ ] 계획과 구현이 단계별로 분리되어 있는가\n- [ ] 정상·경계·실패 사례의 테스트가 있는가\n- [ ] 비밀 정보와 개인정보가 프롬프트 및 로그에서 제외되는가\n- [ ] 사람이 검토할 diff와 실행 증거를 요청했는가\n\n좋은 Claude Code 프롬프트의 핵심은 명령을 길게 쓰는 것이 아니다. 에이전트가 추측해야 하는 부분을 줄이고, 결과가 맞는지 제3자도 재현해 판정할 수 있도록 만드는 것이다.","content_html":"\u003cp\u003eClaude Code와 같은 코딩 에이전트는 코드 한 조각만 생성하는 도구가 아니라 저장소를 탐색하고, 여러 파일을 수정하며, 테스트와 명령을 실행할 수 있는 작업 환경이다. 따라서 결과물의 품질은 문장이 얼마나 그럴듯한가보다 \u003cstrong\u003e작업 범위와 검증 방법을 얼마나 명확히 정의했는가\u003c/strong\u003e에 크게 좌우된다.\u003c/p\u003e\n\u003cp\u003e좋은 프롬프트는 긴 설명문이 아니라 실행 가능한 작업 명세다. 무엇을 만들지뿐 아니라 왜 필요한지, 어떤 조건을 지켜야 하는지, 실패를 어떻게 처리할지, 무엇을 통과하면 완료인지까지 전달해야 한다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%EB%A8%BC%EC%A0%80-%EA%B5%AC%EB%B6%84%ED%95%A0-%EA%B2%83-%ED%94%84%EB%A1%AC%ED%94%84%ED%8A%B8%EC%99%80-%EC%8B%A4%ED%96%89-%ED%99%98%EA%B2%BD\" class=\"anchor\" id=\"먼저-구분할-것-프롬프트와-실행-환경\"\u003e\u003c/a\u003e먼저 구분할 것: 프롬프트와 실행 환경\u003c/h2\u003e\n\u003cp\u003e바이브 코딩은 자연어로 의도를 전달하고 AI 에이전트가 구현을 맡는 협업 방식이다. 그러나 자연어로 요청했다는 사실이 코드의 정확성이나 운영 안정성을 보장하지는 않는다.\u003c/p\u003e\n\u003cp\u003eClaude Code 작업에는 다음 요소가 함께 작용한다.\u003c/p\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003e요소\u003c/th\u003e\n\u003cth\u003e역할\u003c/th\u003e\n\u003cth\u003e프롬프트에서 확인할 내용\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"요소\"\u003e사용자 요청\u003c/td\u003e\n\u003ctd data-label=\"역할\"\u003e목표와 변경 범위를 전달\u003c/td\u003e\n\u003ctd data-label=\"프롬프트에서 확인할 내용\"\u003e목적, 우선순위, 금지 사항\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"요소\"\u003e저장소 문맥\u003c/td\u003e\n\u003ctd data-label=\"역할\"\u003e기존 구조와 규칙을 제공\u003c/td\u003e\n\u003ctd data-label=\"프롬프트에서 확인할 내용\"\u003e프레임워크, 실행 명령, 관련 파일\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"요소\"\u003e\u003ccode\u003eCLAUDE.md\u003c/code\u003e\u003c/td\u003e\n\u003ctd data-label=\"역할\"\u003e반복해서 적용할 프로젝트 지침을 제공\u003c/td\u003e\n\u003ctd data-label=\"프롬프트에서 확인할 내용\"\u003e코딩 규칙, 테스트 방법, 디렉터리 관례\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"요소\"\u003e도구 권한\u003c/td\u003e\n\u003ctd data-label=\"역할\"\u003e파일 수정과 명령 실행의 허용 범위를 통제\u003c/td\u003e\n\u003ctd data-label=\"프롬프트에서 확인할 내용\"\u003e실행해도 되는 명령과 사전 확인이 필요한 작업\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"요소\"\u003e외부 연결\u003c/td\u003e\n\u003ctd data-label=\"역할\"\u003eAPI, 데이터베이스, MCP 서버 등에 접근\u003c/td\u003e\n\u003ctd data-label=\"프롬프트에서 확인할 내용\"\u003e인증 방식, 신뢰 경계, 실패 정책\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"요소\"\u003e검증 절차\u003c/td\u003e\n\u003ctd data-label=\"역할\"\u003e결과가 요구사항을 충족하는지 판정\u003c/td\u003e\n\u003ctd data-label=\"프롬프트에서 확인할 내용\"\u003e테스트, 정적 분석, 수동 확인 항목\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003e프롬프트만 잘 작성해도 모든 문제가 해결되는 것은 아니다. 예를 들어 Claude Code가 예약 실행 코드를 만들 수는 있지만, 컴퓨터가 꺼져 있을 때도 작업을 실행하려면 별도의 서버, CI 서비스 또는 운영체제 스케줄러가 필요하다. 이메일 전송 역시 실제 공급자의 인증 정보와 발송 권한이 없으면 완성할 수 없다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%EC%9B%90%EC%B9%99-1-%EB%B0%B0%EA%B2%BD%EB%AA%A9%EC%A0%81%EC%A0%9C%EC%95%BD%EC%9D%84-%EB%A8%BC%EC%A0%80-%EC%84%A4%EB%AA%85%ED%95%9C%EB%8B%A4\" class=\"anchor\" id=\"원칙-1-배경목적제약을-먼저-설명한다\"\u003e\u003c/a\u003e원칙 1. 배경·목적·제약을 먼저 설명한다\u003c/h2\u003e\n\u003cp\u003e\u003ccode\u003e뉴스 수집 에이전트 만들어 줘\u003c/code\u003e처럼 결과물 이름만 제시하면 에이전트는 사용자, 데이터 출처, 실행 환경과 성공 기준을 추측해야 한다. 같은 뉴스 수집기라도 사업 개발 담당자, 투자자, 대학 신문 편집자가 필요로 하는 출처와 분류 기준은 다르다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EB%B6%88%EC%B6%A9%EB%B6%84%ED%95%9C-%EC%9A%94%EC%B2%AD\" class=\"anchor\" id=\"불충분한-요청\"\u003e\u003c/a\u003e불충분한 요청\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003eAI 뉴스 수집 에이전트를 만들어 줘.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EA%B0%9C%EC%84%A0%ED%95%9C-%EC%9A%94%EC%B2%AD\" class=\"anchor\" id=\"개선한-요청\"\u003e\u003c/a\u003e개선한 요청\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e나는 IT 스타트업의 사업 개발 담당자다.\n\u003c/span\u003e\u003cspan\u003e매일 업무 시작 전에 AI, 클라우드, 핀테크 분야에서\n\u003c/span\u003e\u003cspan\u003e사업 제휴나 제품 전략에 영향을 줄 뉴스를 빠르게 확인하려고 한다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e목표:\n\u003c/span\u003e\u003cspan\u003e- 지정한 키워드별로 최신 기사 후보를 수집한다.\n\u003c/span\u003e\u003cspan\u003e- URL이 같은 기사와 제목이 유사한 중복 기사를 제거한다.\n\u003c/span\u003e\u003cspan\u003e- 3개월 안에 제품 또는 제휴 의사결정이 필요한지를 기준으로\n\u003c/span\u003e\u003cspan\u003e  영향도를 높음, 보통, 낮음으로 분류한다.\n\u003c/span\u003e\u003cspan\u003e- 결과를 한국어 이메일 브리핑으로 만든다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e제약:\n\u003c/span\u003e\u003cspan\u003e- 현재 저장소의 Python 버전과 패키지 관리 방식을 유지한다.\n\u003c/span\u003e\u003cspan\u003e- 새 라이브러리를 추가하기 전 필요성과 대안을 설명한다.\n\u003c/span\u003e\u003cspan\u003e- API 키와 이메일 비밀번호를 코드나 로그에 기록하지 않는다.\n\u003c/span\u003e\u003cspan\u003e- 실제 메일 발송 전에는 미리보기 파일만 생성한다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e먼저 저장소 구조와 실행 방법을 조사한 뒤 구현 계획을 제안해 줘.\n\u003c/span\u003e\u003cspan\u003e모르는 환경 정보는 추측하지 말고 질문 목록으로 정리해 줘.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e좋은 배경 정보에는 다음 네 가지가 들어간다.\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003e\n\u003cstrong\u003e사용자와 이용 상황:\u003c/strong\u003e 누가, 언제, 어떤 의사결정에 사용하는가\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003e목표:\u003c/strong\u003e 코드 작성 자체가 아니라 해결해야 할 문제는 무엇인가\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003e제약:\u003c/strong\u003e 유지해야 할 기술, 보안 규칙, 비용 또는 시간 한도는 무엇인가\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003e비목표:\u003c/strong\u003e 이번 변경에서 명시적으로 제외할 기능은 무엇인가\u003c/li\u003e\n\u003c/ol\u003e\n\u003cp\u003e비목표를 적으면 범위가 무한히 커지는 것을 막을 수 있다. 예를 들어 \u003ccode\u003e이번 단계에서는 예약 실행과 실제 이메일 발송은 제외한다\u003c/code\u003e고 정하면 수집과 분류 로직부터 안정적으로 검증할 수 있다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%EC%9B%90%EC%B9%99-2-%EC%9B%90%ED%95%98%EB%8A%94-%EC%B6%9C%EB%A0%A5-%ED%98%95%EC%8B%9D%EC%9D%84-%EC%B6%9C%EB%A0%A5-%EA%B3%84%EC%95%BD%EC%9C%BC%EB%A1%9C-%EB%A7%8C%EB%93%A0%EB%8B%A4\" class=\"anchor\" id=\"원칙-2-원하는-출력-형식을-출력-계약으로-만든다\"\u003e\u003c/a\u003e원칙 2. 원하는 출력 형식을 출력 계약으로 만든다\u003c/h2\u003e\n\u003cp\u003e\u003ccode\u003e메일로 보기 좋게 보내 줘\u003c/code\u003e는 사람마다 다르게 해석된다. 출력 형식은 예시만 보여 주기보다 필수 필드, 허용 값, 누락 처리, 정렬 순서를 함께 정의해야 한다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e이메일 제목:\n\u003c/span\u003e\u003cspan\u003e[뉴스 브리핑] {YYYY-MM-DD} 오늘의 핵심 뉴스\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e본문의 기사 형식:\n\u003c/span\u003e\u003cspan\u003e1. {제목}\n\u003c/span\u003e\u003cspan\u003e요약: {한국어 1~2문장}\n\u003c/span\u003e\u003cspan\u003e영향도: {높음|보통|낮음}\n\u003c/span\u003e\u003cspan\u003e판정 이유: {1문장}\n\u003c/span\u003e\u003cspan\u003e출처: {매체명}\n\u003c/span\u003e\u003cspan\u003e링크: {원문 URL}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e정렬 규칙:\n\u003c/span\u003e\u003cspan\u003e1. 영향도 높은 순서\n\u003c/span\u003e\u003cspan\u003e2. 영향도가 같으면 게시 시각이 최신인 순서\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e하단 통계:\n\u003c/span\u003e\u003cspan\u003e- 전체 기사 수\n\u003c/span\u003e\u003cspan\u003e- 영향도별 기사 수\n\u003c/span\u003e\u003cspan\u003e- 검색 결과가 없었던 키워드\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e제약:\n\u003c/span\u003e\u003cspan\u003e- 요약에서 원문에 없는 수치나 주장을 만들지 않는다.\n\u003c/span\u003e\u003cspan\u003e- 날짜를 확인할 수 없으면 날짜를 추정하지 않고 '확인 불가'로 표시한다.\n\u003c/span\u003e\u003cspan\u003e- 링크가 없는 항목은 최종 브리핑에서 제외한다.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e프로그램 간에 결과를 전달해야 한다면 사람이 읽는 예시와 함께 JSON 스키마 또는 타입 정의를 요구하는 것이 좋다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e{\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003etitle\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003esummary\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003eimpact\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003ehigh | medium | low\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003ereason\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003esource\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003eurl\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003eabsolute URL\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003epublished_at\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003eISO 8601 string | null\u003c/span\u003e\u003cspan\u003e\"\n\u003c/span\u003e\u003cspan\u003e}\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e출력 계약에는 형식뿐 아니라 의미도 포함된다. \u003ccode\u003eimpact: high\u003c/code\u003e가 무엇을 뜻하는지 판정 기준이 없다면 JSON 문법은 정확해도 분류 결과는 일관되지 않을 수 있다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%EC%9B%90%EC%B9%99-3-%EC%98%88%EC%99%B8-%EC%83%81%ED%99%A9%EA%B3%BC-%EB%B3%B5%EA%B5%AC-%EC%A0%95%EC%B1%85%EC%9D%84-%EB%AA%85%EC%8B%9C%ED%95%9C%EB%8B%A4\" class=\"anchor\" id=\"원칙-3-예외-상황과-복구-정책을-명시한다\"\u003e\u003c/a\u003e원칙 3. 예외 상황과 복구 정책을 명시한다\u003c/h2\u003e\n\u003cp\u003e운영 코드의 완성도는 정상 경로보다 실패 경로에서 드러난다. 프롬프트에는 예상 가능한 실패, 재시도 가능 여부, 사용자에게 알릴 조건, 기록하면 안 되는 정보를 함께 적어야 한다.\u003c/p\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003e예외 상황\u003c/th\u003e\n\u003cth\u003e권장 정책 예시\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"예외 상황\"\u003e검색 결과 없음\u003c/td\u003e\n\u003ctd data-label=\"권장 정책 예시\"\u003e해당 키워드를 건너뛰고 최종 통계에 기록\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"예외 상황\"\u003e일시적인 네트워크 오류\u003c/td\u003e\n\u003ctd data-label=\"권장 정책 예시\"\u003e일정 간격으로 제한된 횟수만 재시도\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"예외 상황\"\u003e인증 실패\u003c/td\u003e\n\u003ctd data-label=\"권장 정책 예시\"\u003e재시도하지 말고 즉시 중단한 뒤 설정 확인 안내\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"예외 상황\"\u003eAPI 사용량 제한\u003c/td\u003e\n\u003ctd data-label=\"권장 정책 예시\"\u003e응답의 대기 지침을 존중하고 무한 재시도 금지\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"예외 상황\"\u003e중복 기사\u003c/td\u003e\n\u003ctd data-label=\"권장 정책 예시\"\u003e정규화한 URL과 제목 유사도 기준으로 제거\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"예외 상황\"\u003e형식이 잘못된 데이터\u003c/td\u003e\n\u003ctd data-label=\"권장 정책 예시\"\u003e원본을 보존하고 해당 항목만 격리\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"예외 상황\"\u003e메일 발송 실패\u003c/td\u003e\n\u003ctd data-label=\"권장 정책 예시\"\u003e재시도 후에도 실패하면 대체 알림 또는 실패 상태 기록\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"예외 상황\"\u003e부분 성공\u003c/td\u003e\n\u003ctd data-label=\"권장 정책 예시\"\u003e성공한 결과와 실패한 항목을 구분해 보고\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003e다음처럼 정책을 구체적으로 요청할 수 있다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e네트워크 시간 초과는 재시도 가능한 오류로 처리해 줘.\n\u003c/span\u003e\u003cspan\u003e재시도 사이에는 대기 시간을 두고, 최대 횟수를 넘으면 해당 출처만 실패 처리해 줘.\n\u003c/span\u003e\u003cspan\u003e인증 오류와 잘못된 요청은 반복해도 해결되지 않으므로 즉시 중단해 줘.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e모든 오류 로그에는 시각, 작업 단계, 출처, 오류 유형을 남기되\n\u003c/span\u003e\u003cspan\u003eAPI 키, 이메일 주소 전체, 인증 헤더, 기사 본문 전문은 기록하지 마.\n\u003c/span\u003e\u003cspan\u003e프로세스 종료 상태로 전체 성공, 부분 성공, 전체 실패를 구분해 줘.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e\u003ccode\u003e세 번 재시도\u003c/code\u003e나 \u003ccode\u003e5초 대기\u003c/code\u003e 같은 값은 보편적인 정답이 아니다. 외부 서비스의 공식 제한, 작업의 긴급성, 중복 실행 위험에 따라 프로젝트에서 결정해야 한다. 결제나 메시지 발송처럼 부작용이 있는 작업은 멱등성 보장 없이 자동 재시도하면 중복 처리될 수 있다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%EC%9B%90%EC%B9%99-4-%EA%B3%84%ED%9A%8D%EC%B5%9C%EC%86%8C-%EA%B5%AC%ED%98%84%EA%B2%80%EC%A6%9D-%EC%88%9C%EC%84%9C%EB%A1%9C-%EC%A0%90%EC%A7%84-%EA%B0%9C%EB%B0%9C%ED%95%9C%EB%8B%A4\" class=\"anchor\" id=\"원칙-4-계획최소-구현검증-순서로-점진-개발한다\"\u003e\u003c/a\u003e원칙 4. 계획·최소 구현·검증 순서로 점진 개발한다\u003c/h2\u003e\n\u003cp\u003e여러 외부 서비스와 자동 실행을 한 번에 연결하면 오류 원인을 분리하기 어렵다. 구현을 작은 검증 단위로 나누면 각 단계의 입력과 출력을 확인할 수 있다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EA%B6%8C%EC%9E%A5-%EC%A7%84%ED%96%89-%EC%88%9C%EC%84%9C\" class=\"anchor\" id=\"권장-진행-순서\"\u003e\u003c/a\u003e권장 진행 순서\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003e저장소 구조, 관련 파일, 실행 명령을 조사한다.\u003c/li\u003e\n\u003cli\u003e코드 변경 전에 계획과 영향을 받을 파일을 제시하게 한다.\u003c/li\u003e\n\u003cli\u003e하나의 키워드와 고정된 샘플 데이터로 수집 기능을 구현한다.\u003c/li\u003e\n\u003cli\u003e중복 제거와 영향도 분류를 각각 테스트한다.\u003c/li\u003e\n\u003cli\u003e이메일은 실제 발송 대신 로컬 미리보기로 검증한다.\u003c/li\u003e\n\u003cli\u003e테스트가 통과한 뒤 실제 공급자 연동과 예약 실행을 추가한다.\u003c/li\u003e\n\u003c/ol\u003e\n\u003cp\u003e첫 요청은 다음과 같이 제한할 수 있다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e지금은 1단계만 수행해 줘.\n\u003c/span\u003e\u003cspan\u003e저장소를 조사하고 다음 내용을 보고해 줘.\n\u003c/span\u003e\u003cspan\u003e- 현재 애플리케이션의 진입점\n\u003c/span\u003e\u003cspan\u003e- 관련 모듈과 테스트 파일\n\u003c/span\u003e\u003cspan\u003e- 사용하는 패키지 관리 및 테스트 명령\n\u003c/span\u003e\u003cspan\u003e- 변경이 필요할 것으로 예상되는 파일\n\u003c/span\u003e\u003cspan\u003e- 구현 전에 결정해야 할 질문\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e아직 파일은 수정하지 마.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e계획을 검토한 다음에는 변경 범위를 좁혀 구현한다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e승인한 계획 중 뉴스 수집과 중복 제거만 구현해 줘.\n\u003c/span\u003e\u003cspan\u003e분류, 이메일 발송, 예약 실행은 추가하지 마.\n\u003c/span\u003e\u003cspan\u003e고정된 테스트 데이터로 실행할 수 있게 하고,\n\u003c/span\u003e\u003cspan\u003e수정한 파일과 실행한 테스트 결과를 마지막에 요약해 줘.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003eClaude Code 환경에서 계획 전용 모드를 사용할 수 있다면 탐색과 설계 단계에서 활용할 수 있다. 다만 계획이 그럴듯하다는 사실은 구현이 정확하다는 뜻이 아니므로 실제 테스트와 코드 검토가 뒤따라야 한다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%EC%9B%90%EC%B9%99-5-%ED%94%BC%EB%93%9C%EB%B0%B1%EC%9D%84-%EC%8B%A4%ED%8C%A8-%EC%82%AC%EB%A1%80%EC%99%80-%EC%88%98%EC%B9%98%EB%A1%9C-%EC%A0%84%EB%8B%AC%ED%95%9C%EB%8B%A4\" class=\"anchor\" id=\"원칙-5-피드백을-실패-사례와-수치로-전달한다\"\u003e\u003c/a\u003e원칙 5. 피드백을 실패 사례와 수치로 전달한다\u003c/h2\u003e\n\u003cp\u003e\u003ccode\u003e결과가 별로다\u003c/code\u003e, \u003ccode\u003e성능이 느리다\u003c/code\u003e, \u003ccode\u003e분류가 틀렸다\u003c/code\u003e는 수정 방향을 결정하기 어렵다. 현재 상태, 기대 상태, 재현 입력, 허용 가능한 변화 범위를 전달해야 한다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EA%B8%B8%EC%9D%B4-%EC%88%98%EC%A0%95-%EC%9A%94%EC%B2%AD\" class=\"anchor\" id=\"길이-수정-요청\"\u003e\u003c/a\u003e길이 수정 요청\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e현재 이메일 본문은 약 3,000자로 생성된다.\n\u003c/span\u003e\u003cspan\u003e모바일에서 빠르게 읽을 수 있도록 500자 이내로 줄이고 싶다.\n\u003c/span\u003e\u003cspan\u003e각 기사 요약을 1~2문장으로 제한하고 판정 이유는 유지해 줘.\n\u003c/span\u003e\u003cspan\u003e원문 URL은 제목에 연결하고 별도 링크 줄은 제거해 줘.\n\u003c/span\u003e\u003cspan\u003e하단 통계는 유지해 줘.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EB%B6%84%EB%A5%98-%EA%B8%B0%EC%A4%80-%EC%88%98%EC%A0%95-%EC%9A%94%EC%B2%AD\" class=\"anchor\" id=\"분류-기준-수정-요청\"\u003e\u003c/a\u003e분류 기준 수정 요청\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e테스트 데이터 10건 중 8건이 '높음'으로 분류됐다.\n\u003c/span\u003e\u003cspan\u003e장기적인 기술 전망이나 일반 제품 소개는 '낮음'으로 분류해 줘.\n\u003c/span\u003e\u003cspan\u003e3개월 안에 가격, 제품 로드맵, 규제 대응 또는 제휴 결정을 바꿔야 하는\n\u003c/span\u003e\u003cspan\u003e구체적인 근거가 있을 때만 '높음'으로 분류해 줘.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e첨부한 사례에서 A와 B는 높음, C는 낮음이 정답이다.\n\u003c/span\u003e\u003cspan\u003e분류 규칙을 수정하고 이 사례들을 회귀 테스트로 추가해 줘.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EC%84%B1%EB%8A%A5-%EC%88%98%EC%A0%95-%EC%9A%94%EC%B2%AD\" class=\"anchor\" id=\"성능-수정-요청\"\u003e\u003c/a\u003e성능 수정 요청\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e동일한 샘플 입력의 평균 실행 시간이 현재 약 45초다.\n\u003c/span\u003e\u003cspan\u003e목표는 같은 환경에서 30초 이내다.\n\u003c/span\u003e\u003cspan\u003e먼저 단계별 시간을 측정해 병목을 보여 줘.\n\u003c/span\u003e\u003cspan\u003e결과의 정확도와 오류 처리를 제거하지 말고,\n\u003c/span\u003e\u003cspan\u003e개선 대안의 효과와 위험을 비교한 뒤 가장 작은 변경부터 적용해 줘.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e성능 수치는 측정 환경과 입력 데이터가 같을 때만 비교할 수 있다. 한 번의 실행 결과만으로 개선됐다고 판단하지 말고 측정 방법, 표본, 캐시 상태를 함께 고정해야 한다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%EC%9B%90%EC%B9%99-6-%EC%9E%91%EC%97%85-%EC%9C%A0%ED%98%95%EB%B3%84-%ED%94%84%EB%A1%AC%ED%94%84%ED%8A%B8-%ED%85%9C%ED%94%8C%EB%A6%BF%EC%9D%84-%EC%82%AC%EC%9A%A9%ED%95%9C%EB%8B%A4\" class=\"anchor\" id=\"원칙-6-작업-유형별-프롬프트-템플릿을-사용한다\"\u003e\u003c/a\u003e원칙 6. 작업 유형별 프롬프트 템플릿을 사용한다\u003c/h2\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EC%83%88-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8-%EC%83%9D%EC%84%B1-%ED%85%9C%ED%94%8C%EB%A6%BF\" class=\"anchor\" id=\"새-에이전트-생성-템플릿\"\u003e\u003c/a\u003e새 에이전트 생성 템플릿\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e[역할과 상황]\n\u003c/span\u003e\u003cspan\u003e나는 {직업/역할}이며 {문제 상황}을 해결하려고 한다.\n\u003c/span\u003e\u003cspan\u003e이 결과는 {사용자 또는 후속 시스템}이 사용한다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[목표]\n\u003c/span\u003e\u003cspan\u003e{달성해야 할 결과와 성공 기준}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[실행 트리거]\n\u003c/span\u003e\u003cspan\u003e{수동 실행, 이벤트, 예약 시각 등}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[입력]\n\u003c/span\u003e\u003cspan\u003e- 데이터 출처: {파일/API/데이터베이스}\n\u003c/span\u003e\u003cspan\u003e- 필수 필드: {필드 목록}\n\u003c/span\u003e\u003cspan\u003e- 인증 방식: {환경 변수 또는 비밀 관리 방식}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[처리 로직]\n\u003c/span\u003e\u003cspan\u003e1. {단계 1}\n\u003c/span\u003e\u003cspan\u003e2. {단계 2}\n\u003c/span\u003e\u003cspan\u003e3. {단계 3}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[출력 계약]\n\u003c/span\u003e\u003cspan\u003e{파일 형식, 스키마, 템플릿, 정렬과 누락 규칙}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[예외 처리]\n\u003c/span\u003e\u003cspan\u003e{빈 결과, 시간 초과, 인증 오류, 부분 실패 정책}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[제약과 비목표]\n\u003c/span\u003e\u003cspan\u003e- 유지해야 할 기술: {항목}\n\u003c/span\u003e\u003cspan\u003e- 금지 사항: {항목}\n\u003c/span\u003e\u003cspan\u003e- 이번 작업에서 제외할 기능: {항목}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[검증]\n\u003c/span\u003e\u003cspan\u003e- 통과해야 할 테스트: {항목}\n\u003c/span\u003e\u003cspan\u003e- 완료 보고에 포함할 내용: 변경 파일, 실행 명령, 테스트 결과, 남은 위험\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e먼저 저장소를 조사하고 구현 계획을 제시해 줘.\n\u003c/span\u003e\u003cspan\u003e모르는 정보는 추측하지 말고 질문해 줘.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EA%B8%B0%EC%A1%B4-%EA%B8%B0%EB%8A%A5-%EC%B6%94%EA%B0%80-%ED%85%9C%ED%94%8C%EB%A6%BF\" class=\"anchor\" id=\"기존-기능-추가-템플릿\"\u003e\u003c/a\u003e기존 기능 추가 템플릿\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e기존 {에이전트 또는 모듈 이름}에 {새 기능}을 추가해 줘.\n\u003c/span\u003e\u003cspan\u003e새 기능은 {기존 단계 A} 다음, {기존 단계 B} 전에 실행돼야 한다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e세부 로직:\n\u003c/span\u003e\u003cspan\u003e- {조건과 처리 규칙}\n\u003c/span\u003e\u003cspan\u003e- {입출력 형식}\n\u003c/span\u003e\u003cspan\u003e- {실패 시 동작}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e유지 조건:\n\u003c/span\u003e\u003cspan\u003e- 기존 공개 인터페이스와 설정 형식을 바꾸지 않는다.\n\u003c/span\u003e\u003cspan\u003e- 기존 테스트를 모두 유지한다.\n\u003c/span\u003e\u003cspan\u003e- 관련 없는 파일은 수정하지 않는다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e먼저 영향 범위와 회귀 위험을 설명하고,\n\u003c/span\u003e\u003cspan\u003e기존 동작을 보존하는 테스트를 추가한 뒤 구현해 줘.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EC%98%A4%EB%A5%98-%EC%88%98%EC%A0%95-%ED%85%9C%ED%94%8C%EB%A6%BF\" class=\"anchor\" id=\"오류-수정-템플릿\"\u003e\u003c/a\u003e오류 수정 템플릿\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e다음 오류를 재현하고 근본 원인을 수정해 줘.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e오류 메시지 전체:\n\u003c/span\u003e\u003cspan\u003e{비밀 정보와 개인정보를 제거한 오류 메시지 및 스택 추적}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e발생 조건:\n\u003c/span\u003e\u003cspan\u003e- 실행 명령: {명령}\n\u003c/span\u003e\u003cspan\u003e- 입력: {최소 재현 입력}\n\u003c/span\u003e\u003cspan\u003e- 환경: {운영체제, 런타임, 관련 버전}\n\u003c/span\u003e\u003cspan\u003e- 발생 시점: {어떤 단계인지}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e기대 동작:\n\u003c/span\u003e\u003cspan\u003e{정상이라면 나타나야 할 결과}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e실제 동작:\n\u003c/span\u003e\u003cspan\u003e{현재 관찰되는 결과}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e요청:\n\u003c/span\u003e\u003cspan\u003e1. 먼저 오류를 재현한다.\n\u003c/span\u003e\u003cspan\u003e2. 증거를 바탕으로 원인을 설명한다.\n\u003c/span\u003e\u003cspan\u003e3. 가장 작은 범위로 수정한다.\n\u003c/span\u003e\u003cspan\u003e4. 같은 오류를 막는 회귀 테스트를 추가한다.\n\u003c/span\u003e\u003cspan\u003e5. 실행한 테스트와 남은 위험을 보고한다.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e오류 메시지를 붙여 넣을 때는 API 키, 세션 토큰, 고객 데이터, 내부 주소와 같은 민감 정보를 제거해야 한다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%EC%99%84%EC%84%B1-%EC%98%88%EC%8B%9C-%EB%89%B4%EC%8A%A4-%EB%B8%8C%EB%A6%AC%ED%95%91-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8-%EC%9A%94%EC%B2%AD\" class=\"anchor\" id=\"완성-예시-뉴스-브리핑-에이전트-요청\"\u003e\u003c/a\u003e완성 예시: 뉴스 브리핑 에이전트 요청\u003c/h2\u003e\n\u003cp\u003e다음 예시는 여섯 원칙을 하나의 요청에 결합한 형태다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e나는 SaaS 스타트업의 사업 개발 담당자다.\n\u003c/span\u003e\u003cspan\u003eAI, 클라우드, 핀테크 시장 변화 중 3개월 안에 제품이나 제휴 결정을\n\u003c/span\u003e\u003cspan\u003e바꿀 수 있는 뉴스만 매일 확인하고 싶다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e현재 저장소를 조사해 뉴스 브리핑 도구를 설계해 줘.\n\u003c/span\u003e\u003cspan\u003e첫 단계에서는 샘플 JSON을 읽어 중복을 제거하고 영향도를 분류한 뒤\n\u003c/span\u003e\u003cspan\u003eHTML 미리보기 파일을 만드는 기능까지만 구현한다.\n\u003c/span\u003e\u003cspan\u003e웹 검색, 실제 메일 발송, 예약 실행은 이번 단계에서 제외한다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e입력 필드:\n\u003c/span\u003e\u003cspan\u003e- title, url, source, published_at, body\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e처리 규칙:\n\u003c/span\u003e\u003cspan\u003e- 정규화한 URL이 같으면 중복으로 본다.\n\u003c/span\u003e\u003cspan\u003e- URL이 다르더라도 제목이 유사한 경우 중복 후보로 표시한다.\n\u003c/span\u003e\u003cspan\u003e- 3개월 안에 가격, 규제 대응, 제품 로드맵 또는 제휴 판단에\n\u003c/span\u003e\u003cspan\u003e  구체적인 변화가 필요한 기사만 영향도 '높음'으로 분류한다.\n\u003c/span\u003e\u003cspan\u003e- 근거가 부족하면 높은 등급을 추측하지 않는다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e출력:\n\u003c/span\u003e\u003cspan\u003e- 제목, 1~2문장 요약, 영향도, 판정 이유, 출처, URL을 표시한다.\n\u003c/span\u003e\u003cspan\u003e- 영향도 높은 순서로 정렬한다.\n\u003c/span\u003e\u003cspan\u003e- 전체 건수, 중복 제거 건수, 등급별 건수를 하단에 표시한다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e예외 처리:\n\u003c/span\u003e\u003cspan\u003e- 필수 필드가 없는 항목은 제외하지 말고 별도 오류 목록에 기록한다.\n\u003c/span\u003e\u003cspan\u003e- 잘못된 날짜는 추정하지 않고 null로 유지한다.\n\u003c/span\u003e\u003cspan\u003e- 로그에 기사 본문 전체나 인증 정보를 남기지 않는다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e검증:\n\u003c/span\u003e\u003cspan\u003e- 정상 입력, 빈 입력, 중복 URL, 잘못된 날짜, 필수 필드 누락을 테스트한다.\n\u003c/span\u003e\u003cspan\u003e- 기존 테스트가 있다면 모두 통과해야 한다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e작업 순서:\n\u003c/span\u003e\u003cspan\u003e1. 저장소 구조와 관련 파일을 조사한다.\n\u003c/span\u003e\u003cspan\u003e2. 수정할 파일과 테스트 계획을 제시한다.\n\u003c/span\u003e\u003cspan\u003e3. 내가 계획을 확인하기 전에는 코드를 변경하지 않는다.\n\u003c/span\u003e\u003cspan\u003e4. 승인 후 최소 기능을 구현하고 테스트 결과를 보고한다.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e이 요청은 필요한 기능을 모두 한 번에 운영 환경에 배포하라고 요구하지 않는다. 범위가 제한되어 있고, 출력 의미와 실패 처리, 테스트 항목이 함께 정의되어 있어 결과를 판정하기 쉽다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%ED%94%84%EB%A1%AC%ED%94%84%ED%8A%B8%EB%A7%8C%EC%9C%BC%EB%A1%9C-%EB%86%93%EC%B9%98%EA%B8%B0-%EC%89%AC%EC%9A%B4-%EC%99%84%EC%84%B1%EB%8F%84-%EA%B8%B0%EC%A4%80\" class=\"anchor\" id=\"프롬프트만으로-놓치기-쉬운-완성도-기준\"\u003e\u003c/a\u003e프롬프트만으로 놓치기 쉬운 완성도 기준\u003c/h2\u003e\n\u003cp\u003e많은 바이브 코딩 안내는 더 자세한 지시를 작성하는 데 집중한다. 하지만 실제 완성도를 좌우하는 추가 요소는 \u003cstrong\u003e검증 가능성, 변경 통제, 관찰 가능성, 보안 경계\u003c/strong\u003e다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#1-%EC%9D%B8%EC%88%98-%EC%A1%B0%EA%B1%B4%EC%9D%84-%ED%85%8C%EC%8A%A4%ED%8A%B8%EB%A1%9C-%EB%B0%94%EA%BE%BC%EB%8B%A4\" class=\"anchor\" id=\"1-인수-조건을-테스트로-바꾼다\"\u003e\u003c/a\u003e1. 인수 조건을 테스트로 바꾼다\u003c/h3\u003e\n\u003cp\u003e\u003ccode\u003e잘 작동하게 해 줘\u003c/code\u003e 대신 입력과 기대 출력을 짝으로 제공한다. 중요한 분류 사례는 회귀 테스트로 남겨 다음 변경에서도 결과가 유지되는지 확인한다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#2-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8%EC%9D%98-%EC%9E%90%EA%B8%B0%ED%8F%89%EA%B0%80%EB%A5%BC-%EC%B5%9C%EC%A2%85-%EC%A6%9D%EA%B1%B0%EB%A1%9C-%EC%82%AC%EC%9A%A9%ED%95%98%EC%A7%80-%EC%95%8A%EB%8A%94%EB%8B%A4\" class=\"anchor\" id=\"2-에이전트의-자기평가를-최종-증거로-사용하지-않는다\"\u003e\u003c/a\u003e2. 에이전트의 자기평가를 최종 증거로 사용하지 않는다\u003c/h3\u003e\n\u003cp\u003e에이전트가 \u003ccode\u003e완료했다\u003c/code\u003e고 말하는 것과 테스트가 통과한 것은 다르다. 실행한 명령, 테스트 결과, 변경 파일, 미해결 위험을 보고하게 하고 사람이 diff를 검토해야 한다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#3-%EA%B6%8C%ED%95%9C%EA%B3%BC-%EB%B9%84%EB%B0%80-%EC%A0%95%EB%B3%B4%EB%A5%BC-%EC%B5%9C%EC%86%8C%ED%99%94%ED%95%9C%EB%8B%A4\" class=\"anchor\" id=\"3-권한과-비밀-정보를-최소화한다\"\u003e\u003c/a\u003e3. 권한과 비밀 정보를 최소화한다\u003c/h3\u003e\n\u003cp\u003e필요하지 않은 디렉터리, 운영 데이터베이스, 배포 자격 증명까지 한꺼번에 제공하지 않는다. API 키는 프롬프트나 저장소에 직접 넣지 말고 환경 변수나 승인된 비밀 관리 시스템을 사용한다. 출처를 알 수 없는 MCP 서버나 스크립트에는 민감한 저장소 접근 권한을 주지 않는다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#4-%EA%B4%80%EC%B0%B0-%EA%B0%80%EB%8A%A5%ED%95%9C-%EC%BD%94%EB%93%9C%EB%A5%BC-%EC%9A%94%EA%B5%AC%ED%95%9C%EB%8B%A4\" class=\"anchor\" id=\"4-관찰-가능한-코드를-요구한다\"\u003e\u003c/a\u003e4. 관찰 가능한 코드를 요구한다\u003c/h3\u003e\n\u003cp\u003e자동화 작업에는 단계별 상태, 구조화된 오류, 실행 시간, 처리 건수처럼 장애 원인을 찾는 데 필요한 정보를 남긴다. 반면 인증 정보와 개인정보는 로그에서 제거한다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#5-%EB%B3%80%EA%B2%BD%EC%9D%84-%EB%90%98%EB%8F%8C%EB%A6%B4-%EC%88%98-%EC%9E%88%EA%B2%8C-%EB%A7%8C%EB%93%A0%EB%8B%A4\" class=\"anchor\" id=\"5-변경을-되돌릴-수-있게-만든다\"\u003e\u003c/a\u003e5. 변경을 되돌릴 수 있게 만든다\u003c/h3\u003e\n\u003cp\u003e관련 없는 리팩터링과 기능 추가를 한 변경에 섞지 않는다. 작은 단위로 diff를 검토하고 버전 관리에 기록하면 잘못된 변경을 분리해 되돌리기 쉽다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#claude-code-%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8-%EC%9A%B4%EC%98%81-%ED%8C%81\" class=\"anchor\" id=\"claude-code-프로젝트-운영-팁\"\u003e\u003c/a\u003eClaude Code 프로젝트 운영 팁\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e반복되는 프로젝트 규칙은 \u003ccode\u003eCLAUDE.md\u003c/code\u003e에 짧고 구체적으로 기록한다.\u003c/li\u003e\n\u003cli\u003e빌드, 테스트, 린트 명령은 실제로 실행 가능한 형태로 제공한다.\u003c/li\u003e\n\u003cli\u003e비밀 정보, 일회성 오류 로그, 긴 참고 문서를 \u003ccode\u003eCLAUDE.md\u003c/code\u003e에 넣지 않는다.\u003c/li\u003e\n\u003cli\u003e대규모 변경 전에는 관련 파일과 의존 관계를 먼저 조사하게 한다.\u003c/li\u003e\n\u003cli\u003e새 패키지를 추가할 때는 필요성, 라이선스, 유지보수 위험을 검토한다.\u003c/li\u003e\n\u003cli\u003e위험한 삭제, 배포, 데이터 변경 명령은 자동 승인하지 않는다.\u003c/li\u003e\n\u003cli\u003e외부 API나 MCP를 연결하기 전 데이터가 어디로 전송되는지 확인한다.\u003c/li\u003e\n\u003cli\u003e완료 시 변경 파일, 실행 명령, 테스트 결과와 남은 제한을 요약하게 한다.\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003e\n\u003ca href=\"#%EC%A0%9C%EC%B6%9C-%EC%A0%84-%EC%B2%B4%ED%81%AC%EB%A6%AC%EC%8A%A4%ED%8A%B8\" class=\"anchor\" id=\"제출-전-체크리스트\"\u003e\u003c/a\u003e제출 전 체크리스트\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e 사용자와 사용 상황이 설명되어 있는가\u003c/li\u003e\n\u003cli\u003e 목표와 비목표가 분리되어 있는가\u003c/li\u003e\n\u003cli\u003e 기존 기술과 변경 금지 범위가 명시되어 있는가\u003c/li\u003e\n\u003cli\u003e 입력 데이터와 출력 형식이 정의되어 있는가\u003c/li\u003e\n\u003cli\u003e 분류 값과 상태 값의 의미가 설명되어 있는가\u003c/li\u003e\n\u003cli\u003e 빈 결과, 인증 실패, 시간 초과, 부분 실패 정책이 있는가\u003c/li\u003e\n\u003cli\u003e 계획과 구현이 단계별로 분리되어 있는가\u003c/li\u003e\n\u003cli\u003e 정상·경계·실패 사례의 테스트가 있는가\u003c/li\u003e\n\u003cli\u003e 비밀 정보와 개인정보가 프롬프트 및 로그에서 제외되는가\u003c/li\u003e\n\u003cli\u003e 사람이 검토할 diff와 실행 증거를 요청했는가\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003e좋은 Claude Code 프롬프트의 핵심은 명령을 길게 쓰는 것이 아니다. 에이전트가 추측해야 하는 부분을 줄이고, 결과가 맞는지 제3자도 재현해 판정할 수 있도록 만드는 것이다.\u003c/p\u003e\n","tags":["프롬프트 엔지니어링","하네스 엔지니어링","Claude Code","AI 코딩","코딩 에이전트"],"faqs":[{"question":"Claude Code 프롬프트는 길수록 좋은가요?","answer":"길이보다 작업에 필요한 정보가 구조적으로 들어 있는지가 중요합니다. 배경, 목표, 제약, 출력 계약, 예외 처리와 완료 조건은 구체적으로 쓰되 관련 없는 설명과 중복 지시는 제거하는 편이 좋습니다."},{"question":"처음부터 전체 프로그램을 만들어 달라고 하면 안 되나요?","answer":"작은 독립 도구라면 가능하지만 외부 API, 데이터베이스, 이메일, 예약 실행이 함께 있는 작업은 단계적으로 개발하는 편이 안전합니다. 먼저 저장소 조사와 계획을 검토하고 최소 기능, 테스트, 외부 연동 순서로 확장하면 실패 원인을 분리하기 쉽습니다."},{"question":"Plan Mode를 사용하면 테스트를 생략해도 되나요?","answer":"아닙니다. 계획 모드는 변경 전에 구조와 접근법을 검토하는 데 유용하지만 실제 코드의 정확성을 증명하지 않습니다. 구현 후 자동 테스트, 정적 분석, 변경 내역 검토와 필요한 수동 확인을 별도로 수행해야 합니다."},{"question":"CLAUDE.md에는 무엇을 적어야 하나요?","answer":"프로젝트 구조, 코딩 규칙, 빌드·테스트 명령, 수정하면 안 되는 영역처럼 여러 작업에서 반복되는 지침을 적는 것이 적합합니다. API 키, 비밀번호, 개인정보, 일회성 작업 설명과 지나치게 긴 참고 자료는 넣지 않는 것이 좋습니다."},{"question":"오류 수정 요청에는 어떤 정보를 제공해야 하나요?","answer":"민감 정보를 제거한 오류 메시지와 스택 추적, 실행 명령, 최소 재현 입력, 관련 환경, 실제 동작과 기대 동작을 함께 제공해야 합니다. 원인 설명, 최소 범위의 수정, 회귀 테스트와 실행 결과도 요청하는 것이 좋습니다."},{"question":"Claude Code에 API 키를 프롬프트로 전달해도 되나요?","answer":"프롬프트나 소스 코드에 실제 API 키를 직접 기록하지 않는 것이 원칙입니다. 승인된 환경 변수나 비밀 관리 시스템을 사용하고, 로그와 테스트 결과에도 인증 정보가 노출되지 않도록 해야 합니다."},{"question":"프롬프트에 재시도 횟수와 대기 시간을 반드시 적어야 하나요?","answer":"운영 자동화라면 재시도 가능한 오류와 즉시 중단할 오류를 구분하는 것이 중요합니다. 다만 구체적인 횟수와 대기 시간은 외부 서비스의 제한, 작업 긴급성, 중복 처리 위험을 확인해 결정해야 하며 모든 오류를 무조건 재시도해서는 안 됩니다."},{"question":"생성된 코드가 완성됐는지는 어떻게 판단하나요?","answer":"사전에 정한 인수 조건을 기준으로 판단합니다. 필수 기능과 예외 사례의 테스트 통과 여부, 실행한 명령, 변경된 파일, 성능이나 보안 제약 충족 여부를 확인하고 사람이 코드 변경 내역을 검토해야 합니다."}],"sources":[{"url":"https://docs.anthropic.com/en/docs/claude-code/overview","title":"Claude Code overview","type":"source"},{"url":"https://www.anthropic.com/engineering/claude-code-best-practices","title":"Claude Code: Best practices for agentic coding","type":"source"},{"url":"https://github.com/anthropics/claude-code","title":"Anthropic Claude Code GitHub repository","type":"source"}],"images":[{"id":845,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MTExNTQsInB1ciI6ImJsb2JfaWQifX0=--9f2d2e2c8a61fc294a6019e4807ece297f36e85a/ai-4caeb237.webp","is_representative":true,"generation_method":"ai_photo","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"코드와 작업 흐름이 표시된 대형 모니터 앞에서 작업하는 개발자","caption":"개발자가 여러 화면의 코드와 문서를 검토하며 작업하고 있다.","description":null},"en":{"alt":"Developer working at a desk with code and a workflow diagram on a large monitor","caption":"A developer reviews code and documentation across multiple screens.","description":null},"ja":{"alt":"コードとワークフロー図を映した大型モニターの前で作業する開発者","caption":"開発者が複数の画面でコードとドキュメントを確認している。","description":null},"es":{"alt":"Desarrollador trabajando frente a un monitor grande con código y un diagrama de flujo","caption":"Un desarrollador revisa código y documentación en varias pantallas.","description":null},"id":{"alt":"Pengembang bekerja di depan monitor besar yang menampilkan kode dan diagram alur kerja","caption":"Seorang pengembang meninjau kode dan dokumentasi di beberapa layar.","description":null},"pt":{"alt":"Desenvolvedor trabalhando diante de um monitor grande com código e diagrama de fluxo","caption":"Um desenvolvedor analisa código e documentação em várias telas.","description":null},"zh-hant":{"alt":"開發人員在顯示程式碼與工作流程圖的大型螢幕前工作","caption":"開發人員正透過多個螢幕檢視程式碼與文件。","description":null},"de":{"alt":"Entwickler vor einem großen Monitor mit Code und einem Ablaufdiagramm","caption":"Ein Entwickler prüft Code und Dokumentation auf mehreren Bildschirmen.","description":null}}},{"id":846,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MTExNjAsInB1ciI6ImJsb2JfaWQifX0=--285d7ecdc8209e07e0fc4eb68085cd8a304b9a81/ai-062b34c5.webp","is_representative":false,"generation_method":"ai_image","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"코드 편집기가 열린 노트북과 요구사항, 표, 오류, 버전 관리, 성과 차트를 연결한 개발 워크플로","caption":"체계적인 프롬프트가 코딩 결과물의 검증과 완성도를 높이는 과정을 보여준다.","description":null},"en":{"alt":"Laptop code editor connected to requirements, tables, errors, version control, and performance charts","caption":"The workflow shows how structured prompts support validation and more polished coding results.","description":null},"ja":{"alt":"要件、表、エラー、バージョン管理、成果グラフにつながるコードエディター搭載ノートPC","caption":"構造化されたプロンプトがコードの検証と完成度向上を支える流れを示している。","description":null},"es":{"alt":"Portátil con editor de código conectado a requisitos, tablas, errores, versiones y gráficos de rendimiento","caption":"El flujo muestra cómo los prompts estructurados ayudan a validar y perfeccionar el código.","description":null},"id":{"alt":"Laptop dengan editor kode yang terhubung ke spesifikasi, tabel, galat, kontrol versi, dan grafik kinerja","caption":"Alur ini menunjukkan bagaimana prompt terstruktur membantu validasi dan penyempurnaan hasil kode.","description":null},"pt":{"alt":"Notebook com editor de código ligado a requisitos, tabelas, erros, controle de versão e gráficos de desempenho","caption":"O fluxo mostra como prompts estruturados ajudam a validar e aprimorar os resultados do código.","description":null},"zh-hant":{"alt":"筆電程式碼編輯器連結需求、表格、錯誤、版本控制與成效圖表","caption":"此流程呈現結構化提示如何協助驗證程式碼並提升成果完成度。","description":null},"de":{"alt":"Laptop mit Code-Editor, verbunden mit Anforderungen, Tabellen, Fehlern, Versionskontrolle und Leistungsdiagrammen","caption":"Der Ablauf zeigt, wie strukturierte Prompts die Prüfung und Verfeinerung von Code unterstützen.","description":null}}},{"id":847,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MTExNjYsInB1ciI6ImJsb2JfaWQifX0=--603c0f726413446c519a8ca44a5b00809769819d/ai-bd8a1ca8.webp","is_representative":false,"generation_method":"ai_infographic","license":"ai_generated","mime_type":"image/webp","visible_locales":["ko"],"translations":{"ko":{"alt":"Claude Code 프롬프트 6원칙을 아이콘과 단계별 항목으로 정리한 인포그래픽","caption":"배경·목적·제약부터 반복 가능한 작업 명세까지 여섯 가지 프롬프트 원칙을 설명한다.","description":null},"en":{"alt":"Infographic outlining six Claude Code prompting principles with icons and step-by-step items","caption":"It presents six principles for turning prompts into actionable, testable work specifications.","description":null},"ja":{"alt":"Claude Codeのプロンプト6原則をアイコンと手順別の項目でまとめたインフォグラフィック","caption":"背景や制約の提示から検証可能な作業仕様まで、6つの原則を説明している。","description":null},"es":{"alt":"Infografía con seis principios para prompts de Claude Code, ilustrados con iconos y pasos","caption":"Resume seis principios para convertir prompts en especificaciones de trabajo ejecutables y verificables.","description":null},"id":{"alt":"Infografik enam prinsip prompt Claude Code dengan ikon dan rincian langkah demi langkah","caption":"Enam prinsip ini membantu mengubah prompt menjadi spesifikasi kerja yang dapat dijalankan dan diuji.","description":null},"pt":{"alt":"Infográfico com seis princípios de prompts para Claude Code, organizados em etapas com ícones","caption":"A imagem resume seis princípios para criar especificações de trabalho executáveis e testáveis.","description":null},"zh-hant":{"alt":"以圖示和分步項目整理 Claude Code 提示詞六大原則的資訊圖表","caption":"圖表說明如何從背景與限制出發，建立可執行且可驗證的工作規格。","description":null},"de":{"alt":"Infografik mit sechs Prinzipien für Claude-Code-Prompts, dargestellt mit Symbolen und Schritten","caption":"Sie zeigt sechs Prinzipien für ausführbare und überprüfbare Arbeitsanweisungen.","description":null}}}],"published_at":"2026-08-23T02:30:01+09:00","updated_at":"2026-08-23T02:30:01+09:00","license":"cc_by","translation_status":"original","available_locales":["ko","en","ja","es"],"data_locales":["ko","en","ja","es","id","pt","zh-hant","de"],"url":"https://injoys.com/ko/articles/claude-code-prompt-six-principles-and-templates"}