Claude Code를 기획부터 운영 배포까지 쓰는 법

기능 목록보다 작업 순서를 먼저 익힌다

안전한 학습 흐름은 설치와 기본 명령에서 시작해 프로젝트 지침, 계획, 외부 도구, 병렬 에이전트, 인증과 데이터베이스, 테스트와 배포로 확장됩니다. 제품 화면과 명령은 달라질 수 있지만, 구현 전에 맥락을 모으고 계획을 검토한 뒤 작은 단계로 완성한다는 뼈대는 여전히 유효합니다.

기능 이름을 훑는 것만으로는 실제 작업 순서를 익히기 어렵습니다. 각 주제는 독자가 자기 저장소에서 범위와 검증 기준을 결정할 수 있도록 독립적인 실행 가이드로 설명합니다.

에이전트에게 맡길 일과 사람이 남겨야 할 일

에이전트는 코드 탐색, 반복 수정, 테스트 실행과 결과 요약을 빠르게 수행합니다. 사람은 해결할 문제, 허용할 변경 범위, 데이터와 권한의 경계, 수용 기준과 배포 판단을 맡아야 합니다. 요구사항이 모호한 상태에서 수정 권한부터 넓히면 속도는 빨라져도 통제력은 낮아집니다.

작업을 시작할 때는 현재 브랜치와 변경 파일, 관련 문서, 실행 가능한 검증 명령을 먼저 확인합니다. 끝날 때는 차이, 테스트 결과, 배포 상태와 남은 위험을 다시 확인합니다. 시작과 끝에 사람이 판단할 지점을 남기는 것이 핵심입니다.

처음부터 전편을 읽을 필요는 없습니다

처음 쓰는 사람은 안전 설정 → 프로젝트 지침 → 계획 모드로 시작하면 됩니다. 혼자 기능을 만드는 개발자는 작업 분할 → 테스트 계층 → 배포 완료 기준을 이어 읽습니다. 팀 리드는 `worktree`와 Agent Teams의 차이를 먼저 보고, 보안·CI 담당자는 샌드박스 → MCP 보안 → 구독과 API 비용 순서로 확인하면 됩니다.

각 편은 따로 읽어도 되지만 역할은 다릅니다. 설치 글은 실행 환경, 샌드박스 글은 파일·네트워크 경계, Agent Teams 글은 팀원 간 조율을 답합니다. 지금 해결하려는 질문과 맞지 않는 글까지 순서대로 소비할 필요는 없습니다.

오래 유지되는 가이드의 조건

모델명, 구독 한도와 단축키처럼 변동이 큰 정보는 날짜를 표시하고 공식 문서를 우선합니다. 반면 최소 권한, 변경 전 상태 확인, 테스트와 롤백처럼 제품 버전에 덜 의존하는 원칙은 실무 기준으로 분리합니다.

서드파티 확장 도구는 편리함보다 유지보수 주체, 설치 권한, 데이터 전송과 제거 가능성을 먼저 확인합니다. 공식 기능으로 충분한 경우에는 도구를 더 설치하지 않는 선택도 좋은 자동화입니다.

한 세션은 이렇게 흘러갑니다

예시 세션은 다국어 도움말 페이지의 깨진 내부 링크를 다룹니다. 저장소 루트에서 Plan Mode로 시작하고, Claude에게 프로젝트 지침과 문서 라우팅 코드, 링크 검사만 읽게 합니다.

claude --permission-mode plan

먼저 CLAUDE.md, package.json, docs/**, scripts/check-links.*를 읽으세요.
파일은 수정하지 마세요.
반환 형식:
1. 현재 링크 생성 흐름
2. 실패를 재현할 명령
3. 최소 변경 파일
4. 예상 부작용
5. 검증과 롤백
외부 API, DB, Git 원격은 사용하지 마세요.

사람이 계획을 줄인 뒤에만 편집을 엽니다

Claude가 문서 시스템 교체까지 제안했다면 사람은 기존 라우터를 유지하고 언어 접두어 처리와 링크 검사만 고치도록 범위를 줄입니다. 그다음 “승인한 라우터와 검사 파일만 수정하세요. 문서 본문 전체 변환과 배포는 하지 마세요”라고 후속 요청합니다. Plan Mode 승인 화면에서는 편집을 자동 수락할지, 매 편집을 검토할지 선택할 수 있습니다.

수정 뒤에는 링크 검사와 `git diff --check`, 관련 경로의 변경 차이를 확인합니다. 기대하는 결과는 한국어·영어 샘플 링크가 모두 올바른 페이지로 연결되고 관련 없는 문서가 바뀌지 않는 상태입니다. 외부 CMS 자격이나 운영 리디렉션 변경이 필요해지면 현재 결과를 남기고 별도 작업으로 분리합니다.

재고 알림 하나를 운영까지 보내 본 과정

가상의 예시로, 품절 상품이 다시 입고되면 구독자에게 알리는 기능을 다룬다면, 처음 요청은 “알림을 추가해 줘”뿐이었습니다. 곧바로 구현했을 때는 재고 갱신마다 같은 고객에게 알림이 반복됐고, 전송 실패를 다시 처리할 기준도 없었습니다. 기능이 보인다는 사실과 운영할 수 있다는 사실이 달랐습니다.

작업을 다시 시작하면서 알림 대상, 한 재입고 주기당 한 번이라는 수용 기준, 관리자 수동 재고 변경은 제외한다는 범위를 먼저 정했습니다. 저장소를 읽어 재고 갱신 경로와 기존 큐를 찾고, 계획 모드에서 데이터 표시, 작업 생성, 전송 결과 기록, 실패 재시도의 순서를 합의했습니다.

단계마다 다음 단계로 넘어갈 증거를 남겼다

이 가상 세션에서는 같은 재고 사건을 반복 처리해도 알림 작업이 중복되지 않는지 단위 테스트로 관찰합니다. 이어서 전송 실패 뒤 재시도와 구독 취소 사용자의 제외를 통합 테스트로 확인했습니다. 미리보기 환경에서는 상품을 품절에서 재고 있음으로 바꾸고 알림 기록이 한 번만 남는 장면을 확인했습니다.

가상 첫 구현은 화면까지 도착해도 중복 알림을 막지 못한 상태입니다. 다시 설계한 흐름은 단계가 더 많았지만 실패 위치가 드러났고, 운영 URL에서 핵심 흐름과 로그를 확인한 뒤에만 완료로 판정할 수 있었습니다. 이 사례가 기획부터 배포까지 각 편을 연결하는 이유입니다.

흐름을 멈추고 계획으로 돌아갈 때

운영 고객 데이터가 있어야 재현되거나 기존 큐의 전달 보장을 설명할 수 없으면 구현을 멈춥니다. 데이터 마이그레이션에 되돌릴 순서가 없고, 외부 메시지 발송 비용과 승인자가 정해지지 않은 경우도 배포 단계로 넘기지 않습니다.

반대로 수정 파일, 자동 검증, 사람 확인 장면, 운영 관찰과 롤백이 모두 설명된다면 다음 단계로 갈 수 있습니다. 이 가이드의 목적은 모든 작업을 길게 만드는 것이 아니라 위험한 빈칸을 코드가 대신 결정하지 못하게 하는 데 있습니다.

2026년의 선택지: 혼자, 서브에이전트, 에이전트 팀

한 세션 안의 짧은 조사는 서브에이전트가 알맞고, 서로 다른 브랜치에서 독립 구현할 일은 Git `worktree`가 안전합니다. 실험 기능인 Agent Teams는 팀원이 서로 메시지를 주고받고 공유 작업 목록을 조정해야 할 때만 켭니다. 작업 이름에 “병렬”이 들어간다는 이유만으로 가장 비싼 방식을 고르지 않습니다.

파일과 네트워크 접근은 권한 규칙과 샌드박스를 함께 봐야 합니다. 새 확장 가이드에서는 이 선택을 별도 실습으로 다룹니다. 기존 8편의 흐름에 안전한 실행 경계와 팀 협업을 더해, 기획부터 운영까지의 빈칸을 줄였습니다.