[공식문서읽기] Claude Code 모범 사례 1편 - 환경 구성으로 생산성 극대화하기

Claude Code는 단순한 챗봇이 아닌 에이전트 코딩 환경입니다. 파일을 읽고, 명령을 실행하고, 변경을 수행하며 자율적으로 문제를 해결할 수 있습니다. 이 글에서는 Claude Code의 환경을 최적으로 구성하여 생산성을 극대화하는 방법을 알아봅니다.

이 이미지는 AI가 생성한 이미지로, 글의 내용과 직접적인 관련이 없을 수 있습니다.

---

효과적인 CLAUDE.md 작성

CLAUDE.md는 Claude가 모든 대화의 시작 부분에서 읽는 특수 파일입니다. /init 명령으로 시작 파일을 생성한 다음 시간이 지남에 따라 개선하세요.

CLAUDE.md 작성 원칙

짧고 인간이 읽을 수 있도록 유지하세요. 각 라인에 대해 "이것을 제거하면 Claude가 실수를 할까?"라고 물어보세요. 그렇지 않으면 삭제하세요.

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

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

포함해야 할 것 vs 제외해야 할 것

제외	포함
Claude가 추측할 수 없는 Bash 명령	Claude가 코드를 읽어서 파악할 수 있는 것
기본값과 다른 코드 스타일 규칙	Claude가 이미 알고 있는 표준 언어 규칙
테스트 지시사항 및 선호하는 테스트 러너	상세한 API 문서(대신 문서에 링크)
저장소 에티켓(브랜치 이름 지정, PR 규칙)	자주 변경되는 정보
프로젝트에 특정한 아키텍처 결정	긴 설명 또는 튜토리얼
개발자 환경 특이성(필수 환경 변수)	파일별 코드베이스 설명

CLAUDE.md 파일 위치

• 홈 폴더(~/.claude/CLAUDE.md): 모든 Claude 세션에 적용
• 프로젝트 루트(./CLAUDE.md): git에 체크인하여 팀과 공유
• 상위 디렉토리: 모노레포에 유용
• 하위 디렉토리: 해당 디렉토리의 파일로 작업할 때 자동 로드

이 이미지는 AI가 생성한 이미지로, 글의 내용과 직접적인 관련이 없을 수 있습니다.

권한 구성

기본적으로 Claude Code는 시스템을 수정할 수 있는 작업에 대한 권한을 요청합니다. /permissions를 사용하여 안전한 명령을 허용 목록에 추가하거나 /sandbox를 사용하여 OS 수준 격리를 수행하세요.

권한 허용 목록

안전하다고 알고 있는 특정 도구를 허용합니다(예: npm run lint 또는 git commit).

샌드박싱

Claude가 정의된 경계 내에서 더 자유롭게 작동할 수 있도록 OS 수준 격리를 활성화합니다.

---

CLI 도구 사용

Claude Code에 gh, aws, gcloud, sentry-cli와 같은 CLI 도구를 사용하여 외부 서비스와 상호 작용하도록 하세요.

CLI 도구는 외부 서비스와 상호 작용하는 가장 context 효율적인 방법입니다. GitHub를 사용하면 gh CLI를 설치하세요. Claude는 이슈 생성, pull request 열기, 댓글 읽기에 사용하는 방법을 알고 있습니다.

Claude는 아직 알지 못하는 CLI 도구를 배우는 데도 효과적입니다:

Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.

---

MCP 서버 연결

claude mcp add를 실행하여 Notion, Figma 또는 데이터베이스와 같은 외부 도구를 연결하세요.

MCP 서버를 사용하면 다음이 가능합니다:

• 이슈 추적기에서 기능 구현
• 데이터베이스 쿼리
• 모니터링 데이터 분석
• Figma에서 디자인 통합
• 워크플로우 자동화

---

Hooks 설정

Hooks는 Claude의 워크플로우의 특정 지점에서 자동으로 스크립트를 실행합니다. CLAUDE.md 지시사항은 권고사항이지만 hooks는 결정론적이고 작업이 발생함을 보장합니다.

Claude가 hooks를 작성할 수 있습니다:

• "모든 파일 편집 후 eslint를 실행하는 hook을 작성하세요"
• "마이그레이션 폴더에 대한 쓰기를 차단하는 hook을 작성하세요"

대화형 구성을 위해 /hooks를 실행하거나 .claude/settings.json을 직접 편집하세요.

---

Skills 생성

Skills는 프로젝트, 팀 또는 도메인에 특정한 정보로 Claude의 지식을 확장합니다. .claude/skills/에 SKILL.md가 있는 디렉토리를 추가하여 skill을 생성하세요.

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

Skills는 직접 호출하는 반복 가능한 워크플로우를 정의할 수도 있습니다. /fix-issue 1234와 같이 호출할 수 있습니다.

---

사용자 정의 Subagents 생성

Subagents는 자신의 context와 자신의 허용된 도구 세트로 실행됩니다. 많은 파일을 읽거나 주 대화를 복잡하게 하지 않고 전문화된 초점이 필요한 작업에 유용합니다.

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

---

Plugins 설치

Plugins는 커뮤니티 및 Anthropic의 마켓플레이스에서 설치 가능한 단일 단위로 skills, hooks, subagents, MCP 서버를 번들로 제공합니다.

/plugin을 실행하여 마켓플레이스를 탐색하세요. 타입이 지정된 언어로 작업하면 코드 인텔리전스 plugin을 설치하여 Claude에 정확한 기호 탐색 및 편집 후 자동 오류 감지를 제공하세요.

---

마무리

Claude Code의 환경을 제대로 구성하면 모든 세션에서 훨씬 더 효과적으로 작업할 수 있습니다. CLAUDE.md를 간결하게 유지하고, 필요한 권한을 미리 설정하고, CLI 도구와 MCP 서버를 활용하세요.

핵심 포인트:

• CLAUDE.md는 짧고 명확하게 유지
• /init으로 시작하여 점진적으로 개선
• Hooks로 결정론적 작업 보장
• Skills와 Subagents로 전문화된 워크플로우 구축

---

참고 자료

• Claude Code 모범 사례 공식 문서
• Claude Code 확장 기능
• CLAUDE.md 메모리 가이드

이 글은 Claude Code를 활용하여 작성되었습니다.