모과이의꿈

최근 Claude Code와 Codex를 같이 사용하면서 한 가지 변화가 눈에 들어왔다.

예전에는 Claude Code에서 Codex를 연결하는 방법을 찾다 보면 codex mcp-server를 이용하는 방식이 자주 나왔다.

그런데 2026년 8월 24일 OpenAI가 공식 릴리스 노트에서 codex mcp-server 명령을 deprecated 처리했다.

그리고 Claude Code 안에서 Codex를 사용할 경우에는 Codex plugin for Claude Code를 사용하라고 공식적으로 안내하기 시작했다.

나도 처음에는 “MCP로 연결하던 것을 이제 못 쓰는 건가?”라는 생각이 들었는데, 정확히 보면 Codex 자체가 없어지는 것이 아니라 연결 방식이 바뀌는 쪽에 가깝다.

현재 공식 플러그인은 Claude Code 안에서 Codex에게 코드 리뷰를 맡기거나, 별도의 작업을 위임하거나, Claude Code에서 진행하던 작업을 Codex 쪽으로 넘겨서 이어갈 수 있게 만들어져 있다.

결론부터 말하면 개인적으로는 이제 Claude Code와 Codex를 같이 쓸 생각이라면 예전 codex mcp-server 방식보다 OpenAI가 직접 제공하는 Codex plugin for Claude Code를 사용하는 것이 가장 자연스럽다.

[사용 기준]

Claude Code
현재 프로젝트를 분석하고 구현 작업을 진행

Codex
코드 리뷰, 별도 문제 조사, 다른 관점의 검증, 작업 인계

Codex plugin for Claude Code
Claude Code 안에서 필요할 때 Codex를 바로 호출하고 결과를 다시 받는 연결 역할

이번 글에서는 현재 기준으로 Claude Code에 Codex를 연결하는 방법과 실제로 어떤 식으로 사용할 수 있는지 정리해보려고 한다.


1. 먼저 codex mcp-server가 어떻게 바뀌었는지 알아야 한다

OpenAI는 2026년 8월 24일 공식 Codex 릴리스 노트에서 codex mcp-server 명령을 deprecated 처리했다.

deprecated는 바로 삭제됐다는 뜻은 아니다.

기존 기능을 앞으로 계속 사용하는 것을 권장하지 않고 새로운 방식으로 옮겨가라는 의미에 가깝다.

OpenAI의 공식 안내는 명확하다.

codex mcp-server 대신 Codex app server를 사용하고, Claude Code에서 Codex를 사용할 때는 Codex plugin for Claude Code를 사용하라는 것이다.

따라서 인터넷에서 예전 자료를 보고 다음 방식으로 연결하려고 했다면 최신 방법을 다시 확인하는 것이 좋다.

[이전 방식]

codex mcp-server

현재는 이 명령을 중심으로 새 환경을 구성하기보다 공식 Claude Code용 Codex 플러그인을 사용하는 것이 맞다.

이 부분은 검색해서 오래된 블로그 글이나 예전 설정 예제를 따라갈 때 특히 주의할 필요가 있다.


2. Codex plugin for Claude Code는 무엇인가

OpenAI가 공개한 Codex plugin for Claude Code는 말 그대로 Claude Code 안에서 Codex를 사용할 수 있게 해주는 공식 플러그인이다.

이 플러그인을 설치하면 Claude Code에서 별도의 터미널을 열고 Codex CLI 명령을 직접 입력하지 않아도 Codex에게 작업을 맡길 수 있다.

현재 공식 플러그인에서 제공하는 주요 기능은 다음과 같다.

[주요 기능]

/codex:review
현재 변경사항을 Codex에게 코드 리뷰시킨다.

/codex:adversarial-review
현재 구현 방향이나 설계를 다른 관점에서 비판적으로 검토한다.

/codex:rescue
버그 조사나 수정 같은 작업을 Codex에게 별도로 위임한다.

/codex:transfer
현재 Claude Code 세션을 Codex 세션으로 넘겨서 이어서 작업한다.

/codex:status
백그라운드에서 실행 중인 Codex 작업 상태를 확인한다.

/codex:result
완료된 Codex 작업 결과를 확인한다.

/codex:cancel
실행 중인 Codex 작업을 취소한다.

쉽게 말하면 Claude Code를 메인 작업 공간으로 사용하면서 필요할 때 Codex를 보조 개발자처럼 호출하는 구조다.


3. 설치 전에 필요한 조건

현재 OpenAI 공식 저장소 기준으로 기본 요구사항은 크게 두 가지다.

[필요 조건]

ChatGPT 계정 또는 OpenAI API Key

Node.js 18.18 이상

ChatGPT 구독은 Free를 포함해 사용할 수 있다고 공식 저장소에서 안내하고 있다.

다만 Codex를 사용한 만큼 Codex 사용량 제한에 포함된다.

즉 Claude Code에서 플러그인으로 Codex를 호출한다고 해서 Codex 사용량이 무료로 별도 제공되는 것은 아니다.

이미 PC에서 Codex CLI를 사용하고 있다면 기존 Codex 로그인 상태와 설정을 그대로 이용한다.

이 부분도 생각보다 중요하다.

플러그인이 별도의 Codex를 새로 실행하는 것이 아니라 내 컴퓨터에 설치된 Codex CLI와 Codex app server를 이용하기 때문이다.


4. Claude Code에서 Codex 플러그인 설치하기

설치는 Claude Code 안에서 진행할 수 있다.

먼저 OpenAI의 Codex plugin marketplace를 추가한다.

[명령어]

/plugin marketplace add openai/codex-plugin-cc

그 다음 Codex 플러그인을 설치한다.

[명령어]

/plugin install codex@openai-codex

플러그인을 설치한 뒤 다시 불러온다.

[명령어]

/reload-plugins

마지막으로 Codex 연결 상태를 확인한다.

[명령어]

/codex:setup

현재 공식 문서 기준으로 이 순서가 기본 설치 방법이다.

개인적으로는 설치 후 바로 다른 명령부터 실행하기보다 /codex:setup으로 Codex CLI 설치 여부와 인증 상태를 먼저 확인하는 편이 좋다고 생각한다.


5. Codex CLI가 설치되어 있지 않다면

/codex:setup을 실행했는데 Codex가 설치되어 있지 않으면 npm을 사용할 수 있는 환경에서는 플러그인이 설치를 도와줄 수 있다.

직접 설치하고 싶다면 다음 명령을 사용한다.

[명령어]

npm install -g @openai/codex

설치가 끝났다면 터미널에서 Codex가 정상적으로 실행되는지 확인한다.

[명령어]

codex

이미 Codex CLI를 사용하던 사람이라면 이 과정은 필요하지 않을 수 있다.


6. Codex 로그인이 안 되어 있다면

플러그인은 내 PC에 설치된 Codex CLI의 인증 상태를 그대로 사용한다.

따라서 Codex CLI가 설치되어 있어도 아직 로그인하지 않았다면 먼저 인증이 필요하다.

Claude Code 안에서 쉘 명령으로 로그인하려면 다음처럼 사용할 수 있다.

[명령어]

!codex login

또는 Claude Code 밖의 일반 터미널에서 다음 명령을 실행해도 된다.

[명령어]

codex login

로그인이 완료되면 다시 Claude Code에서 다음 명령으로 상태를 확인한다.

[명령어]

/codex:setup

기존에 Codex CLI를 정상적으로 사용하고 있었다면 별도의 계정을 다시 만드는 것이 아니라 기존 인증 상태를 그대로 사용한다.


7. 설치가 제대로 됐는지 가장 간단하게 확인하는 방법

처음에는 복잡한 기능보다 코드 리뷰부터 실행해보는 것이 가장 쉽다.

현재 작업 중인 프로젝트에서 코드가 변경된 상태라면 다음 명령을 실행한다.

[명령어]

/codex:review

그러면 Codex가 현재 변경사항을 읽고 코드 리뷰를 수행한다.

OpenAI 공식 문서에서는 이 기능을 read-only 리뷰로 설명하고 있다.

즉 /codex:review 자체는 코드를 직접 수정하지 않고 문제점과 개선할 부분을 검토하는 용도다.

여러 파일을 수정한 큰 작업이라면 시간이 걸릴 수 있어서 백그라운드 실행도 지원한다.

[명령어]

/codex:review --background

진행 상태는 다음 명령으로 확인한다.

[명령어]

/codex:status

작업이 끝난 뒤 결과를 확인한다.

[명령어]

/codex:result

개인적으로는 처음 설치한 뒤 이 세 가지를 순서대로 실행해보면 연결 여부를 확인하기 편하다.


8. Claude Code가 만든 코드를 Codex에게 리뷰시키는 방식이 가장 이해하기 쉽다

Claude Code와 Codex를 같이 쓴다고 해서 두 AI에게 똑같은 일을 동시에 시킬 필요는 없다.

오히려 개인적으로는 역할을 나누는 편이 더 자연스럽다고 생각한다.

예를 들어 Claude Code에게 기능을 구현시킨다.

[프롬프트 예시]

“현재 로그인 기능의 문제를 확인하고 필요한 부분을 수정해줘. 수정이 끝나면 테스트도 확인해줘.”

Claude Code가 작업을 마쳤다.

그 다음 Codex에게 현재 변경사항을 검토하게 한다.

[명령어]

/codex:review

이렇게 하면 하나의 AI가 작성한 코드를 다른 AI가 다시 검토하는 구조가 된다.

물론 Codex 리뷰 결과 역시 무조건 맞다고 보면 안 된다.

최종적으로는 개발자가 Git diff와 테스트 결과를 확인해야 한다.

하지만 같은 모델과 같은 대화 흐름 안에서 계속 검토하는 것보다 다른 에이전트의 관점으로 한번 더 확인한다는 점에서는 꽤 의미가 있다.


9. 일반 리뷰보다 더 강하게 검증하고 싶다면 adversarial-review

단순히 버그나 코드 품질을 확인하는 것보다 현재 설계 자체가 맞는지 의심해보고 싶을 때도 있다.

이럴 때 사용할 수 있는 것이 다음 명령이다.

[명령어]

/codex:adversarial-review

이 기능은 현재 구현 방향과 가정, 트레이드오프, 실패 가능성 등을 비판적으로 검토하는 용도다.

특정 부분에 집중해서 검토하게 할 수도 있다.

[명령어]

/codex:adversarial-review 인증 처리에서 보안상 놓친 부분이 없는지 집중해서 확인

일반 /codex:review와 다른 점은 내가 어떤 관점으로 검토할지 추가로 지시할 수 있다는 것이다.

개인적으로는 인증, 결제, 데이터 삭제, 동시성처럼 문제가 생기면 영향이 큰 코드에서 이런 식의 2차 검증이 유용할 수 있다고 생각한다.


10. 해결이 잘 안 되는 문제를 Codex에게 넘길 수도 있다

Claude Code로 한참 디버깅했는데 해결이 잘 안 되는 문제가 있을 수도 있다.

이럴 때는 현재 Claude Code 세션을 계속 끌고 가면서 같은 방향으로 반복하는 것보다 Codex에게 별도의 작업으로 조사시켜볼 수 있다.

[명령어]

/codex:rescue 테스트가 CI에서만 실패하는 이유를 조사해줘

/codex:rescue는 Codex에게 별도의 작업을 위임하는 기능이다.

버그 원인 조사뿐 아니라 실제 수정도 맡길 수 있다.

[명령어]

/codex:rescue 실패하는 테스트를 확인하고 가장 작은 범위로 수정해줘

작업 시간이 길 것 같다면 백그라운드로 실행할 수도 있다.

[명령어]

/codex:rescue --background 간헐적으로 실패하는 테스트 원인을 조사해줘

그리고 Claude Code에서는 다른 작업을 계속하면서 상태를 확인한다.

[명령어]

/codex:status

완료된 결과는 다음 명령으로 확인한다.

[명령어]

/codex:result

이 방식은 한 AI가 막혔을 때 같은 프롬프트를 계속 반복하는 것보다 다른 모델에게 독립적으로 문제를 풀게 한다는 점에서 재미있다.


11. Claude Code에서 하던 작업을 Codex로 그대로 넘길 수도 있다

현재 플러그인에서 개인적으로 흥미로운 기능이 /codex:transfer다.

[명령어]

/codex:transfer

이 명령은 현재 Claude Code 세션 내용을 기반으로 Codex에서 이어서 사용할 수 있는 세션을 만든다.

실행이 끝나면 Codex에서 해당 작업을 이어갈 수 있는 resume 명령을 알려준다.

즉 이런 흐름이 가능하다.

[사용 흐름]

Claude Code에서 요구사항 분석

Claude Code에서 구현 시작

필요한 시점에 /codex:transfer

Codex 세션 생성

Codex CLI나 Codex App에서 같은 작업 흐름을 계속 진행

예전에는 Claude Code에서 작업한 내용을 Codex에게 다시 설명해야 했다면, 이제는 세션 자체를 넘기는 흐름이 공식적으로 제공되는 셈이다.

다만 세션이 넘어간다고 해서 두 AI의 내부 컨텍스트가 완전히 동일해지는 것은 아니다.

플러그인이 Claude의 대화 기록을 Codex가 이어갈 수 있는 형태로 변환해서 새로운 Codex 세션을 만드는 방식이다.

따라서 중요한 변경사항은 여전히 현재 Git 상태와 파일을 확인하는 것이 안전하다.


12. Codex 작업 결과를 Codex에서 직접 이어갈 수도 있다

/codex:rescue처럼 Codex에게 위임한 작업이 끝난 뒤 결과만 Claude Code에서 확인할 수도 있다.

하지만 해당 Codex 작업을 더 깊게 이어서 하고 싶다면 Codex 세션으로 직접 이동할 수도 있다.

/codex:result 또는 /codex:status 결과에서 Codex 세션 ID를 확인할 수 있다.

그 다음 일반 터미널에서 다음처럼 실행한다.

[명령어]

codex resume 세션ID

그러면 Claude Code에서 위임했던 Codex 작업을 Codex CLI에서 직접 이어갈 수 있다.

개인적으로는 간단한 검토는 Claude Code 안에서 끝내고, Codex 쪽 작업이 커지기 시작하면 아예 Codex 세션으로 넘어가는 방식도 괜찮아 보인다.


13. 기존 Codex 설정도 그대로 적용된다

이미 Codex CLI를 사용하고 있었다면 모델이나 reasoning effort 같은 설정을 config.toml에 저장해둔 경우가 있을 수 있다.

공식 플러그인은 별도의 Codex 설정을 새로 만드는 것이 아니라 기존 Codex 설정을 그대로 사용한다.

사용자 전체 설정은 다음 위치를 사용할 수 있다.

[파일 위치]

~/.codex/config.toml

프로젝트별 설정은 프로젝트 루트에 다음처럼 둘 수 있다.

[파일 위치]

.codex/config.toml

예를 들어 프로젝트에서 사용할 기본 모델과 reasoning effort를 지정할 수도 있다.

[설정 예시]

model = "gpt-5.4-mini"

model_reasoning_effort = "high"

현재 사용 가능한 모델이나 설정 옵션은 계속 바뀔 수 있으므로 실제 사용할 때는 최신 Codex 공식 문서를 같이 확인하는 것이 좋다.


14. Claude Code와 Codex가 서로 같은 사용량을 공유하는 것은 아니다

이 부분도 헷갈릴 수 있다.

Claude Code에서 Codex 플러그인을 실행한다고 해서 모든 작업이 Claude 사용량으로만 처리되는 것은 아니다.

플러그인을 통해 Codex를 호출하면 해당 작업은 Codex 사용량에 포함된다.

OpenAI 공식 저장소에서도 플러그인 사용량이 Codex usage limit에 포함된다고 안내하고 있다.

쉽게 말하면 다음과 같다.

[사용 기준]

Claude Code가 직접 수행한 작업

Claude 쪽 사용량에 영향


Codex plugin을 통해 Codex가 수행한 작업

Codex 쪽 사용량에 영향


따라서 Claude 사용량을 아끼려고 모든 작업을 Codex로 넘기는 식으로 사용하면 반대로 Codex 사용량이 빠르게 소모될 수 있다.

두 도구의 사용량을 모두 생각하면서 역할을 나누는 것이 좋다.


15. review gate는 편하지만 처음부터 켜는 것은 조심하는 것이 좋다

Codex 플러그인에는 Claude가 작업을 끝내려고 할 때 Codex 리뷰를 자동으로 실행하는 review gate 기능도 있다.

다음 명령으로 활성화할 수 있다.

[명령어]

/codex:setup --enable-review-gate

끄려면 다음 명령을 사용한다.

[명령어]

/codex:setup --disable-review-gate

기능만 보면 상당히 편해 보인다.

Claude가 작업을 마친다.

Codex가 자동으로 검토한다.

문제가 발견되면 Claude가 다시 수정한다.

하지만 OpenAI 공식 저장소에서도 이 기능에 대해 주의사항을 명확하게 적어두고 있다.

Claude와 Codex 사이에 긴 반복 루프가 만들어질 수 있고 두 도구의 사용량 제한을 빠르게 소비할 수 있기 때문이다.

개인적으로도 처음부터 자동 검토를 항상 켜두기보다 중요한 작업에서 필요할 때 직접 /codex:review를 실행하는 편이 관리하기 쉽다고 생각한다.


16. 예전 MCP 방식과 지금 플러그인 방식의 차이

예전 codex mcp-server 방식은 Claude Code가 MCP를 통해 Codex와 연결되는 형태였다.

현재 공식 Codex plugin for Claude Code는 구조가 조금 다르다.

플러그인이 내 컴퓨터의 Codex CLI와 Codex app server를 이용해서 Codex 작업을 실행한다.

[현재 구조]

Claude Code

↓

Codex plugin for Claude Code

↓

로컬 Codex CLI + Codex app server

↓

Codex 작업 실행

즉 별도의 원격 Codex 계정을 플러그인 안에 새로 만드는 방식이 아니다.

이미 설치되어 있는 Codex와 같은 인증 상태, 같은 설정, 같은 프로젝트 체크아웃과 로컬 환경을 사용한다.

이 부분이 개인적으로는 현재 방식의 가장 큰 장점 중 하나라고 생각한다.


17. Claude Code와 Codex를 같이 쓴다고 무조건 결과가 좋아지는 것은 아니다

두 AI를 연결하면 뭔가 자동으로 코드 품질이 두 배 좋아질 것처럼 생각하기 쉽다.

하지만 실제 개발에서는 그렇게 단순하지 않다.

같은 코드에 두 AI가 서로 다른 의견을 낼 수도 있다.

한쪽의 잘못된 제안을 다른 쪽이 그대로 받아들일 수도 있다.

불필요하게 두 모델을 계속 왕복시키면 사용량만 크게 늘어날 수도 있다.

그래서 개인적으로는 역할을 명확하게 나누는 편이 낫다고 생각한다.

[사용 기준]

Claude Code

현재 프로젝트의 메인 구현 작업


Codex review

Claude가 만든 변경사항 검토


Codex adversarial-review

설계나 위험 요소에 대한 2차 검증


Codex rescue

Claude에서 잘 풀리지 않는 문제를 별도로 조사


Codex transfer

Claude에서 시작한 작업을 Codex 중심으로 계속 진행하고 싶을 때


이 정도로 역할을 나누면 두 도구가 서로 같은 일을 반복하는 것을 줄일 수 있다.


18. 내가 실제 프로젝트에서 사용한다면 이런 흐름이 가장 현실적이다

개인적으로는 모든 작업마다 Claude와 Codex를 동시에 사용하는 것보다 중요한 작업에서 검증 단계에 Codex를 넣는 방식이 가장 현실적이라고 생각한다.

예를 들어 다음과 같다.

[실제 사용 흐름]

1) Claude Code에서 요구사항 정리

2) Claude Code에서 관련 파일 분석

3) Claude Code에서 구현

4) Git diff 확인

5) /codex:review로 Codex 검토

6) 지적된 내용 중 실제로 필요한 것만 개발자가 판단

7) Claude Code 또는 직접 코드 수정

8) 빌드와 테스트 확인

이 흐름이면 Claude와 Codex를 경쟁시키는 것이 아니라 역할을 나눠서 사용할 수 있다.

특히 경력이 있는 개발자라면 두 AI의 결과 중 무엇을 반영해야 하는지 판단하는 과정 자체가 중요하다고 생각한다.


19. 설치 후 내가 먼저 확인할 명령어

설치를 처음 했다면 모든 명령을 한 번에 외울 필요는 없다.

개인적으로는 다음 정도만 먼저 알아도 충분하다.

[자주 사용할 명령어]

/codex:setup

Codex 설치와 로그인 상태 확인


/codex:review

현재 변경사항 코드 리뷰


/codex:rescue

별도의 문제를 Codex에게 위임


/codex:status

백그라운드 작업 상태 확인


/codex:result

완료된 결과 확인


/codex:transfer

현재 Claude Code 작업을 Codex로 넘기기


이 정도를 사용하다가 필요하면 adversarial-review나 review gate 같은 기능을 추가로 사용하는 편이 좋다.


20. 기존 codex mcp-server 설정이 있다면 어떻게 해야 할까

이미 codex mcp-server를 사용하고 있다고 해서 당장 모든 환경이 작동하지 않는다는 뜻은 아니다.

현재 OpenAI 표현은 removed가 아니라 deprecated다.

따라서 기존 환경이 당장 깨졌다고 단정할 필요는 없다.

다만 새로 구성하거나 앞으로 계속 사용할 환경이라면 공식적으로 권장되는 Codex plugin for Claude Code 쪽으로 옮기는 것이 맞다.

특히 블로그나 오래된 가이드에서 codex mcp-server 명령을 보고 처음 설치하는 사람이라면 현재 OpenAI 릴리스 노트를 먼저 확인하는 것이 좋다.

개인적으로는 deprecated 된 방식을 새 프로젝트에 다시 구축하기보다 현재 공식 플러그인을 사용하는 편이 유지보수 측면에서도 안전하다고 생각한다.


21. 결론: 이제 Claude Code에서 Codex를 쓸 때는 공식 플러그인이 기준이다

Claude Code와 Codex를 같이 사용하는 방법은 최근에 꽤 명확해졌다.

2026년 8월 24일 OpenAI가 codex mcp-server를 deprecated 처리했고, Claude Code에서 Codex를 사용할 때는 Codex plugin for Claude Code를 사용하라고 공식 안내했다.

현재 플러그인을 설치하면 Claude Code 안에서 Codex에게 코드 리뷰를 맡기고, 별도 작업을 위임하고, 백그라운드 작업을 관리하고, 필요하면 현재 Claude 세션을 Codex 쪽으로 넘겨서 이어갈 수도 있다.

개인적으로는 Claude Code와 Codex를 무조건 동시에 돌리는 것보다 역할을 나눠 사용하는 것이 가장 현실적이라고 생각한다.

Claude Code에서 구현한다.

Codex에서 한번 더 검증한다.

Claude에서 잘 풀리지 않는 문제는 Codex에 별도로 맡긴다.

작업 성격에 따라 필요하면 아예 Codex로 넘겨서 계속한다.

이 정도로 사용하면 두 AI를 같은 프로젝트에서 꽤 자연스럽게 같이 활용할 수 있다.

그리고 가장 중요한 것은 두 AI가 모두 같은 결론을 냈다고 해서 그 결과가 자동으로 정답이 되는 것은 아니라는 점이다.

최종 Git diff, 빌드, 테스트, 보안상 영향은 결국 개발자가 직접 확인해야 한다.

한 줄로 정리하면 이렇다.

2026년 8월 현재 Claude Code에서 Codex를 같이 사용할 때는 deprecated 된 codex mcp-server 방식보다 OpenAI 공식 Codex plugin for Claude Code를 사용하는 것이 기준이라고 보면 된다.


참고 자료

OpenAI 공식 Release Notes - Codex MCP server command deprecated
https://openai.com/products/release-notes/

OpenAI 공식 GitHub - Codex plugin for Claude Code
https://github.com/openai/codex-plugin-cc

OpenAI Developers - Codex CLI
https://developers.openai.com/codex/cli/

OpenAI Developers - Codex
https://developers.openai.com/codex/

Claude Code를 프로젝트에 처음 적용할 때 가장 먼저 알게 되는 파일 중 하나가 CLAUDE.md다.

처음에는 프로젝트 설명을 자세히 적어두면 Claude가 더 똑똑하게 작업할 것 같아서 이것저것 많이 넣고 싶어진다.

그런데 실제로 사용해보면 무조건 길게 작성하는 것이 좋은 것은 아니었다.

CLAUDE.md는 일반적인 프로젝트 문서와 조금 다르다.

Claude Code가 프로젝트에서 작업할 때 계속 참고하는 정보이기 때문에 정말 필요한 내용만 남기는 것이 중요하다.

Anthropic 공식 문서에서도 CLAUDE.md는 짧고 구체적으로 유지하는 것을 권장하고 있고, 현재 기준으로는 한 파일을 대략 200줄 이하로 유지하는 것을 하나의 기준으로 제시하고 있다.

결론부터 말하면 개인적으로는 이렇게 생각하면 가장 이해하기 쉬웠다.

[사용 기준]

Claude가 이 프로젝트에서 매번 알아야 하는 내용만 CLAUDE.md에 넣는다.

코드만 읽어도 쉽게 알 수 있는 내용은 굳이 적지 않는다.

한 번만 필요한 작업 지시는 현재 대화에서 설명한다.

길고 반복되는 작업 절차는 Skills로 분리한다.

특정 폴더에서만 필요한 규칙은 하위 CLAUDE.md나 Rules를 검토한다.

쉽게 말하면 CLAUDE.md는 프로젝트 전체 설명서를 복사해 넣는 파일이 아니라, Claude에게 매번 전달하는 짧은 개발 인수인계 문서에 가깝다.


1. CLAUDE.md는 무엇을 하는 파일인가

Claude Code는 새로운 세션을 시작하면 이전 대화를 그대로 기억하고 시작하는 것이 아니다.

대신 프로젝트에 CLAUDE.md가 있으면 이 파일의 내용을 읽고 프로젝트의 규칙과 작업 방법을 참고한다.

프로젝트용 CLAUDE.md는 보통 다음 위치에 둔다.

[파일 위치]

./CLAUDE.md

또는

./.claude/CLAUDE.md

둘 다 프로젝트 수준의 지침을 넣는 용도로 사용할 수 있다.

한 번 만들어두면 매번 프롬프트에서 같은 내용을 반복해서 설명할 필요가 줄어든다.

예를 들어 프로젝트에서 npm이 아니라 pnpm을 사용하거나, 테스트 명령이 일반적인 방식과 다르거나, 특정 디렉토리는 직접 수정하면 안 되는 규칙이 있다면 CLAUDE.md에 적어두는 것이 좋다.


2. 처음부터 직접 만들기 어렵다면 /init으로 시작할 수 있다

Claude Code에는 현재 프로젝트를 분석해서 CLAUDE.md의 초안을 만들어주는 명령이 있다.

[명령어]

/init

/init을 실행하면 Claude가 프로젝트 구조와 빌드 시스템, 테스트 방식, 코드 패턴 등을 확인하고 CLAUDE.md 초안을 만든다.

이미 CLAUDE.md가 있는 프로젝트라면 기존 파일을 무조건 덮어쓰는 대신 개선할 내용을 제안할 수 있다.

개인적으로는 처음부터 빈 파일을 놓고 무엇을 적을지 고민하는 것보다 /init으로 기본 틀을 만든 뒤 필요 없는 내용을 지우고 프로젝트 특유의 규칙을 추가하는 방법이 편하다.

다만 /init이 만들어준 내용도 그대로 믿고 끝내는 것은 추천하지 않는다.

Claude가 코드에서 추론한 내용과 실제 팀의 개발 규칙이 다를 수 있기 때문이다.

결국 마지막 검수는 개발자가 직접 하는 것이 좋다.


3. 가장 먼저 넣을 것은 빌드와 테스트 명령이다

CLAUDE.md에 무엇을 적을지 모르겠다면 빌드와 테스트 방법부터 넣는 것을 추천한다.

Claude는 코드만 보고도 많은 것을 알아낼 수 있지만, 실제 프로젝트에서 어떤 명령을 기준으로 검증해야 하는지는 코드만으로 명확하지 않을 때가 많다.

예를 들면 다음과 같다.

[CLAUDE.md에 넣을 내용]

패키지 설치는 pnpm install을 사용한다.

개발 서버는 pnpm dev로 실행한다.

전체 빌드는 pnpm build로 확인한다.

단위 테스트는 pnpm test로 실행한다.

작업 완료 후 최소한 관련 테스트와 빌드를 확인한다.

이런 정보는 Claude가 코드를 수정한 뒤 무엇으로 정상 여부를 검증해야 하는지 바로 알 수 있게 해준다.

개인적으로는 “무엇을 만들어라”보다 “어떻게 검증해야 하는가”를 CLAUDE.md에 명확하게 적는 것이 생각보다 중요했다.


4. 프로젝트 구조는 코드만 보고 알기 어려운 부분만 적는다

프로젝트 폴더 구조를 전부 CLAUDE.md에 복사할 필요는 없다.

Claude Code는 필요하면 직접 디렉토리와 파일을 확인할 수 있다.

대신 이름만 봐서는 역할을 알기 어렵거나, 프로젝트만의 특별한 구조가 있다면 설명해두는 것이 좋다.

예를 들면 다음과 같다.

[CLAUDE.md에 넣을 내용]

src/api는 외부 REST API 엔드포인트를 담당한다.

src/domain은 비즈니스 로직을 담당하며 UI 코드에서 직접 참조하지 않는다.

legacy 폴더는 이전 시스템 호환용이므로 별도 요청이 없으면 수정하지 않는다.

database/migrations의 기존 migration 파일은 수정하지 않고 새로운 migration을 추가한다.

이런 내용은 파일 이름만 보고 Claude가 정확하게 추론하기 어려울 수 있다.

반대로 src/components에는 UI 컴포넌트가 있다는 식으로 코드만 보면 바로 알 수 있는 내용까지 장황하게 적을 필요는 없다고 생각한다.


5. 코딩 규칙은 추상적으로 쓰지 않는 것이 좋다

CLAUDE.md에 규칙을 적을 때는 “깔끔하게 작성한다”, “좋은 코드를 작성한다”처럼 추상적인 표현을 피하는 것이 좋다.

Claude 입장에서 무엇을 지키라는 것인지 판단하기 애매하기 때문이다.

Anthropic 공식 문서도 구체적이고 확인 가능한 지침을 권장한다.

예를 들어 다음과 같이 작성하는 편이 낫다.

[좋은 예]

들여쓰기는 2칸을 사용한다.

CommonJS의 require 대신 ES Module의 import/export를 사용한다.

API 핸들러는 src/api/handlers 아래에 작성한다.

새 API를 추가하면 해당 API 테스트도 같이 작성한다.

작업 완료 후 npm test를 실행한다.


[피하고 싶은 예]

코드를 깔끔하게 작성한다.

최대한 좋은 구조로 만든다.

테스트를 잘 작성한다.

기존 프로젝트 스타일을 잘 따른다.

사람이 읽어도 기준이 애매한 문장은 Claude에게도 애매할 가능성이 높다.


6. 코드에서 바로 알 수 있는 내용까지 반복해서 적지 않는다

CLAUDE.md를 처음 작성하면 프로젝트에서 사용하는 라이브러리와 모든 폴더를 자세하게 설명하고 싶어진다.

하지만 Claude Code는 실제 프로젝트 파일을 읽을 수 있다.

package.json에 이미 명확하게 적혀 있는 라이브러리 목록이나 소스만 읽으면 바로 알 수 있는 사실을 CLAUDE.md에서 다시 길게 반복하는 것은 효율적이지 않을 수 있다.

개인적으로는 다음 질문을 기준으로 판단한다.

[사용 기준]

“Claude가 현재 프로젝트를 조금만 살펴보면 바로 알아낼 수 있는 내용인가?”

그렇다면 굳이 넣지 않는다.

“코드를 읽어도 알기 어렵거나 잘못 판단할 가능성이 있는 프로젝트 특유의 규칙인가?”

그렇다면 넣는다.

이 기준을 적용하면 CLAUDE.md가 상당히 짧아진다.


7. 내가 두 번 이상 같은 것을 다시 설명했다면 추가할 만하다

Anthropic 공식 도움말에서 재미있는 기준을 하나 제시한다.

Claude에게 같은 내용을 두 번째로 다시 설명해야 했다면 CLAUDE.md에 추가하는 것을 생각해보라는 것이다.

개인적으로도 꽤 현실적인 기준이라고 생각한다.

예를 들어 Claude가 한번 npm을 사용했는데 내가 “이 프로젝트는 pnpm을 사용한다”고 수정해줬다고 해보자.

한 번 정도는 우연일 수 있다.

그런데 다음 세션에서도 같은 실수를 해서 또 설명해야 했다면 CLAUDE.md에 넣을 가치가 있다.

[사용 기준]

한 번 발생한 문제

일단 현재 대화에서 수정한다.


같은 문제가 다시 발생

CLAUDE.md에 넣을지 검토한다.


이 방법을 사용하면 처음부터 거대한 CLAUDE.md를 만들지 않아도 실제 작업하면서 필요한 규칙만 자연스럽게 쌓을 수 있다.


8. CLAUDE.md는 가능하면 200줄 안쪽으로 유지한다

현재 Anthropic 공식 문서에서는 CLAUDE.md를 대략 200줄 이하로 유지하는 것을 권장하고 있다.

이 숫자가 절대적인 제한은 아니다.

200줄이 넘는다고 Claude Code가 갑자기 작동하지 않는다는 뜻도 아니다.

중요한 것은 CLAUDE.md가 매 세션의 컨텍스트에 들어간다는 점이다.

파일이 길어질수록 현재 작업과 관계없는 정보도 계속 컨텍스트 공간을 사용하게 되고, 지침이 너무 많으면 Claude가 중요한 규칙을 일관되게 따르기 어려워질 수도 있다.

개인적으로는 200줄을 “허용되는 최대치”라기보다 파일이 너무 커지고 있지는 않은지 확인하는 경고선 정도로 보는 것이 적당하다고 생각한다.

가능하면 그보다 훨씬 짧게 유지하는 편이 좋다.


9. 긴 작업 절차는 CLAUDE.md보다 Skills가 더 잘 맞는다

예를 들어 회사의 배포 절차가 다음처럼 길다고 해보자.

테스트 실행

버전 확인

changelog 작성

staging 배포

staging 확인

production 배포

배포 후 모니터링

이런 내용을 CLAUDE.md에 30줄씩 넣어둘 수도 있다.

하지만 배포하지 않는 대부분의 작업에서도 이 내용이 계속 컨텍스트에 들어가게 된다.

Anthropic은 이런 다단계 작업 절차는 Skills로 분리하는 것을 권장하고 있다.

[사용 기준]

항상 필요한 프로젝트 사실과 규칙

CLAUDE.md


특정 작업에서만 필요한 긴 절차

Skills


예를 들어 “테스트는 pnpm test로 실행한다”는 CLAUDE.md에 두고, “릴리스 전체 절차”는 Skill로 분리하는 식이다.

이렇게 나누면 CLAUDE.md도 짧게 유지할 수 있다.


10. 특정 폴더에만 필요한 규칙은 전체 CLAUDE.md에 넣지 않아도 된다

대규모 프로젝트나 모노레포에서는 모든 개발자가 같은 규칙을 사용하지 않을 수 있다.

예를 들어 frontend와 backend가 서로 다른 테스트 방법과 코딩 규칙을 사용할 수 있다.

이런 규칙까지 프로젝트 루트 CLAUDE.md에 모두 넣으면 frontend 작업을 하는데 backend의 세부 규칙까지 계속 로드될 수 있다.

Claude Code는 하위 디렉토리의 CLAUDE.md를 해당 영역의 파일을 읽을 때 필요에 따라 로드할 수 있다.

예를 들어 다음과 같이 나눌 수 있다.

[파일 구조 예시]

프로젝트 루트

CLAUDE.md

frontend/CLAUDE.md

backend/CLAUDE.md


루트 CLAUDE.md에는 프로젝트 전체 공통 규칙을 넣는다.

frontend/CLAUDE.md에는 frontend에서만 필요한 규칙을 넣는다.

backend/CLAUDE.md에는 backend에서만 필요한 규칙을 넣는다.

개인적으로는 프로젝트가 커질수록 하나의 CLAUDE.md를 계속 키우는 것보다 이런 방식으로 범위를 나누는 것이 훨씬 관리하기 좋다고 생각한다.


11. .claude/rules를 이용해서 규칙을 더 세분화할 수도 있다

현재 Claude Code에서는 .claude/rules 디렉토리를 이용해 프로젝트 규칙을 여러 파일로 나눌 수도 있다.

[파일 위치]

.claude/rules/

예를 들어 다음처럼 주제별로 나눌 수 있다.

[파일 구조 예시]

.claude/rules/code-style.md

.claude/rules/testing.md

.claude/rules/security.md

특정 파일 경로나 확장자에만 적용되는 규칙으로 설정하면 Claude가 해당 파일을 작업할 때만 필요한 지침을 불러오도록 구성할 수도 있다.

프로젝트가 작다면 굳이 처음부터 이렇게까지 나눌 필요는 없다.

하지만 CLAUDE.md가 계속 길어지기 시작한다면 Rules로 분리할 수 있는 내용이 있는지 확인해볼 만하다.


12. 파일을 나눠서 import한다고 컨텍스트가 줄어드는 것은 아니다

CLAUDE.md에서는 @ 경로 형식을 이용해서 다른 파일을 불러올 수도 있다.

예를 들어 프로젝트의 개발 규칙이 별도 문서로 관리되고 있다면 CLAUDE.md에서 해당 파일을 참조할 수 있다.

[예시]

@docs/development-guide.md

@README.md

이 방식은 긴 CLAUDE.md를 파일별로 정리하는 데는 도움이 된다.

하지만 여기서 주의할 점이 있다.

Anthropic 공식 문서에 따르면 import한 파일도 CLAUDE.md와 함께 컨텍스트에 로드된다.

즉 파일을 여러 개로 나눴다고 해서 토큰이나 컨텍스트 사용량 자체가 자동으로 줄어드는 것은 아니다.

[사용 기준]

파일을 보기 좋게 정리하고 싶다

@ import 사용 가능


현재 작업과 관계없는 내용의 컨텍스트 사용까지 줄이고 싶다

Skills 또는 경로가 지정된 Rules를 검토


이 차이를 모르고 CLAUDE.md를 여러 파일로 쪼개기만 하면 겉보기만 깔끔해지고 실제 컨텍스트는 그대로일 수 있다.


13. 개인적인 설정은 프로젝트 CLAUDE.md와 분리하는 것이 좋다

프로젝트 CLAUDE.md는 Git에 같이 올려 팀원과 공유할 수 있다.

따라서 개인적인 취향까지 프로젝트 파일에 넣는 것은 별로 좋지 않다.

Claude Code는 사용자 전체 프로젝트에 적용하는 개인 설정 파일도 지원한다.

[파일 위치]

~/.claude/CLAUDE.md

여기에는 모든 프로젝트에서 개인적으로 사용하는 규칙을 넣을 수 있다.

그리고 특정 프로젝트에서 나만 사용하는 설정이 필요하다면 CLAUDE.local.md를 사용할 수 있다.

[파일 위치]

./CLAUDE.local.md

CLAUDE.local.md는 개인적인 프로젝트 설정에 적합하며 Git에 커밋하지 않도록 .gitignore에 넣는 방식으로 사용할 수 있다.

쉽게 구분하면 이렇다.

[사용 기준]

팀원 모두에게 필요한 프로젝트 규칙

프로젝트 CLAUDE.md


내가 모든 프로젝트에서 사용하는 개인 규칙

~/.claude/CLAUDE.md


현재 프로젝트에서 나만 사용하는 개인 규칙

CLAUDE.local.md


이렇게 구분하면 팀 프로젝트에서도 개인 취향과 공통 규칙이 뒤섞이지 않는다.


14. 비밀번호나 API Key 같은 민감한 정보는 넣지 않는다

CLAUDE.md는 프로젝트와 함께 Git에 커밋될 수 있는 파일이다.

따라서 다음과 같은 정보는 넣지 않는 것이 좋다.

[주의]

API Key

비밀번호

실제 데이터베이스 접속 문자열

Access Token

개인 인증 정보

외부에 노출되면 문제가 될 수 있는 보안 취약점 정보

Anthropic도 CLAUDE.md를 공개될 수 있는 프로젝트 문서처럼 취급하라고 안내한다.

개인적인 개발 환경 정보가 필요하다면 CLAUDE.local.md 같은 로컬 전용 파일을 사용하는 편이 낫다.

물론 로컬 파일이라고 해서 민감한 인증 정보를 무분별하게 넣는 것도 추천하지 않는다.


15. “절대 하지 마라”를 적는 것만으로 보안을 보장할 수는 없다

예를 들어 CLAUDE.md에 다음처럼 적었다고 해보자.

[예시]

production 데이터베이스를 절대 수정하지 않는다.

rm -rf 명령을 절대 실행하지 않는다.

이런 규칙을 적는 것은 Claude의 행동을 유도하는 데 도움이 된다.

하지만 CLAUDE.md는 보안 정책을 강제로 집행하는 기능이 아니다.

Anthropic도 CLAUDE.md는 컨텍스트로 제공되는 지침이지 결정적인 보안 장치가 아니라고 설명한다.

반드시 차단해야 하는 위험한 동작이라면 Permissions나 PreToolUse Hook 같은 실제 실행 제어 기능을 사용하는 것이 맞다.

[사용 기준]

가급적 이렇게 작업해달라는 개발 규칙

CLAUDE.md


무조건 차단해야 하는 위험한 동작

Permissions 또는 Hooks


이 부분은 AI 코딩 도구를 사용할 때 특히 주의할 필요가 있다.


16. CLAUDE.md가 제대로 읽히고 있는지는 /memory로 확인할 수 있다

파일을 만들어놓고 Claude가 실제로 읽고 있는지 궁금할 때가 있다.

이럴 때 다음 명령을 사용할 수 있다.

[명령어]

/memory

현재 Claude Code의 /memory에서는 로드된 CLAUDE.md, CLAUDE.local.md, Rules 파일 등을 확인할 수 있다.

Claude가 내가 작성한 규칙을 계속 무시한다면 먼저 파일이 실제로 로드되고 있는지부터 확인하는 것이 좋다.

그 다음에는 다음 항목을 살펴본다.

[확인 방법]

규칙이 너무 추상적이지 않은지 확인한다.

서로 모순되는 규칙이 여러 파일에 존재하지 않는지 확인한다.

이미 오래되어 현재 프로젝트와 맞지 않는 규칙이 없는지 확인한다.

특정 작업에만 필요한 규칙을 전체 CLAUDE.md에 넣지 않았는지 확인한다.

CLAUDE.md를 만들었다고 해서 Claude가 모든 문장을 기계적으로 100% 지키는 것은 아니기 때문에 지침 자체의 품질도 중요하다.


17. /compact를 해도 프로젝트 루트 CLAUDE.md는 다시 적용된다

Claude Code를 오래 사용하다 보면 컨텍스트가 길어져 /compact를 사용할 때가 있다.

그럼 CLAUDE.md의 내용도 사라지는지 궁금할 수 있다.

현재 Claude Code 공식 문서에 따르면 프로젝트 루트의 CLAUDE.md는 compaction 이후 다시 읽어서 세션에 주입한다.

따라서 프로젝트의 핵심 규칙을 대화에서 한 번 설명하는 것보다 CLAUDE.md에 넣어두는 편이 장시간 작업에서도 안정적이다.

다만 하위 디렉토리의 CLAUDE.md는 해당 디렉토리의 파일을 다시 읽을 때 로드되는 방식이므로 루트 파일과 완전히 동일하게 동작하는 것은 아니다.


18. 내가 만든다면 처음에는 이 정도로 시작한다

처음 CLAUDE.md를 만든다고 가정하면 개인적으로는 너무 많은 내용을 넣지 않고 다음 다섯 가지 정도부터 시작할 것 같다.

[CLAUDE.md 작성 기준]

1) 프로젝트에서 사용하는 핵심 기술과 특이사항

2) 자주 사용하는 빌드 명령

3) 테스트와 검증 명령

4) 코드만 보고 알기 어려운 프로젝트 구조

5) Claude가 반복해서 틀리는 중요한 코딩 규칙


예를 들어 실제 내용은 이런 정도면 된다.

[CLAUDE.md 예시]

프로젝트

Next.js와 TypeScript를 사용한다.

패키지 관리는 pnpm을 사용한다.


구조

src/app은 화면과 라우팅을 담당한다.

src/server는 서버 로직을 담당한다.

기존 migration 파일은 수정하지 않는다.


검증

작업 완료 후 pnpm lint를 실행한다.

기능 변경이 있으면 관련 테스트를 실행한다.

최종적으로 pnpm build가 정상적으로 완료되는지 확인한다.


작업 규칙

현재 작업과 관계없는 파일은 임의로 리팩터링하지 않는다.

대규모 변경은 바로 수정하지 말고 먼저 변경 계획을 정리한다.

이 정도로 시작한 뒤 실제 Claude Code 사용 중 반복해서 생기는 문제를 하나씩 추가하는 것이 좋다.


19. CLAUDE.md를 주기적으로 정리하는 것도 중요하다

CLAUDE.md는 한번 만들고 끝나는 파일이 아니다.

프로젝트가 바뀌면 빌드 방법도 바뀌고 폴더 구조나 코딩 규칙도 달라질 수 있다.

그런데 오래된 내용을 그대로 남겨두면 없는 것보다 더 안 좋을 수 있다.

Claude가 오래된 규칙을 실제 현재 규칙으로 생각하고 작업할 수 있기 때문이다.

개인적으로는 다음과 같은 경우 한번씩 검토하는 것이 좋다고 생각한다.

[점검 시점]

프로젝트 구조가 크게 바뀌었을 때

빌드나 테스트 명령이 변경됐을 때

새로운 프레임워크나 도구를 도입했을 때

Claude가 이상하게 같은 실수를 반복하기 시작했을 때

CLAUDE.md가 너무 길어졌을 때

예전에 적어둔 규칙의 이유가 기억나지 않을 때

Anthropic 공식 도움말에서도 몇 주에 한 번 정도 전체 파일을 읽어보고 오래되거나 의미를 알 수 없는 내용을 제거하는 방식을 권장하고 있다.


20. 내가 생각하는 가장 안 좋은 CLAUDE.md

개인적으로 가장 피하고 싶은 형태는 모든 것을 다 넣은 거대한 CLAUDE.md다.

프로젝트 소개

전체 라이브러리 설명

모든 폴더 구조

프레임워크 공식 사용법

수십 줄의 배포 절차

개발자의 개인 취향

보안 규칙

코드 리뷰 체크리스트

문서 작성 방법

Git 사용법

이걸 한 파일에 전부 넣으면 처음에는 친절한 문서처럼 보일 수 있다.

하지만 Claude에게는 모든 세션에서 계속 들고 있어야 하는 컨텍스트가 된다.

그래서 개인적으로는 “정보를 많이 주는 것”보다 “지금 프로젝트에서 항상 필요한 정보만 주는 것”을 목표로 CLAUDE.md를 작성하는 편이 좋다고 생각한다.


21. 결론: CLAUDE.md는 길게 쓰는 파일이 아니라 잘 골라서 쓰는 파일이다

Claude Code에서 CLAUDE.md는 상당히 유용하다.

한 번 프로젝트 규칙을 정리해두면 새로운 세션을 시작할 때마다 같은 설명을 반복할 필요가 줄어든다.

하지만 모든 것을 CLAUDE.md에 넣는다고 Claude Code가 무조건 더 잘 동작하는 것은 아니다.

오히려 항상 필요한 정보와 특정 작업에서만 필요한 정보를 구분하는 것이 중요하다.

개인적으로는 다음 기준이면 충분하다고 생각한다.

[사용 기준]

매번 알아야 하는 프로젝트 규칙은 CLAUDE.md에 넣는다.

코드를 보면 바로 알 수 있는 사실은 줄인다.

같은 내용을 두 번 이상 다시 설명했다면 추가를 검토한다.

긴 작업 절차는 Skills로 분리한다.

특정 경로에만 필요한 규칙은 하위 CLAUDE.md나 Rules를 검토한다.

개인 설정은 사용자 CLAUDE.md나 CLAUDE.local.md로 분리한다.

보안상 반드시 막아야 하는 것은 CLAUDE.md만 믿지 않는다.

그리고 파일은 가능하면 짧게 유지하고 프로젝트가 바뀔 때마다 같이 정리한다.

한 줄로 정리하면 이렇다.

CLAUDE.md는 프로젝트 문서를 전부 넣는 파일이 아니라, Claude가 모든 작업에서 반드시 알아야 할 내용만 짧고 구체적으로 적어두는 파일이다.


참고 자료

Anthropic 공식 Claude Code 문서 - How Claude remembers your project
https://code.claude.com/docs/en/memory

Anthropic 공식 Claude Code 문서 - Best Practices for Claude Code
https://code.claude.com/docs/en/best-practices

Anthropic 공식 도움말 - Give Claude context: CLAUDE.md and better prompts
https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-prompts

Anthropic 공식 블로그 - Using CLAUDE.MD files: Customizing Claude Code for your codebase
https://claude.com/blog/using-claude-md-files

Anthropic 공식 블로그 - Steering Claude Code: when to use CLAUDE.md, skills, hooks, and subagents
https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more

Claude Code를 처음 사용할 때는 프로젝트 루트에 CLAUDE.md 하나 만들어두고 필요한 내용을 적으면 대부분 해결되는 줄 알았다.

그런데 Claude Code를 조금 더 깊게 사용하다 보면 Skills, Subagents, Hooks 같은 기능이 계속 나온다.

처음 보면 모두 “Claude에게 일을 더 잘 시키기 위한 설정”처럼 보여서 뭐가 다른지 헷갈리기 쉽다.

나도 기능 이름만 봤을 때는 굳이 이렇게 여러 개로 나눠놓을 필요가 있나 싶었다.

그런데 실제 용도를 기준으로 보면 역할은 꽤 명확하게 나뉜다.

결론부터 말하면 개인적으로는 이렇게 생각하면 가장 이해하기 쉬웠다.

[사용 기준]

CLAUDE.md : Claude가 프로젝트에서 항상 알고 있어야 하는 내용

Skills : 필요할 때 반복해서 사용하는 작업 절차

Subagents : 메인 대화와 분리해서 별도로 맡기고 싶은 작업

Hooks : 특정 상황이 발생하면 자동으로 반드시 실행할 작업

쉽게 말하면 CLAUDE.md는 프로젝트 설명서, Skills는 작업 매뉴얼, Subagents는 별도로 일을 맡기는 작업자, Hooks는 조건에 따라 자동으로 실행되는 장치에 가깝다.

이번 글에서는 네 기능이 실제로 어떻게 다르고 어떤 상황에서 선택하면 되는지 내가 이해한 기준으로 정리해보려고 한다.


1. 왜 CLAUDE.md 하나로 전부 해결하지 않는가

Claude Code를 사용하다 보면 가장 먼저 만나게 되는 것이 CLAUDE.md다.

프로젝트 구조, 빌드 방법, 코딩 규칙 등을 적어두면 Claude가 매번 같은 내용을 다시 물어보지 않아도 된다.

그래서 처음에는 여기에 모든 내용을 넣으면 될 것처럼 보인다.

하지만 문제가 하나 있다.

프로젝트 루트의 CLAUDE.md는 세션을 시작할 때 컨텍스트에 들어가고 세션 동안 계속 참고된다.

즉 현재 작업과 관계없는 내용까지 CLAUDE.md에 너무 많이 적어두면 그 내용도 계속 컨텍스트를 차지한다.

Anthropic도 공식 문서에서 CLAUDE.md에는 Claude가 모든 세션에서 알아야 할 핵심 정보만 넣고, 여러 단계로 이루어진 절차는 Skill로 옮기는 것을 권장하고 있다.

이 부분이 생각보다 중요했다.

Claude Code를 잘 설정한다는 것이 CLAUDE.md를 최대한 길게 만드는 것이 아니라, 정보의 성격에 따라 적당한 위치에 나누는 것에 가깝다.


2. CLAUDE.md는 항상 알아야 하는 프로젝트 규칙에 적합하다

CLAUDE.md는 Claude Code가 프로젝트를 이해하기 위한 기본 설명서라고 생각하면 된다.

프로젝트 수준에서는 보통 다음 위치에 둘 수 있다.

[파일 위치]

./CLAUDE.md

또는

./.claude/CLAUDE.md

Claude Code에서는 /init 명령으로 프로젝트를 분석해서 CLAUDE.md 초안을 만들 수도 있다.

[명령어]

/init

Anthropic 공식 문서에서는 CLAUDE.md에 다음과 같은 내용을 넣는 것을 권장한다.

빌드 명령

테스트 명령

프로젝트 구조

코딩 규칙

아키텍처상 중요한 결정

이름 작성 규칙

팀에서 항상 지켜야 하는 작업 방식

개인적으로는 “Claude가 이 프로젝트에서 작업할 때 매번 알아야 하는가?”를 기준으로 판단하면 편했다.


3. CLAUDE.md에 넣기 좋은 내용과 그렇지 않은 내용

예를 들어 이런 내용은 CLAUDE.md와 잘 맞는다.

[예시]

이 프로젝트는 Node.js와 TypeScript를 사용한다.

패키지 관리는 npm을 사용한다.

테스트는 npm test로 실행한다.

API 코드는 src/api 아래에 있다.

새 기능을 추가한 뒤 기존 테스트를 반드시 실행한다.

DB 스키마를 변경할 때 기존 migration 파일은 수정하지 않는다.

이런 내용은 어떤 기능을 개발하더라도 프로젝트 전체에서 계속 필요한 정보다.

반대로 다음처럼 특정 상황에서만 필요한 긴 절차는 CLAUDE.md에 계속 넣어둘 필요가 없다.

[예시]

배포할 때 먼저 테스트를 실행하고 버전을 확인한 다음 changelog를 만들고 staging 환경에 배포하고 확인이 끝나면 production에 배포한다.

이건 프로젝트의 기본 사실이라기보다 하나의 작업 절차다.

이런 내용은 Skill 쪽이 더 잘 맞는다.


4. Skills는 반복해서 사용하는 작업 절차에 적합하다

Skills는 내가 자주 사용하는 작업 방법을 Claude에게 하나의 기능처럼 만들어두는 방식이다.

프로젝트용 Skill은 보통 다음 구조로 만든다.

[파일 위치]

.claude/skills/스킬이름/SKILL.md

예를 들어 코드 리뷰 절차를 항상 비슷하게 사용한다고 해보자.

매번 Claude에게

“현재 변경사항을 확인하고 보안 문제, 에러 처리, 테스트 누락을 순서대로 검토해줘.”

라고 입력할 수도 있다.

하지만 이런 요청을 계속 반복한다면 Skill로 만들어두는 것이 더 자연스럽다.

[예시]

.claude/skills/code-review/SKILL.md

이 파일 안에 코드 리뷰 순서와 확인해야 할 기준을 적어둔다.

그러면 필요할 때 다음처럼 호출할 수 있다.

[명령어]

/code-review

현재 Claude Code에서는 Skill 이름과 설명 정도만 세션 시작 시 인식하고, Skill의 본문 전체는 실제로 필요할 때 로드된다.

따라서 긴 절차를 항상 CLAUDE.md에 넣어두는 것보다 컨텍스트를 효율적으로 사용할 수 있다.


5. CLAUDE.md와 Skills의 차이는 이렇게 보면 쉽다

둘이 가장 많이 헷갈릴 수 있다.

개인적으로는 “항상 필요한 사실인가, 특정 작업을 할 때 필요한 절차인가?”로 구분한다.

[사용 기준]

CLAUDE.md

프로젝트에서 항상 알아야 한다.

모든 작업에 영향을 준다.

프로젝트 구조와 규칙을 설명한다.

예: 빌드 방법, 테스트 명령, 코딩 규칙, 디렉토리 구조


Skills

특정 작업을 할 때만 필요하다.

반복되는 절차를 정의한다.

필요한 순간에 전체 내용을 불러온다.

예: 코드 리뷰, 배포 절차, 릴리스 체크, 문서 생성


예를 들어 “테스트는 npm test로 실행한다”는 CLAUDE.md에 적는 것이 자연스럽다.

반면 “릴리스 전 테스트 → 버전 확인 → changelog 작성 → staging 확인 → production 배포 순서로 진행한다”는 Skill이 더 적합하다.


6. Skills가 특히 좋은 경우

개인적으로는 다음과 같은 작업에서 Skills가 유용하다고 생각한다.

1) 코드 리뷰

검토 기준과 순서를 항상 일정하게 유지하고 싶을 때

2) 배포

매번 동일한 배포 절차를 따라야 할 때

3) 릴리스 준비

버전, 테스트, changelog, 태그 등을 순서대로 확인할 때

4) 반복적인 문서 작성

프로젝트에서 정해진 형식의 문서를 반복해서 만들 때

5) 팀에서 동일한 작업 절차를 공유할 때

결국 내가 Claude Code에 같은 프롬프트나 체크리스트를 계속 붙여넣고 있다면 Skill로 만들 수 있는지 한번 생각해볼 만하다.

Anthropic 공식 문서도 “같은 명령이나 여러 단계의 절차를 계속 붙여넣고 있다면 Skill을 만들어볼 것”을 하나의 기준으로 제시하고 있다.


7. Subagents는 별도의 컨텍스트에서 작업하는 작업자에 가깝다

Subagent는 Skills와 또 다르다.

Skill은 현재 Claude와 같은 대화 흐름 안에서 특정 작업 방법을 불러와 실행하는 개념에 가깝다.

Subagent는 아예 별도의 컨텍스트를 가진 작업자에게 일을 맡기는 방식이다.

프로젝트 전용 Subagent는 다음 위치에 둘 수 있다.

[파일 위치]

.claude/agents/

Claude Code에서 다음 명령으로 Subagent를 관리할 수도 있다.

[명령어]

/agents

Anthropic 공식 문서에 따르면 Subagent는 자체 컨텍스트 윈도우, 시스템 프롬프트, 도구 접근 권한 등을 가지고 독립적으로 작업한 뒤 결과를 메인 세션으로 돌려준다.

쉽게 말하면 내가 메인 Claude와 개발을 하고 있는데 조사할 일이 생겼을 때 별도의 Claude에게 그 조사만 맡기는 것과 비슷하다.


8. Subagents의 가장 큰 장점은 메인 컨텍스트를 덜 어지럽힌다는 점이다

예를 들어 프로젝트에서 특정 라이브러리 사용처를 전부 조사해야 한다고 해보자.

Claude가 프로젝트 전체를 검색하면 많은 파일 내용과 검색 결과가 대화 과정에 들어올 수 있다.

하지만 실제로 내가 필요한 것은 마지막 결론일 수도 있다.

이런 경우 Subagent에게 조사를 맡기면 Subagent는 자신의 별도 컨텍스트에서 파일을 검색하고 분석한다.

그리고 메인 세션에는 최종 결과와 필요한 정보만 돌아온다.

[사용 기준]

메인 Claude

현재 기능 개발을 계속 진행


Subagent

프로젝트 전체에서 오래된 API 사용처 조사

로그 대량 분석

의존성 문제 조사

보안 관점의 별도 검토


결과

필요한 결론만 메인 대화로 전달

이 구조가 Subagent의 가장 큰 장점이라고 생각한다.


9. Skills와 Subagents는 어떻게 구분할까

이 둘도 상당히 헷갈린다.

둘 다 특정 일을 전문적으로 처리하도록 만들 수 있기 때문이다.

하지만 기준은 꽤 단순하다.

[사용 기준]

Skills

현재 대화 안에서 정해진 절차를 실행하고 싶다.

중간 과정도 내가 같이 보면서 작업하고 싶다.

반복되는 작업 방법을 재사용하고 싶다.


Subagents

작업을 메인 대화와 분리하고 싶다.

조사 과정에서 많은 파일이나 로그를 읽어야 한다.

중간 과정은 별로 중요하지 않고 결과만 받고 싶다.

별도의 도구 권한이나 모델을 가진 전문 작업자를 만들고 싶다.


예를 들어 코드 리뷰 체크리스트를 현재 대화에서 순서대로 진행하고 싶다면 Skill이 잘 맞는다.

반대로 프로젝트 전체를 훑으면서 보안 문제를 별도로 조사하게 하고 마지막에 결과만 받고 싶다면 Subagent가 더 자연스럽다.

Anthropic도 공식 블로그에서 이런 “격리된 컨텍스트”를 Skill과 Subagent를 나누는 중요한 기준으로 설명하고 있다.


10. Subagents는 토큰을 무조건 줄여주는 기능은 아니다

Subagent를 사용하면 메인 세션의 컨텍스트를 깨끗하게 유지하는 데 도움이 된다.

그렇다고 Subagent 자체가 아무 토큰도 사용하지 않는다는 뜻은 아니다.

Subagent도 별도의 모델 호출과 컨텍스트를 사용해서 실제 작업을 한다.

차이는 그 작업 과정 전체를 메인 대화에 계속 넣지 않아도 된다는 데 있다.

따라서 개인적으로는 Subagent를 단순한 “토큰 절약 기능”이라고 생각하기보다 “컨텍스트를 분리해서 복잡한 작업을 관리하는 기능”으로 보는 편이 더 정확하다고 생각한다.


11. Hooks는 AI에게 부탁하는 것이 아니라 자동으로 실행되게 만드는 기능이다

Hooks는 앞의 세 기능과 성격이 가장 다르다.

CLAUDE.md, Skills, Subagents는 결국 Claude가 읽고 판단해서 행동하는 영역이 크다.

Hooks는 특정 이벤트가 발생했을 때 미리 정해둔 작업을 자동으로 실행하는 기능이다.

프로젝트 Hooks는 보통 다음 설정 파일에 등록할 수 있다.

[파일 위치]

.claude/settings.json

설정된 Hook은 Claude Code의 특정 이벤트에 맞춰 실행된다.

대표적으로 이런 이벤트가 있다.

PreToolUse : Claude가 도구를 실행하기 전

PostToolUse : 도구 실행이 성공한 뒤

SessionStart : 세션이 시작될 때

Stop : Claude가 작업을 끝내려고 할 때

PreCompact : 컨텍스트 압축이 일어나기 전

Claude Code에서는 다음 명령으로 현재 설정된 Hooks를 확인할 수도 있다.

[명령어]

/hooks


12. Hooks는 반드시 지켜야 하는 자동화에 잘 맞는다

예를 들어 Claude에게 CLAUDE.md로 이렇게 적어둘 수 있다.

[예시]

“파일 수정 후 가능하면 lint를 실행한다.”

하지만 이것은 어디까지나 Claude에게 주는 지침이다.

상황에 따라 Claude가 판단해서 행동하는 영역이 남아 있다.

반대로 파일이 수정될 때마다 반드시 formatter나 linter를 실행해야 한다면 Hook이 더 적합하다.

[사용 기준]

파일을 수정한 뒤 자동으로 formatter 실행

특정 Bash 명령 실행 전 차단 검사

Claude가 작업을 끝내기 전에 테스트 실행

세션 시작 시 필요한 환경 정보 출력

컨텍스트 압축 전에 작업 기록 백업

특정 이벤트 발생 시 외부 시스템 호출

이런 것은 “Claude가 기억해서 해줬으면 좋겠다”가 아니라 “조건이 발생하면 자동으로 실행되어야 한다”에 가깝다.

그래서 Hooks를 사용하는 것이다.


13. CLAUDE.md와 Hooks의 차이도 중요하다

예를 들어 이런 규칙이 있다고 해보자.

“production 데이터베이스에 직접 접속하지 않는다.”

CLAUDE.md에 적어두면 Claude에게 중요한 프로젝트 규칙을 알려줄 수 있다.

하지만 정말 위험한 명령이라면 단순히 AI가 규칙을 기억하기를 기대하는 것보다 PreToolUse Hook 등을 이용해 실행 전에 검사하거나 차단하는 방법이 더 강하다.

쉽게 구분하면 이렇다.

[사용 기준]

CLAUDE.md

Claude에게 “이 규칙을 지켜라”라고 알려준다.


Hooks

특정 조건이 발생했을 때 실제 자동화나 검사를 실행한다.


개인적으로는 코딩 스타일이나 프로젝트 관례처럼 판단이 필요한 것은 CLAUDE.md에 두고, 보안이나 자동 검사처럼 반드시 실행돼야 하는 것은 Hooks를 검토하는 것이 좋다고 생각한다.


14. 네 가지를 한 번에 비교하면

처음에는 복잡해 보여도 목적만 놓고 보면 꽤 간단하다.

[사용 기준]

CLAUDE.md

역할 : 프로젝트의 기본 설명과 항상 필요한 규칙

언제 로드되는가 : 프로젝트 루트 기준 세션 시작부터 계속 참고

컨텍스트 영향 : 항상 들어가므로 길수록 부담이 커질 수 있음

예 : 빌드 명령, 폴더 구조, 코딩 규칙


Skills

역할 : 반복해서 사용하는 작업 절차

언제 로드되는가 : 이름과 설명은 인식하고, 본문은 실제 필요할 때

컨텍스트 영향 : 필요한 시점에만 본문을 불러옴

예 : 코드 리뷰, 배포, 릴리스 체크


Subagents

역할 : 별도로 분리해서 맡길 전문 작업

언제 로드되는가 : 필요할 때 별도 에이전트로 실행

컨텍스트 영향 : 자체 컨텍스트에서 작업하고 결과 중심으로 메인 세션에 전달

예 : 대규모 코드 조사, 로그 분석, 의존성 감사


Hooks

역할 : 특정 이벤트에서 자동으로 실행되는 작업

언제 실행되는가 : 설정된 이벤트가 발생했을 때

컨텍스트 영향 : 설정 자체는 메인 컨텍스트 밖에서 동작하며 필요한 출력만 전달될 수 있음

예 : 자동 lint, 위험 명령 차단, 테스트 실행


15. 실제 프로젝트라면 나는 이렇게 나눌 것 같다

예를 들어 Node.js 기반 웹 프로젝트가 있다고 해보자.

1) CLAUDE.md

프로젝트는 TypeScript를 사용한다.

npm으로 패키지를 관리한다.

API 코드는 src/api에 있다.

테스트는 npm test로 실행한다.

기존 migration 파일은 수정하지 않는다.


2) Skills

release

코드 검사 → 테스트 → 버전 확인 → changelog 작성 → 배포 준비


code-review

현재 diff 확인 → 에러 처리 → 보안 → 테스트 누락 순으로 검토


3) Subagents

security-reviewer

프로젝트 전체를 별도로 조사해서 보안상 위험한 부분만 정리


dependency-checker

패키지와 의존성 구조를 확인하고 문제가 될 만한 부분을 정리


4) Hooks

파일 수정 후 formatter 실행

특정 위험 명령 실행 전 검사

Claude가 종료하기 전 테스트 결과 확인


이렇게 놓고 보면 네 기능을 왜 따로 제공하는지 이해하기 쉬워진다.


16. 처음부터 네 가지를 전부 설정할 필요는 없다

기능이 많다고 처음부터 다 만들어야 하는 것은 아니다.

오히려 개인적으로는 필요한 시점에 하나씩 추가하는 편이 좋다고 생각한다.

처음 Claude Code를 사용하는 프로젝트라면 CLAUDE.md 정도부터 시작해도 충분하다.

그러다가 같은 작업 절차를 계속 입력하게 되면 Skill을 만든다.

프로젝트 조사가 커져 메인 대화가 너무 복잡해지면 Subagent를 사용한다.

반드시 자동으로 실행해야 할 작업이 생기면 Hooks를 추가한다.

[추천 순서]

1) CLAUDE.md

2) 반복 작업이 생기면 Skills

3) 별도 작업자가 필요하면 Subagents

4) 자동으로 강제할 작업이 생기면 Hooks

처음부터 설정 파일을 잔뜩 만드는 것보다 실제 불편함이 생길 때 하나씩 추가하는 것이 관리하기도 쉽다.


17. 컨텍스트 사용량을 생각하면 더 명확해진다

최근 Claude Code를 사용하면서 사용량과 컨텍스트 관리가 생각보다 중요하다고 느꼈다.

이 관점에서 보면 네 기능을 나누는 이유가 더 명확해진다.

CLAUDE.md는 항상 필요한 정보만 넣는다.

특정 절차는 Skill로 빼서 필요할 때만 불러온다.

많은 조사 과정은 Subagent의 별도 컨텍스트에서 처리한다.

반드시 실행돼야 하는 자동화는 Hooks로 처리한다.

이렇게 하면 모든 것을 하나의 거대한 CLAUDE.md와 하나의 긴 대화에 몰아넣는 것보다 역할을 나누기가 쉽다.

특히 Anthropic이 2026년 6월 공개한 공식 가이드에서도 각 방법을 “언제 컨텍스트에 로드되는가”, “압축 후 어떻게 유지되는가”, “컨텍스트 비용은 어느 정도인가”를 기준으로 비교하고 있다.

결국 Claude Code의 설정 기능들은 단순히 기능이 많아진 것이 아니라 컨텍스트를 어디에 어떻게 사용할지 나누는 장치이기도 하다.


18. 하나를 선택해야 할 때 내가 사용하는 질문

기능 이름을 외우는 것보다 아래 질문으로 판단하는 것이 편했다.

[사용 기준]

“Claude가 이 프로젝트에서 항상 알아야 하는가?”

그렇다면 CLAUDE.md


“특정 작업을 할 때 반복해서 사용하는 절차인가?”

그렇다면 Skills


“메인 대화를 어지럽히지 않고 별도로 조사하거나 처리하고 싶은가?”

그렇다면 Subagents


“Claude의 판단과 관계없이 특정 상황에서 자동으로 실행되어야 하는가?”

그렇다면 Hooks


이 네 질문만 기억해도 대부분의 경우 어디에 넣어야 할지 결정할 수 있다.


19. 결론: 무엇이 더 좋은지가 아니라 역할이 다르다

Claude Code의 CLAUDE.md, Skills, Subagents, Hooks를 처음 보면 비슷한 기능을 여러 개 만들어놓은 것처럼 느껴질 수 있다.

하지만 직접 사용 기준으로 나눠보면 목적은 상당히 다르다.

CLAUDE.md는 프로젝트에서 항상 필요한 기본 정보와 규칙을 제공한다.

Skills는 특정 작업에서 반복해서 사용하는 절차를 필요할 때 불러온다.

Subagents는 메인 대화와 분리된 별도 컨텍스트에서 전문 작업을 수행한다.

Hooks는 특정 이벤트가 발생했을 때 정해진 자동화를 실행한다.

개인적으로는 Claude Code를 처음 사용할 때부터 이 기능들을 전부 사용할 필요는 없다고 생각한다.

CLAUDE.md부터 시작하고 실제로 반복되는 작업이나 불편함이 생겼을 때 Skills, Subagents, Hooks를 하나씩 추가하는 정도면 충분하다.

한 줄로 정리하면 이렇다.

Claude가 항상 알아야 하면 CLAUDE.md, 반복 작업 절차라면 Skills, 별도로 일을 맡기려면 Subagents, 조건이 발생했을 때 자동으로 실행해야 한다면 Hooks를 사용하면 된다.


참고 자료

Anthropic 공식 블로그 - Steering Claude Code: when to use CLAUDE.md, skills, hooks, and subagents
https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more

Anthropic 공식 Claude Code 문서 - How Claude remembers your project
https://code.claude.com/docs/en/memory

Anthropic 공식 Claude Code 문서 - Extend Claude with skills
https://code.claude.com/docs/en/slash-commands

Anthropic 공식 Claude Code 문서 - Create custom subagents
https://code.claude.com/docs/en/sub-agents

Anthropic 공식 Claude Code 문서 - Automate workflows with hooks
https://code.claude.com/docs/en/hooks-guide

Anthropic 공식 Claude Code 문서 - Hooks reference
https://code.claude.com/docs/en/hooks