💡 Anthropic Academy - Claude Code in Action을 수강하며 정리한 글입니다.

Code Assistant는 무엇일까요?

= 코드 작성부터 실행까지, 스스로 계획하고 행동하는 AI 에이전트다.

작동 방식

1. Task 생성: e.g. 오류를 수정해줘
2. Task가 내부 언어 모델로 전달
3. 언어 모델이 Task를 분석하고 Context를 수집
4. Task를 해결할 계획을 수립
5. 문제 해결 Action 실행

LLM은 Task를 해결하기 위해 직접 액션을 실행하는 게 아니라 "어떤 도구를 어떤 인자로 호출할지"를 결정한다. 출력 형태는 구조화된 tool_use 블록이다.

{
  "type": "tool_use",
  "name": "read_file",
  "input": {
    "path": "/src/index.ts"
  }
}

LLM이 tool_use를 출력하면 Claude Code CLI가 로컬 머신에서 실제로 실행하고, 결과를 tool_result로 다시 LLM에 돌려준다.

LLM → tool_use 출력
        ↓
Claude Code CLI가 실제 파일 읽기 실행
      ↓
tool_result로 내용을 LLM에 반환
      ↓
LLM이 다음 단계 결정

• LLM은 "무엇을 할지" 판단 (reasoning)
• Claude Code는 "실제로 실행" (execution)
• 이 루프가 반복되면서 태스크가 완성된다

도구의 종류

도구 전체 목록 보기

프로젝트에서 Claude Code 시작하기

/init & CLAUDE.md

프로젝트에서 Claude Code를 처음 사용할 때는 /init 명령어 실행을 권장한다. 실행하면 현재 코드베이스를 스캔하고, 프로젝트 구조와 내용을 요약해서 CLAUDE.md 파일에 저장한다. 이후 모든 요청 시 CLAUDE.md를 자동으로 컨텍스트에 포함한다.

💡 이미 CLAUDE.md가 있는 경우엔 /init이 기존 내용을 덮어쓰지 않고 보강하는 방식으로 동작한다.

CLAUDE.md 유형

커스텀 지침 추가하기 — #

#을 사용하면 "메모리 모드"로 들어가 CLAUDE.md를 지능적으로 수정할 수 있다.

# 주석은 최소한으로 사용하세요. 복잡한 코드에만 주석을 다는 것이 좋습니다.

Claude가 해당 지침을 자동으로 CLAUDE.md에 추가한다.

파일 선택하기 — @

특정 파일이나 URL을 컨텍스트로 넘길 때 @를 사용한다.

인증 시스템이 어떻게 작동하고 있어? @auth

대화 흐름 제어하기

Planning Mode

복잡한 작업에서 Claude가 변경사항을 바로 구현하지 않고, 실행 계획을 먼저 수립한 뒤 승인을 기다리게 하는 모드다.

활성화: Shift + Tab 두 번

Thinking Mode

복잡한 아키텍처 설계나 까다로운 버그 추적 등에서 사용을 권장한다. 모드마다 내부 추론에 사용하는 thinking budget(토큰)이 늘어나며, 그만큼 더 정교한 분석이 가능하다.

커스텀 명령어 추가하기

1. .claude/commands 폴더를 생성한다.
2. [명령어].md 파일을 만들고 실행할 내용을 작성한다.
3. Claude Code를 재시작한다.
4. /[명령어]로 실행한다.

$ARGUMENTS 변수로 인수를 받을 수 있다.

Write comprehensive tests for: $ARGUMENTS
 
Testing conventions:
* Use Vitest with React Testing Library
* Place test files in __tests__ directory
* Name test files as [filename].test.ts(x)

Hooks

도구 실행 전후에 원하는 코드를 끼워 넣을 수 있는 기능이다.

설정 파일 위치는 아래와 같다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [{ "type": "command", "command": "node /home/hooks/read_hook.ts" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",  // | 로 여러 도구에 동시 적용 가능
        "hooks": [{ "type": "command", "command": "node /home/hooks/edit_hook.ts" }]
      }
    ]
  }
}

MCP 서버 사용하기

Playwright를 예시로 MCP 서버를 연결해본다.

claude mcp add playwright npx @playwright/mcp@latest

매번 권한 요청이 번거롭다면 사전 승인해둘 수 있다.

// .claude/settings.local.json
{
  "permissions": {
    "allow": ["mcp__playwright"],
    "deny": ["mcp__playwright__navigate"]  // 특정 도구만 차단도 가능
  }
}