책에 포함된 노트Claude Code 실전 활용법: 설치부터 자동화·MCP·운영까지

일상 개발 워크플로 10선: 버그 수정·리팩터·테스트·문서·리뷰

2026-03-22Views 10약 5분

왜 '표준 루프'가 품질을 고정시키는가

Claude Code를 매일 쓰다 보면, 결과물의 편차는 대부분 "무엇을 시켰는가"가 아니라 "어떤 순서로, 어떤 증거를 모아, 어떤 기준으로 끝냈는가"에서 생깁니다. 그래서 반복 업무를 재현 → 원인 → 수정 → 검증의 표준 루프로 고정하면, 같은 종류의 작업에서 항상 비슷한 수준의 품질이 나옵니다.

특히 버그는 정보가 빠질수록 왕복이 늘어납니다. 구조화된 버그 리포트 템플릿을 쓰는 팀이 해결 속도가 더 빨라진다는 주장도 있고¹, 실무에서 체감되는 차이도 큽니다. 중요한 건 "툴이 무엇이냐"가 아니라, 매번 같은 필드를 채우게 만들어 정보 누락을 막는 것입니다.³⁵

이 장에서는 일상 개발에서 가장 자주 마주치는 10가지 작업을, Claude Code에 바로 붙여 넣어 쓸 수 있는 프롬프트 템플릿으로 루틴화합니다.

공통 준비물: '작업 카드' 1장으로 시작하기

아래 템플릿은 이 장의 모든 워크플로에 공통으로 쓰는 "작업 카드"입니다. 버그/개선/문서/리뷰 등 유형이 달라도, 이 카드만 채우면 Claude Code가 길을 잃지 않습니다.

[작업 카드]
- 목표: (무엇을 끝내면 성공인가?)
- 범위: (어떤 파일/모듈/기능까지만?)
- 금지: (이번 작업에서 하지 말 것: 예. 기능 추가, 대규모 리팩터)
- 재현/증거:
  - 현상: 
  - 재현 절차(있다면):
  - 기대 vs 실제:
  - 환경/버전:
  - 로그/스크린샷/링크:
- 검증(How to verify):
  - 실행할 테스트:
  - 수동 확인 시나리오:
  - 회귀 범위:
- 완료 정의(DoD):
  - (예: 관련 테스트 추가/통과, 문서 업데이트, 린트 통과)

버그 작업이라면 '재현/증거' 영역을 더 엄격하게 채우는 게 핵심입니다. 버그 리포트에 흔히 요구되는 필드(환경, 재현 단계, 기대/실제, 심각도/우선순위, 시각 자료, 로그 등)를 고정하면 커뮤니케이션 비용이 확 줄어듭니다.³⁵

워크플로 1) 버그 수정(재현 가능한 일반 버그)

버그 수정은 "감으로 고치는 일"이 아니라, 재현 가능한 실험을 설계하는 일입니다. 표준 프로세스에서 반복적으로 강조되는 단계는 (1) 상세 리포트 → (2) 재현 및 확인 → (3) 우선순위/영향 판단 → (4) RCA(근본 원인) → (5) 수정 → (6) 테스트/회귀 → (7) 배포 준비입니다.²

프롬프트 템플릿

너는 이 리포지토리의 유지보수 개발자다.
아래 [작업 카드]를 기준으로 버그를 고쳐라.

규칙:
- 먼저 재현부터 한다. 재현이 불가능하면 '추가 정보 요청 목록'을 만든다.
- 수정은 최소 변경으로 한다(원인과 무관한 리팩터/기능 추가 금지).
- 반드시 검증(테스트/수동 시나리오)까지 포함해 완료한다.

[작업 카드]
- 목표: (예: 결제 페이지에서 쿠폰 적용 시 500 오류 제거)
- 범위: (예: src/payments/**)
- 금지: 기능 추가, 리팩터링
- 재현/증거:
  - 현상:
  - 재현 절차:
  - 기대 vs 실제:
  - 환경/버전:
  - 로그:
- 검증(How to verify):
  - 실행할 테스트:
  - 수동 확인:
  - 회귀 범위:

진행 방식:
1) 재현 절차를 따라가며 원인을 좁히기 위한 관찰 포인트(로그/브레이크포인트/추적)를 제안
2) 근본 원인(RCA)을 한 문장으로 요약
3) 최소 수정안 1개 + 대안 1개(트레이드오프 포함)
4) 수정 후 실행할 테스트와 회귀 체크리스트 제시
5) 커밋 메시지 초안 작성

검증 요령

수정 후에는 "버그가 사라졌다"만 확인하지 말고, 재현 절차가 더 이상 성립하지 않음과 연관 플로우가 깨지지 않음(회귀)를 함께 확인합니다. 표준 프로세스에서 회귀 테스트/테스트 케이스 실행 결과를 기록하는 항목이 따로 있는 이유가 여기 있습니다.²

워크플로 2) 재현이 어려운 버그(간헐적/환경 의존)

재현이 어려운 버그는 보통 정보 부족이 문제입니다. 이때는 "고치기"보다 "재현 조건 만들기"가 우선입니다. 좋은 템플릿은 환경, URL, 콘솔 로그, 시각 자료, 재현 단계 같은 단서를 강제합니다.³

프롬프트 템플릿

아래 현상은 재현이 어렵다. 먼저 재현 가능성을 올려라.

입력:
- 현상 설명:
- 발생 빈도/패턴(추정):
- 영향(사용자/비즈니스):
- 환경(브라우저/OS/기기/버전):
- 로그/스크린샷/영상/링크:

요구 사항:
1) '추가로 수집해야 할 정보' 질문 리스트를 우선순위로 정리
2) 로깅/메트릭/트레이싱을 어디에 어떤 키로 심을지 제안
3) 재현을 위한 실험 설계(조건 변수, 가설, 기대 관찰값)
4) 재현이 되면 바로 워크플로 1로 전환할 수 있게 [작업 카드]를 채워서 출력

워크플로 3) 핫픽스(시간 제한이 있는 장애/치명 버그)

핫픽스는 속도가 중요하지만, 무엇을 생략할지가 더 중요합니다. 표준 프로세스에서도 "우선순위/심각도", "배포 준비 여부", "릴리스 노트" 같은 필드를 별도로 둡니다.²

프롬프트 템플릿

상황: 프로덕션 장애/치명 버그로 핫픽스가 필요하다.

원칙:
- '가장 작은 안전한 변경'으로 증상을 멈춘다.
- 근본 원인 해결은 후속 티켓으로 분리한다.
- 배포 후 검증과 롤백 플랜을 문서화한다.

입력:
- 장애 징후(알람/로그/사용자 신고):
- 영향 범위:
- 최근 변경(PR/커밋):
- 즉시 목표(예: 500 비율 0으로):
- 허용 가능한 임시방편(있다면):

출력:
1) 가능한 원인 후보 3개와 확인 순서
2) 임시 완화(mitigation)안 1~2개
3) 핫픽스 PR 체크리스트(테스트 최소 세트, 모니터링 지표, 롤백)
4) 후속 작업 티켓 초안(근본 원인/개선 항목)

워크플로 4) 리팩터링(품질 개선, 기능 변경 없음)

리팩터링은 "버그 수정"과 섞이면 원인 추적이 어려워집니다. 결함 수정과 리팩터링을 분리하라는 권고는 반복적으로 등장합니다.¹¹ 리팩터링의 정의 자체가 "외부 동작을 유지한 채 내부 구조를 개선"하는 것이기 때문에, 테스트가 경계선입니다.¹²

프롬프트 템플릿

너는 리팩터링만 수행한다(기능 변경 금지).

입력:
- 대상 코드/파일:
- 문제(코드 스멜/중복/복잡도/가독성):
- 유지해야 할 동작(핵심 시나리오):
- 기존 테스트 현황:

요구 사항:
1) 리팩터 목표를 2~3개로 좁혀 명시
2) '기능 변경 없이' 가능한 리팩터 단계들을 작은 커밋 단위로 나눠 제안
3) 리팩터 전후에 반드시 통과해야 할 테스트 목록 제시(없으면 먼저 추가)
4) 변경이 커질 경우의 중단 기준(롤백/분리 PR 기준) 제안

실무 팁

리팩터링은 "한 번에 크게"보다 "작게 자주"가 안전합니다. 작은 단계, 테스트 유지, 자동화 도구 활용 같은 원칙이 여러 가이드에서 반복됩니다.¹⁸

워크플로 5) 테스트 추가/보강(버그 재발 방지)

버그를 고친 뒤 테스트가 없으면, 다음번엔 더 빨리 다시 만납니다. 표준 버그 프로세스가 "실행한 테스트 케이스"와 "회귀 이슈"를 기록하게 하는 이유도 같습니다.²

프롬프트 템플릿

목표: 아래 버그/변경사항이 다시 발생하지 않도록 테스트를 추가한다.

입력:
- 관련 이슈/버그 설명:
- 수정된 코드 위치:
- 사용 중인 테스트 프레임워크/러너:
- 테스트 실행 방법:

요구 사항:
1) 최소 재현 테스트 1개(버그가 있으면 실패, 수정 후 통과)
2) 경계값/에러 케이스 2개 이상
3) 테스트가 느려지지 않도록(불필요한 통합 의존 제거) 구조 제안
4) 테스트 이름/설명은 '행동(what) + 조건(when)' 형태로 구체화

워크플로 6) 테스트가 불안정할 때(플레이키 테스트)

플레이키 테스트는 제품 버그보다도 팀의 집중력을 갉아먹습니다. 원칙은 단순합니다. 원인 분류(시간/동시성/외부 의존/환경)를 먼저 하고, 재현 확률을 올리는 장치를 만든 뒤, 고립시키고 안정화합니다.

프롬프트 템플릿

플레이키 테스트를 안정화하자.

입력:
- 테스트 이름/파일:
- 실패 로그(최근 3회):
- CI 환경 정보:
- 최근 변경:

요구 사항:
1) 실패 패턴을 분류(타임아웃/레이스/외부 API/순서 의존/데이터 오염)
2) 재현 확률을 올리는 방법(반복 실행, 시드 고정, 격리 실행)을 제안
3) 근본 해결책(동기화/대기 조건 개선/테스트 데이터 팩토리/목킹) 제안
4) '임시 완화'(skip/retry)는 최후 수단으로만 제시하고, 조건을 명시

워크플로 7) 문서 업데이트(README, API 문서, 변경 로그)

문서는 "나중에"가 아니라, 코드가 바뀌는 순간 같이 바뀌어야 합니다. 특히 릴리스 직전에는 "릴리스 노트"가 표준 프로세스의 산출물로 들어가기도 합니다.²

프롬프트 템플릿

변경사항을 사용자/동료가 이해할 수 있게 문서화하라.

입력:
- 변경된 PR/커밋 요약:
- 영향 받는 사용자/개발자:
- 문서 위치(README, docs/, API spec 등):

출력:
1) 문서에서 수정해야 할 섹션 후보
2) 추가/수정 문구 초안(짧고 단정한 문장)
3) '사용 방법' 예시 1개(요청/응답, CLI 사용, 코드 스니펫 등)
4) 호환성/마이그레이션 주의사항(있다면)

워크플로 8) 성능 문제(느린 API/쿼리/렌더링)

성능 작업도 표준 루프가 필요합니다. "최적화"라고 뭉뚱그리면, 어디를 얼마나 개선했는지 증거가 사라집니다. 먼저 측정 기준(전/후)을 고정해야 합니다.

프롬프트 템플릿

성능 병목을 찾아 개선하자. 반드시 '측정 가능한 전/후'를 남긴다.

입력:
- 느린 구간(엔드포인트/함수/화면):
- 현재 지표(p95, 평균, CPU, 메모리 등):
- 목표 지표:
- 제약(정확성/비용/캐시 정책):
- 프로파일/트레이스/쿼리 플랜(가능하면):

출력:
1) 병목 후보와 근거(로그/프로파일에서 볼 포인트)
2) 개선안 2가지(저위험/고효과 vs 고효과/중위험)
3) 변경 후 검증 계획(벤치/부하/회귀)
4) 롤백 기준(지표 악화/에러 증가)

워크플로 9) 보안/입력 검증 강화(취약점 의심)

보안은 "문제가 생기면"이 아니라 "의심이 생기면" 바로 점검하는 편이 싸게 먹힙니다. 코드 리뷰 프롬프트 라이브러리들도 보안 카테고리를 별도로 분리해 반복 점검을 권합니다.²²

프롬프트 템플릿

다음 변경/코드를 보안 관점에서 점검하고, 최소 수정으로 위험을 낮춰라.

입력:
- 관련 코드/파일:
- 데이터 흐름(입력 → 처리 → 저장/전송):
- 인증/인가 전제:

체크 포인트:
- 입력 검증/정규화/인코딩
- 민감정보 노출(로그 포함)
- 권한 우회 가능성
- 인젝션(XSS/SQL/명령) 가능성

출력:
1) 발견한 위험을 심각도(Critical/High/Medium/Low)로 분류
2) 각 위험의 악용 시나리오(한 문단)
3) 구체적 수정안(코드 스니펫 포함)
4) 보안 회귀 테스트/체크리스트

워크플로 10) PR 리뷰(항상 같은 기준으로 보는 리뷰어 만들기)

리뷰는 실력이 아니라 체력에서 흔들립니다. 그래서 AI를 "두 번째 눈"으로 쓰되, 프롬프트로 기준을 고정해야 합니다. 좋은 리뷰 프롬프트는 범위를 명시(버그/보안/성능/스타일), 맥락을 제공(언어/프레임워크/제약), 그리고 "왜 문제인지 + 고치는 법"을 요구합니다.²⁹

프롬프트 템플릿

너는 시니어 엔지니어로서 PR을 리뷰한다.

컨텍스트:
- 언어/프레임워크:
- 서비스 특성(트래픽, 보안 민감도, 장애 비용):
- 팀 규칙(스타일/아키텍처/에러 처리 원칙):

입력:
- PR 목적:
- 변경 파일 목록:
- diff 또는 핵심 코드:

리뷰 항목:
- 코드 품질(가독성/유지보수성/복잡도)
- 베스트 프랙티스(DRY/SOLID 등)
- 보안(입력 검증, 권한, 민감정보)
- 성능(병목, 불필요한 계산/쿼리)
- 테스트(누락된 케이스, 의미 있는 테스트인지)
- 문서(공개 API/README/릴리스 노트)

출력 형식:
- 이슈마다: (1) 문제 설명 (2) 왜 중요한지 (3) 구체 수정안 (4) 심각도(Critical/High/Medium/Low)
- 마지막에: 승인 여부(Approve / Changes Requested / Discuss)와 이유