개요

본 문서는 Hyperithm 테크팀 IA (Intelligent Automation) 팀이, 사내 개발인력 생산성 강화를 위해 작성한 Claude Code 사용에 대한 종합적인 가이드입니다.
작성 시점은 2025년 6월 4일이며 작성자는 Hyperithm 엔지니어 이한결 님입니다.
회사와 팀에 대한 소개는 다음에서 볼 수 있습니다.
- 홈페이지 - https://www.hyperithm.com
- 채용 - https://hyperithm.career.greetinghr.com
- CTO 양준하 https://www.linkedin.com/in/junha-y-5923061b6
  - 커피챗 신청 환영입니다 - junha@hyperithm.com

설치

CLI 설치

# Claude Code CLI 설치
npm install -g @anthropic-ai/claude-code
claude --version   # v1.x.x 출력 확인

계정 생성 및 결제

사용 유형

플랜	월 요금	주요 대상	특징
Claude Max	$200	개인·소규모 팀	Code 포함 모든 채팅·업로드 기능 무제한 - pro 대비 20x 사용량
Claude Max	$100	개인·소규모 팀	Code 포함 모든 채팅·업로드 기능 무제한 - pro 대비 5x 사용량
Console(토큰 과금)	사용량 기반	엔터프라이즈	GPT 계열과 유사한 토큰식 요금, 팀·역할 관리

결제 과정

anthropic.com/claude-code → Try Claude 클릭
이메일·비밀번호 입력 → 계정 생성
https://claude.ai/upgrade/max 사이트에서 플랜 업그레이드 (100달러 요금 선택)
Payment 단계에서 카드 입력
결제 승인 후 같은 계정으로 CLI claude login 가능

첫 실행, OAuth 인증

cd ~/my-project
claude login

브라우저가 열리면 Anthropic 권한 요청 → Authorize
터미널에 Logged in as you@hyperithm.com 메시지가 보이면 성공
(추가적으로) /status 명령어 실행후 : 아래와 같이 login method Claude Max Account 라고 표기

IDE 연동 (중요)

설치

ide내 터미널 창에서 claude 입력 → 자동으로 extension 이 설치됨

extension 이 설치된 이후에는 오른쪽 상단, 클로드 아이콘을 통해 실행 가능

추가 설정

ide 관련 추가 설정
- 코드 수정 diff view를 windsurf 뷰어 내에서 보기 (미 설정시 terminal diff view만 보임)
- /config → auto 로 설정
- diff view 설정 완료 예시

핵심 CLI 명령, 옵션

자동으로 허용 옵션

shift-tab시 자동으로 다음 스텝을 허용합니다. (whitelist 되지 않은 명령어 수행시 확인 절차 있음)
- claude /allowed-tools 에서 화이트 리스트 설정
claude --dangerously-skip-permissions 로 실행
- 완전 자동화 (권한 확인 생략)
- dev container를 사용해 격리된 환경에서 이용하는 것을 권장
  - https://github.com/anthropics/claude-code/tree/main/.devcontainer

CLI Commands

claude “query” (interactive mode로 호출)
claude -p (단발성 non interactive mode로 호출)
Non Interactive Mode 에서 세션 아이디로 대화 이어가기 가능
- claude -r "7b2f060- …" "query"
- Interactive mode 에서는 해당 피쳐 개발 진행중 (Issue #1407)

CLI Flags

대표 워크플로우

코드 설명

> what does the payment processing system do?
> find where user permissions are checked
> explain how the caching layer works

git 관련 작업 자동화

> commit my changes
> create a pr
> which commit added tests for markdown back in December?
> rebase on main and resolve any merge conflicts

코드 일부 수정

> add input validation to the signup form
> refactor the logger to use the new API
> fix the race condition in the worker queue

테스트 작성

> run tests for the auth module and fix failures
> find and fix security vulnerabilities
> explain why this test is failing

Extended Thinking 모드 활용하는 방법

먼저 클로드에게 작업에 대해 설명하고 프로젝트에서 컨텍스트를 수집하도록 지시
이후 think hard라는 표현으로 생각을 더 깊게해서 결과물을 내도록 프롬팅

> think about how we should architect the new payment service
> think hard about the edge cases in our authentication flow

MCP 연동

windsurf 설정 활용

cmd + p → ~/.codeium/windsurf/mcp_config.json 내용 복사
- 프로젝트 단위의 mcp 서버 설정
  - ./.mcp.json 붙여넣기
  - .gitignore에 .mcp.json 포함시키기
- 모든 프로젝트에서 자주 사용하는 mcp 서버 설정
  - ~/.claude.json > mcpServers 필드 수정

이용할 MCP 서버 목록 선택

claude 실행
space로 선택/해제 → enter 로 최종 확인
기록되는 위치 .claude/settings.local.json 디렉토리에 화이트 리스팅한 서버 목록이 기록됨
- claude mcp reset-project-choices 로 리셋 또는 .claude/settings.local.json 의 "enabledMcpjsonServers", "disabledMcpjsonServers” 필드 내용 삭제후 claude 재실행하여, 리스트 재설정

클로드 프로젝트 메모리

메모리 유형

클로드에서 지원하는 메모리 유형은 크게 2가지입니다.
- 유저 메모리 (~/.claude/CLAUDE.md)
  - 개인적인 코딩 선호도, 본인만의 숏컷 정의 등
- 프로젝트 메모리 (./CLAUDE.md)
  - 팀에서 공유할 필요가 있는 프로젝트 아키텍처, 코딩 표준
- 핵심은 유저 메모리는 git 에서 관리가 안되고, 프로젝트 메모리는 git 에서 관리가 된다는점.
- /memory 명령어 또는 직접 파일 편집을 통해 관리

작동 과정

클로드 코드는 메모리를 재귀적으로 찾음. 현재 작업 디렉토리(cwd)에서 시작하여 루트 디렉토리(/)까지 거슬러 올라가면서 발견하는 모든 CLAUDE.md 또는 CLAUDE.local.md 파일을 읽음.
예시
- 가령 claude 를 실행한 위치가 ./claude-code-test/utils/ 일때, ./claude-code-test/CLAUDE.md , ./claude-code-test/utils/CLAUDE.md 의 메모리를 전부다 로드함.
```
  claude-code-test/
  ├── CLAUDE.md
  ├── README.md
  ├── test.py
  └── utils/ (claude 실행 위치)
      ├── CLAUDE.md
      ├── __init__.py
      └── simple_utils.py
```
- 반대로 실행 위치가 claude-code-test/ 일때는 해당 디렉토리안의 ./CLAUDE.md 로드하고 필요시에 ./claude-code-test/utils/CLAUDE.md 의 메모리를 로드함.

정리

영역	핵심 내용
메모리 종류	(1) 프로젝트 메모리 `./CLAUDE.md` : 팀이 공유하는 규칙·워크플로 정의 (2) 사용자 메모리 `~/.claude/CLAUDE.md` : 개인 선호하는 규칙 정의
메모리 탐색 규칙	실행 디렉터리(cwd)부터 프로젝트 루트(`/`)까지 거슬러 올라가며 `CLAUDE.md` / `CLAUDE.local.md`를 재귀적으로 모두 로드합니다. 하위 폴더에 있는 `CLAUDE.md`는 해당 폴더의 파일을 읽을 때만 포함됨
빠른 메모리 추가	터미널에서 프롬프트를 `#` 로 시작하면 “이 문장을 어느 메모리에 저장할까요?”라는 선택창이 뜹니다.
직접 편집	세션 중 `/memory` 명령을 실행하면 기본 에디터에서 메모리 파일을 열어 수정·정리가 가능

Claude Code 권한 설정 방법 총정리

Claude Code는 셸 명령 실행, 파일 수정, 외부 API 접근 등 중요한 작업을 할 때 사용자에게 허가를 요청함. 아래 4가지 방법으로 설정이 가능함.

실시간 허가 방식
세션 중 권한 보기/수정 (로컬 프로젝트 수정)
- claude > /allowed-tools
settings.json 파일 편집
cli 방식으로 일시 허용
- claude —-allowed-tools “…”

실시간 허가 방식 (기본)

Claude가 뭔가 하려고 하면 이렇게 물어봄:

“npm install 실행해도 될까요?”

허용(Allow): 한 번만 실행
항상 허용(Always allow): 허용 리스트에 추가됨 (자동 실행 가능)
거부(Deny): 실행 안 됨

이렇게 응답하면 내부적으로 설정이 갱신됨

세션 중 권한 보기/수정

Claude 대화창에 /allowed-tools 입력하면 현재 허용된 도구 리스트가 나옵니다. 여기서 직접 추가하거나 삭제가능

Settings.json 파일 편집

settings.json 파일을 프로젝트 또는 전체 사용자 기준으로 작성

경로
- ~/.claude/settings.json (유저 개인 셋팅으로 취급)
- .claude/settings.local.json (.gitignore에 포함되어 공유 x)
- .claude/settings.json (프로젝트 파일로 팀내 공유)

예시 (지원 명령어 참조)

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)"
    ]
  }
}

필드
- allow: 자동으로 허용할 작업
- deny: 무조건 거부할 작업
명령어
- Bash(...): 셸 명령
- Read(...) / Edit(...): 파일 읽기/쓰기

CLI 방식으로 일시 허용

# 특정 도구만 허용
claude --allowedTools "Bash(npm run dev),WebFetch(domain:example.com)"

# 특정 명령어는 거부
claude --disallowedTools "Bash(rm -rf *)"

대화 세션이 길어지는 경우

내장 요약 프롬트 사용

대화 기록이 요약된 파일 (.md) 생성
- /compact summarize and create xxx_history.md
새로운 claude 세션을 열어서
- claude > Based on the information in @xxx_history.md, please analyze the current status of our conversation and identify the key topics, decisions, and unresolved issues.

(optional) 커스텀 프롬트 사용

커스텀 요약 프롬트 다운로드해, compact_custom_prompt.md 로 저장
interactive 모드에서 대화 기록이 길어질 경우 위 프롬트를 사용해서 .md 파일로 요약된 내용 저장
- @compact_custom_prompt.md summarize and create xxx_history.md
새로운 세션 내에서 해당 파일 열어서 태스크 이어서 진행
- claude > Based on the information in @xxx_history.md, please analyze the current status of our conversation and identify the key topics, decisions, and unresolved issues.

Git WorkTree를 활용한 동시 작업

언제 사용하나요?

여러 개의 Claude Code 세션을 동시에 실행하여, 각 세션이 서로 다른 브랜치 또는 작업 디렉토리에서 독립적으로 작업할 때 유용합니다. 예를 들어, 한쪽에서는 버그를 수정하고, 다른 쪽에서는 새로운 기능을 개발하고 싶을 때 사용할 수 있음

Git Worktree는 하나의 Git 저장소에서 여러 개의 작업 디렉토리를 만들 수 있게 해주는 기능입니다. 각 디렉토리는 서로 다른 브랜치나 커밋을 체크아웃할 수 있어, 여러 작업을 동시에 진행할 때 매우 유용합니다.

사용법

Worktree 생성

# 1. 기존 저장소로 이동
cd /path/to/your/repo

# 2. 새로운 worktree 디렉토리 생성 (feature-branch를 체크아웃)
git worktree add ../repo-feature feature-branch

/path/to/your/repo : 기존 저장소 경로
../repo-feature : 새로 만들 worktree 디렉토리 (원본 저장소와 같은 상위 폴더에 생성)
feature-branch : 체크아웃할 브랜치

각 worktree에서 Claude Code 세션 실행 (tmux 활용하면 편함)

# 첫 번째 세션 (main 브랜치)
cd /path/to/your/repo
claude

# 두 번째 세션 (feature-branch)
cd ../repo-feature
claude

추가 팁

worktree를 삭제하려면 git worktree remove <디렉토리> 명령어를 사용
Claude Code의 각 세션은 해당 디렉토리의 코드베이스와 대화 내역을 따로 관리됨

이외 추가 명령어

/pr_comments

오픈,closed 된 PR 내용을 컨텍스트로 가져오는 기능

/review

claude-code에게 PR 코드 리뷰를 요청

/init

claude code에게 명시적으로 CLAUDE.md 파일및 프로젝트 셋업 지시 (참고, 프로젝트 루트에서 claude 명령어 실행시 자동으로 수행됨)

/model

opus4 또는 sonnet4를 선택
사용량 관련 (25.06.04 기준)
- 사용량 50% 까지는 opus4 사용 나머지 사용량의 50%는 sonnet4 사용. 5시간마다 리셋
- Max 5x Pro ($100/month): 일반적인 사용자는 클로드에게 5시간마다 약 225개의 메시지
- Max 20x Pro ($200/month): 일반적인 사용자는 클로드에게 5시간마다 약 900개의 메시지

Claude Code 사용 가이드

개요

설치