jaysnote

06. Claude Code와 결합한 실전 워크플로

#agentic-engineering #claude-code #워크플로

앞 문서들(방법론·경계·문서)을 Claude Code의 실제 기능과 묶어 하나의 반복 가능한 절차로 만든다.

Claude Code의 어떤 기능이 어디에 쓰이나

아래 기능들을 실제 코딩 세션에서 어떤 명령·단축키로 쓰는지는 명령어로 코드 짜기 예제에서 입력 단위로 따라간다.

Claude Code 기능역할연결되는 개념
CLAUDE.md매 세션 자동 로딩되는 상시 컨텍스트(규칙·명령·함정)헌법·문서
Plan mode탐색·계획과 실행을 분리. 코드 짜기 전에 계획을 검토받음SDD의 Plan 단계, 아키텍처 게이트
Subagents (.claude/agents/)격리된 컨텍스트에서 탐색·전문 작업 위임대규모 탐색, 메인 대화 오염 방지
Slash commands / Skills반복 절차를 명령으로 박제SpecKit 명령
/clear컨텍스트 초기화 (상세)작업 전환 시 컨텍스트 열화 방지
Permission modes도구 실행 승인 게이트사람 게이트

2026년 best practice의 합의: 계획을 먼저(planning before implementation은 협상 불가), 그리고 컨텍스트를 강박적으로 관리하라(CLAUDE.md, 적극적 /clear) — 컨텍스트 열화가 1순위 실패 모드다. (Claude Code Docs)

핵심 루프: 한 기능을 만드는 절차

[사람] 문제·가치 정의              ← 위임 불가
   ↓
[사람 주도+Claude] PRD/Spec 작성    ← Claude가 초안, 모호함 질문 / 사람이 수용 기준 확정
   ↓  ───── 게이트 1: spec 승인
[Claude plan mode] 아키텍처·계획     ← Claude가 옵션·트레이드오프 제시
[사람] 아키텍처 결정 + ADR 기록
   ↓  ───── 게이트 2: plan 승인
[Claude] tasks 분해                 ← 기계적, 사람은 검토만
   ↓
[Claude] 구현 (TDD 루프)            ← 테스트→구현, CLAUDE.md 규칙 준수
   ↓  ───── 게이트 3: diff 리뷰
[사람] 코드 리뷰 + 머지
   ↓  ───── 게이트 4: 배포 승인
[사람] 배포

4개의 게이트가 04. 경계 문서의 “체인 경계 체크포인트”다. 게이트 사이는 Claude가 자율적으로 일한다.

단계별 Claude Code 사용법

0. 세팅 — CLAUDE.md 먼저

프로젝트 규칙·빌드/테스트 명령·함정을 CLAUDE.md에 적는다. SpecKit을 쓴다면 specify init . --integration claude로 헌법과 명령을 깐다. 헌법의 원칙은 CLAUDE.md에도 요약해 두면 매 세션 강제된다.

1. Spec 작성

  • Claude에게 PRD/spec 초안을 시키되, 결정은 사람이 한다.
  • “수용 기준을 측정 가능하게 다시 써줘”, “빠진 엣지 케이스를 질문으로 나열해줘”처럼 모호함을 끌어내는 프롬프트를 쓴다.
  • SpecKit: /speckit.specify → /speckit.clarify.
  • 게이트 1: 사람이 spec을 읽고 승인. 여기서 틀리면 이후 전부 틀린다.

2. 계획 — Plan mode를 반드시 켜라

  • Plan mode로 들어가 Claude가 코드를 건드리지 않고 접근법·파일 변경 계획·아키텍처를 제시하게 한다.
  • 여러 파일 변경·낯선 코드·아키텍처 결정에는 plan mode가 필수. 몇 분의 선투자로 “20분간 자신만만하게 엉뚱한 문제를 푸는” 사태를 막는다. (Claude Code Docs)
  • 중요한 결정은 ADR로 남긴다.
  • SpecKit: /speckit.plan → /speckit.analyze.
  • 게이트 2: 사람이 계획·아키텍처 승인.

3. 작업 분해 & 구현

  • /speckit.tasks로 분해, /speckit.implement로 구현. SpecKit 없이는 plan을 작은 단계로 쪼개 순서대로 시킨다.
  • TDD 루프를 강제: “이 작업은 실패하는 테스트부터 쓰고, 통과시키고, 리팩터해” → 테스트가 검증 게이트가 된다. → 02. TDD.
  • 큰 탐색(많은 파일 읽기)은 subagent에 위임해 메인 컨텍스트를 깨끗이 유지.
  • 작업 전환 시 /clear로 컨텍스트 리셋.

4. 리뷰 & 머지

  • 게이트 3: 사람이 diff를 리뷰. 단, 04. 경계대로 모든 줄이 아니라 위험한 부분(데이터·보안·되돌리기 어려운 것)에 집중. 테스트가 자동 검증을 맡는다.
  • 테스트가 올바른 것을 검증하는지 확인(통과 여부만 보지 말 것).

5. 배포

  • 게이트 4: 항상 사람이 승인. permission mode로 배포성 명령을 게이트.

신뢰가 쌓이면: in-the-loop → on-the-loop

처음엔 게이트마다 꼼꼼히 승인(in-the-loop). 다음을 갖추면 점점 물러난다(on-the-loop):

  • 촘촘한 자동 테스트·타입·린트·CI → 검증성을 올린다.
  • CLAUDE.md/헌법에 가드레일 명문화.
  • 잘 도는 영역은 자율 허용, 자주 틀리는 영역만 다시 당긴다.

안티패턴 (Claude Code 한정)

  • ❌ Plan mode 없이 큰 변경을 바로 구현 → 엉뚱한 문제를 푼다.
  • ❌ 한 세션에서 여러 작업을 섞음 → 컨텍스트 열화. /clear로 끊어라.
  • ❌ CLAUDE.md 없이 매번 같은 맥락을 다시 설명.
  • ❌ 생성 코드를 보지도 않고 머지 → 게이트 3 포기.

최소 실천 (오늘 당장)

도구·문서 다 갖추기 부담된다면 이 3가지만:

  1. CLAUDE.md에 빌드/테스트 명령과 규칙을 적는다.
  2. 큰 변경 전엔 plan mode로 계획을 받고 승인한다(게이트 2).
  3. 머지 전 diff를 리뷰한다(게이트 3).

나머지(SpecKit, PRD, ADR, 헌법)는 프로젝트가 커지고 모호함·협업이 늘어날 때 더한다.

다음: 이 루프를 실제 명령어로 따라가는 07. 예제 프로젝트를 agent와 나눠 만들기.

← 목록으로