Claude Code & OpenCode 실전 가이드: 38가지 베스트 프랙티스

서론

안녕하세요, Twodragon입니다.

2026년 현재 Claude Code와 OpenCode는 단순한 코드 생성 도구를 넘어 자율적으로 파일을 탐색하고, 코드를 수정하고, 테스트를 실행하는 에이전틱 코딩 도구로 진화했습니다. 특히 Opus 4.6 모델의 등장과 에이전트 팀 기능의 안정화로, 복잡한 멀티파일 리팩토링이나 대규모 마이그레이션까지 자동화할 수 있게 되었습니다.

하지만 도구가 강력해질수록 올바르게 사용하는 방법이 더욱 중요해집니다. 컨텍스트 윈도우를 낭비하면 성능이 급격히 떨어지고, CLAUDE.md가 비대해지면 핵심 규칙이 무시되며, 에이전트 팀의 파일 소유권을 관리하지 않으면 덮어쓰기 충돌이 발생합니다.

이 포스트는 Anthropic 공식 Best Practices 문서, 에이전트 팀 가이드, Opus 4.6 활용 가이드를 기반으로, 실무에서 반복 검증된 38가지 Best Practice를 11개 파트로 정리한 종합 레퍼런스입니다.

이 가이드에서 다루는 내용

관련 포스트: CLAUDE.md 보안 가이드: AI 에이전트 시대의 프로젝트 보안 설계

AI vs Claude Code: AI 코딩 어시스턴트 심층 비교

Part 1. 핵심 원칙

Claude Code는 챗봇이 아니라 에이전트다

“질문에 답하고 기다리는 챗봇이 아닙니다. 원하는 것을 설명하면 Claude가 탐색하고, 계획하고, 구현합니다.” — Anthropic 공식 문서

단순히 코드를 물어보는 도구가 아니라, 파일을 읽고, 명령어를 실행하고, 코드를 변경하고, 자율적으로 문제를 해결하는 에이전트입니다. 이 관점이 모든 Best Practice의 출발점입니다.

가장 중요한 제약: 컨텍스트 윈도우

“대부분의 베스트 프랙티스는 하나의 제약에 기반합니다: Claude의 컨텍스트 윈도우는 빠르게 채워지고, 채워질수록 성능이 저하됩니다.” — Anthropic 공식 Best Practices

컨텍스트 윈도우는 전체 대화, 읽은 파일, 명령어 출력을 모두 포함합니다. 디버깅 세션 하나에도 수만 토큰이 소비됩니다. 컨텍스트를 관리하는 것이 곧 성능을 관리하는 것입니다.

Part 2. 환경 설정 Best Practices

BP-01. 필수 환경 변수 3가지

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80"
  }
}

BP-02. 권한은 넓게, 보안이 필요하면 Sandbox로

{
  "permissions": {
    "allow": [
      "Bash(*)", "Edit(*)", "Write(*)", "NotebookEdit(*)",
      "WebFetch(*)", "WebSearch(*)", "mcp__playwright__*",
      "mcp__filesystem__*", "mcp__context7__*"
    ]
  }
}

원칙: 반복적인 승인 요청은 집중을 방해합니다. 개발 환경에서는 넓게 허용하고, 민감한 작업에는 /sandbox로 OS 수준 격리를 사용합니다.

# 보안이 필요한 환경에서는
/sandbox              # OS 수준 격리 활성화
# 또는 특정 도구만 허용
claude --allowedTools "Edit,Bash(npm test *)"

BP-03. 상태라인으로 토큰 실시간 모니터링

Claude Code는 커스텀 상태라인을 지원합니다. 현재 모드, 활성 에이전트 수, 토큰 사용량을 실시간으로 추적할 수 있습니다.

{
  "statusLine": {
    "type": "command",
    "command": "node path/to/your-hud-script.mjs"
  }
}

공식 문서에서도 “컨텍스트 사용량을 커스텀 상태라인으로 지속적으로 추적하라”고 권장합니다.

BP-04. MCP 서버로 외부 도구 연동

// ~/.claude/settings.local.json
{
  "enabledMcpjsonServers": ["context7", "filesystem"],
  "enableAllProjectMcpServers": true
}

BP-05. 플러그인으로 기능 확장

Claude Code는 플러그인 시스템을 지원합니다. 마켓플레이스에서 필요한 플러그인을 검색하여 설치할 수 있습니다.

# 플러그인 탐색
/plugin    # 마켓플레이스에서 검색

주요 플러그인 카테고리:

• 에이전트 오케스트레이션: 특화 에이전트, 실행 모드, 자동 모델 라우팅
• HUD/상태라인: 실시간 상태 디스플레이
• 코드 인텔리전스: 정적 분석, 코드 품질 도구

Part 3. CLAUDE.md Best Practices

BP-06. 프로젝트마다 CLAUDE.md 생성

# 프로젝트 디렉토리에서 실행 → 빌드 시스템, 테스트 프레임워크, 코드 패턴을 분석하여 자동 생성
/init

BP-07. 배치 위치별 역할 구분

BP-08. 간결하게 유지 (핵심 규칙만)

포함해야 할 것:

• Claude가 코드만 보고는 알 수 없는 Bash 명령어
• 기본값과 다른 코드 스타일 규칙
• 테스트 실행 방법, 선호 테스트 러너
• 브랜치 네이밍, PR 컨벤션
• 프로젝트 고유 아키텍처 결정사항

제외해야 할 것:

• 코드를 읽으면 알 수 있는 것 (Claude가 이미 파악 가능)
• 표준 언어 규칙 (Claude가 이미 앎)
• 상세한 API 문서 (링크로 대체)
• “깨끗한 코드를 작성하라” 같은 자명한 것

# 좋은 예시
# Code style
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible

# Workflow
- Typecheck after code changes: npm run typecheck
- Run single tests, not the whole suite: npm test -- --testPathPattern=<file>

핵심: 각 줄에 대해 “이걸 제거하면 Claude가 실수할까?” 아니면 삭제. 너무 길면 Claude가 중요한 규칙을 무시합니다!

BP-09. @ 구문으로 외부 파일 임포트

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

BP-10. 강조로 준수율 향상

# IMPORTANT: Always run tests before committing
# YOU MUST use the existing error handling pattern in src/utils/errors.ts

Part 4. 프롬프팅 Best Practices

BP-11. 검증 수단을 반드시 제공하라 (최고 효과)

“Claude가 스스로 작업을 검증할 수 있을 때 극적으로 더 좋은 결과를 냅니다. 이것이 가장 높은 효과를 내는 단일 조치입니다.” — Anthropic 공식 Best Practices

BP-12. 구체적 컨텍스트를 프롬프트에 포함

BP-13. 풍부한 입력 활용

예시:

• 파일 직접 참조: @src/auth/handler.ts
• 이미지 붙여넣기: 복사/붙여넣기 또는 드래그 앤 드롭
• 에러 로그 파이프: cat error.log | claude
• URL로 문서 제공: 이 API 문서를 참고해서 구현해: https://docs.anthropic.com/en/docs/claude-code/overview
• 직접 조회 지시: gh issue view 123 의 내용을 읽고 해결해

BP-14. 역할 설정 대신 작업을 명확히 (Opus 4.6)

# Bad - 불필요한 역할 설정
"너는 시니어 풀스택 개발자야. React와 TypeScript 전문가로서..."

# Good - 바로 작업 내용
"이 함수의 에러 핸들링을 개선하되, 기존 API 계약은 유지해"

Opus 4.6은 역할 프롬프트 없이도 맥락을 파악합니다. 범위, 제약, 검증 기준을 명확히 하는 것이 더 효과적입니다.

BP-15. 큰 기능은 Claude에게 먼저 인터뷰시키기

실시간 알림 시스템을 구현하고 싶어. AskUserQuestion 도구로 나를 자세히 인터뷰해줘.

기술 구현, UI/UX, 엣지 케이스, 트레이드오프에 대해 질문해.
뻔한 질문은 하지 말고, 내가 고려하지 못했을 어려운 부분을 파고들어.

모든 것을 다룰 때까지 인터뷰하고, 완료되면 SPEC.md에 전체 스펙을 작성해.

스펙 완성 후 새 세션에서 구현 시작 → 클린 컨텍스트에서 구현에만 집중.

Part 5. 워크플로우 Best Practices

BP-16. 탐색 - 계획 - 구현 - 커밋 (공식 4단계)

1. 탐색 (Plan Mode: Ctrl+G): “src/auth를 읽고 세션과 로그인 처리 방식을 이해해”
2. 계획 (Plan Mode): “Google OAuth 추가하려면 어떤 파일 변경? 계획 만들어” → Ctrl+G로 계획을 에디터에서 직접 편집
3. 구현 (Normal Mode): “계획대로 구현해. 콜백 핸들러 테스트 작성하고 실행해”
4. 커밋: “설명적 커밋 메시지로 커밋하고 PR 열어”

Tip: 범위가 명확하고 작은 수정이면 (오타, 로그 추가, 변수명 변경) 계획을 건너뛰세요. 계획은 접근법이 불확실하거나, 여러 파일 수정이거나, 코드에 익숙하지 않을 때 유용합니다.

BP-17. 실행 모드를 작업 복잡도에 맞게 선택

간단한 질문/수정      → 일반 모드 (기본)
새 기능 프로토타입     → autopilot 모드
중규모 기능 개발      → autopilot 또는 ultrawork 모드
대규모 리팩토링       → ultrawork (최대 병렬)
복잡한 버그 (끈질기게) → ralph 모드 (목표 달성까지 반복)
비용 절감 필요        → ecomode (Haiku+Sonnet 조합)
품질 보증/테스트      → ultraqa (테스트→검증→수정 반복)
대규모 마이그레이션    → swarm (N개 에이전트 공유 작업)
순차 파이프라인       → pipeline

BP-18. 계획은 검증까지 포함

# Bad - 구현만 요청
> OAuth 구현해

# Good - 계획 → 리뷰 → 구현 → 검증
> 1) OAuth 구현 계획 수립
> 2) 계획 리뷰
> 3) 계획대로 구현
> 4) 코드 리뷰
> 5) 보안 리뷰

BP-19. 에이전트 비용 최적화 (모델 라우팅)

자동 라우팅 원칙:

• quick-lookup → haiku
• standard-work → sonnet
• complex-reasoning → opus
• security-review → opus
• code-review → sonnet

Part 6. 세션 관리 Best Practices

BP-20. 컨텍스트를 공격적으로 관리하라

핵심 규칙: 두 번 수정 실패하면 더 이상 수정하지 말고 /clear 후 배운 것을 반영한 새 프롬프트로 재시작. 깨끗한 세션 + 좋은 프롬프트가 오염된 세션 + 반복 수정보다 거의 항상 낫습니다.

BP-21. 서브에이전트로 탐색을 위임

컨텍스트가 근본적 제약이므로, 탐색은 서브에이전트에 위임하여 메인 컨텍스트를 보호합니다:

# 탐색 위임 → 메인 컨텍스트 깨끗
> 서브에이전트를 사용해서 인증 시스템의 토큰 리프레시 방식과
  재사용 가능한 OAuth 유틸리티가 있는지 조사해줘

# 구현 후 검증도 서브에이전트로
> 서브에이전트로 이 코드의 엣지 케이스를 리뷰해줘

BP-22. 세션을 브랜치처럼 관리

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

/rename oauth-migration   # 세션에 설명적 이름 부여

다른 작업 흐름은 별도 세션으로 관리하면 지속적인 컨텍스트를 유지할 수 있습니다.

BP-23. 체크포인트로 부담 없이 실험

Claude는 변경 전 자동으로 체크포인트를 생성합니다:

Esc + Esc 또는 /rewind  →  되돌리기 메뉴
  ├── 대화만 복원
  ├── 코드만 복원
  ├── 둘 다 복원
  └── 선택 지점부터 요약

Tip: 위험한 시도도 부담 없이 하세요. 안 되면 되돌리고 다른 접근법을 시도하면 됩니다. 체크포인트는 세션 종료 후에도 유지됩니다.

BP-24. 자동 압축 시 중요 정보 보존

CLAUDE.md에 다음을 추가하면 압축 시 핵심 컨텍스트가 살아남습니다:

# Compaction rules
When compacting, always preserve:
- The full list of modified files
- Test commands and their results
- Key architectural decisions made in this session

Part 7. 에이전트 팀 Best Practices (공식)

BP-25. Subagent vs 에이전트 팀 선택 기준

결과만 보고받으면 충분      → 서브에이전트
팀원 간 토론/도전이 필요    → 에이전트 팀
구조화된 파이프라인 필요    → 팀 프리셋

BP-26. 에이전트 팀 적정 규모: 3-5명

• 팀원당 5-6개 작업 유지
• 15개 독립 작업이 있으면 3명이 적정
• 세 명의 집중된 팀원이 다섯 명의 산만한 팀원보다 나음

BP-27. 파일 충돌 방지

두 팀원이 같은 파일을 편집하면 덮어쓰기 발생. 각 팀원이 다른 파일 집합을 소유하도록 분할:

> 에이전트 팀을 만들어줘:
  - 팀원 A: src/api/ 디렉토리 담당
  - 팀원 B: src/components/ 디렉토리 담당
  - 팀원 C: tests/ 디렉토리 담당

BP-28. 팀원에게 충분한 컨텍스트 제공

팀원은 리더의 대화 기록을 상속하지 않습니다. 생성 프롬프트에 작업 세부사항을 포함하세요:

# Bad
> 보안 리뷰 팀원 추가해

# Good
> 보안 리뷰어 팀원을 생성해. 프롬프트:
  "src/auth/의 인증 모듈 보안 취약점을 리뷰해.
   토큰 핸들링, 세션 관리, 입력 검증에 집중.
   앱은 httpOnly 쿠키에 JWT를 저장. 심각도 등급과 함께 보고해."

BP-29. 연구/리뷰부터 시작

에이전트 팀을 처음 사용할 때는 코드 작성이 없는 작업으로 시작:

• PR 검토, 라이브러리 연구, 버그 조사
• 병렬 탐색의 가치를 파악한 후 구현 작업으로 확장

Part 8. Hook & Skills Best Practices

BP-30. 반드시 실행되어야 하는 것은 Hook으로

“CLAUDE.md 지시사항은 권고적이지만, Hook은 결정적(deterministic)입니다.”

# Claude가 Hook을 작성해줌
> "파일 편집 후 매번 eslint를 실행하는 Hook을 작성해줘"
> "migrations 폴더에 쓰기를 차단하는 Hook을 작성해줘"

# 대화형 설정
/hooks

Hook 이벤트 종류

BP-31. 도메인 지식은 Skill로

매 세션에 로드되는 CLAUDE.md와 달리, Skill은 관련 있을 때만 자동 로드됩니다:

# .claude/skills/api-conventions/SKILL.md
---
name: api-conventions
description: REST API design conventions
---
- Use kebab-case for URL paths
- Use camelCase for JSON properties

반복 가능한 워크플로우도 Skill로 정의:

# .claude/skills/fix-issue/SKILL.md
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
1. `gh issue view` → 관련 파일 검색 → 수정 → 테스트 → PR

/fix-issue 1234    # 직접 호출

Part 9. OpenCode Best Practices

BP-32. 작업에 따라 도구 선택

BP-33. OpenCode 에이전트 역할 분담

BP-34. Claude Code와 OpenCode 비교

Part 10. 자동화 & 스케일링 Best Practices

BP-35. Headless 모드로 CI/스크립트 통합

예시:

• 일회성 쿼리: claude -p "이 프로젝트가 무엇을 하는지 설명해"
• 구조화된 출력: claude -p "모든 API 엔드포인트를 나열해" --output-format json
• 실시간 스트리밍: claude -p "이 로그 파일을 분석해" --output-format stream-json
• 파이프라인 연결: claude -p "<프롬프트>" --output-format json | your_command

BP-36. Writer/Reviewer 패턴으로 품질 향상

세션 A (Writer): "API rate limiter 구현해"
          ↓ 완료
세션 B (Reviewer): "@src/middleware/rateLimiter.ts 리뷰해.
                    엣지 케이스, 레이스 컨디션, 미들웨어 패턴 일관성 확인"
          ↓ 피드백
세션 A (Writer): "리뷰 피드백 반영해: [피드백 내용]"

왜 효과적인가: 새 컨텍스트는 Claude가 자신이 작성한 코드에 편향되지 않게 합니다.

BP-37. 대규모 Fan-out 패턴

권장 흐름:

1. 작업 목록 파일 생성
2. 파일 목록 기준으로 병렬 실행
3. 2~3개로 먼저 테스트 → 프롬프트 조정 → 전체 실행

BP-38. 팀 프리셋으로 반복 워크플로우 자동화

워크플로우별 에이전트 파이프라인을 프리셋으로 정의하여 재사용할 수 있습니다:

코드 리뷰:    explore → architect → critic → executor
기능 구현:    planner → executor → tdd-guide
디버깅:       explore → architect → build-fixer
리서치:       parallel(researcher, explore) → architect → writer
리팩토링:     explore → architect → executor → qa-tester
보안 감사:    explore → security-reviewer → executor → security-reviewer

Part 11. 흔한 실패 패턴과 해결법

자기 진단 체크리스트

직감 개발하기 (공식 가이드)

“이 가이드의 패턴은 시작점이지 절대 규칙이 아닙니다.”

• 때로는 컨텍스트를 쌓는 것이 맞음 (하나의 복잡한 문제에 깊이 파고들 때)
• 때로는 계획을 건너뛰는 것이 맞음 (탐색적인 작업일 때)
• 때로는 모호한 프롬프트가 맞음 (Claude의 해석을 먼저 보고 싶을 때)

좋은 결과가 나왔을 때 무엇을 했는지 관찰하세요: 프롬프트 구조, 제공한 컨텍스트, 사용한 모드. 실패했을 때 원인을 분석하세요: 컨텍스트가 너무 시끄러웠는지, 프롬프트가 모호했는지, 작업이 한 번에 하기엔 컸는지.

부록 A. 빠른 참조 카드

키보드 단축키

Claude Code 내장 커맨드

CLI 실행 옵션

부록 B. 설정 파일 위치

마무리

이 38가지 Best Practice를 한 문장으로 요약하면: 컨텍스트를 아끼고, 검증을 제공하고, 전문가에게 위임하라입니다.

핵심 3가지

1. 컨텍스트가 곧 성능이다 — /clear를 두려워하지 말고, 서브에이전트로 탐색을 위임하고, CLAUDE.md는 간결하게 유지하세요. 두 번 실패하면 깨끗한 세션에서 다시 시작하는 것이 거의 항상 정답입니다 (BP-08, BP-20, BP-21).
2. 검증 수단이 가장 높은 ROI — “테스트 실행해”, “스크린샷 찍어”, “빌드 성공 확인해”를 프롬프트에 포함하는 것만으로 결과 품질이 극적으로 향상됩니다 (BP-11).
3. 적절한 모델에 적절한 작업을 — 파일 탐색에 Opus를 쓰는 것은 낭비이고, 아키텍처 설계에 Haiku를 쓰는 것은 위험합니다. 모델 라우팅을 의식적으로 관리하세요 (BP-19, BP-25).

이 가이드의 패턴은 시작점이지 절대 규칙이 아닙니다. 좋은 결과가 나왔을 때 무엇을 했는지 관찰하고, 실패했을 때 원인을 분석하여 자신만의 직감을 개발하세요.

참조 링크

Anthropic 공식 문서

커뮤니티 및 참고 자료

이 문서는 Anthropic 공식 Best Practices, 에이전트 팀 문서, Opus 4.6 가이드를 기반으로 실무 경험을 종합하여 작성되었습니다. 번호(BP-01~38)로 특정 항목을 빠르게 참조할 수 있습니다.

작성자: Twodragon 작성일: 2026년 2월 25일 카테고리: DevOps, AI Coding