터미널에서 작동하는 AI 코딩 툴 「Claude Code」를 실제로 직접 움직이며 사용할 수 있게 되기 위한 가이드입니다. 설치 및 계약 플랜에 대해서는 Claude의 계약과 Claude Code의 설치 절차에 정리해 두었으므로, 여기서는 도입 후의 실전적인 사용법에 집중하여 설명합니다.

• 가장 먼저 할 일
• 동작 모드 선택하기 (처음에 이해해야 할 안전 설정)
• 모델 선택하기
• 자주 사용하는 조작 (역참조)
• CLAUDE.md 작성 및 육성하기
• 계획을 세워 진행하기 (페이즈·스텝 단위)
• 반복되는 작업을 시스템화하기
• 컨텍스트 (Context)와 비용 관리하기
• 기존 프로젝트에서의 진행 방법
• GitHub와 연동하기
• 멀티 디바이스·플러그인 활용하기
• 코딩 이외의 업무에 사용하기
• 어려움이 생겼을 때의 체크리스트

설치와 로그인이 완료되었다면, 다음 흐름에 따라 첫걸음을 내딛는다.

• 프로젝트의 루트 디렉토리에서 claude를 실행한다
• /init을 실행하여 CLAUDE.md (프로젝트 설명서)의 초안을 만든다
• 간단한 지시를 하나 내려본다 (예: "README의 내용을 요약해줘")
• 종료할 때는 /exit를 입력하거나 터미널을 닫는다

Claude Code가 파일을 편집하거나 명령을 실행하기 전에, 어디까지 확인을 요청할지를 「모드」로 제어한다. Shift + Tab을 누르면 모드가 전환된다.

절차:

• 실행 직후에는 Manual 모드로 되어 있다
• 코드베이스를 조사한 뒤 진행하고 싶은 규모가 큰 변경은, Shift + Tab으로 Plan 모드로 전환한 뒤 의뢰한다 - Claude가 계획을 제시하면 내용을 확인하고, "승인하여 편집을 진행한다"를 선택한다
• 익숙해지면, 리뷰를 전제로 하는 작업은 Accept Edits 모드 상태로 진행하는 것이 효율적이다
• Bypass Permissions (--dangerously-skip-permissions)는 네트워크를 차단한 컨테이너 등 격리된 환경 이외에서는 사용하지 않는다

처음에 이 모드의 개념을 이해해 두면, "무슨 일이 일어날지 모르는 채 실행된다"는 불안감 없이 진행할 수 있다.

Claude Code에서는 용도에 따라 여러 모델을 구분하여 사용할 수 있다. 위치 선정의 기준은 다음과 같다 (모델명이나 라인업은 향후 변경될 수 있으므로, 최신 정보는 claude.com에서 확인하는 것이 좋다).

절차:

• 모델을 전환하고 싶다 → /model을 실행하여 목록에서 선택한다 (기본값으로 저장도 가능) - 추론의 깊이만 바꾸고 싶다 (모델은 바꾸지 않음) → /effort를 실행한다 - 출력을 빠르게 하고 싶다 (상위 모델 이용 시) → /fast로 Fast mode를 전환한다

선택 기준: 평소 작업은 표준 모델부터 시작한다. 설계 판단이나 복잡한 자율 작업이 필요해지면 상위 모델로 전환한다. 가장 어려운 승부수를 던져야 하는 태스크에는 최상위 모델을 사용한다. 대량의 반복 작업이나 서브 에이전트(Sub-agent)에게 맡기는 가벼운 작업은 경량 모델로 비용을 절감한다.

CLAUDE.md는 Claude가 해당 프로젝트를 이해하기 위한 '색인(Index)'이다. 상세한 검토 경위까지 모두 적으면 파일이 비대해져 컨텍스트를 압박하므로, 다음과 같이 3단계로 키워나간다.

• 만들기: 프로젝트 루트에서 /init을 실행하여 틀을 만든다.
• 쓰기: 프로젝트 개요, 자주 사용하는 작업, 디렉토리 구성, 명명 규칙 등 '매번 다시 설명하고 싶지 않은 전제 지식'을 적는다.
• 분할하기: CLAUDE.md가 커지면 다음과 같이 분할한다.
  • 서브 디렉토리별 CLAUDE.md (해당 디렉토리의 파일을 다룰 때만 읽힘)
  • .claude/rules/ 하위에 파일 패턴 한정 규칙을 배치

.claude/
├── CLAUDE.md
└── rules/
...

.claude/rules/ 내의 파일은 frontmatter의 paths로 적용 범위를 좁힐 수 있다.

---
paths: src/**/*.{ts,tsx}
---
...

'CLAUDE.md에 전부 적지 않고 docs/ 하위에 Markdown 문서를 두는 방식' 자체는 자주 보이는 방법이지만, docs/라는 이름 자체는 Claude Code 고유의 기능이 아닌 일반적인 폴더일 뿐이다. Claude Code는 '필요할 때 프로젝트 파일을 읽으러 가기' 때문에, docs/ 하위에 무언가 있고 README 등에서 참조되고 있다면 CLAUDE.md에 적지 않아도 자연스럽게 읽으러 간다.

그 외에 공식에서 제공하는 'CLAUDE.md를 무겁게 만들지 않으면서 상세 내용을 분리하는' 메커니즘은 다음 두 가지다.

사용 구분 결론:

• 항상 Claude가 전제로 알고 있어야 하는 내용 $\rightarrow$ CLAUDE.md 본체에 직접 적거나 @docs/xxx.md로 임포트
• 특정 파일 종류나 디렉토리에서만 필요한 규칙 $\rightarrow$ .claude/rules/ (paths 지정)
• 일회성이 아니라 반복되는 '절차' $\rightarrow$ Skills화 (7장 참조)
• 단순 참고 자료나 상세 문서 (매번 읽게 할 필요는 없음) $\rightarrow$ docs/와 같은 일반 폴더에 두기만 하면 된다. Claude는 필요할 때 스스로 읽으러 간다. CLAUDE.md 측에는 "자세한 내용은 docs/xxx.md"

라고 한 마디만 적어두면 충분하다.

두 방식 모두 문제없으며, "매번 읽게 하고 싶은 색인 (CLAUDE.md)"과 "필요할 때 읽으러 가는 상세 내용 (폴더 하위의 파일)"을 분리한다는 것이 본질이다. 폴더명은 docs/에 국한되지 않고, specs/ (사양), notes/ (검토 경위), reports/ (진척)와 같이 목적별로 나누어도 상관없다.

"결국 무엇을 어떻게 나누어야 하는가"를 고민될 때는 다음 형식을 그대로 사용하면 좋다. 실무에서 바로 사용하기 쉬운 최소 구성으로 만들었다.

docs/
├── design/ # 설계 문서 (왜 그렇게 만들었는지, 구성도 등)
├── how-to/ # 절차서 (셋업 절차, 운용 절차 등)
...

설계 문서를 작성하게 하는 예시:

로그인 기능의 설계를 docs/design/2026-07-22_로그인설계.md에 정리해 주세요.
어떤 선택지를 검토했고, 왜 지금의 구성으로 결정했는지 알 수 있도록 작성해 주세요.

절차서를 작성하게 하는 예시:

이번 배포 절차를 docs/how-to/배포절차.md에 작성해 주세요.
다음에 다른 사람이 읽어도 그대로 실행할 수 있도록 번호가 매겨진 절차로 만들어 주세요.

CLAUDE.md에는 "자세한 설계는 docs/design/을, 절차는 docs/how-to/를 참조"라고 한 마디만 적어두면, Claude는 필요할 때 스스로 해당 폴더를 읽으러 간다.

Claude Code는 실행 중인 디렉토리 하위의 파일을 필요에 따라 스스로 읽으러 간다. 디렉토리 하위에 존재하지 않는 것이라도, URL을 전달하면 해당 페이지를 가져온다. 이 두 가지 성질을 이해해 두면, 무언가를 의뢰하기 전 "참고했으면 하는 정보의 전달 방식"에서 고민하지 않게 된다.

전달 방식은 크게 두 가지다.

의뢰 예시 (파일을 참조하게 하는 경우):

docs/refs/API사양서.pdf를 참고하여 이 기능을 구현해 주세요.

의뢰 예시 (URL을 참조하게 하는 경우):

https://example.com/spec 를 보고 그 내용에 따라 구현해 주세요.

일시적인 질문이라면 프롬프트에 직접 붙여넣는 것으로 충분하지만, 여러 번 참조할 자료는 docs/refs/에 두면 다음부터는 "그 파일을 봐"라고 지정하기만 하면 되며, 참고 정보 자체가 자산으로 남는다.

저장 예시:

• docs/refs/ — 사용 중인 프로그래밍 언어·프레임워크의 공식 매뉴얼이나 레퍼런스 PDF 등을 저장한다.
• docs/design/ (또는 docs/inspiration/ 등) — 디자인 참고용 또는 영향을 받은 이미지나 스크린샷을 저장한다.

이처럼 자료 종류별로 폴더를 나누어 두면, "docs/design/의 이미지를 참고해서 이 화면의 UI를 생각해 봐"와 같이 폴더명만 지정하여 참조시킬 수 있다.

CLAUDE.md의 내용은 "현재 작업과 관련이 있다고 판단될 때만" 중시된다. 따라서 추상적인 마음가짐이 아니라, "〇〇한 후에는 반드시 △△한다"와 같이 행동과 세트로 작성하면 전달하기 쉽다.

여러 프로젝트나 여러 안건을 하나의 워크스페이스에서 횡단 관리하고 싶다면, CLAUDE.md에 다음과 같은 기교를 더하면 좋다.

• 프로젝트 목록·회의 목록·안건 목록을 각각 테이블화하여 상태와 폴더 경로를 세트로 관리한다.
• 변경 이력을 쌓아서 언제 무엇을 변경했는지 추적할 수 있게 한다.
• 정형 작업은 .claude/skills/에 Agent Skills로 분리하여 CLAUDE.md 본체가 비대해지지 않게 한다.

많은 사람이 가장 곤란해하는 점은 "결국 무엇을 어디까지 스스로 결정하고, 어디서부터 Claude에게 맡겨도 되는지 모르겠다"는 점이다. **"갑자기 구현하게 하지 말고, 먼저 계획을 세우게 한 뒤에 진행한다"**라는 패턴만 기억해 두면 망설임 없이 진행할 수 있다.

먼저 파일에 남기는 방법부터 시작하는 것이 좋다. Claude Code의 조작 화면을 보지 않더라도, 파일만 열면 "지금 어디까지 끝났는지"를 알 수 있다.

구현을 시키기 전에, 먼저 계획만 세우게 한다.

〇〇 기능의 구현 계획을 페이즈·스텝 단위로 docs/plans/2026-07-22_〇〇계획.md에 체크박스를 포함하여 작성해 주세요. 구현은 시작하지 말고, 계획 작성만 부탁드립니다.

완성된 계획 내용을 확인한다 (이 시점에서는 아무것도 구현되지 않았다).

문제가 없다면, 계획에 따라 진행하도록 요청한다.

docs/plans/2026-07-22_〇〇계획.md의 계획에 따라 페이즈 1부터 진행해 주세요. 하나의 스텝이 끝날 때마다 체크박스에 체크를 해주세요.

Claude는 각 스텝이 끝날 때마다 계획서의 해당 부분을

- [ ]

에서 - [x]

로 바꿔 나간다.

세션을 종료하고 훗날 재개할 때는 계획서를 지정하기만 하면 된다.

docs/plans/2026-07-22_〇〇계획.md를 보고, 끝나지 않은 스텝부터 이어서 진행해 주세요.

# 〇〇 기능 구현 계획
## 페이즈 1: 조사
- [ ] 기존 코드의 해당 부분을 확인한다
...

계획서가 작성된 후, 각 페이즈의 구현에 들어가기 전에 Shift + Tab으로 Plan 모드로 전환하면, "해당 페이즈에서 구체적으로 무엇을 할지"를 한 단계 더 세밀하게 확인한 뒤 진행할 수 있다. 큰 계획(파일) 속의 작은 한 수(Plan 모드)라는 조합으로 생각하면 좋다.

단 한 번의 의뢰는 채팅으로 끝낼 수 있지만, "반복적으로 같은 형태로 요청하는 작업"은 시스템화하면 효율이 올라간다.

• 절차가 있는 경우 → Agent Skills

• 팀에서 재사용·공유하고 싶은 경우 → 플러그인화

• 전문적인 역할(Role) 분리 → 서브 에이전트

• 반드시 자동 실행하고 싶은 처리 → Hooks

• 외부 서비스 연동 → MCP 서버

.claude/skills/회의록 정리/와 같은 폴더를 만든다.

그 안에 SKILL.md를 만들고, 서두에 다음과 같이 작성한다.

--- name: 회의록 정리 description: 회의 녹취록을 정형 포맷의 회의록으로 정리한다 --- (여기에 구체적인 절차를 작성한다)

Claude Code를 재시작하거나 새로운 세션에서 /회의록 정리라고 입력하여 동작을 확인한다.

Claude Code는 토큰 소비량에 따라 과금된다 (구독 플랜의 경우 플랜 내 사용량으로 소비). 조직 도입 시의 비용 체감은 실제 이용 실태에 따라 크게 변동되므로, 우선 /usage로 수시로 확인하며 실태를 파악하는 것이 좋다.

• 단순한 작업은 표준 모델, 복잡한 설계 판단 시에만 상위 모델로 전환한다 (/model)
• 사용하지 않는 MCP 서버는 /mcp로 비활성화한다
• CLAUDE.md는 200행 정도를 기준으로 하며, 빈도가 낮은 절차는 Skills로 넘긴다
• 로그 출력이나 테스트 결과 등 대량의 텍스트는 Hooks를 통해 필요한 부분만 추출한 뒤 전달한다

• 구현 전에 먼저 조사 전용 서브 에이전트 (Explore 등)에게 "〇〇의 구현 위치를 조사해줘"라고 의뢰한다

• 조사 결과의 요약만 받고, 본체의 대화에 로그나 대량의 코드를 흘려넣지 않는다

• 조사 결과를 바탕으로 Plan 모드 (Shift + Tab)에서 구현 방침을 확인한다

• 방침에 합의하면 Accept Edits 모드 등으로 전환하여 구현을 진행한다

• 심볼 (Symbol) 정의나 코드 참조를 정확하게 추적하고 싶다면, LSP (Language Server Protocol) 대응 플러그인을 도입하면 grep에만 의존하는 것보다 정확하게 구조를 파악할 수 있다

• 불확실성 낮추기: 태스크를 적절한 입도 (Granularity)로 분할하고, 무관한 화제로 컨텍스트를 섞지 않는다

• 제어 가능하게 만들기: Lint/Formatter/테스트를 Hooks로 자동 실행시키고, 위험한 조작은 허용 규칙으로 방지한다

• 모듈화 및 정형화하기: 의존성이 적고 테스트 가능한 (Testable) 코드일수록 정밀도가 올라간다. 정형 작업은 Skills화한다

• 가독성 높이기: /config에서 출력 스타일을 Explanatory 계열로 설정하면 "왜 그렇게 했는지"를 설명해 준다

brew install gh # 설치
gh auth login # GitHub 계정 연동

• 리포지토리 관리자 권한으로, Claude Code 터미널에서 /install-github-app을 실행한다
• 안내에 따라 GitHub App을 설치한다 (Contents / Issues / Pull requests에 대한 읽기/쓰기 권한을 허용)
• 워크플로 (Workflow) 파일 (.github/workflows/)과 API 키 (리포지토리의 Secrets) 설정까지 대화형으로 진행한다
• 설정 후, PR이나 Issue의 코멘트에서 @claude라고 멘션하여 동작을 확인한다

@claude 이 Issue의 내용을 바탕으로 구현해 주세요
@claude 이 엔드포인트의 인증은 어떻게 구현해야 합니까
@claude 사용자 대시보드의 TypeError를 수정해 주세요

자동 리뷰를 항상 실행하고 싶다면, PR 생성/갱신 시 발화하는 워크플로를 추가하고, prompt에 Skill 호출 (예: /code-review:code-review)을 전달하도록 설정한다.

• 워크플로의 claude_args에 --max-turns를 지정하여 폭주를 방지한다
• API 이용료와 GitHub Actions 실행 시간 (분 단위 과금)이 모두 발생한다는 점에 주의한다

개인 및 프로젝트 한정 설정은 .claude/

하위 디렉토리에 두는 것만으로도 충분하지만, 팀이나 여러 프로젝트에서 동일한 Skills, 서브 에이전트 (Sub-agents), Hooks를 재사용하고 싶다면 플러그인 (Plugin)화 한다.

claude plugin init <name>

으로 템플릿을 생성한다 -
skills/

agents/

hooks/

등에 내용을 추가한다 -
/plugin marketplace add <repository>

으로 마켓플레이스에 등록하고, /plugin install

으로 배포한다

Claude Code는 "절차를 언어화할 수 있는 작업"이라면, 코딩 이외의 업무에도 그대로 사용할 수 있다.

• 반복하고 있는 정형화된 작업을 하나 선택한다 (회의록 정리, 보고서 리뷰, 요구사항 정의 등)
• 해당 작업의 절차를 말로 표현하여
  .claude/skills/[이름]/SKILL.md

에 작성한다 - 실제로 사용하면서 절차의 누락이나 오류를 수정해 나간다

비엔지니어링 (Non-engineering) 정형 업무라도, 다음과 같은 Skills를 준비해 두면 일상적인 작업을 패턴화할 수 있다.

코드를 작성하는 일이 아니더라도, 절차를 말로 표현할 수 있는 작업이라면 이 장의 사고방식을 그대로 적용할 수 있다.

• 어떤 일이 일어날지 불안하다 → Shift + Tab으로 Manual 모드인 상태로 진행한다
• 동작이 이상하거나 방향성이 어긋났다 → Esc를 2번 누르거나 /rewind를 사용한다
• 반응이 느리거나 컨텍스트 (Context)가 무겁다 → /compact 또는 /clear를 사용한다
• 지금 무엇이 일어나고 있는지 알고 싶다 → /context (컨텍스트) / /usage (비용)를 사용한다
• 설정이 이상하다 → /doctor를 사용한다
• 사용법을 모르는 명령어가 있다 → /help를 사용한다

더 자세한 도입 절차는 Claude의 계약 및 Claude Code의 설치 절차도 참조해 주세요.

원문 기사 (자사 사이트): https://www.bitz.co.jp/notebook/claude-code-usage-guide.html