도메인 3: Claude Code 구성 및 워크플로 (20%) — 심화편
비중: 전체 시험의 20%
태스크: 6개 (3.1 ~ 3.6)
교차 시나리오: Claude Code를 이용한 코드 생성, 개발자 생산성, CI/CD를 위한 Claude Code
핵심 기술: CLAUDE.md,.claude/rules/,.claude/commands/,.claude/skills/, plan mode,-p플래그
이 도메인은 시험 준비에서 가장 과소평가되기 쉬운 영역이다. “Claude Code 설정”이라고 하면 단순한 환경 구성처럼 느껴지지만, 실제로는 팀 워크플로의 일관성, 문맥 효율성, CI/CD 자동화에 직결되는 아키텍처 결정을 다룬다.
도메인 1(에이전트 아키텍처)과 3의 합산 비중이 47%로 시험의 거의 절반이다. 그런데 도메인 1은 대부분의 수험자가 집중적으로 준비하는 반면, 도메인 3은 “설정 파일 경로나 외우면 되겠지”라고 넘기는 경향이 있다. 시험에서는 설정의 의미와 트레이드오프를 묻는 시나리오 문제가 출제되므로, 단순 암기로는 대응할 수 없다.
이 장은 아래 세 질문을 기준으로 읽으면 훨씬 빨리 정리된다.
- 이 규칙은 항상 적용되어야 하는가, 아니면 필요할 때만 호출하면 되는가?
- 이 설정은 나만 쓰는가, 팀 전체가 공유해야 하는가, 아니면 특정 경로에서만 적용되어야 하는가?
- 지금 작업은 먼저 탐색과 설계가 필요한가, 아니면 바로 구현에 들어가도 되는가?
Domain 3 Concept Primer
이 도메인은 Claude Code 기능 목록을 외우는 장이 아니다.
더 정확히는 Claude Code를:
- 어떤 규칙 구조 안에 둘지
- 반복 판단을 어디에 외부화할지
- 언제 계획하고 언제 실행할지
- 어떤 작업 루프로 굴릴지
- 팀 차원에서 어떻게 재현 가능하게 만들지
- 어디서 자동 검증하고 어디서 인간 검토로 넘길지
를 함께 설계하는 장에 가깝다.
즉 Domain 3는 Claude Code를 단순한 코딩 도구가 아니라, 운영 가능한 coding harness로 다루는 관점이 핵심이다.
특히 아래 개념 문서를 같이 보면 흐름이 훨씬 잘 잡힌다.
- CLAUDE.md & Instruction Hierarchy: 규칙이 어디서 오고 어떤 우선순위로 적용되는가
- Rules as Operational Memory: 반복 판단을 rules로 외부화하는 이유
- Plan Mode & Execution Control: 언제 실행을 보류하고 먼저 정렬할 것인가
- Coding Workflow Design: 읽기·계획·수정·검증·검토 루프를 어떻게 설계할 것인가
- Team Conventions & Reproducibility: 여러 사람이 비슷한 방식으로 작업하고 검토하게 만드는 구조
- CI, Guardrails & Review Boundaries: 작업 종료 조건과 신뢰 경계를 어디에 둘 것인가
한 문장으로 줄이면 Domain 3의 핵심은:
Claude Code를 잘 쓰는 법보다, Claude Code가 예측 가능하고 재현 가능하며 검증 가능한 방식으로 일하게 만드는 법
이다.
3.1 — CLAUDE.md는 어디에 놓아야 하는가
관련 개념 문서: CLAUDE.md & Instruction Hierarchy
세 단계 계층 구조
CLAUDE.md는 Claude Code가 프로젝트의 맥락을 이해하기 위해 참조하는 설정 파일이다. 이 파일은 세 가지 레벨에 존재할 수 있으며, 각 레벨은 적용 범위와 공유 방식이 다르다.
| 레벨 | 위치 | 누구에게 적용되는가 | 버전 관리로 공유되는가 |
|---|---|---|---|
| 사용자(User) | ~/.claude/CLAUDE.md | 해당 사용자만 | ✗ 아니오 — 로컬 전용 |
| 프로젝트(Project) | .claude/CLAUDE.md 또는 루트 CLAUDE.md | 레포를 clone한 모든 팀원 | ✓ 예 |
| 디렉터리(Directory) | 하위 디렉터리 내 CLAUDE.md | 해당 디렉터리에서 작업할 때만 | ✓ 예 |
빠르게 고르는 규칙은 단순하다.
- 나만의 선호나 실험이면 사용자 레벨
- 팀 공통 규칙이면 프로젝트 레벨
- 특정 하위 영역에서만 항상 필요하면 디렉터리 레벨
이 구분이 왜 중요한가
이 계층 구조에서 가장 흔한 실수 — 그리고 시험에서 자주 등장하는 함정 — 는 팀 전체에 적용되어야 할 지시를 사용자 레벨에 넣는 것이다.
구체적인 시나리오를 생각해 보자: 당신이 팀 리드로서 “모든 API 응답에는 에러 핸들링을 포함해야 한다”는 규칙을 만들었다. 이것을 ~/.claude/CLAUDE.md에 넣으면 당신의 환경에서는 잘 작동한다. 그런데 새로 합류한 팀원이 레포를 clone하면, 그 팀원의 Claude Code에는 이 규칙이 존재하지 않는다. 사용자 레벨 설정은 버전 관리에 포함되지 않기 때문이다.
올바른 위치는 .claude/CLAUDE.md (프로젝트 레벨)이다. 이 파일은 레포에 포함되어 버전 관리되므로, clone하는 모든 사람에게 동일하게 적용된다.
진단 방법: 팀원 간에 Claude Code의 동작이 일관되지 않다면, /memory 명령으로 현재 세션에 어떤 설정 파일이 로드되어 있는지 확인한다. 이것으로 사용자 레벨에 놓인 규칙이 문제인지, 아니면 다른 원인인지를 빠르게 진단할 수 있다.
모듈화: 거대한 CLAUDE.md를 관리하는 법
프로젝트가 커지면 CLAUDE.md도 커진다. 수백 줄이 되면 관리가 어려워진다. 이때 두 가지 모듈화 전략이 있다.
전략 1: @import 문법
<!-- .claude/CLAUDE.md -->
# 프로젝트 규칙
@import ./standards/api-conventions.md
@import ./standards/testing.md
@import ./standards/deployment.md각 패키지의 CLAUDE.md에서 해당 도메인 유지보수자가 관리하는 표준 파일만 선택적으로 가져올 수 있다. 이렇게 하면 하나의 거대한 파일을 관리하는 부담 없이, 각 영역의 전문가가 자기 규칙을 독립적으로 관리할 수 있다.
전략 2: .claude/rules/ 디렉터리
단일 CLAUDE.md 대신, .claude/rules/ 디렉터리에 주제별 규칙 파일을 분리하여 관리한다.
| 경로 | 역할 |
|---|---|
.claude/CLAUDE.md | 핵심 규칙만 유지 |
.claude/rules/testing.md | 테스트 규칙 |
.claude/rules/api-conventions.md | API 규칙 |
.claude/rules/deployment.md | 배포 규칙 |
이 방식은 @import와 유사한 효과를 내지만, 다음 섹션(3.3)에서 다룰 경로 기반 조건부 로딩과 결합하면 훨씬 강력해진다.
두 전략을 고르는 기준도 기억해 두면 좋다.
- 항상 함께 읽혀야 하는 공통 규칙 묶음이면
@import - 특정 파일 경로나 작업 영역에서만 필요하면
.claude/rules/+ 경로 조건 - 파일이 커져서 관리가 어려운 문제와, 필요할 때만 로드해야 하는 문제는 서로 다른 문제다. 전자는 모듈화, 후자는 조건부 로딩으로 푼다.
3.2 — 슬래시 명령과 스킬은 무엇이 다른가
관련 개념 문서: Rules as Operational Memory
슬래시 명령: 팀 공유 vs 개인 전용
슬래시 명령(slash command)은 반복적인 작업을 한 번의 호출로 실행하는 단축키다.
| 종류 | 위치 | 공유 | 전형적 용도 |
|---|---|---|---|
| 프로젝트 명령 | .claude/commands/ | ✓ VCS를 통해 팀 전체 | /review — 팀 표준 코드 리뷰 체크리스트 실행 |
| 개인 명령 | ~/.claude/commands/ | ✗ 로컬 전용 | /myformat — 개인 선호 코드 포맷팅 |
공식 샘플 문제 4번이 정확히 이것을 묻는다:
팀의 표준 코드 리뷰 체크리스트를 실행하는
/review슬래시 명령을 만들려고 합니다. 레포를 clone하거나 pull하는 모든 개발자가 이 명령을 사용할 수 있어야 합니다. 명령 파일을 어디에 만들어야 합니까?
정답은 .claude/commands/ 디렉터리이다. ~/.claude/commands/(개인)에 만들면 다른 팀원은 사용할 수 없고, CLAUDE.md에 넣는 것은 명령 정의 메커니즘이 아니며, .claude/config.json의 commands 배열은 존재하지 않는 기능이다.
스킬: 온디맨드 실행과 격리
스킬(skill)은 .claude/skills/ 디렉터리의 SKILL.md 파일로 정의되며, 슬래시 명령보다 더 풍부한 설정을 가진다. 핵심은 YAML frontmatter를 통한 세 가지 설정이다.
context: fork — 왜 필요한가
스킬이 대규모 코드베이스 분석이나 탐색적 브레인스토밍 같은 작업을 수행하면, 그 과정에서 장황한 출력이 대량으로 생성된다. 이 출력이 메인 대화 세션에 남으면, 후속 작업의 문맥을 오염시키고 문맥 창을 빠르게 소진한다.
context: fork를 설정하면 스킬이 격리된 서브에이전트에서 실행된다. 스킬이 아무리 많은 중간 출력을 생성해도, 메인 세션에는 최종 결과만 돌아온다.
---
context: fork
allowed-tools: ["Read", "Grep", "Glob"]
argument-hint: "분석할 디렉터리 경로를 입력하세요"
---
# 코드베이스 분석 스킬
이 스킬은 지정된 디렉터리의 코드 구조를 분석하고 요약합니다.allowed-tools — 스킬의 행동 범위를 제한
스킬 실행 중에 사용할 수 있는 도구를 제한한다. 예를 들어, 코드 분석 스킬에는 Read, Grep, Glob만 허용하고, Write나 Bash는 제외하면 — 스킬이 실수로 파일을 수정하거나 위험한 명령을 실행하는 것을 구조적으로 방지할 수 있다.
argument-hint — 사용자에게 필수 입력을 요청
스킬이 인수 없이 호출되었을 때, 어떤 파라미터가 필요한지를 사용자에게 안내한다. “분석할 디렉터리 경로를 입력하세요” 같은 힌트가 표시된다.
스킬 vs CLAUDE.md — 언제 무엇을 쓰는가
이 구분은 시험에서 판단력을 측정하는 데 활용된다.
| 스킬 | CLAUDE.md | |
|---|---|---|
| 로딩 시점 | 호출될 때만 (온디맨드) | 항상 로드됨 |
| 용도 | 특정 워크플로에 특화된 작업 | 범용적인 코딩 표준, 규칙 |
| 격리 | context: fork로 격리 가능 | 격리 불가 — 항상 메인 문맥에 존재 |
| 예시 | 코드베이스 분석, 마이그레이션 도우미, 보안 스캔 | 코딩 스타일, 테스트 규칙, API 규약 |
다시 말해, 항상 적용되어야 하는 규칙은 CLAUDE.md에, 필요할 때만 실행하는 작업은 스킬에 넣는다.
여기에 슬래시 명령까지 포함해 세 가지를 한 번에 비교하면 더 명확하다.
| 메커니즘 | 가장 잘 맞는 용도 | 로딩/실행 방식 | 대표 예시 |
|---|---|---|---|
| CLAUDE.md | 상시 적용 규칙 | 항상 로드 | 테스트 규칙, API 규약, 코딩 표준 |
| 슬래시 명령 | 자주 반복되는 호출 단축 | 사용자가 호출할 때 실행 | /review, /release-check |
| 스킬 | 온디맨드 전문 워크플로 | 사용자가 호출할 때 실행, 필요하면 격리 | 코드베이스 분석, 보안 스캔, 마이그레이션 가이드 |
실전 감각으로 말하면, “항상 지켜야 하는 규칙”은 CLAUDE.md, “자주 쓰는 단축 실행”은 슬래시 명령, “무겁거나 전문화된 작업”은 스킬로 두는 편이 안정적이다.
개인 스킬 변형
팀 스킬의 개인 변형이 필요한 경우 — 예를 들어, 동일한 분석 스킬이지만 자신만의 출력 포맷을 원하는 경우 — ~/.claude/skills/에 다른 이름으로 개인 스킬을 만들 수 있다. 같은 이름을 사용하면 팀원에게 영향을 줄 수 있으므로, 반드시 이름을 다르게 해야 한다.
3.3 — 규칙은 어떤 파일에만 적용되어야 하는가
관련 개념 문서: CLAUDE.md & Instruction Hierarchy, Rules as Operational Memory
경로 기반 조건부 규칙
.claude/rules/ 디렉터리의 규칙 파일에 YAML frontmatter의 paths 필드를 사용하면, 해당 규칙이 특정 파일을 편집할 때만 로드된다.
---
paths: ["terraform/**/*"]
---
# Terraform 규칙
- 재사용 가능한 인프라에는 항상 모듈을 사용할 것
- 변수에는 반드시 description을 포함할 것
- remote state를 구성할 것핵심은 Claude가 “지금 어떤 규칙 섹션을 읽어야 하지?”를 추론하게 만들지 않는 데 있다. 규칙의 적용 여부는 가능한 한 사람의 분류가 아니라 경로 조건으로 자동화하는 편이 더 안정적이다.
이 규칙은 terraform/ 디렉터리 안의 파일을 편집할 때만 문맥에 로드된다. React 컴포넌트를 작업할 때 Terraform 규칙이 문맥을 차지할 이유가 없으므로, 이것은 토큰 효율성을 크게 향상시킨다.
경로 기반 규칙 vs 디렉터리 CLAUDE.md — 왜 전자가 나은가
여기서 한 가지 중요한 설계 판단이 있다. 디렉터리마다 CLAUDE.md를 두는 것도 가능하지만, 파일 유형별 규칙에는 경로 기반 규칙이 더 적합하다.
이유를 구체적인 예시로 살펴보자. 프로젝트에서 테스트 파일이 소스 코드 옆에 위치한다고 가정하자:
| 경로 | 설명 |
|---|---|
src/components/Button.tsx | 컴포넌트 구현 |
src/components/Button.test.tsx | 컴포넌트 테스트 |
src/api/orders.ts | API 구현 |
src/api/orders.test.ts | API 테스트 |
src/utils/format.ts | 유틸리티 구현 |
src/utils/format.test.ts | 유틸리티 테스트 |
모든 테스트 파일에 동일한 규칙(“React Testing Library를 사용하라”, “describe-it 구조를 따르라”)을 적용하고 싶다면:
- 디렉터리 CLAUDE.md 접근:
components/,api/,utils/세 디렉터리 각각에 동일한 테스트 규칙을 복사해야 한다 → 유지보수 악몽 - 경로 기반 규칙 접근: 단일 파일에
paths: ["**/*.test.tsx", "**/*.test.ts"]를 지정 → 위치에 관계없이 모든 테스트 파일에 적용
공식 샘플 문제 6번이 정확히 이 판단을 묻는다:
React 컴포넌트는 함수형 + 훅, API 핸들러는 async/await + 에러 핸들링, DB 모델은 레포지토리 패턴을 따릅니다. 테스트 파일은 코드 옆에 분산되어 있고, 모든 테스트에 동일한 규칙을 적용해야 합니다. 가장 유지보수하기 쉬운 방법은?
정답은 .claude/rules/에 glob 패턴이 있는 규칙 파일을 만드는 것(A)이다. 루트 CLAUDE.md에 섹션별로 정리하는 것(B)은 Claude가 어떤 섹션을 적용해야 하는지 추론에 의존하므로 불안정하다. 스킬(C)은 수동 호출이 필요하므로 “자동 적용”이 아니다. 디렉터리 CLAUDE.md(D)는 여러 디렉터리에 분산된 파일을 처리하지 못한다.
3.4 — Plan mode를 쓸 것인가, 바로 실행할 것인가
관련 개념 문서: Plan Mode & Execution Control, Coding Workflow Design
판단 기준
이것은 매우 실용적인 아키텍처 결정이다. 잘못된 모드를 선택하면 — plan mode가 필요한 작업을 직접 실행하면 비용이 큰 재작업이 발생하고, 단순한 작업에 plan mode를 쓰면 불필요한 시간을 낭비한다.
| Plan Mode를 써야 할 때 | 직접 실행을 써야 할 때 |
|---|---|
| 수십 개 파일에 걸친 대규모 변경 | 단일 파일의 범위가 명확한 버그 수정 |
| 구현 방법이 여러 가지이고, 어떤 것이 나은지 판단이 필요 | 스택 트레이스가 명확하고, 수정이 자명한 경우 |
| 아키텍처 결정이 수반되는 작업 (서비스 분리, 라이브러리 교체) | 날짜 유효성 검사 추가 같은 단순한 조건 추가 |
| 기존 코드의 의존 관계를 먼저 파악해야 하는 경우 | 변경의 영향 범위가 한눈에 보이는 경우 |
plan mode의 실제 흐름을 짧게 쓰면 이렇다.
- 코드베이스를 탐색한다.
- 의존성과 영향 범위를 파악한다.
- 접근법과 작업 순서를 설계한다.
- 그다음에 범위를 좁혀 직접 실행으로 넘어간다.
공식 샘플 문제 5번이 이 판단을 직접 묻는다:
모놀리식 애플리케이션을 마이크로서비스로 재구성하는 작업을 맡았습니다. 수십 개의 파일에 걸친 변경이 필요하고, 서비스 경계와 모듈 의존성에 대한 결정이 필요합니다. 어떤 접근을 취해야 합니까?
정답은 (A) plan mode로 코드베이스를 탐색하고, 의존성을 이해하고, 구현 접근법을 설계한 후 변경을 시작하는 것이다. 직접 실행부터 시작하면(B, C) 의존성을 나중에 발견하여 비용이 큰 재작업이 발생한다. 복잡성이 “나중에 나타날 수 있다”며 일단 직접 실행하는 것(D)은 이미 요구사항에 복잡성이 명시되어 있으므로 무의미하다.
Explore 서브에이전트
plan mode에서 코드베이스를 탐색할 때, 탐색 과정 자체가 대량의 장황한 출력을 생성한다. Grep 결과, 파일 내용, 의존성 추적 — 이 모든 것이 메인 대화 문맥에 쌓이면 문맥 창이 빠르게 소진된다.
Explore 서브에이전트는 이 문제를 해결한다. 탐색 작업을 Explore 서브에이전트에 위임하면, 장황한 중간 출력은 서브에이전트 내부에 남고, 요약된 결과만 메인 세션에 반환된다.
가장 효과적인 조합 패턴
실전에서 가장 권장되는 패턴은 두 모드의 조합이다:
- Plan mode에서 코드베이스를 탐색하고, 의존성을 파악하고, 접근법을 설계한다. 장황한 탐색은 Explore 서브에이전트로 격리한다.
- 직접 실행 단계에서 1단계에서 정리한 접근법을 구현한다. 범위가 분명해졌기 때문에 직접 실행이 더 적합하다.
3.5 — Claude와 어떻게 반복 작업을 하는가
관련 개념 문서: Coding Workflow Design, Team Conventions & Reproducibility
산문 설명이 통하지 않을 때
Claude에게 원하는 결과를 자연어로 설명했는데, 결과가 기대와 다를 수 있다. “인라인 스타일을 CSS 모듈로 변환해 줘”라고 했는데 매번 다른 방식으로 변환한다거나, 특정 엣지 케이스를 일관되게 처리하지 못한다거나.
이때 가장 효과적인 해결책은 2~3개의 구체적인 입출력 예시를 제공하는 것이다. “이런 입력이 들어오면, 이런 출력이 나와야 한다”를 보여주면, Claude는 패턴을 파악하여 새로운 경우에도 일관되게 적용한다.
예시 1:
입력: <div style={{color: 'red', fontSize: '14px'}}>Hello</div>
출력: <div className={styles.greeting}>Hello</div>
/* styles.module.css: .greeting { color: red; font-size: 14px; } */
예시 2:
입력: <span style={{marginLeft: '8px'}}>World</span>
출력: <span className={styles.suffix}>World</span>
/* styles.module.css: .suffix { margin-left: 8px; } */
이 예시들은 Claude에게 “클래스 이름을 의미적으로 정하라”, “camelCase를 kebab-case로 변환하라” 같은 규칙을 암묵적으로 전달한다.
무엇을 먼저 꺼내야 할지도 구분해 두면 좋다.
- 원하는 출력 형식은 분명한데 일관성이 부족하면 입출력 예시
- 정답 여부를 객관적으로 판정해야 하면 테스트 주도 반복
- 문제 공간 자체가 낯설고 고려 사항이 많으면 먼저 질문하기
테스트 주도 반복
더 강력한 반복 패턴이 있다. 테스트 스위트를 먼저 작성하고, 그 테스트의 실패 결과를 Claude에게 공유하면서 점진적으로 개선하는 것이다.
1. 기대 동작, 엣지 케이스, 성능 요건을 포함한 테스트 작성
2. Claude에게 구현을 요청
3. 테스트 실행 → 실패한 테스트 결과를 Claude에게 공유
4. Claude가 실패를 분석하고 수정
5. 모든 테스트가 통과할 때까지 3~4 반복
이 접근법의 장점은 “잘 되었다/안 되었다”를 객관적으로 판단할 수 있다는 것이다. 산문으로 “좀 더 정확하게 해 줘”라고 하는 것보다 실패한 테스트 케이스를 보여주는 것이 훨씬 효과적이다.
인터뷰 패턴: 구현 전에 먼저 질문하기
낯선 도메인에서 작업할 때 특히 유용한 패턴이다. 바로 구현을 요청하는 대신, Claude에게 먼저 설계 고려 사항을 도출하도록 요청한다.
예를 들어, 캐시 시스템을 구현해야 하는데 캐싱에 익숙하지 않다면:
“Redis 기반 캐시 레이어를 구현하기 전에, 고려해야 할 설계 사항들을 먼저 정리해 줘. 캐시 무효화 전략, 실패 모드, 동시성 문제 등.”
Claude가 개발자가 미처 생각하지 못한 고려 사항(cache invalidation, thundering herd, 부분 실패 복구 등)을 제시하면, 그 다음에 정보에 기반한 설계 결정을 내릴 수 있다.
이슈를 한 번에 보낼 것인가, 하나씩 보낼 것인가
| 상황 | 접근법 | 이유 |
|---|---|---|
| 이슈들이 서로 상호작용함 | 하나의 메시지에 모두 포함 | 한 이슈의 수정이 다른 이슈에 영향을 미치므로, 전체 맥락을 보고 수정해야 함 |
| 이슈들이 독립적임 | 하나씩 순차적으로 | 각 이슈를 깔끔하게 해결하고 넘어가는 것이 더 안정적 |
예를 들어, “함수 A의 반환 타입이 잘못되었고, 이 타입을 사용하는 함수 B도 수정이 필요하다”는 상호작용 이슈이므로 한 메시지에 보내야 한다. 반면 “로그 포맷 변경”과 “새 환경 변수 추가”는 독립적이므로 순차 처리가 적합하다.
판별 공식으로 줄이면, 한 수정이 다른 수정의 정답 조건을 바꾸면 함께 보내고, 그렇지 않으면 분리하는 편이 낫다.
3.6 — CI/CD 파이프라인에서 Claude Code를 어떻게 쓰는가
관련 개념 문서: CI, Guardrails & Review Boundaries, Team Conventions & Reproducibility
첫 번째 문제: 파이프라인이 멈춘다
CI/CD 파이프라인에서 Claude Code를 처음 사용할 때 가장 흔한 문제는 파이프라인이 무한히 멈추는 것이다. Claude Code는 기본적으로 대화형(interactive) 모드로 실행되어 사용자 입력을 기다리기 때문이다.
기준은 간단하다. 사람이 터미널에서 대화하며 조정할 작업이면 대화형이 맞고, 파이프라인처럼 입력 없이 실행되고 종료되어야 하는 작업이면 비대화형 플래그를 써야 한다.
공식 샘플 문제 10번이 정확히 이것을 묻는다:
파이프라인 스크립트가
claude "Analyze this pull request for security issues"를 실행하지만 무한히 멈춥니다. 로그에 따르면 Claude Code가 대화형 입력을 기다리고 있습니다. 올바른 접근은?
정답은 -p (또는 --print) 플래그를 추가하는 것이다:
claude -p "Analyze this pull request for security issues"-p 플래그는 Claude Code를 **비대화형 모드(non-interactive mode)**로 실행한다. 프롬프트를 처리하고, 결과를 stdout으로 출력한 뒤, 사용자 입력을 기다리지 않고 종료한다.
✗ CLAUDE_HEADLESS=true 환경 변수 → 존재하지 않는 기능
✗ --batch 플래그 → 존재하지 않는 기능
✗ < /dev/null로 stdin 리다이렉트 → Unix 편법이지 Claude Code의 올바른 사용법이 아님
구조화된 CI 출력
코드 리뷰 결과를 PR에 인라인 코멘트로 자동 게시하려면, 사람이 읽는 텍스트가 아니라 기계가 파싱할 수 있는 구조화된 출력이 필요하다.
claude -p "Analyze this PR for issues" \
--output-format json \
--json-schema '{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"severity":{"type":"string"},"message":{"type":"string"}}}}'--output-format json과 --json-schema를 결합하면, Claude Code가 지정된 스키마에 맞는 JSON을 출력한다. 이 출력을 파싱하여 PR의 해당 파일, 해당 라인에 코멘트를 자동으로 게시할 수 있다.
중복 코멘트를 방지하는 법
코드가 수정된 후 리뷰를 다시 실행하면, 이전에 이미 보고한 이슈를 또 보고하는 문제가 발생한다. 해결 방법은 이전 리뷰 결과를 문맥에 포함시키고, “새로운 이슈 또는 아직 해결되지 않은 이슈만 보고하라”고 지시하는 것이다.
마찬가지로, 테스트를 생성할 때는 기존 테스트 파일을 문맥에 포함시켜야 이미 있는 테스트 시나리오를 중복 생성하지 않는다.
자기 리뷰의 한계
여기서 한 가지 중요한 아키텍처 원칙이 있다: 코드를 생성한 Claude 세션이 그 코드를 리뷰하는 것은 효과적이지 않다.
왜 그런가? 모델은 생성 과정에서의 추론 문맥(reasoning context)을 유지하고 있다. “이 방식으로 구현하는 것이 좋겠다”는 판단을 이미 내렸기 때문에, 같은 세션에서 리뷰를 요청하면 자기 결정에 의문을 제기할 가능성이 낮다.
따라서 CI 파이프라인에서 생성과 리뷰를 모두 수행한다면, **독립적인 세션(또는 인스턴스)**을 사용해야 한다. 생성 세션의 추론 문맥 없이 코드만 보는 리뷰어가 더 미묘한 이슈를 잡아낸다.
CLAUDE.md를 통한 테스트 생성 품질 향상
Claude Code가 테스트를 생성할 때, 프로젝트의 테스트 관습을 모르면 가치가 낮은 테스트를 만들어낸다. CLAUDE.md에 다음을 문서화하면 품질이 크게 향상된다:
- 사용하는 테스트 프레임워크와 설정
- 가치 있는 테스트의 기준 (예: “행동을 테스트하라, 구현을 테스트하지 마라”)
- 사용 가능한 테스트 픽스처(fixture)와 헬퍼
- 피해야 할 테스트 패턴
자주 나오는 오답 패턴 정리
| # | 안티패턴 | 왜 틀린가 | 올바른 접근 |
|---|---|---|---|
| 1 | 팀 규칙을 ~/.claude/CLAUDE.md에 배치 | 사용자 레벨 설정은 VCS에 포함되지 않아 다른 팀원에게 적용 안 됨 | .claude/CLAUDE.md (프로젝트 레벨)에 배치 |
| 2 | 루트 CLAUDE.md에 모든 규칙을 영역별 헤더로 정리 | Claude가 어떤 섹션을 적용할지 추론에 의존 — 불안정 | .claude/rules/에 경로 기반 조건부 규칙 사용 |
| 3 | 마이크로서비스 재구성을 직접 실행부터 시작 | 의존성을 나중에 발견하여 비용 큰 재작업 | Plan mode로 먼저 탐색하고 설계 |
| 4 | CI에서 -p 없이 Claude Code 실행 | 대화형 입력을 기다리며 파이프라인 멈춤 | -p (또는 --print) 플래그 사용 |
| 5 | 코드 생성한 세션에서 바로 리뷰 | 생성 시 추론 문맥이 남아 자기 리뷰 편향 발생 | 독립적인 리뷰 세션/인스턴스 사용 |
| 6 | 스킬을 CLAUDE.md에 기능 설명으로 대체 | CLAUDE.md는 항상 로드 — 온디맨드 실행, 격리 불가 | .claude/skills/에 frontmatter와 함께 스킬로 정의 |
| 7 | 디렉터리마다 CLAUDE.md로 테스트 규칙 복사 | 분산된 파일에 대한 유지보수 악몽 | paths: ["**/*.test.*"] glob 규칙 하나로 해결 |
직접 해보기
연습: 팀 워크플로를 위한 Claude Code 구성
-
프로젝트 레벨 CLAUDE.md를 작성한다. 범용 코딩 표준과 테스트 규칙을 포함한다. 프로젝트 레벨에 작성한 규칙이 clone 후에도 일관되게 적용되는지 확인한다.
-
.claude/rules/에 경로 기반 규칙을 3개 만든다. 예:paths: ["src/api/**/*"](API 규칙),paths: ["**/*.test.*"](테스트 규칙),paths: ["terraform/**/*"](인프라 규칙). 각 유형의 파일을 편집할 때 해당 규칙만 로드되는지 확인한다. -
context: fork와allowed-tools가 설정된 스킬을 만든다. 코드베이스 분석 스킬을 만들고, 실행 시 장황한 탐색 출력이 메인 대화를 오염시키지 않는지 확인한다.allowed-tools에서Write를 제외하고, 스킬이 파일을 수정하려 할 때 차단되는지 테스트한다. -
.mcp.json에 프로젝트 레벨 MCP 서버를 설정하고,~/.claude.json에 실험용 서버를 추가한다. 두 서버 모두 동시에 사용 가능한지 확인한다. -
Plan mode와 직접 실행을 비교한다. 복잡도가 다른 세 가지 작업에 각각 적용해 본다: (a) 단일 파일 버그 수정, (b) 3개 파일에 걸친 함수 리네이밍, (c) 라이브러리 마이그레이션 (45+ 파일). 각 경우에 어떤 모드가 더 효과적인지 직접 경험한다.
-
CI 파이프라인에서
-p플래그로 Claude Code를 실행한다.--output-format json으로 구조화된 결과를 생성하고, 이 결과를 PR 코멘트로 변환하는 스크립트를 작성한다. 이전 리뷰 결과를 문맥에 포함시키고, 중복 코멘트가 생기지 않는지 확인한다.
참고 링크
| 주제 | 링크 |
|---|---|
| Claude Code 개요 | Claude Code Overview — Anthropic Docs |
| Claude Code 설정 | Claude Code Configuration — Anthropic Docs |
| 장기 실행 에이전트 하니스 | Effective Harnesses for Long-Running Agents — Anthropic Engineering |
| 문맥 공학 | Effective Context Engineering — Anthropic Engineering |
| 에이전트를 위한 도구 작성법 | Writing Tools for Agents — Anthropic Engineering |
| 공식 시험 가이드 PDF | CCAF Exam Guide |