요즘 매일 블로그 정리를 Claude Code/Claude와 같이 하다 보니 정작 이 도구들을 상황에 맞게 제대로 쓰고 있는지 궁금해졌다. Claude 아카데미 교육 자료를 보면서 기능별로 상황에 맞는 사용법을 정리해봤다. 개발 쪽(Claude Code)과 일반 업무 쪽(Claude.ai)을 나눠서 실제로 뭘 하려고 할 때 어떤 기능을 꺼내야 하는지 위주로 적는다.
Claude Code 설치부터 첫 대화까지
Claude Code는 터미널, IDE(VS Code/JetBrains), 데스크톱 앱, 웹(claude.ai/code) 중 어디서든 쓸 수 있다. 새 기능은 항상 터미널에 가장 먼저 나오기 때문에, 최신 상태를 유지하고 싶으면 터미널이 제일 유리하고, 평소 쓰던 에디터에 붙여서 쓰고 싶으면 IDE 통합, 다른 작업을 하면서 백그라운드로 돌리고 싶으면 데스크톱, GitHub 저장소를 원격으로 다루거나 여러 세션을 동시에 돌리고 싶으면 웹이 낫다.
프롬프트를 입력할 때는 파일 변경을 자동으로 승인할지(Auto Accept), 매번 확인받을지를 Shift+Tab으로 전환할 수 있다. 이 메뉴 안에 Plan Mode도 있는데, 이건 파일을 읽기만 하고 편집은 하지 않은 채로 구현 방법을 조사해서 계획만 돌려준다. 복잡한 기능을 구현하거나 안전하게 코드 리뷰를 하고 싶을 때 특히 유용하다.
탐색 → 계획 → 코드 작성 → 커밋
Claude Code에서 딱 하나만 기억해야 한다면 이 흐름이다.
탐색(코드베이스 파악) → 계획(Plan Mode로 실행 계획 수립) → 코드 작성(승인 후 구현) → 커밋(리뷰 후 푸시)이 순서를 생략하고 곧바로 코드를 짜는 것부터 시작하면 나중에 수정할 일이 더 많아진다는 게 요지다. Plan Mode에서는 아직 코드가 하나도 작성되지 않은 상태라 방향을 수정하기 가장 좋은 시점이고 계획이 만족스러우면 승인해서 실제 구현으로 넘어가면 된다. 커밋 전에는 서브에이전트로 코드 리뷰를 한 번 돌리고 Claude에게 커밋 메시지까지 맡기는 흐름을 권장하고 있었다.
컨텍스트는 유한한 작업 메모리다
Claude가 읽는 파일, 실행하는 명령, 주고받는 메시지가 전부 컨텍스트 윈도우를 채운다. 한도에 가까워지면 자동으로 압축(compaction)되는데 이 과정에서 예전 대화의 세부 사항이 날아갈 수 있다.
- 같은 기능을 계속 작업 중인데 컨텍스트가 부족할 때 →
/compact로 수동 압축(맥락은 유지한 채 공간만 확보) - 완전히 새 기능을 시작할 때 →
/clear로 이전 대화 기억을 완전히 비움(이전 작업이 새 작업에 편향을 주지 않도록) - 다른 세션에서도 계속 기억해야 할 내용 → CLAUDE.md에 저장
또 프롬프트를 짧게 쓰는 게 오히려 장기적으로 더 많은 컨텍스트를 잡아먹는다. 지시가 불명확하면 Claude가 코드베이스를 더 많이 뒤지면서 스스로 알아내야 하기 때문이다. 안 쓰는 MCP 서버는 꺼두고 반복되는 절차는 스킬로 옮기는 것도 컨텍스트를 아끼는 방법이라는 점도 눈에 띄었다.
CLAUDE.md — 프로젝트의 온보딩 스크립트
CLAUDE.md 파일이 없으면 Claude Code는 세션을 열 때마다 코드베이스를 처음부터 다시 탐색해야 한다. CLAUDE.md는 프로젝트 루트에 두는 마크다운 파일로 세션 시작 시 자동으로 읽힌다. /init 명령으로 코드베이스 기반 초안을 만들 수 있고 여기에 명령어/코드 스타일/디렉터리 구조 같은 걸 적어두면 매번 같은 설명을 반복할 필요가 없다.
계층 구조도 있는데 프로젝트 루트의 CLAUDE.md는 팀 전체가 공유하고 설정 폴더의 사용자 수준 CLAUDE.md는 나만을 위한 개인 선호(코드 주석 스타일 등)를 담는다. 실전 팁으로는 처음엔 CLAUDE.md 없이 시작해서 Claude를 계속 고쳐야 하는 지점이 어딘지 확인한 다음 그 부분만 채워 넣으라는 조언이 있었다 — (파일을 간결하게 유지하기 위해서)
컨텍스트 윈도우를 나누는 서브에이전트
서브에이전트는 각자 독립된 컨텍스트 윈도우를 가지고 작업한 뒤 메인 스레드에는 요약만 돌려준다. 과정은 필요 없고 결과만 필요한 조사 작업에 특히 유용하다. 서브에이전트 없이 직접 하면 15개 파일을 읽고 여러 번 검색해야 할 일도 서브에이전트에게 맡기면 메인 컨텍스트는 깨끗하게 유지한 채 답만 받을 수 있다. 대신 서브에이전트가 어떻게 그 결론에 도달했는지에 대한 가시성은 잃는다는 트레이드오프가 있다.
스킬 — 반복 설명을 없애는 방법
같은 코딩 표준, 같은 PR 리뷰 형식, 같은 커밋 메시지 스타일을 매번 설명하고 있다면 스킬로 만들 차례다. 스킬은 SKILL.md 하나로 구성되고 필요해지기 전까지는 이름과 설명만 컨텍스트에 로드되기 때문에 컨텍스트 비용이 거의 들지 않는다. 개인 스킬(~/.claude/skills)은 모든 프로젝트를 따라다니고 프로젝트 스킬(저장소 안 .claude/skills)은 그 저장소를 쓰는 모두가 자동으로 받는다.
CLAUDE.md와 차이는 CLAUDE.md는 모든 대화에 항상 로드되는 반면 스킬은 요청과 일치할 때만 필요에 따라 로드된다는 점이다. 디버깅 중에는 PR 리뷰 체크리스트가 컨텍스트에 있을 필요가 없는데 스킬이면 실제로 리뷰를 요청할 때만 로드된다.
MCP — 외부 도구/데이터에 연결하기
MCP(Model Context Protocol)는 Claude Code를 데이터베이스나 프로젝트 관리 툴 같은 외부 소스에 연결하는 개방형 표준이다. claude mcp add로 추가하고, /mcp로 연결 상태를 확인·관리한다. 범위는 local(나 혼자, 현재 프로젝트만) / user(나, 모든 프로젝트) / project(팀 전체, .mcp.json으로 버전 관리) 세 가지로 나뉜다.
주의할 점은 MCP 서버는 쓰지 않을 때도 도구 정의 자체가 컨텍스트 윈도우를 차지한다는 것이다. 그래서 적극적으로 안 쓰는 서버는 비활성화하는 게 좋고 GitHub의 gh처럼 CLI가 있는 도구는 CLI를 쓰는 게 컨텍스트 면에서 더 효율적이라고 한다.
Hooks — 규칙을 가끔이 아니라 항상으로
CLAUDE.md에 적어두면 대부분은 지켜지지만 가끔 빠뜨릴 수 있다. Hooks는 이 차이를 없앤다 — 조건에 맞으면 예외 없이 매번 실행된다. 상황별로 쓰는 이벤트가 다르다.
- 파일 편집 후 자동 포맷팅/린트 → PostToolUse
- 위험한 작업(main 브랜치 커밋, 프로덕션 설정 수정 등) 차단 → PreToolUse (종료 코드 2로 차단, 0은 통과)
- Claude가 끝냈다고 판단해도 조건이 안 맞으면 계속 시키기 → Stop
- 압축 후에도 작업 맥락을 잃지 않게 하기 → SessionStart(compact 매처)
PreToolUse는 단순히 막는 것 외에도 updatedInput으로 호출 자체를 다시 써서 넘길 수도 있다. 예를 들어 명령어에 포함된 비밀 키를 자리표시자로 바꿔치기하면서도 명령은 그대로 실행되게 만드는 식이다. 차단이 아니라 안전하게 걸러서 통과시키는 방식이다.
코드 리뷰는 diff부터
Claude가 만든 요약만 믿지 말고 실제 diff를 직접 읽는 게 첫 번째 원칙이었다. /code-review로 깨끗한 컨텍스트에서 두 번째 의견을 구하고 각 발견 사항은 지금 수정 / 이유 묻기 / 그대로 두기 중 하나로 처리한다. 같은 문제가 계속 지적된다면 그걸 CLAUDE.md에 규칙으로 적어두는 게 다음 세션부터 반복을 줄이는 방법이라는 조언도 있었다.
감독 없이 돌아가는 실행(auto 모드, 무인 파이프라인)일수록 검증은 더 엄격해야 한다는 게 핵심이다: diff를 직접 읽고 테스트를 부탁이 아니라 stop hook 같은 게이트로 만들고, 새 세션에서 아무 배경지식 없는 상태로 다시 검토(두 번째 의견)를 받는 식이다.
자동화, 어디까지 올릴까
반복 작업을 자동화하려 할 때 선택지가 네 가지 있는데 필요한 통제 수준에 따라 고르면 된다.
루틴(클라우드 저장 프롬프트) → 헤드리스 모드(-p, 내 파이프라인 필요) → --bare(CI용 결정론적 실행) → Agent SDK(내 제품 안에 내장)- 매일 아침 의존성 감사, PR 들어올 때 자동 분류처럼 반복되는 트리거 + 같은 프롬프트 → 루틴. 인프라도 Anthropic 것이라 내가 유지보수할 서버가 없음.
- 내 파이프라인에서 스크립트로 결과를 가공해야 할 때 → 헤드리스 모드(
-p). 다만 이 모드는 훅/스킬/MCP/CLAUDE.md를 자동으로 안 읽으니 내가 명시적으로 허용한 것만 쓰임. - CI에서 실행마다 똑같은 결과가 보장돼야 할 때 → --bare
- 내 제품 자체에 Claude Code를 내장해야 할 때 → Agent SDK
PR 리뷰, 관리형 VS 직접
- PR이 열릴 때마다 자동으로 인라인 코멘트만 받고 싶다 → Code Review (Claude GitHub 앱, Anthropic 호스팅). PR을 승인/차단하지는 않고 발견 사항만 게시한다. 로컬에서
/code-review --fix로 적용은 내가 한다. - 리뷰를 넘어서 댓글에서 바로 구현까지 하거나 예약 보고서를 돌리고 싶다 → GitHub Action (
anthropics/claude-code-action@v1)./install-github-app으로 설정하고,claude_args에서--max-turns같은 세부 조정을 한다.
플러그인 — 세팅을 패키징해서 공유하기
잘 만든 .claude 디렉터리(스킬, 서브에이전트, 훅, MCP 설정)를 팀원들에게 일일이 복사해서 붙여넣게 하는 대신 플러그인으로 묶어서 배포할 수 있다. /plugin marketplace add로 팀 마켓플레이스를 추가해두면 이후 설치가 그곳을 통해 해결된다.
여기서 제일 신경 써야 할 부분은 설치 전에 먼저 읽어야 한다는 것이었다. 플러그인은 내 권한으로 내 기기에서 코드를 실행하고 훅은 일치하는 모든 도구 호출에서 실행된다. 스킬 때문에 설치했더라도 그 플러그인의 PreToolUse나 Stop 훅까지 같이 딸려온다는 뜻으로 Anthropic이 서드파티 플러그인 내부를 다 통제하지는 않기 때문에 신뢰할 수 있는 출처인지 확인하고 실제로 뭘 하는 플러그인인지 살펴본 뒤 설치하는 게 맞다.
Claude.ai — 데스크톱에서의 세 가지 작업 형태
Claude Code가 개발자를 위한 것이라면 Claude.ai 쪽은 일반 업무를 세 가지 형태로 나눠서 본다.
- Chat — 주고받으며 작업하기: 질문 하나, 브레인스토밍, 초안 편집처럼 매 턴의 판단이 핵심이고 결과물이 한 번에 안 나오는 경우. 즉흥적인 질문에 적합하다.
- Cowork — 작업 맡기기: 완성된 결과물, 여러 도구에 걸친 작업, 일정에 따라 반복 실행되는 작업. 로컬 폴더 접근, 예약 작업, 서브에이전트, 브라우저/컴퓨터 사용까지 지원한다.
- Code 탭 — 소프트웨어 구축: 코드베이스에서 직접 읽고 쓰고 테스트하는, 사실상 Claude Code를 데스크톱 안에서 쓰는 것과 같다.
지금 하려는 일의 성격을 먼저 파악하면 탭은 자연스럽게 정해진다.
프로젝트 — 지식을 저장하는 곳
프로젝트는 관련 문서를 업로드해두고 프로젝트 지침을 설정해서 그 프로젝트 안의 모든 대화에 일관되게 적용되도록 하는 공간이다. 권한은 볼 수 있음/편집할 수 있음/생성자 세 단계로 나뉘고 정보가 많아지면 자동으로 RAG 모드로 전환돼서 컨텍스트 한도를 넘지 않도록 처리된다.
아티팩트 — 결과물이 머무는 곳
아티팩트는 문서/프레젠테이션/디자인/대시보드처럼 한 번 읽고 끝나는 게 아니라 계속 편집하거나 공유하고 싶은 것을 만들 때 쓴다. 유료 플랜에서는 대화와 별개로 아티팩트 탭에 저장되어서 나중에 다시 열어 편집할 수 있다. 다운로드 파일 생성(.docx, .xlsx, .pptx)과는 다른데 아티팩트는 Claude 안에서 바로 열리고 업데이트되며 링크로 공유되는 반면 파일 생성은 다운로드해서 다른 앱에서 여는 용도다. 준비가 되면 아티팩트도 내보내기를 통해 파일로 전환할 수 있다.
스킬과 프로젝트, 뭐가 다른지
프로젝트는 지식(무엇을)을 저장하고, 스킬은 프로세스(어떻게)를 저장한다. 프로젝트는 참고 자료/회의록/리서치 문서를 담아두는 지식 허브고 스킬은 반복 가능한 워크플로우를 인코딩한다. 둘은 서로 참조할 수도 있다.
커넥터 — 실제 데이터에 접근하기
커넥터는 Google Drive, Slack, Notion 같은 서비스에 Claude를 연결해서 실제 정보를 읽고(권한에 따라) 작업까지 하게 해준다. 웹 커넥터(클라우드 서비스)와 데스크톱 확장 프로그램(로컬 파일/네이티브 앱)으로 나뉘고 claude.ai/directory에서 찾아 연결할 수 있다. 중요한 원칙은 Claude는 내가 보는 것만 본다는 것 — 업무 이메일을 연결해도 내 받은 편지함만 접근 가능하고 남의 것은 볼 수 없다.
Enterprise Search / 리서치, 언제 쓸까
- 회사 내부 정책, 지난주 회의 결정, 사내 문서/Slack/이메일을 통합해서 찾아야 할 때 → Enterprise Search
- 경쟁사 비교, 시장 분석처럼 여러 출처를 종합한 포괄적 보고서가 필요할 때 → 리서치(웹 검색 활성화 필요, 몇 분 이상 소요)
- 오늘 주가처럼 빠르고 구체적인 사실 하나만 필요할 때 → 그냥 웹 검색
- 외부 정보 없이 수학/디버깅/논리적 분석 같은 깊은 추론이 필요할 때 → 확장 사고
📍 참고 자료: Anthropic Claude 아카데미의 「Claude Code 101」, 「Claude Code 실전 활용」, 「Claude.ai 101」 교육 자료를 참고해 정리함
