CLAUDE.md로 시작하는 Claude Code 프로젝트 장악 전략

Claude Code를 단순 코드 생성기로 쓰고 있다면, 절반도 못 쓰는 거다. 컨텍스트를 심어주고 검증 루프를 닫는 순간, 결과물의 질이 완전히 달라진다.

---

컨텍스트가 없으면 AI는 같은 실수를 반복한다

처음 Claude Code를 쓸 때 가장 많이 낭비한 게 토큰이었다. 매 대화마다 "우리 프로젝트는 TypeScript 써", "테스트는 npm test로 해", "클래스 말고 함수형으로 작성해"를 반복해서 설명해야 했다. Claude가 멍청한 게 아니라, 내가 컨텍스트를 안 줬던 거다.

해결책은 단순하다. 프로젝트 루트에 CLAUDE.md 파일 하나를 두면 된다.

# CLAUDE.md 예시
## Tech Stack
- Runtime: Node.js 20, TypeScript 5
- Workflow Engine: n8n (self-hosted)
- Test: npm test (Jest)

## Coding Style
- 함수형 프로그래밍 우선, class 사용 금지
- 파일명: kebab-case
- 비동기: async/await, Promise 체이닝 금지

## Folder Structure
src/
  services/   # 비즈니스 로직
  routes/     # API 엔드포인트
  utils/      # 공통 유틸

이 파일을 추가한 뒤 컨텍스트 재설명에 드는 토큰 비용이 체감상 30~40% 줄었다. Claude가 파일을 읽는 순간, 10년 경력 시니어처럼 프로젝트 문화를 파악하고 움직인다.

---

n8n을 신경계로, Claude Code를 두뇌로

n8n과 Claude Code를 같이 쓰기 시작하면서 관점이 바뀌었다. n8n은 시스템의 신경계다. 에러를 감지하고 신호를 보낸다. Claude Code는 두뇌다. 신호를 받아서 분석하고 판단한다.

실제로 적용한 패턴은 이렇다. n8n 워크플로우에서 특정 에러 로그가 발생하면, 해당 로그를 Claude Code에 자동으로 전달해 원인 분석과 수정안 제안을 받는 구조다.

IDE에서 코드를 짜는 것과 전체 시스템 흐름 안에서 수정하는 건 다른 차원의 일이다. 냉장고 재고까지 파악하고 요리하는 셰프와, 레시피만 보는 요리사의 차이라고 보면 된다.

---

명령 순서가 결과의 품질을 결정한다

"이 버그 고쳐줘"라고만 하면 Claude가 엉뚱한 파일을 건드릴 수 있다. 작업 순서를 명확하게 가져가야 한다.

1단계: 구조 파악 먼저

claude "Run ls -R and summarize the folder structure before making any changes"

2단계: 범위를 좁혀서 수정 지시

claude "Analyze the error in auth.ts line 42 and suggest a fix. Do not modify other files."

3단계: 테스트로 검증

claude "Fix the bug in user_service.py and run pytest to verify the result"

단계를 나눌수록 AI가 시스템을 망가뜨리는 리스크가 줄어든다. 한 번에 모든 걸 시키면 Claude는 최선을 다하지만, 그 최선이 의도와 다를 수 있다.

---

피드백 루프를 닫아야 진짜 자동화다

수정 명령을 내리는 것만으로는 절반이다. 반드시 검증이 따라와야 한다. 테스트가 없으면 Claude가 짠 코드를 믿고 올리기 불안하고, 그 불안감이 결국 수작업 검토로 이어진다.

# 수정 + 검증을 하나의 명령으로
claude "Fix the authentication bug in auth.ts, then run npm test and report the results"

기대 출력:

✓ auth.test.ts — 12 tests passed
✓ user.test.ts — 8 tests passed
All tests passed. Changes are safe to commit.

이 루프가 완성되면 "AI가 짠 코드"라는 심리적 불안이 사라진다. 테스트가 통과했다는 사실 자체가 배포 근거가 된다.

---

마무리

CLAUDE.md로 컨텍스트를 심고, 단계적 명령으로 범위를 제한하고, 테스트로 루프를 닫는다. 이 세 가지가 갖춰지면 Claude Code는 코드 생성기가 아니라 실제로 같이 일하는 동료가 된다.

다음 글에서는 이 구조를 n8n 자동화 파이프라인에 직접 연결해 에러 감지부터 PR 생성까지 무인 운영하는 방법을 다룰 예정이다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 활용
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독