Claude Code in Action 후기

Anthropic Academy에서 제공하는 "Claude Code in Action" 코스는 AI 에이전트 기반 개발 워크플로우를 체계적으로 학습할 수 있는 무료 과정이다. 2026년 3월 출시된 13개 코스 중 하나로, Claude Code를 실무에 활용하는 방법을 다룬다.

---

코스 개요

항목	내용
코스명	Claude Code in Action
제공	Anthropic Academy (Skilljar)
분량	15개 레슨, 4개 모듈, 퀴즈 8문제
소요 시간	약 2~3시간
비용	무료 (인증서 포함)
난이도	Intermediate

---

1. 에이전틱 루프 — Claude Code의 핵심 동작 원리

Claude Code는 단순한 코드 자동완성 도구가 아니다. 에이전틱 루프라는 자율적 실행 구조로 동작한다.

프롬프트 입력
    ↓
[Context 수집]     파일 읽기, 코드 검색
    ↓
[Action 실행]      코드 편집, 명령 실행
    ↓
[결과 검증]        테스트 실행, 빌드 확인
    ↓
반복 또는 종료

핵심은 stop_reason이다. Claude가 도구 호출을 요청하면(tool_use) 루프가 계속되고, 텍스트만 응답하면(end_turn) 루프가 종료된다. 이 외에도 사용자 인터럽트, maxTurns 제한, Hook의 Stop 이벤트 등이 루프를 종료시킬 수 있지만, stop_reason이 루프 흐름을 결정하는 핵심 메커니즘이다.

도구 실행의 병렬성

코스에서 설명하는 바에 따르면, Read-only 도구(Read, Glob, Grep)는 병렬로 실행되고, 상태를 변경하는 도구(Edit, Write, Bash)는 순차로 실행된다. 이 구분을 이해하면 Claude Code의 동작 속도가 왜 특정 작업에서 빠르고 느린지 감을 잡을 수 있다.

---

2. CLAUDE.md — 프로젝트의 "사용 설명서"

CLAUDE.md는 Claude Code에게 프로젝트의 컨텍스트를 전달하는 파일이다. 세션 시작 시 자동으로 로드되며, 코딩 컨벤션, 아키텍처 규칙, 주요 참조 사항을 담는다.

계층 구조

우선순위	위치	용도
1 (최고)	Managed Policy	조직 전체 규칙
2	`.claude/CLAUDE.md`	프로젝트 규칙 (팀 공유)
3	`~/.claude/CLAUDE.md`	개인 전역 설정

서브디렉토리의 CLAUDE.md는 세션 시작 시 로드되지 않는다. Claude가 해당 디렉토리의 파일을 읽을 때 on-demand로 로드된다.

실무 작성 팁

## Database
We use Dexie.js for IndexedDB. Before implementing:
1. Fetch docs from https://dexie.org/llms.txt
2. Use liveQuery() for reactive binding
3. Follow repository pattern in src/db/

200줄 이하로 유지하는 것이 권장된다. 길면 Claude가 무시할 확률이 높아진다. "코드 정리해주세요" 같은 모호한 지시 대신 "2-space 들여쓰기 사용" 같은 구체적 지시가 효과적이다.

Auto Memory

~/.claude/projects/<project>/memory/MEMORY.md에 세션 간 기억이 자동 저장된다. 첫 200줄 또는 25KB까지 다음 세션 시작 시 자동 로드된다. 별도 설정 없이 기본 활성화 상태이다.

---

3. 커스텀 명령어 & Skills

.claude/commands/ 또는 .claude/skills/ 디렉토리에 마크다운 파일을 넣으면 /명령어명으로 호출할 수 있다.

기본 구조

---
name: deploy
description: 스테이징 서버 배포
argument-hint: [environment]
allowed-tools: Bash(npm run *)
---

$ARGUMENTS 환경에 배포를 진행하세요.
현재 브랜치의 테스트를 먼저 실행하고, 통과하면 배포합니다.

실무 활용 예시

필자는 이직 준비 프로젝트에서 /blog, /algo, /review 같은 명령어를 만들어 사용하고 있다. 블로그 글 작성, 알고리즘 풀이, 코드 리뷰를 각각의 워크플로우로 자동화했다.

---
name: blog
description: 블로그 글 작성
allowed-tools: Read, Write, Edit, WebSearch
---

blog/style-guide.md를 먼저 읽고, 스타일에 맞춰 글을 작성하세요.
$ARGUMENTS

동적 컨텍스트 주입

!`command` 문법으로 셸 명령 결과를 전처리해서 삽입할 수 있다.

---
name: pr-summary
---

## PR 컨텍스트
- PR diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`

이 PR을 요약해주세요.

Claude는 최종 결과만 본다. 이 기능은 PR 리뷰 자동화에 특히 유용하다.

---

4. Hooks — CLAUDE.md와 다른 "강제 규칙"

CLAUDE.md가 "제안"이라면, Hooks는 **"규칙"**이다. CLAUDE.md는 Claude가 무시할 수 있지만, Hook은 매번 반드시 실행된다.

4가지 핵심 이벤트

이벤트	시점	차단 가능
`PreToolUse`	도구 실행 전	Yes
`PostToolUse`	도구 성공 후	No
`Stop`	Claude 응답 완료	Yes
`SessionStart`	세션 시작/재개	No

Exit Code가 핵심이다

코드	동작
**0**	진행 허용
**2**	**차단** (stderr가 Claude에게 피드백)
기타	진행 (로깅만)

.env 파일 보호 Hook (실전 패턴)

settings.json에 Hook을 등록한다.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/protect-files.sh"
      }]
    }]
  }
}

보호 스크립트는 간단하다.

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
PROTECTED=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches '$pattern'" >&2
    exit 2
  fi
done
exit 0

이 패턴 하나만으로도 실수로 .env 파일이 수정되는 사고를 방지할 수 있다.

기타 실용 패턴

패턴	Hook	매처	용도
자동 포맷팅	PostToolUse	Edit|Write	Prettier 실행
데스크톱 알림	Notification	-	입력 대기 시 macOS 알림
SQL 읽기 전용	PreToolUse	Bash	INSERT/UPDATE/DELETE 차단
파일 변경 감시	FileChanged	.env	direnv 자동 리로드

---

5. Subagents — 무거운 작업을 위임하는 방법

Subagent는 독립된 컨텍스트 윈도우에서 실행되는 전문화된 AI 어시스턴트이다. 메인 컨텍스트를 보호하면서 무거운 리서치를 위임할 수 있다.

내장 서브에이전트

에이전트	모델	용도
**Explore**	Haiku (고정)	코드 검색/분석
**Plan**	부모 모델 상속 (기본 Opus, /fast 시 Sonnet)	변경 계획 수립
**general-purpose**	부모 모델 상속 (기본 Opus, /fast 시 Sonnet)	복잡한 멀티스텝 작업

커스텀 서브에이전트

.claude/agents/ 디렉토리에 AGENT.md를 만든다.

---
name: code-reviewer
description: 코드 품질/보안 리뷰 전문가
tools: Read, Glob, Grep
disallowedTools: Write, Edit
model: sonnet
---

당신은 시니어 코드 리뷰어이다.
git diff로 최근 변경을 확인하고, 보안/품질 이슈를 리포트하라.

disallowedTools로 Write/Edit을 막아두면 리뷰어가 실수로 코드를 수정하는 일을 방지할 수 있다. 이 패턴은 "읽기 전용 분석" 에이전트를 만들 때 유용하다.

Skill과 Subagent의 차이

구분	Skill	Subagent
비유	재사용 가능한 **레시피**	전문화된 **동료**
컨텍스트	메인 (fork 시만 분리)	**항상 독립**
영구 메모리	X	O

---

6. MCP 서버 통합

MCP(Model Context Protocol)는 Claude Code를 외부 도구에 연결하는 표준 프로토콜이다.

# Playwright 브라우저 자동화
claude mcp add playwright npx @playwright/mcp@latest

# GitHub 연동
claude mcp add github --transport http --url https://api.github.com/mcp

# Notion 연동
claude mcp add --transport http notion https://mcp.notion.com/mcp

MCP 도구 정의는 deferred로 처리되어, 도구 이름만 컨텍스트에 로드되고 전체 스키마는 사용할 때 on-demand로 로드된다. 이 덕분에 MCP 서버를 많이 연결해도 컨텍스트 비용이 크게 증가하지 않는다.

실전 활용

필자는 MCP 서버를 직접 개발해서 npm에 배포한 경험이 있다(claude-session-continuity-mcp). 코스에서 배운 MCP 통합 방식은 이미 실무에서 사용하고 있었지만, 스코프(Local > Project > User) 우선순위 개념은 코스를 통해 새로 알게 되었다.

---

7. 컨텍스트 관리 — 가장 실용적인 팁

Claude Code를 오래 사용하면 컨텍스트가 차오른다. 이 관리가 생산성의 핵심이다.

사용률	권장
0-50%	자유 작업
50-70%	모니터링
70-90%	**`/compact` 필수**
90%+	**`/clear` 필수**

/compact은 대화를 요약하되 CLAUDE.md는 디스크에서 재로드한다. /clear는 전체 히스토리를 삭제한다. 자동 컴팩션은 컨텍스트 한계에 가까워지면 자동으로 발동된다.

팁: Compact Instructions

CLAUDE.md에 아래를 추가하면 컴팩션 후에도 핵심 정보가 보존된다.

## Compact Instructions
컴팩션 시 항상 보존할 것:
- 현재 태스크 목표
- 읽거나 수정한 파일 경로
- 테스트 결과와 에러 메시지
- 결정 사항과 그 이유

---

8. Permission 시스템

와일드카드 문법 — 공백이 핵심

패턴	매칭
`Bash(ls *)`	`ls -la` O, `lsof` **X**
`Bash(ls*)`	`ls -la` O, `lsof` **O**

공백 유무로 단어 경계가 달라진다. Bash(ls *)는 ls로 시작하는 명령만, Bash(ls*)는 ls로 시작하는 모든 문자열을 매칭한다. 이 차이를 모르면 권한 설정에서 실수할 수 있다.

규칙 평가 순서

deny → ask → allow (첫 매칭 규칙 적용)

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Read"],
    "deny": ["Bash(git push *)", "Read(./.env)"]
  }
}

---

9. 수료 후 느낀 점

이미 알고 있던 것 vs 새로 배운 것

이미 알고 있던 것	새로 배운 것
CLAUDE.md 기본 사용	계층 구조 우선순위 (Managed > Project > User)
슬래시 명령어	`context: fork` + `agent: Explore` 조합
MCP 서버 연동	스코프 우선순위 (Local > Project > User)
기본 Hook 개념	4가지 Handler 타입 (command/http/prompt/agent)
서브에이전트 사용	`disallowedTools` > `tools` 우선 적용

실무에 바로 적용한 것

1. .env 보호 Hook — 프로젝트에 즉시 적용. 실수 방지 효과가 크다
2. Compact Instructions — CLAUDE.md에 추가. 긴 세션에서 컨텍스트 유실이 줄었다
3. context: fork 스킬 — 리서치 무거운 작업을 서브에이전트로 분리

이 코스가 필요한 사람

• Claude Code를 이미 사용하지만 체계적으로 정리하고 싶은 개발자
• CCA (Claude Certified Architect) 시험을 준비하는 사람
• AI 에이전트 기반 개발 워크플로우를 구축하고 싶은 팀 리드

---

정리

• Claude Code는 에이전틱 루프로 동작하며, stop_reason이 루프 흐름을 결정하는 핵심 메커니즘이다
• CLAUDE.md는 "제안", Hook은 "규칙" — 강제해야 할 것은 Hook으로 처리한다
• 컨텍스트 70%에서 /compact, 90%에서 /clear가 생산성의 핵심이다
• 서브에이전트로 무거운 작업을 위임하면 메인 컨텍스트를 보호할 수 있다
• MCP 도구는 on-demand 로드되므로 많이 연결해도 비용 부담이 적다

---

참고:

• Anthropic Academy - Claude Code in Action
• Claude Code 공식 문서
• Claude Code Best Practices
• Hooks Guide