Claude Code를 처음 쓰면 채팅창에서 AI에게 질문하는 것과 비슷하게 씁니다. 하지만 Claude Code는 그 이상입니다. 제대로 된 설정과 사용 방식으로 개발 워크플로 자체를 바꿀 수 있습니다.
프로젝트에서 Claude Code를 처음 쓰기 전에 CLAUDE.md를 먼저 작성합니다. 이 파일 하나가 모든 세션의 품질을 결정합니다.
# 최소 CLAUDE.md
## 명령어
- 테스트: `npm test`
- 빌드: `npm run build`
- 린트: `npm run lint`
## 중요 규칙
- any 타입 사용 금지
- 테스트 없는 기능 추가 금지
- .env 파일 수정 금지
/init으로 초안을 만들고 팀과 함께 보완합니다.
작업 지시에 항상 검증 기준을 함께 줍니다.
X: "이 함수 리팩토링해줘"
O: "이 함수 리팩토링해줘. 완료 후 npm test 실행해서
기존 테스트 전부 통과해야 해."
Claude Code가 스스로 검증하고, 실패하면 수정을 반복합니다.
파일 수정 후 린트나 포맷팅을 매번 직접 실행하는 것은 비효율적입니다.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "npm run lint --fix" }]
}
]
}
}
파일을 수정할 때마다 자동으로 린트가 실행됩니다.
하나의 요청이 클수록 에러 복구가 어렵고 검토가 힘듭니다.
X: "인증 모듈 전체 구현해줘"
O:
1. "User 엔티티 만들어줘"
2. "AuthService에 회원가입 로직 추가해줘"
3. "로그인 엔드포인트 추가해줘"
4. "JWT 인증 미들웨어 추가해줘"
각 단계 후에 코드를 확인하고 다음으로 넘어갑니다.
큰 작업 전에 계획을 먼저 확인합니다.
claude> /plan "결제 모듈을 PaymentService와 BillingService로 분리해줘"
계획이 예상과 다르면 수정 지시를 준 뒤 실행합니다. 잘못된 방향으로 파일을 수정한 뒤 되돌리는 것보다 훨씬 효율적입니다.
GitHub 이슈를 보면서 코드를 수정하고, 완료하면 PR을 자동으로 여는 워크플로를 만들 수 있습니다.
claude> "ISSUE-234 처리해줘"
Claude:
1. GitHub에서 이슈 내용 읽기
2. 관련 파일 수정
3. 테스트 통과 확인
4. PR 생성 후 이슈에 링크
GitHub MCP 연결 하나로 전체 이슈 처리 플로우가 자동화됩니다.
새 기능 시작 → 새 세션
기능 이어서 → --resume
무관한 새 작업 → /clear 또는 새 세션
긴 작업 중 → /compact (컨텍스트 관리)
세션을 작업 단위로 관리하면 컨텍스트가 오염되지 않습니다.
매번 설명하는 내용은 자동화합니다.
{
"hooks": {
"UserPromptSubmit": [{
"hooks": [{ "type": "command", "command": "node .claude/inject.js" }]
}]
}
}
// .claude/inject.js
const branch = require('child_process')
.execSync('git branch --show-current').toString().trim();
process.stdout.write(`작업 브랜치: ${branch}`);
Git 브랜치, 환경, 최근 변경 파일 등을 자동으로 컨텍스트에 추가합니다.
허용할 것과 금지할 것을 미리 정의합니다.
{
"permissions": {
"allow": ["Read", "Edit", "Write", "Bash(npm *)", "Bash(git add *)", "Bash(git commit *)"],
"deny": ["Bash(git push --force *)", "Bash(rm -rf *)"]
}
}
매번 확인을 받는 번거로움을 줄이되, 위험한 작업은 항상 차단합니다.
같은 절차를 반복한다면 Skill로 만듭니다.
<!-- .claude/skills/pr-ready.md -->
PR 제출 전 체크리스트:
1. npm test 실행 → 전부 통과 확인
2. npm run lint → 오류 없음 확인
3. 변경 파일 목록 출력
4. 커밋 메시지 검토
5. PR 제목과 설명 초안 작성
claude> /skills pr-ready
PR 준비 과정 전체가 명령 하나로 실행됩니다.