[이제와서 시작하는 Claude AI 마스터하기 #18] Claude Code 워크플로우 설계

게시 2026/02/01 업데이트 2026/02/08

"[이제와서 시작하는 Claude AI 마스터하기 #18] Claude Code 워크플로우 설계"

By YonYonWare

10 분읽는 시간

[이제와서 시작하는 Claude AI 마스터하기 #18] Claude Code 워크플로우 설계

Editor’s Note 확인되지 않은 제품명이나 마법 같은 자동화를 기대하기보다, 공식 Claude Code가 제공하는 slash command, settings, subagents, hooks를 조합해 재현 가능한 개발 워크플로우를 만드는 편이 안전합니다. 이 글에서는 티켓 분석부터 코드 수정, 검증, 리뷰까지 이어지는 실무 흐름을 실제 기능 기준으로 설계합니다.

1. The Bottleneck: 왜 우리는 코딩하다 멈추는가?

개발자가 가장 집중력을 잃는 순간은 코드를 짤 때가 아닙니다. 터미널 ↔ 브라우저 ↔ 슬랙 ↔ 지라를 오가며 컨텍스트 스위칭(Context Switching)을 할 때입니다.

기존: 에러 로그 복사(Cmd+C) → 브라우저 탭 열기 → ChatGPT에 붙여넣기(Cmd+V) → 답변 읽기 → 다시 IDE로 돌아오기
문제점: 이 짧은 10초 동안 우리의 뇌는 ‘Flow’ 상태에서 빠져나옵니다.

Solution: Claude Code Workflow

Claude Code의 강점은 OS 전체를 마법처럼 제어하는 데 있지 않습니다. 프로젝트 폴더, 터미널, Git, 테스트, 문서 맥락을 한 세션 안에서 묶고, 반복 작업을 명령과 설정으로 표준화하는 데 있습니다.

핵심 구성 요소

Slash commands: 자주 쓰는 프롬프트를 .claude/commands/*.md로 저장해 재사용합니다.

CLAUDE.md memory: 프로젝트 규칙, 실행 방법, 금지 사항을 시작 맥락으로 제공합니다.

Settings: 권한, 환경 변수, hooks 같은 팀 설정을 계층적으로 관리합니다.

Subagents: 리뷰어, 테스트 작성자, 문서 점검자처럼 전문 역할을 분리합니다.

Hooks: 도구 사용 전후에 검증 스크립트를 실행해 안전장치를 둡니다.

2. In Action: “티켓에서 PR까지” 워크플로우

실제 시니어 개발자가 Claude Code를 활용해 반복 가능한 흐름을 만드는 예시입니다.

상황: “결제 페이지에서 할인 쿠폰이 적용 안 되는 버그 수정해줘.” (Jira #402)

Step 1. Context Injection (상황 주입)

사용자가 Jira 티켓을 띄워놓고 Claude에게 말합니다.

“이 티켓 내용을 아래에 붙일게. 재현 조건, 영향 범위, 수정 후보 파일, 검증 명령을 먼저 정리해줘.”

화면을 자동으로 읽는다고 가정하지 말고, 티켓 본문/로그/스크린샷 설명을 명시적으로 제공하는 편이 재현성이 높습니다. 필요하면 /add-dir로 관련 workspace를 추가하고, /init 또는 CLAUDE.md로 프로젝트 실행 규칙을 알려줍니다.

“관련된 결제 로직 파일 찾아서 띄워줘.”

Claude Code에는 repository 검색과 파일 읽기를 맡깁니다.

관련 파일을 직접 수정하기 전에 다음을 해줘.
할인 코드, coupon, payment 키워드로 관련 파일을 찾아라.
데이터 흐름을 요약해라.
수정 후보와 테스트 후보를 분리해라.
내가 승인하기 전에는 파일을 수정하지 마라.

Step 3. Fix & Verify (수정 및 검증)

“방어 코드 추가하고, 기존 테스트 깨지는지 확인해.”

수정 후에는 결과를 말로만 믿지 말고 명령으로 확인합니다.

수정 후 다음 순서로 검증해줘.
- 단위 테스트
- 타입 체크
- lint
- 관련 E2E 또는 smoke test
- 실패하면 원인을 요약하고 작은 수정으로 다시 시도

이 과정을 custom slash command로 저장하면 팀 전체가 같은 품질 기준을 반복할 수 있습니다.

3. Expert Configuration: 마스터를 위한 세팅

공식 Claude Code 설정은 .claude/settings.json, .claude/settings.local.json, CLAUDE.md, .claude/commands, .claude/agents를 중심으로 구성합니다.

A. CLAUDE.md로 프로젝트 규칙 고정

프로젝트 루트에 CLAUDE.md를 두면 Claude Code가 시작 시 참고할 팀 규칙을 정리할 수 있습니다.

  
# Project Guide

## Commands
- Install: pnpm install
- Type check: pnpm typecheck
- Test: pnpm test
- Build: pnpm build

## Rules
- Do not edit generated files.
- Do not commit `.env*`.
- Prefer small, focused changes.
- Run tests before finalizing changes.

B. Custom slash command 만들기

반복되는 “티켓 분석 → 수정 계획 → 테스트” 흐름은 명령으로 만듭니다.

  
---
description: Analyze a bug ticket and propose a verified fix plan
---

Analyze the following ticket:

$ARGUMENTS

Return:
1. Reproduction hypothesis
2. Suspected files
3. Minimal fix plan
4. Tests to add or run
5. Risks and rollback notes

파일 위치:

.claude/commands/bug-plan.md

사용 예:

/bug-plan 쿠폰 코드가 null일 때 결제 페이지에서 500 발생

C. Subagents로 역할 분리

큰 작업은 한 모델에게 전부 맡기는 것보다 역할을 나누면 좋습니다.

  
---
name: code-reviewer
description: Reviews code for regressions, missing tests, and maintainability risks
tools: Read, Grep
---

You are a strict code reviewer. Focus on bugs, regressions, missing tests,
security risks, and unclear ownership boundaries. Return findings first.

파일 위치:

.claude/agents/code-reviewer.md

적용 예:

code-reviewer subagent로 이번 auth 변경의 회귀 위험을 점검해줘.

D. Hooks는 안전장치로만 사용

Hooks는 도구 사용 전후에 shell command를 실행할 수 있어 강력하지만 위험합니다. 임의 명령 자동 실행이므로 팀에서 합의한 검증만 최소로 둡니다.

  
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-style.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

권장하지 않는 방식:

rm, 배포, DB migration 같은 파괴적 명령을 hook으로 자동 실행
secret 파일을 읽는 검사
너무 오래 걸리는 전체 E2E를 매 파일 수정마다 실행
팀원마다 다른 local path에 의존하는 스크립트

E. 권한 설정

프로젝트 설정은 공유 가능한 것과 개인 설정을 나눕니다.

파일	용도
`.claude/settings.json`	팀에 공유할 기본 설정
`.claude/settings.local.json`	개인 실험/로컬 설정, git 제외
`~/.claude/settings.json`	모든 프로젝트에 적용되는 개인 설정

민감 파일을 보호하려면 권한 deny 규칙을 활용하고, .env, key, credential 파일은 Claude가 읽지 않도록 명확히 제한하세요.

4. Takeaway

좋은 Claude Code 워크플로우는 “AI가 알아서 다 해준다”가 아니라, 반복 가능한 절차와 검증 가능한 결과를 만드는 것입니다.

지금 당장 해야 할 일:

프로젝트 루트에 CLAUDE.md를 만들고 실행/검증 명령을 적는다.
자주 쓰는 프롬프트 하나를 .claude/commands에 저장한다.
리뷰용 subagent 하나를 만든다.
hooks는 formatting이나 빠른 정적 검사처럼 작고 안전한 것부터 시작한다.
“수정했다”보다 “어떤 검증을 통과했다”를 완료 기준으로 삼는다.

“이제와서 시작하는 Claude AI 마스터하기” 시리즈는 AI 개발 도구를 처음 접하는 분들을 위한 실전 가이드입니다.

AI, Claude

[이제와서 시작하는 Claude AI 마스터하기 #18] Claude Code 워크플로우 설계

1. The Bottleneck: 왜 우리는 코딩하다 멈추는가?

Solution: Claude Code Workflow

2. In Action: “티켓에서 PR까지” 워크플로우

상황: “결제 페이지에서 할인 쿠폰이 적용 안 되는 버그 수정해줘.” (Jira #402)

Step 1. Context Injection (상황 주입)

Step 2. Code Navigation (코드 탐색)

Step 3. Fix & Verify (수정 및 검증)

3. Expert Configuration: 마스터를 위한 세팅

A. CLAUDE.md로 프로젝트 규칙 고정

B. Custom slash command 만들기

C. Subagents로 역할 분리

D. Hooks는 안전장치로만 사용

E. 권한 설정

4. Takeaway

인기 태그