Claude Code 페어 프로그래밍 실전 가이드: AI에 맡기되 통제권은 지키는 방법

Claude Code 페어 프로그래밍은 AI에게 모든 코드를 맡기는 방식이 아닙니다. 안정적으로 쓰는 사람들은 목표, 제약, 검증 기준을 사람이 잡고, Claude Code에는 코드베이스 탐색, 작은 수정, 테스트 실행, 리뷰 준비를 맡깁니다.

공식 Claude Code overview는 Claude Code를 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하며, 개발 도구와 통합되는 agentic coding tool로 설명합니다. 일반 챗봇보다 강력하지만, 지시가 모호하면 잘못된 방향으로도 빠르게 진행됩니다.

이 글은 Claude Code 시작 가이드 다음에 볼 실전 편입니다. 작은 버그 수정, 테스트 추가, PR 준비에서 바로 쓸 수 있는 프롬프트와 절차, 그리고 자주 발생하는 함정을 함께 정리했습니다.

먼저 역할을 나눈다

Claude Code를 실행하기 전에 누가 어떤 결정을 하는지 정해야 합니다. Claude는 파일을 빠르게 읽고 코드를 바꿀 수 있지만, 제품 의도, 보안 경계, 머지 가능 여부는 사람이 판단해야 합니다.

영역	사람이 맡을 일	Claude Code가 맡을 일
목표	무엇을 바꾸고 무엇을 바꾸지 않을지 결정	관련 파일과 구현 경로 찾기
조사	읽을 범위 지정	소스, 테스트, diff, 로그 읽기
구현	변경 크기와 위험 승인	작고 명확한 수정 생성
검증	통과 기준 정의	테스트, lint, build 실행
리뷰	머지 여부 판단	위험, 누락된 테스트, 대안 정리

이렇게 나누면 Claude Code는 감독 없는 대체자가 아니라 실행력이 좋은 동료가 됩니다. 초보자에게도 좋습니다. 처음부터 큰 기능을 맡기기보다 버그 하나, 테스트 하나, 컴포넌트 하나로 시작하는 편이 훨씬 배우기 쉽습니다.

처음 10분에 환경을 정리한다

좋은 준비는 좋은 프롬프트보다 더 큰 차이를 만듭니다. Claude Code best practices는 검증 가능한 신호를 제공하고, 탐색, 계획, 구현, 검증을 나누라고 강조합니다. 실무에서는 세 가지를 먼저 확인합니다.

첫째, main에서 직접 작업하지 않고 브랜치나 worktree를 씁니다. 둘째, 짧은 CLAUDE.md를 둡니다. 공식 memory documentation에 따르면 CLAUDE.md는 세션 시작 시 읽히는 지속 지시문입니다. 셋째, 프로젝트에서 검증에 쓰는 명령을 알려 줍니다.

# CLAUDE.md

## Project rules
- Before editing, summarize the files you plan to inspect.
- Prefer small diffs and explain risky changes before applying them.
- After code edits, run `npm run lint` and the narrowest relevant test.
- Do not read `.env*` files or change deployment settings without approval.

## Common commands
- `npm run lint`
- `npm run test`
- `npm run build`

CLAUDE.md는 길수록 좋은 파일이 아닙니다. 반복 절차가 길어진다면 현재 Claude Code 문서의 Skills로 분리하는 편이 낫습니다. 필요한 순간에만 불러오므로 매 세션의 컨텍스트를 낭비하지 않습니다.

기본 루프는 탐색, 계획, 구현, 검증

가장 흔한 실패는 처음부터 “구현해 줘”라고 하는 것입니다. 더 안전한 루프는 다음과 같습니다.

flowchart LR
  A[목표를 설명] --> B[관련 파일 탐색]
  B --> C[계획 확인]
  C --> D[작게 수정]
  D --> E[검사 실행과 diff 확인]
  E --> F{통과?}
  F -- 아니오 --> C
  F -- 예 --> G[PR 요약 작성]

첫 프롬프트는 길 필요가 없지만 목표, 범위, 금지 사항, 검증 방법은 들어가야 합니다.

목표: 로그인 후 프로필 페이지에서 500 오류가 나는 문제를 수정하고 싶습니다.
범위: 먼저 `src/auth`와 `src/pages/profile`을 확인하세요.
금지: 인증 전략 변경, DB 스키마 변경, `.env` 파일 읽기는 하지 마세요.
진행: 관련 파일을 읽고 가능한 원인 3개를 제시한 뒤, 수정 전에 계획을 보여 주세요.
검증: 기존 인증 테스트와 `npm run lint`를 실행하세요.

계획이 너무 크면 바로 줄입니다.

방향은 좋지만 먼저 재현 테스트만 작성하세요.
그 테스트가 실패하는지 확인한 다음 production code를 수정하세요.
production code 변경은 파일 하나씩 제안하세요.

이 방식은 TDD, 즉 테스트 주도 개발과 잘 맞습니다. 실패하는 테스트를 먼저 만들면 Claude Code가 문제를 실제로 재현했는지 확인할 수 있고, 리뷰도 쉬워집니다.

바로 실행해 볼 수 있는 작은 예제

연습은 실제 서비스 코드보다 작은 함수로 시작하는 편이 안전합니다. 아래 코드는 변경 위험에 따라 Claude Code에게 맡길 모드를 결정합니다. pair-check.test.ts로 저장하고 Vitest로 실행할 수 있습니다.

import { describe, expect, it } from "vitest";

type ClaudeMode = "direct" | "plan-first" | "human-review";

export function decideClaudeMode(input: {
  changedFiles: number;
  touchesSecrets: boolean;
  hasReliableTests: boolean;
}): ClaudeMode {
  if (input.touchesSecrets) return "human-review";
  if (input.changedFiles > 3) return "plan-first";
  if (!input.hasReliableTests) return "plan-first";
  return "direct";
}

describe("decideClaudeMode", () => {
  it("allows direct work for small, well-tested changes", () => {
    expect(
      decideClaudeMode({
        changedFiles: 1,
        touchesSecrets: false,
        hasReliableTests: true,
      }),
    ).toBe("direct");
  });

  it("requires a plan for broad changes", () => {
    expect(
      decideClaudeMode({
        changedFiles: 5,
        touchesSecrets: false,
        hasReliableTests: true,
      }),
    ).toBe("plan-first");
  });

  it("requires human review for secret-related work", () => {
    expect(
      decideClaudeMode({
        changedFiles: 1,
        touchesSecrets: true,
        hasReliableTests: true,
      }),
    ).toBe("human-review");
  });
});

npm install -D vitest typescript
npx vitest run pair-check.test.ts

다음에는 Claude Code에게 “billing을 건드리면 human-review가 필요하다”는 규칙을 추가하라고 해 보세요. 먼저 테스트를 추가하고, 실패를 확인하고, 구현하고, 다시 테스트하게 하면 됩니다. 작은 예제지만 실제 API 핸들러나 React 컴포넌트에서도 같은 감각이 필요합니다.

실무에서 잘 맞는 4가지 사용 사례

첫째는 기존 기능에 작은 조건을 추가하는 작업입니다. 예를 들어 “무료 플랜에서는 CSV 내보내기를 숨긴다”는 변경은 UI, 권한, 테스트를 함께 확인해야 하지만 전체 구조를 바꿀 필요는 없습니다.

둘째는 버그 조사입니다. 오류 메시지, 재현 단계, 기대 결과를 함께 전달합니다. 공식 Common workflows는 재현 명령과 stack trace를 제공해 원인 추적을 돕는 방식을 소개합니다.

셋째는 테스트 추가입니다. Claude가 기존 테스트 스타일을 먼저 읽게 한 뒤 성공, 권한 없음, 잘못된 입력, 빈 데이터 같은 케이스를 추가하게 합니다. 더 체계적으로 하고 싶다면 testing strategies guide와 함께 보면 좋습니다.

넷째는 PR 전 셀프 리뷰입니다. git diff를 읽게 하고 보안, 하위 호환성, 테스트 부족, 이름 짓기 문제를 우선순위로 지적하게 합니다. GitHub의 pull request review documentation는 리뷰가 댓글, 승인, 변경 요청으로 품질을 지키는 과정임을 설명합니다. Claude Code는 사람 리뷰를 대체하기보다 리뷰 전에 거친 부분을 줄이는 도구로 쓰는 편이 현실적입니다.

자주 빠지는 함정과 피하는 법

함정	벌어지는 일	더 안전한 습관
“좋게 고쳐 줘”	요청하지 않은 리팩터링이 섞임	범위, 비목표, 통과 기준을 적기
큰 diff	리뷰가 어려워지고 버그가 숨음	한 작업, 한 diff, 한 계획
검증 없음	겉으로만 끝난 것처럼 보임	테스트, lint, build, 스크린샷 요구
너무 긴 CLAUDE.md	중요한 규칙이 묻힘	절차는 Skills로 분리
넓은 권한	비밀 정보나 production 작업에 닿음	권한과 hooks 사용

숨은 위험은 승인 피로입니다. 모든 작업이 승인을 요구하면 사람은 기계적으로 허용하게 됩니다. 반대로 거의 모든 작업을 허용하면 나쁜 프롬프트가 너무 멀리 갑니다. 실용적인 기준은 되돌릴 수 있는 일에는 높은 신뢰, 되돌리기 어려운 일에는 높은 마찰입니다. 자세한 설정은 approval and sandbox guide를 참고하세요.

세션을 PR로 남긴다

팀에서 쓸 때는 대화 내용을 PR로 남겨야 합니다. 마지막에 다음 프롬프트를 사용하면 리뷰가 쉬워집니다.

이 diff를 pull request 설명으로 정리해 주세요.
포함할 내용:
- 변경 이유
- 주요 변경 파일
- 실행한 검증 명령과 결과
- 리뷰어가 집중해서 봐야 할 위험
- 이번에 의도적으로 바꾸지 않은 범위

Claude Code가 초안을 만들 수는 있지만 최종 문장은 사람이 다듬어야 합니다. 보안, 결제, 개인정보, 데이터 삭제와 관련된 변경에서는 특히 조심해야 합니다. Claude의 확신은 증거가 아닙니다. 증거는 diff, 테스트 출력, 로그, 리뷰 토론입니다.

실제로 적용해 본 결과

Masa가 작은 Next.js 수정에 이 루프를 적용했을 때, 단순히 “구현해 줘”라고 했을 때보다 리뷰 시간이 짧았습니다. 첫 프롬프트에서 파일 범위, 금지 사항, lint와 테스트 실행을 지정했기 때문입니다. Claude Code는 관련 없는 파일을 덜 건드렸고, 검증 결과도 대화에 남겼습니다. 다만 테스트가 약한 UI 변경은 여전히 사람이 눈으로 확인해야 했습니다. 결론은 분명합니다. Claude Code 페어 프로그래밍은 책임을 넘기는 기술이 아니라, 어떤 책임을 넘길지 설계하는 기술입니다.

다음 세션에서는 오늘 할 작은 작업 하나를 골라 탐색, 계획, 구현, 검증 순서로 진행해 보세요. 팀용 프롬프트와 리뷰 기준을 정리하고 싶다면 ClaudeCodeLab training도 참고할 수 있습니다.