Claude Code 모범 사례

​

Claude에게 작업을 검증할 방법 제공하기

​

먼저 탐색하고, 그 다음 계획하고, 그 다음 코드 작성하기

/src/auth를 읽고 세션 및 로그인을 어떻게 처리하는지 이해하세요.
또한 비밀에 대한 환경 변수를 어떻게 관리하는지 살펴보세요.

Google OAuth를 추가하고 싶습니다. 어떤 파일을 변경해야 합니까?
세션 흐름은 무엇입니까? 계획을 작성하세요.

계획에서 OAuth 흐름을 구현하세요. 콜백 핸들러에 대한 테스트를 작성하고,
테스트 스위트를 실행하고 실패를 수정하세요.

설명적인 메시지로 커밋하고 PR을 열기

​

프롬프트에서 구체적인 컨텍스트 제공하기

​

풍부한 콘텐츠 제공하기

• @로 파일 참조 코드가 어디에 있는지 설명하는 대신. Claude는 응답하기 전에 파일을 읽습니다.
• 이미지를 직접 붙여넣기. 프롬프트에 이미지를 복사/붙여넣기 또는 드래그 앤 드롭하십시오.
• 문서 및 API 참조에 URL 제공. /permissions를 사용하여 자주 사용되는 도메인을 허용 목록에 추가하십시오.
• 데이터 파이프 cat error.log | claude를 실행하여 파일 내용을 직접 전송하십시오.
• Claude가 필요한 것을 가져오도록 하기. Bash 명령, MCP 도구 또는 파일 읽기를 사용하여 Claude가 자체적으로 컨텍스트를 가져오도록 하십시오.

​

환경 구성하기

​

효과적인 CLAUDE.md 작성하기

# 코드 스타일
- ES 모듈(import/export) 구문을 사용하고, CommonJS(require)는 사용하지 마세요
- 가능하면 import를 구조 분해하세요 (예: import { foo } from 'bar')

# 워크플로우
- 일련의 코드 변경을 완료했을 때 타입 체크를 확인하세요
- 성능상 이유로 전체 테스트 스위트가 아닌 단일 테스트를 실행하는 것을 선호하세요

프로젝트 개요는 @README.md를 참조하고 사용 가능한 npm 명령은 @package.json을 참조하세요.

# 추가 지시사항
- Git 워크플로우: @docs/git-instructions.md
- 개인 재정의: @~/.claude/my-project-instructions.md

• 홈 폴더(~/.claude/CLAUDE.md): 모든 Claude 세션에 적용됨
• 프로젝트 루트(./CLAUDE.md): git에 체크인하여 팀과 공유
• 상위 디렉토리: 모노레포에 유용하며, root/CLAUDE.md와 root/foo/CLAUDE.md 모두 자동으로 가져와집니다
• 하위 디렉토리: Claude는 해당 디렉토리의 파일로 작업할 때 필요에 따라 하위 CLAUDE.md 파일을 가져옵니다

​

권한 구성하기

• Auto mode: 별도의 분류기 모델이 명령을 검토하고 위험해 보이는 것만 차단합니다: 범위 확대, 알 수 없는 인프라, 또는 적대적 콘텐츠 기반 작업. 작업의 일반적인 방향을 신뢰하지만 모든 단계를 클릭하고 싶지 않을 때 최고입니다
• 권한 허용 목록: 안전하다고 알고 있는 특정 도구 허용(예: npm run lint 또는 git commit)
• 샌드박싱: Claude가 정의된 경계 내에서 더 자유롭게 작동할 수 있도록 하는 OS 수준 격리를 활성화하여 파일 시스템 및 네트워크 액세스를 제한합니다

​

CLI 도구 사용하기

​

MCP 서버 연결하기

​

hooks 설정하기

​

skills 생성하기

---
name: api-conventions
description: 우리 서비스의 REST API 설계 규칙
---
# API 규칙
- URL 경로에 kebab-case 사용
- JSON 속성에 camelCase 사용
- 항상 목록 엔드포인트에 페이지 매김 포함
- URL 경로에서 API 버전 지정 (/v1/, /v2/)

---
name: fix-issue
description: GitHub 이슈 수정
disable-model-invocation: true
---
GitHub 이슈를 분석하고 수정하세요: $ARGUMENTS.

1. `gh issue view`를 사용하여 이슈 세부 정보 가져오기
2. 이슈에 설명된 문제 이해
3. 관련 파일에 대한 코드베이스 검색
4. 이슈를 수정하기 위해 필요한 변경 사항 구현
5. 수정을 확인하기 위해 테스트 작성 및 실행
6. 코드가 linting 및 타입 체크를 통과하는지 확인
7. 설명적인 커밋 메시지 생성
8. 푸시 및 PR 생성

​

사용자 정의 subagents 생성하기

---
name: security-reviewer
description: 보안 취약점에 대한 코드 검토
tools: Read, Grep, Glob, Bash
model: opus
---
당신은 선임 보안 엔지니어입니다. 다음에 대해 코드를 검토하세요:
- 주입 취약점(SQL, XSS, 명령 주입)
- 인증 및 권한 부여 결함
- 코드의 비밀 또는 자격 증명
- 안전하지 않은 데이터 처리

특정 줄 참조 및 제안된 수정 사항을 제공하세요.

​

plugins 설치하기

​

효과적으로 소통하기

​

코드베이스 질문 하기

• 로깅은 어떻게 작동합니까?
• 새로운 API 엔드포인트를 어떻게 만듭니까?
• foo.rs의 134번 줄에서 async move { ... }는 무엇을 합니까?
• CustomerOnboardingFlowImpl은 어떤 엣지 케이스를 처리합니까?
• 이 코드가 333번 줄에서 bar() 대신 foo()를 호출하는 이유는 무엇입니까?

​

Claude가 당신을 인터뷰하도록 하기

[간단한 설명]을 빌드하고 싶습니다. AskUserQuestion 도구를 사용하여 자세히 인터뷰해주세요.

기술 구현, UI/UX, 엣지 케이스, 우려 사항, 트레이드오프에 대해 질문하세요. 명백한 질문을 하지 마세요, 당신이 고려하지 않았을 수 있는 어려운 부분을 파고드세요.

모든 것을 다룰 때까지 인터뷰를 계속한 다음 SPEC.md에 완전한 사양을 작성하세요.

​

세션 관리하기

​

조기에 자주 방향 수정하기

• Esc: Esc 키로 Claude의 작업을 중간에 중지하십시오. Context는 보존되므로 방향을 바꿀 수 있습니다.
• Esc + Esc 또는 /rewind: Esc를 두 번 누르거나 /rewind를 실행하여 rewind 메뉴를 열고 이전 대화 및 코드 상태를 복원하거나 선택한 메시지에서 요약하십시오.
• "Undo that": Claude에게 변경 사항을 되돌리도록 하십시오.
• /clear: 관련 없는 작업 간에 context를 재설정하십시오. 관련 없는 context가 있는 긴 세션은 성능을 줄일 수 있습니다.

​

context 적극적으로 관리하기

• 작업 간에 자주 /clear를 사용하여 context window를 완전히 재설정하십시오
• 자동 압축이 트리거되면 Claude는 코드 패턴, 파일 상태, 주요 결정을 포함하여 가장 중요한 것을 요약합니다
• 더 많은 제어를 위해 /compact <instructions>를 실행하십시오(예: /compact Focus on the API changes)
• 대화의 일부만 압축하려면 Esc + Esc 또는 /rewind를 사용하고, 메시지 체크포인트를 선택하고, Summarize from here를 선택하십시오. 이는 해당 지점부터의 메시지를 압축하면서 이전 context를 유지합니다.
• CLAUDE.md에서 "When compacting, always preserve the full list of modified files and any test commands"와 같은 지시사항으로 압축 동작을 사용자 정의하여 중요한 context가 요약을 통해 유지되도록 하십시오
• 빠른 질문의 경우 context에 들어가지 않아야 하므로 /btw를 사용하십시오. 답변은 해제 가능한 오버레이에 나타나고 대화 기록에 들어가지 않으므로 context를 증가시키지 않고 세부 정보를 확인할 수 있습니다.

​

subagents를 사용하여 조사하기

subagents를 사용하여 인증 시스템이 토큰 새로 고침을 어떻게 처리하는지,
그리고 재사용해야 할 기존 OAuth 유틸리티가 있는지 조사하세요.

subagent를 사용하여 이 코드를 엣지 케이스에 대해 검토하세요

​

체크포인트로 rewind하기

​

대화 재개하기

claude --continue    # 가장 최근 대화 재개
claude --resume      # 최근 대화에서 선택

​

자동화 및 확장하기

​

비대화형 모드 실행하기

# 일회성 쿼리
claude -p "이 프로젝트가 무엇을 하는지 설명하세요"

# 스크립트를 위한 구조화된 출력
claude -p "모든 API 엔드포인트 나열" --output-format json

# 실시간 처리를 위한 스트리밍
claude -p "이 로그 파일 분석" --output-format stream-json

​

여러 Claude 세션 실행하기

• Claude Code 데스크톱 앱: 여러 로컬 세션을 시각적으로 관리하십시오. 각 세션은 자신의 격리된 worktree를 가집니다.
• 웹의 Claude Code: Anthropic의 안전한 클라우드 인프라에서 격리된 VM에서 실행하십시오.
• Agent teams: 공유 작업, 메시징, 팀 리더를 사용한 여러 세션의 자동 조정.

​

파일 전체에 fan out하기

for file in $(cat files.txt); do
  claude -p "React에서 Vue로 $file 마이그레이션. OK 또는 FAIL 반환." \
    --allowedTools "Edit,Bash(git commit *)"
done

claude -p "<your prompt>" --output-format json | your_command

​

auto mode로 자율적으로 실행하기

claude --permission-mode auto -p "fix all lint errors"

​

일반적인 실패 패턴 피하기

• 주방 싱크 세션. 한 작업으로 시작한 다음 Claude에게 관련 없는 것을 물어본 다음 첫 번째 작업으로 돌아갑니다. Context는 관련 없는 정보로 가득 찹니다.

  수정: 관련 없는 작업 간에 /clear.

• 반복적으로 수정. Claude가 뭔가 잘못하고, 당신이 수정하고, 여전히 잘못되고, 다시 수정합니다. Context는 실패한 접근 방식으로 오염됩니다.

  수정: 두 번의 실패한 수정 후 /clear를 하고 배운 내용을 통합하는 더 나은 초기 프롬프트를 작성하십시오.

• 과도하게 지정된 CLAUDE.md. CLAUDE.md가 너무 길면 Claude는 중요한 규칙이 노이즈에 손실되기 때문에 절반을 무시합니다.

  수정: 무자비하게 정리하십시오. Claude가 지시사항 없이 이미 올바르게 수행하면 삭제하거나 hook으로 변환하십시오.

• 신뢰-검증 간격. Claude는 그럴듯해 보이지만 엣지 케이스를 처리하지 않는 구현을 생성합니다.

  수정: 항상 검증(테스트, 스크립트, 스크린샷)을 제공하십시오. 검증할 수 없으면 배포하지 마십시오.

• 무한 탐색. 범위를 지정하지 않고 Claude에게 뭔가를 “조사”하도록 요청합니다. Claude는 수백 개의 파일을 읽으며 context를 채웁니다.

  수정: 조사를 좁게 범위 지정하거나 subagents를 사용하여 탐색이 주요 context를 소비하지 않도록 하십시오.

​

직관 개발하기

​

관련 리소스

• Claude Code 작동 방식: 에이전트 루프, 도구, context 관리
• Claude Code 확장: skills, hooks, MCP, subagents, plugins
• 일반적인 워크플로우: 디버깅, 테스트, PR 등에 대한 단계별 레시피
• CLAUDE.md: 프로젝트 규칙 및 지속적인 context 저장