[Claude Code] 2. 모범 사례 가이드

0. 모든 팁은 컨텍스트 관리가 핵심

• 컨텍스트 윈도우가 꽉 찰수록 Claude의 성능은 떨어짐
• ⚠️ 지시사항을 잊어버리거나 실수가 늘어남
• ➡️ 모든 팁은 "컨텍스트를 어떻게 아껴 쓰고 관리할 것인가"로 수렴함

 

1. 효과적인 작업 요청 공식

• 단순히 "수정해달라" 하기 보다 구체적으로 전달하는 것이 좋음

항목	설명
목표	최종적으로 해결하거나 완성하려는 내용
현재 상황	현재 증상, 오류, 기존 구조
작업 범위	우선 확인하거나 수정할 모듈과 파일
제약조건	수정하면 안 되는 영역이나 지켜야 할 규칙
검증 방법	테스트, 빌드, 실행 확인 방법
결과 보고	변경 파일, 원인, 테스트 결과 등 최종 보고 형식

 

예시) OAuth2 Login 문제 조사

OAuth2 로그인 성공 후 프런트엔드로 리다이렉트되지 않는 문제를 조사해주세요.

목표:
- 로그인 성공 후 정상적으로 프런트엔드 로그인 성공 페이지로 이동해야 합니다.

현재 상황:
- 인증은 성공합니다.
- LoginSuccessHandler도 호출됩니다.
- 브라우저에는 404가 표시됩니다.

작업 범위:
- oauth2-client와 api-gateway를 우선 확인하세요.
- 관련 설정과 리다이렉트 URI를 조사하세요.

제약조건:
- 아직 파일을 수정하지 마세요.
- 먼저 원인 후보를 근거 파일과 함께 정리하세요.
- 관련 없는 모듈은 수정하지 마세요.

검증:
- 수정 후 관련 테스트를 실행하세요.
- 최종 리다이렉트 URL이 어떻게 구성되는지도 설명하세요.

결과 보고:
- 문제 원인
- 수정한 파일
- 실행한 테스트
- 최종 리다이렉트 흐름
- 검증하지 못한 항목

 

2. Permission Mode

• 권한 모드를 변경하여 파일 수정과 명령 실행 방식을 제어할 수 있음
• 'shift+tab' 으로 모드 전환 가능

 

Mode

모드	설명	사용하는 상황
Plan Mode	파일을 수정하지 않고 코드 조사와 작업 계획 수립에 집중	큰 기능, 리팩터링, 인증, 배포, DB 변경
Accept Edits Mode	파일 편집을 자동 승인하며 일부 파일 시스템 명령도 허용	검토가 끝난 계획을 구현할 때
기본 모드	파일 수정이나 셸 명령이 필요할 때 사용자에게 권한을 확인	일반적인 안전한 개발 작업

 

명령어) mode 설정

claude --permission-mode plan

 

3. 작업 검증 방법을 반드시 마련하기

• 통과/실패를 알려주는 수단이 있으면 스스로 돌려보고 실패하면 고치는 루프를 돔
• ✅ 한 프롬프트 안에서 "실행하고 반복해줘"라 요청하기
• ⚠️ 확인 방법이 없으면 사람이 매번 검토해줘야함

 

예시) 이메일 검증 프롬프팅

• ❌ "이메일 검증 함수 만들어줘"
• ✅ "validateEmail 함수 작성. 테스트 케이스: user@example.com→true, invalid→false. 구현 후 테스트 실행"

 

예시) 대시보드 생성 프롬프팅

• ❌  "대시보드 좀 더 예쁘게"
• ✅ "[스크린샷] 이 디자인대로 구현. 결과 스크린샷 찍어서 원본과 비교, 차이점 나열 후 수정"

 

증거 기반 검증

• "성공했다"는 말만 시키지 말고 테스트 출력/명령 결과/스크린샷 등 실제 증거를 보여주게 하기

 

검증 강도

단계	검증 방식	동작 방식	적합한 사용 상황
1	프롬프트 내 요청	별도 설정 없이 같은 대화에서 실행 → 검증 → 수정을 반복하도록 요청	짧은 작업, 직접 지켜보는 작업, 간단한 코드 수정
2	/goal 조건	세션 전체에 검증 조건을 설정하고, 매 턴이 끝날 때 별도 평가자가 조건 충족 여부를 재확인	장시간 작업, 자리를 비우는 작업, 일정 기준을 만족할 때까지 반복해야 하는 작업
3	Stop hook	검증 스크립트가 실패를 반환하면 턴 종료를 차단하고 작업을 계속하게 함. 8회 연속 차단 시 강제 종료	테스트·빌드·린트처럼 반드시 통과해야 하는 명확한 자동 검증 조건이 있는 작업
4	서브에이전트 2차 검토	작성자와 검토자를 분리하고, 새 컨텍스트의 서브에이전트가 변경된 diff를 독립적으로 검토	중요한 배포, 보안 코드, 대규모 리팩터링, 작성자의 편향을 줄여야 하는 작업

 

4. Second Brain

• Claude와 함께 작업하면서 발견한 지식과 경험을 축적하는 지식관리 체계
• ✅ CLAUDE.md, docs/, TODO.md, 자동 메모리 등을 함께 활용함
• ex) 빌드 명령어, 자주 발생하는 오류, 해결 방법, 프로젝트 패턴, 디버깅 노하우 등

 

5. Skill

• Claude에게 특정 작업을 어떻게 하는지 가르치는 지침서
• ✅ 반복되는 지식/절차 등을 정의함
• ✅ 경로: ".claude/skills/<이름>/SKILL.md" 
• ex) Skill 사용 조건, 작업 순서, 검토 기준, 필요한 참고 자료

 

예시) SKILL.md 프론트매터

---
name: api-conventions          # 소문자, 숫자, 하이픈만 (최대 64자)
description: >-                 # 최대 200자 정도 — 가장 중요한 필드
  REST API 설계 컨벤션. URL 경로 규칙, JSON 네이밍,
  페이지네이션 관련 작업 시 사용.
allowed-tools: Read, Grep, Bash(git *)   # 이 스킬이 쓸 수 있는 도구 제한
disable-model-invocation: true   # true면 자동호출 안 됨, /명령어로만 실행
model: opus                      # 이 스킬 실행 시 쓸 모델 지정
---

• description: 이 스킬을 언제 쓸지 근거가 되는 요소. (가장 중요)

 

점진적 공개 구조

1. 항상 로드: name+description 만 시스템 프롬프트에
2. 필요시 로드: SKILL.md 본문 전체
3. 필요시 로드: SKILL.md가 참조하는 추가 파일 (스크립트, 참고문서, 템플릿)

 

종류

종류	설명	예시
지식형	컨벤션/규칙. 절차 없이 "이런 규칙이 있다"만 전달	API 컨벤션, 코드 스타일
절차형	여러 단계로 된 반복 워크플로우	이슈 수정, PR 생성, 보안 리뷰

 

 

 

예시) 지식형 스킬

---
name: api-conventions
description: >-
  REST API 설계 컨벤션. URL 경로 규칙, JSON 네이밍,
  페이지네이션 관련 작업 시 사용.
allowed-tools: Read, Grep
---
# API 컨벤션

- URL 경로는 kebab-case 사용 (예: /user-profiles)
- JSON 속성명은 camelCase 사용
- 목록을 반환하는 엔드포인트는 항상 페이지네이션 포함
  (page, pageSize, totalCount 필드)
- API 버전은 URL 경로에 명시 (/v1/, /v2/)
- 에러 응답은 { error: { code, message } } 형식 통일

 

예시) 절차형 스킬

---
name: fix-issue
description: GitHub 이슈를 조사하고 수정하는 표준 절차
disable-model-invocation: true
allowed-tools: Bash(gh *), Read, Edit, Grep, Glob
---
# 이슈 수정 절차

GitHub 이슈를 분석하고 수정: $ARGUMENTS

1. `gh issue view $ARGUMENTS`로 이슈 상세 확인
2. 문제 원인 파악을 위해 관련 코드 검색
3. 재현 가능한 실패 테스트 작성
4. 최소 범위로 수정 구현
5. 테스트 실행하여 통과 확인
6. 린트/타입체크 통과 확인
7. `feat:` / `fix:` 컨벤션에 맞춰 커밋 메시지 작성
8. 브랜치 푸시 및 PR 생성 (이슈 번호 링크 포함)

## 검토 기준
- 수정 범위가 이슈 내용을 벗어나지 않았는가
- 엣지 케이스 테스트가 포함됐는가
- 기존 코드 스타일을 따랐는가

 

구조

my-skill/
├── SKILL.md          # 필수 — 메인 지침
├── references/        # 선택 — 참고 문서 (긴 내용은 여기로 분리)
│   └── REFERENCE.md
├── scripts/            # 선택 — Claude가 실행할 스크립트
│   └── process.py
├── templates/          # 선택 — 채워넣을 템플릿
└── examples/            # 선택 — 예시 결과물

• 메인 지침: 프로세스만 담음
• 별도 파일: 배경지식, 긴 레퍼런스을 담음

 

호출 방식

• 자동 호출: 작업 중 Claude가 알아서 description을 보고 매칭함
• 수동 호출: 사용자가 "/스킬이름" 으로 직접 실행
  • disable-model-invocation: true 옵션 시 자동 호출 막음

 

6. WAT 프레임워크

• 복잡한 작업 구조화하기

 

요소

요소	정의	팁
Workflows	코드 작성 전 작업이 어떤 순서로 진행되어야 하는지 자연어로 정의
Agents	역할을 전문 분야로 분리	서로 독립적인 작업은 Subagent로 나누어 병렬 처리
Tools	실제 작업을 수행할 도구 제공

 

예시) Workflows - 10단계 표준 워크플로우

단계	설명	예시
1. 프로젝트 분석	코드와 설정 파일을 읽어 구조, 모듈 역할, 실행 흐름을 파악. 이 단계에서는 수정하지 않음	"프로젝트의 주요 모듈, 인증 흐름, 데이터 저장소를 분석해주세요. 아직 파일은 수정하지 마세요."
2. CLAUDE.md 정비	분석 결과를 바탕으로 공통 규칙, 명령어, 금지사항을 정리	"기존 CLAUDE.md에서 실제 프로젝트와 다른 내용을 찾고 핵심 규칙만 보완해주세요."
3. TODO.md 작성	요구사항을 한 번에 구현 가능한 작은 작업 단위로 분해	"회원가입 개선 작업을 구현·테스트 가능한 단위로 분해해 TODO.md에 작성해주세요."
4. Plan Mode	코드 수정 전, 관련 파일·영향 범위·구현 순서를 조사	"TODO.md의 첫 번째 항목을 조사하고 구현 계획만 작성해주세요. 수정은 하지 마세요."
5. 계획 리뷰	계획에서 누락된 요구사항, 위험, 과도한 설계를 검토	"이 계획의 잘못된 가정, 회귀 위험, 테스트 누락을 비판적으로 검토해주세요."
6. 구현	승인한 계획의 범위만 작은 단위로 수정	"승인한 계획의 1단계만 구현해주세요. 관련 없는 파일은 수정하지 마세요."
7. 검증	테스트, 빌드, 린트 등을 실행해 변경사항이 정상인지 확인	"관련 테스트를 실행하고 실행 명령어와 결과를 정리해주세요."
8. 리뷰	Git diff를 기준으로 버그, 보안 문제, 불필요한 변경을 검사	"현재 Git diff를 검토해주세요. 코드는 수정하지 말고 문제점만 보고해주세요."
9. 기록	완료된 작업, 설계 결정, 장애 해결 방법을 문서에 반영	"TODO.md를 갱신하고 새로 확인한 장애 해결 방법은 docs/troubleshooting에 기록해주세요."
10. 세션 종료	현재 상태와 다음 시작 지점을 남기고 추가 작업을 중단	"이번 세션의 수정 파일, 테스트 결과, 남은 작업을 정리하고 다음 작업은 시작하지 마세요."

 

예시) Agents - 역할 분리

 

• 아키텍처 분석 Agent
• 구현 Agent
• 테스트 Agent
• 보안 리뷰 Agent
• 문서 작성 Agent

 

 

예시) Tools - 프롬프트에 원본 데이터 그대로 전달하기

에러 로그처럼 원본 그대로 줘야 정확한 진단이 나오는 데이터는, 요약하지 말고 그대로 붙여넣으세요.

다음은 실제 오류 로그입니다.
[오류 로그 전체 붙여넣기]

다음 순서로 분석해주세요.
1. 로그에서 직접 확인되는 사실
2. 최초 원인 예외
3. 연쇄적으로 발생한 후속 예외
4. 가장 가능성 높은 원인
5. 추가 확인이 필요한 설정
6. 수정 방법

추측과 확인된 사실을 구분해주세요.

 

 

출처

• Claude Code Docs - Claude Code의 작동 방식
• Claude Code Docs - Claude Code 모범 사례
• 실밸개발자 (youtube) - 메타 엔지니어의 클로드 코드 완벽 가이드 [입문편] - 설정부터 단축키까지 25분 총정리
• 실밸개발자 (youtube) - 메타 엔지니어의 클로드코드 완벽 가이드 [실전편] — 컨텍스트 관리, 실전 워크플로우 20분 총정리