[Claude Code] 30분 만에 Claude Code 마스터하기 by Anthropic

앤트로픽에서 "Mastering Claude Code in 30 minutes"라는 영상을 올렸다. 요즘에는 본인의 호불호가 어떻든 개발자로서 ChatGPT나 Claude Code 같은 AI 툴을 안 쓰기란 쉽지 않다고 생각하기도 하고, 나 스스로가 이런 툴들을 사용할 줄은 알지만 '잘' 사용한다고 생각하지는 않기 때문에 영상을 보기로 했다. 사실 나온 지는 1년 쯤된 영상인데, 늦게라도 보고 정리하는 게 어디인가...

🔗영상 링크: https://www.youtube.com/live/6eBSHbLKuN0?si=aJZV73Rd5CEcPz0g

 

Notice 참고로 영상에서는 OS를 Mac으로 가정하고 진행하는 듯하다.

 

🔖목차

• 1. 소개
• 2. 환경 설정하기
• 3. 코드베이스 Q&A 기초
• 4. 효율적으로 코드 수정하기
• 5.팀 도구 연결하기
• 6. 컨텍스트 관리
• 7. 팀과 공유하기
• 8. 유용한 키 바인딩
• 9. 클로드 스크립팅
• 10. 멀티 클로드

소개

발표를 따라가려면 클로드 코드를 설치해야 한다. Node.js가 먼저 설치되어 있는지 확인하고, 설치되어 있다면 아래 명령어를 터미널에 입력하여 클로드 코드를 설치하자. 

npm install -g @anthropic-ai/claude-code

 

지금까지의 AI 어시스턴트(AI assistant)는 한 번에 코드를 한 줄에서 몇 줄 정도를 작성하는데 그쳤다면, 클로드 코드는 완전히 새로운 어시스턴트로 fully agentic 하다. (AI 어시스턴트보다는 AI 에이전트에 가깝다는 의미인 것 같다) 클로드 코드는 기능을 생성하거나 함수 전체 또는 파일 전체를 작성하고, 전체 버그를 고치는 일이 가능하다. 게다가 다른 도구와도 함께 사용이 가능하기 때문에 기존 워크플로우를 수정하거나 IDE나 터미널 같은 환경을 바꿀 필요가 없다. 

 

클로드 코드와 같은 자유로운 형태의 코딩 어시스턴트를 사용해 본 적이 없다면, 처음에는 어떻게 사용해야 할지 막막할 수 있다. 그렇지만 클로드 코드는 어떤 워크플로우를 유도하지는 않는다. 이 도구가 할 수 있는 일이 매우 많기 때문에 엔지니어인 본인이 원하는 방식으로 쓸 수 있어야 한다. 

 

환경 설정하기

클로드 코드를 처음 열었을 때 환경 설정을 위해 추천하는 매우 간단한 것들이 있다. 

• `/terminal-setup` : 'shift-enter'를 이용하여 줄 바꿈 할 수 있도록 함
• `/slash-theme` : 다크/라이트 모드 설정하기
• `/install-github-app` : 깃허브 이슈나 PR에 @claude 멘션 하기
• `/allowed-tools` : 클로드 코드의 도구 접근 권한 커스터마이징 (해두면 매번 확인하지 않아도 됨)
• `/config` : 알람 활성화
• Turn on MacOS dictation: 많은 프롬프트를 작성해야 할 때 클로드 코드에 직접 입력(hand type) 하지 않고 말로 입력하기.
  • macOS의 경우, 시스템 설정에서 손쉬운 사용의 받아쓰기로 가서 기능을 활성화할 수 있음
  • 구체적일수록 좋고, 다른 엔지니어와 대화하듯 클로드 코드와 핑퐁 하면 된다. 

코드베이스 Q&A 기초

처음 클로드 코드를 사용하면 어디서 시작하는 것이 좋을까? 가장 먼저 추천하는 건 '코드 기반으로 Q&A를 던지는 것'으로, 코드베이스에 관해 질문하는 것이다. 다음은 프롬프트 예시이다. 

• `@RoutingController.py`가 어떻게 사용되고 있어? (How is `@RoutingController.py` used?)
• 어떻게 새로운 `@app/services/ValidationTemplateFactory`를 만들어야 할까? (How do I make a new `@app/services/ValidationTemplateFactory`?)
• `recoverFromException`은 왜 이리 많은 인자를 갖고 있는 거야? `git history`를 확인하고 대답해. (Why does recoverFromExeption take so many arguments? Look through `git history` to answer)
• 왜 `@src/login.ts` API에 `if/else`를 추가해서 이슈 #18363를 해결했지? (Why did we fix the issue #18363 by adding `if/else` in `@src/login.ts` API?)
• 새로운 `@api/ext/PreHoots.php` API를 어떤 버전에 릴리즈 했지? (In which version did we release the  new `@api/ext/PreHoots.php` API?)
• PR #9383을 보고 어떤 앱 버전이 영향을 받았는지 꼼꼼하게 검증해. (Look at PR #9383, then carefully verify which app versions were impacted)
• 지난주에 뭘 릴리스했지? (What did I ship last week?)

클로드 코드는 단순히 텍스트 검색으로만 답을 하지 않고, 보통 한 단계 더 깊이 들어가서 예시를 찾으려고 한다. 그래서  위키나 문서에서 찾을 수 있는 정보가 아닌, 더 깊은 대답을 줄 수 있다. 

 

다음은 클로드 코드를 처음 사용해 보는 사람에게 추천하는 팁이다. Tip1을 하다 보면 Tip2를 자연스레 경험하게 된다. 

• Tip 1 : 코드베이스 Q&A
• Tip 2 : 프롬프팅 하는 방법을 익히고, 클로드 코드가 어디까지 할 수 있는지(무슨 일을 할 수 있는지) 또는 어느 부분에서 추가적인 명령이 필요한지 이해하기 
  • practice prompting, and start to understand what Claude Code "gets" immediately vs. what needs more specific instructions

효율적으로 코드 수정하기 

이렇게 첫 클로드 코드 사용을 경험했다면, 이제는 코드 수정을 해 볼 차례다. 

도구를 활용하여 일을 처리하자 (Use tools to get things done)

클로드 코드 같은 에이전트 방식은 도구만 주면 일을 스스로 처리할 수 있다. 클로드 코드는 툴 셋이 많지 않다. 하지만 이러한 툴들을 잘 섞어 사용하기 때문에 강력하다. 빌트인 도구들은 파일 수정, bash 실행, 파일 검색 등이 있으며 이를 활용하여 코드를 탐색하고 브레인스토밍을 하고 마지막으로 수정한다. 그래서 클로드 코드에게 어떤 툴을 사용하라고 하는 것보다 어떤 작업을 해달라고 해야 한다. 이후에는 알아서 방법을 찾아내고 필요한 것을 잘 엮어낸다. 이러한 방식이 클로드 코드에게 자연스럽다. 

원하는 방식으로 도구를 사용하도록 클로드 코드를 설정하자 (Steer Claude Code to use tools your way)

클로드 코드가 코드를 작성하기 전에 먼저 아이디어를 내거나 계획을 세워달라고 해보자. "3,000줄짜리 거대한 기능을 구현해 줘"라고 하는 것보다 먼저 생각하게 해야 더 좋은 결과를 얻을 수 있다. 클로드 코드가 코드를 작성하기 전에 생각하게 하고, 계획을 세우도록 하고, 엔지니어는 그것을 확인하면 된다(approve before coding). 여기에는 딱히 plan mode나 특별한 도구가 필요하지 않다. "코드를 작성하기 전에 계획부터 세워줘"라고 요청만 하면 된다. 

다음은 예시 프롬프트이다.

• 이슈 #8732에 대한 수정안을 몇 가지 제안한 다음, 내가 선택한 수정안을 구현해 줘. (Propose a few fixes for issue #8732, then implement the one I pick)
• `@app/tests/signupTest.ts`에서 다루지 않은(커버되지 않은) 엣지 케이스를 발견하고, 이를 포함하도록 테스트를 수정해. 깊이 생각해. (Identify edge cases that are not covered in `@app/tests/signupTest.ts`, then update the tests to cover these. think hard)
• commit, push, pr
  • 클로드 코드가 알아서 커밋하고, 브랜치에 푸시하고, 브랜치를 만들어서 깃허브에 PR까지 한다. 
  • 코드랑 히스토리, git log도 스스로 확인하여 커밋 형식 따위를 파악한 뒤 올바른 방식으로 커밋하고 푸시한다. 
• 3개의 병렬 에이전트를 사용해서 `@services/aggregator/feed_service.cpp`를 정리할 방법에 관한 브레인스토밍을 진행해.  (Use 3 parallel agents to brainstorm ideas for how to clean up `@services/aggregator/feed_service.cpp`)

팀 도구 연결하기 (Plug in)

다음 단계는 클로드 코드에게 도구를 사용하는 방법을 알려주고, 작업에 맞게 워크플로우를 조정하는 것이다. 

• Tip 3 : 클로드에게 도구 알려주기
• Tip 4 : 작업(task)에 맞게 워크플로우를 조정하기(tailor)

클로드 코드를 팀에서 사용하는 도구에 연결(적용)하자. 도구는 보통 두 가지로 나뉜다.

1. 클로드 코드에게 사용하는 bash 툴 알려주기 (Tell Claude about your bash tools)
2. 클로드 코드에게 사용하는 MCP 툴 알려주기 (Tell Claude about your MCP tools)

하나는 bash 도구이다. 아래는 예시 프롬프트로, 효율적인 방식이다. 

Use CLI to check for error logs in the last training run. Use -h to check how to use it.

위는 CLI로 무언가를 해보라고 시키고, -h(--help)로 어떻게 사용하는 건지 알아내게 하는 프롬프트이다. 이를 자주 사용한다면, 해당 내용을 CLAUDE.md에 넣어두는 것을 추천한다. 그러면 세션이 바뀌어도 클로드 코드가 이 내용을 기억할 수 있다. 

 

또 다른 예시로는 MCP이다. 첫 줄이 클로드 명령어이고, 아래는 프롬프트이다. 

$ claude mcp add xxx_server -- node myserver
> Use the Xxx MCP server to check for the error logs in the last training run.

위처럼 MCP 도구를 추가하고 사용법을 알려주기만 하면, 클로드 코드는 그 도구를 바로 사용할 수 있다. 

자주 사용하는 워크플로우 (Common workflows)

아래 2, 3번은 클로드 코드가 자기 작업을 확인할 수 있는 경우로, 단위 테스트를 작성하거나 스크린 샷을 이후에는 반복하여 개선할 수 있다. 여기서 핵심은 클로드 코드에게 결과를 확인하고 피드백을 받을 수 있는 도구를 주는 것이다. 스스로 반복하게 하여, 훨씬 좋은 결과가 나올 수 있다. 

• Explore > plan > confirm > code > commit (코드 작성 전에 계획 세우기) 
  • 이슈 #983의 근본 원인을 파악한 후, 몇 가지 해결 방안을 제안해. 코딩하기 전에 접근 방식을 내가 선택할 수 있게 해 줘. `ultrathink` (Figure out the root cause for issue #983, then propose a few fixes. Let me choose an approach before you code. `ultrathink`)
• Write tests > commit > code > iterate > commit 
  • @utilis/markdown.ts에 대한 테스트를 작성하고 링크가 제대로 랜더링 되는지 확인해. (아직 링크 기능이 구현되지 않아서 테스트는 통과하지 않을 거야) 그러고 나서 커밋하고, 테스트가 통과되도록 코드를 수정해. (Write tests for @utilis/markdown.ts to make sure links render properly (note the tests won't pass yet, since links aren't yet implemented). Then commit. Then update the code to make the tests pass.)
• Write code > screenshot result > iterate
  • [mock.png]를 구현해. 그리고 Puppeteer를 사용해서 스크린 샷을 찍고, 목업과 똑같이 보일 때까지 반복해. (Implement [mock.png]. Then screenshot it with Puppeteer and iterate till it looks like the mock.)

컨텍스트 관리

클로드 코드에게 컨텍스트 주기 (Give Claude context)

맥락을 많이 전달할수록, 더 나은 결정을 내릴 수 있다(More context = Better performance). 그리고 클로드 코드에게 다양한 방법으로 시스템이나 과거 이력 등과 같은 맥락을 전달할 수 있다. 가장 간단한 방법은 CLAUDE.md이다. 

 

아래 CLAUDE.md 파일들은 매 세션마다 자동으로 클로드 코드가 읽어온다. 

• `/<enterprise root>/CLAUDE.md`          모든 프로젝트에 공유되는 파일 (회사 입장에서 관리할 때)
• `~/.claude/CLAUDE.md`                       모든 프로젝트에 공유되는 파일
• `project-root/`
  • `CLAUDE.md`                                 버전 관리 대상 O
  • `CLAUDE.local.md`                        버전 관리 대상 X

(단축키: #)

 

CLAUDE.md는 특별한 파일로, 프로젝트 루트 위치에 두는 것이 가장 쉬운 방법이다. 클로드 코드를 시작하는 디렉터리에 CLAUDE.md를 두면, 세션을 시작할 때마다 자동으로 컨텍스트에 읽힌다. 이는 사용자의 첫 입력에 CLAUDE.md가 포함되는 것과 동일하다. 중첩 디렉터리에 존재하는 CLAUDE.md 파일도 해당 디렉터리에서 작업할 때 자동으로 읽힌다. 

프로젝트 별 CLAUDE.md 말고도 로컬 전용인 CLAUDE.local.md를 생성할 수도 있다. 팀 프로젝트의 경우, CLAUDE.md를 한 번 작성하고 버전 관리로 팀 내에서 공유하여 같이 사용하도록 하고, 로컬 파일은 버전 관리 없이 개인용으로 사용하면 된다. 

 

CLAUDE.md에 들어가는 내용은 보통 작업하기 위해 알아야 하는 것들로 자주 사용하는 배치 명령이나 MCP 도구, 아키텍처와 관련된 결정, 중요 파일 등이 있다. 이 파일은 가능한 짧게 유지하는 것이 좋다. 길어질수록 많은 컨텍스트를 요구하고, 대부분 그렇게 유용하지 않다.

 

아래는 필요할 때마다 컨텍스트를 불러올 수 있는 방법이다.

• `~/.claude/commands/foo.md`              타이핑: `/user:foo`
• `project-root/`
  • `.claude/commands/foo.md`          타이핑: `/project:foo`
  • `a/`                                                 타이핑: `@a`
    • `commands/foo.md`               타이핑: `/project:a:foo`
    • `CLAUDE.md`                        필요시 가져옴
    • `foo.py`                                   타이핑: `@a/foo.py`

이 섹션의 핵심은 '클로드 코드에게 더 많은 컨텍스트를 제공하자'는 것이다. 

• Tip 5: 클로드 코드에게 더 많은 컨텍스트를 줄수록, 클로드 코드는 더 똑똑해진다. 
• Tip 6: 컨텍스트를 조정하는 데 시간을 할애해라(take time to tune context). '잘' 조정하면 성능이 크게 좋아진다. 다음의 것들을 고려하자.
  • 프롬프트 개선 도구를 사용해 보거나
  • 해당 컨텍스트가 누구를 위한 것인지
  • 자동으로 매번 불러올 건지 필요할 때만 불러올 건지
  • 팀과 공유할 건지 
  • 개인 취향에 관한 건지

권한, 메모리, MCP 서버를 팀과 공유하기

클로드와 관련된 모든 것을 계층 구조 식으로 불러올 수 있다. 

• [최상위] Enterprise policy → Global (just me) → Project (버전관리) → [최하위] Project (just me) 
  • 글로벌 설정(Global config)은 모든 프로젝트에 적용할 수도 있고, 엔터프라이즈 정책으로 관리할 수도 있다. 
  • 엔터프라이즈 정책은 사실상 글로벌 설정과 같기 때문에 팀 전체에 자동으로 적용된다. 

팀과 공유하기 (Share with your team)

Tip 7: CLAUDE.md 파일과 MCP 서버와 같이 팀이 사용하는 모든 것들을 설정해라. 한 번 설정해 두면, 모두와 공유하여 사용할 수 있다. (configure CLAUDE.md, MCP servers, permissions, and slash commands for your team, and check them into git)

 

	Enterprise policy (shared)	Global (just me)	Project (shared)	Project (just me)
Memory	/Library/Application Support/ClaudeCode/CLAUDE.md	~/.claude/CLAUDE.md	CLAUDE.md	CLAUDE.local.md
Slash commands	-	~/.claude/commands	.claude/commands/	-
Permissions	/Library/Application Support/ClaudeCode/policies.json	~/.claude/settings.json	.claude/settings.json	.claude/settings.loca.json
MCP servers	-	claude mcp	.mcp.json	claude mcp

예를 들어, 모든 직원이 공통으로 실행하는 bash 명령어나 다 같이 사용하는 테스트 명령이 있다고 하자. 이러한 명령어들은 엔터프라이즈 정책 파일에 넣어두면 된다. 이후 직원이 그 명령어를 실행하면 자동으로 승인된다.

이는 명령을 차단하는 용도로도 사용할 수도 있다. 절대 접속하면 안 되는 URL이 있다고 하자. 이 경우에도 설정에 추가하면 직원이 해당 URL을 임의로 덮어쓰거나 불러올 수 없다(fetch). 이는 사람들의 작업을 방해하지 않고, 코드베이스도 안전하게 지킬 수 있기 때문에 편리하다. 

MCP 서버도 마찬가지이다. MCP JSON 파일(.mcp.json)을 생성해 코드베이스에 넣어두자. 이후 코드베이스에서 누군가 ClaudeCode를 실행할 때마다 MCP 서버를 설치하라는 안내를 받게 되고, 팀과 공유할 수 있다. 

어디서부터 시작해야 할지 잘 모르겠다면, 공유 프로젝트 컨텍스트로 시작해 보는 것을 추천한다. 이것을 한 번 작성하고 팀원 모두와 공유하자. 그러면 누군가 조금만 작업해도 팀 전체가 혜택을 보게 되는 네트워크 효과 같은 것을 얻을 수 있다. 

 

클로드 코드에는 이러한 것을 관리하는 많은 빌트인 도구들이 있다. 예를 들어, `/memory` 명령어를 실행하면 다양한 메모리 파일들을 볼 수 있다. 엔터프라이즈 정책이나, 사용자 메모리, 프로젝트 CLAUDE.md, 하위 CLAUDE.md 등이 있을 수 있다. 이러한 파일을 보는 것뿐만 아니라, 특정 메모리 파일을 편집할 수도 있다. 무언가 기억시키기 위해 `#`을 입력하면 어느 메모리에 넣을지 선택할 수 있다. 

유용한 몇 가지 키 바인딩

다음은 일반적인 작업(common task)을 위한 키 조합이다.

• 편집 자동 승인(auto-accept) 모드 : `Shift+tab` 
  
  • bash 명령은 여전히 승인 필요 
  • 예를 들어, 클로드가 제대로 진행하고 있는 상황에서 단위 테스트나 반복해서 진행해야 할 때 자동 승인 모드를 사용하면 편리하다. 
• 메모리 생성 : `#` 
  • 클로드가 무언가 기억하도록 하고 싶을 때, `#`를 입력하고 기억할 내용을 넣으면 된다. 이후 자동으로 CLAUDE.md에 반영된다. (클로드가 툴을 옳은 방식으로 사용하게 하고 싶은 경우 등)
• bash 모드 진입 : `!`
  • 해당 기호를 타이핑하고 명령을 입력하면 bash 모드로 전환된다. 로컬에서 실행되고, 동시에 컨텍스트 창에도 들어가기 때문에 클로드가 다음 차례에 확인할 수 있다. 
  • 정확히 무엇을 해야 할지 알고 있거나 컨텍스트에 추가하고 싶은 명령이 있을 때, 오래 걸리는 명령어에 유용하다. 클로드가 명령과 출력까지 확인할 수 있다. 
• 컨텍스트에 파일/폴더 추가 : `@`
• 취소 : `Esc`
  • 클로드가 무엇을 하든 상관없이 `Esc`를 눌러도 문제없다. 세션이 망가지거나, 무언가 꼬이지도 않는다. 
• 히스토리로 돌아가기: `Ecs` 두 번
  • 세션이 끝나면, 클로드 코드를 `--resume` 명령어로 시작하면 해당 세션을 이어서 진행할 수 있다. `--continue`도 가능하다. 
• 상세 출력 : `ctrl+r`
  • 전체 출력을 확인할 수 있다. 이는 클로드 코드가 컨텍스트 창에서 보는 것과 같은 출력이다. 
• `/vibe` (이 명령어도 소개에 있었는데 설명을 안 하고 넘어갔다)

클로드 스크립팅 (Scripting Claude)

Claude Code SDK

클로드 코드에서 `-p` 플래그를 사용하면, 그게 바로 SDK이다. 이 SDK 위에 아무거나 자유롭게 만들 수 있다. 예를 들어, `claude -p` 명령어는 CLI SDK이다. 프롬프트나 허용할 도구, 특정 bash 명령어 등을 넘길 수 있다. JSON이나 스트리밍 JSON 등 원하는 형식도 지정할 수 있다. 앤트로픽은 이것을 CI에서 언제나 사용한다고 한다. 인시던트 대응이나 온갖 파이프라인에서 사용한다. 

이 SDK를 유닉스 유틸리티처럼 사용하면 된다. 파이핑(piping)을 예로 들면, `git status`를 실행하여 결과를 넘겨줄 수도 있고 JQ로 원하는 결과만 고를 수 있다. 

$ git status | claude -p "what are my changes?" \
	--output-format-json | jq '.result'

멀티 클로드 (Multi-claude)

• 별도의 터미널 창에서 여러 개의 체크아웃을 사용하기
  • 여러 터미널 탭을 열어서 여러 repo를 동시에 처리한다. 
• git worktree를 사용하여 단일 체크아웃 사용하기
  • 동일한 저장소를 여러 개 체크아웃해서 클로드로 병렬 처리하거나, git worktree를 사용해 격리할 수 있다. 
• SSH + TMUX
  • SSH 세션을 열어두고, 클라우드 세션으로 연결되는 tmux(terminal multilexer) 터널을 설정한다. 
• 깃허브 액션, 병렬 잡(job) 실행 

 

---

 

가이드는 여기까지다. 이후에는 Q&A(24분쯤부터)가 진행되었고 딱히 여기 글에는 옮기지 않았다.