[개발 가이드] Claude Code 제대로 쓰는 법: Anthropic이 공개한 8가지 베스트 프랙티스

최근 공개된 Claude Code는 단순한 코딩 어시스턴트를 넘어, 직접 파일을 수정하고 터미널 명령어를 실행하는 '에이전트'형 도구입니다. 하지만 강력한 만큼 제대로 쓰는 법을 아는 것이 중요합니다. Anthropic 공식 문서( https://code.claude.com/docs/en/best-practices )를 바탕으로, Claude Code의 성능을 극대화하는 꿀팁을 정리했습니다. 

 

---

1. 핵심 철학: "검증 가능하게 지시하라"

Claude Code를 사용할 때 가장 중요한 한 가지를 꼽으라면 바로 **'검증 수단 제공'**입니다. Claude가 코드를 짠 후 잘 돌아가는지 스스로 확인할 수 있게 해주세요.

• Bad: "이메일 유효성 검사 함수 만들어줘."
• Good: "이메일 유효성 검사 함수를 만들고, test.js에 있는 테스트 케이스를 실행해서 통과하는지 확인해줘."
• 효과: 여러분이 일일이 코드를 확인할 필요 없이, Claude가 스스로 오류를 잡고 수정까지 마칩니다.

---

2. 3단계 워크플로우: 탐색 → 계획 → 구현

무작정 코딩부터 시키면 산으로 갈 수 있습니다. Claude Code의 Plan Mode를 적극 활용하세요.

1. 탐색 (Explore): Plan Mode에서 현재 코드 구조와 로직을 파악하게 합니다.
2. 계획 (Plan): 어떤 파일을 수정할지, 어떤 로직을 추가할지 계획을 세우게 합니다.
3. 구현 (Implement): Normal Mode로 전환해 계획대로 코드를 작성하고 테스트하게 합니다.
   • Tip: 수정 사항이 아주 간단하다면(오타 등) 바로 구현을 요청해도 됩니다.

---

3. '컨텍스트'는 금이다: 세션 관리의 기술

Claude의 성능은 대화 내용(컨텍스트 창)이 길어질수록 조금씩 떨어질 수 있습니다. 이를 관리하는 것이 실력입니다.

• /clear: 작업 주제가 바뀌면 이전 대화 내역을 지워 컨텍스트를 초기화하세요.
• /compact: 대화가 너무 길어지면 중요한 맥락만 남기고 압축하세요.
• 서브에이전트 활용: "서브에이전트를 써서 라이브러리 문서를 조사해와"라고 시키세요. 메인 대화창은 깨끗하게 유지하면서 정보만 쏙 가져올 수 있습니다.

---

4. 우리 팀만의 규칙, CLAUDE.md 활용하기

프로젝트 루트에 CLAUDE.md 파일을 만들면, Claude가 매 세션마다 이 파일을 읽고 프로젝트 특성을 파악합니다.

• 포함할 내용: 빌드 명령어, 테스트 실행법, 선호하는 코드 스타일(예: "세미콜론 생략"), 프로젝트 특유의 아키텍처 규칙.
• 장점: 매번 "우리 프로젝트는 이렇게 짜야 해"라고 설명할 필요가 없어집니다.

---

5. 프롬프트는 구체적일수록 좋다

Claude는 독심술사가 아닙니다. 구체적인 가이드를 줄수록 결과물이 좋아집니다.

• @파일명: "그 파일"이라고 하지 말고 @src/auth.ts 처럼 직접 지칭하세요.
• 패턴 참조: "이미 구현된 @Notification.tsx 의 디자인 패턴을 참고해서 새로운 모달을 만들어줘"라고 지시하세요.
• 이미지 활용: UI 수정 시에는 스크린샷을 터미널에 직접 붙여넣어 시각적인 피드백을 주세요.

---

6. CLI 도구와 MCP로 날개 달기

Claude Code는 터미널 도구를 직접 다룰 수 있습니다.

• CLI 도구: gh(GitHub CLI), aws, npm 등을 설치해두면 Claude가 직접 PR을 올리거나 인프라 설정을 확인합니다.
• MCP (Model Context Protocol): 외부 데이터베이스나 Notion, Figma 등을 연결하면 Claude가 코드 밖의 정보까지 참조하여 작업합니다.

---

7. 실수했을 땐? '되감기(Rewind)'와 '인터뷰'

• /rewind: Claude가 코드를 망쳐놨다면 당황하지 마세요. 체크포인트 기능을 통해 이전 상태(코드 및 대화)로 되돌릴 수 있습니다.
• 나를 인터뷰해줘: 큰 기능을 만들 땐 "이 기능을 구현하기 위해 필요한 정보를 나한테 질문해줘"라고 시켜보세요. 여러분이 놓친 엣지 케이스를 Claude가 먼저 짚어줍니다.

---

마치며: Claude Code는 동료 엔지니어입니다

Claude Code를 단순한 '도구'가 아니라 '함께 일하는 주니어~미들급 엔지니어' 라고 생각해보세요. 명확한 업무 지시를 내리고, 결과물을 검토할 수 있는 환경(테스트)을 만들어준다면, 여러분의 생산성은 상상 이상으로 높아질 것입니다.