Claude Code 커스텀 MCP·스킬·CLAUDE.md 계층화 셋업

2026년 5월 · 귀찮은개발자

Claude Code를 처음 쓸 땐 기본 상태로 썼다. 그냥 띄우고 시키는 식이었다. 잠깐은 괜찮았는데, 같은 프로젝트를 오래 굴리니 한계가 보였다.

매번 똑같은 걸 설명했고, 매번 같은 외부 작업을 손으로 찾아 넣었다. Claude는 세션마다 처음 만난 사람이라 어제 맞춘 규칙도 다 잊었다. 결국 셋업을 세 층으로 짰다. CLAUDE.md, 커스텀 MCP, 스킬이다.

이 글은 그 세 층을 코드 단위로 푼다. 다른 활용법 글이랑 다른 점은, 남이 안 쓰는 내가 직접 만든 MCP까지 까놓는다는 거다. 하루 흐름 전체가 궁금하면 아래 관련 글이 입구다.

기본 Claude Code론 왜 부족했나

기본 Claude Code도 충분히 똑똑하다. 문제는 기억과 능력이 매번 초기화된다는 거다. 세션을 새로 열면 어제 맞춘 규칙도, 어제 본 데이터도 다 사라진다.

그래서 세 가지가 매번 반복됐다. 프로젝트 설명, 외부 데이터 조회, 긴 지시 재입력. 하나하나는 사소한데 매일 쌓이니 개발보다 잡일이 길어졌다. 이걸 층으로 나눠서 없앴다.

1층 — CLAUDE.md를 세 층으로 쪼갰다

CLAUDE.md는 Claude가 세션 시작 때 자동으로 읽는 안내문이다. 새 직원에게 주는 인수인계서 같은 거다. 근데 한 장에 다 넣으니 금방 지저분해졌다.

그래서 세 층으로 나눴다. 회사 규정에 비유하면, 전사 공통 규칙·팀 규칙·프로젝트 규칙을 따로 두는 것과 같다. Claude는 가까운 순서로 셋을 합쳐 읽는다.

글로벌엔 모든 프로젝트에 통하는 걸 둔다. 한국어로 답할 것, 작동하는 코드부터, 안 망가진 건 건드리지 말 것 같은 행동 원칙이다. 이건 한 번 적어두면 어느 프로젝트를 열든 따라온다.

프로젝트 층엔 그 레포만의 규칙을 둔다. 블로그 프로젝트라면 글 톤, 금지 단어, 발행 체크리스트가 들어간다. 폴더 층은 정말 복잡한 하위 디렉토리에만 둔다. 안 그러면 또 지저분해진다.

2층 — 외부 작업은 커스텀 MCP로 뺐다

CLAUDE.md가 "설명"을 없앴다면, MCP는 "능력"을 더한다. MCP는 Claude한테 외부 도구를 꽂아주는 USB 포트 같은 거다. 기본 Claude는 내 코드 안만 보지만, MCP를 물리면 앱 데이터나 외부 API까지 직접 가져다 쓴다.

나는 두 개를 직접 만들어 물려 쓴다. 하나는 앱 데이터용, 하나는 내 작업 보조용이다.

앱 데이터 MCP. 매출, 다운로드, 키워드 순위, 리뷰 요약 같은 걸 도구로 등록했다. 그래서 코드 짜다 말고 "이번 주 매출 지난주랑 비교해줘" 하면 대시보드를 안 켜고 바로 답이 나온다.

작업 보조 MCP. 이게 남들 셋업엔 없는 부분이다. 내 톤으로 초안 쓰기, 어제 작업 한 줄 복구, 콘텐츠 갭 리서치 같은 도구를 넣었다. 도구를 부르면 대략 이런 식이다.

핵심은 "매일 반복하는 외부 작업"만 도구로 뺐다는 거다. 한 번 쓰고 말 건 안 만든다. 같은 동작을 매일 손으로 반복할 때만 MCP가 값을 한다.

MCP를 직접 만든 이유

남이 만든 MCP도 많다. 근데 내 작업은 내 톤, 내 앱, 내 루틴에 묶여 있어서 범용 도구로는 안 맞았다. 그래서 직접 만들었다.

MCP 서버라고 거창한 게 아니다. 도구 이름, 입력 스키마, 실행 함수 세 개를 정의한 작은 서버다. 공식 SDK로 도구를 선언하고, 안에서 평소 쓰던 API나 스크립트를 부르게 짜면 끝이다.

예를 들어 "내 톤으로 초안" 도구는 안에서 내 말투 규칙을 불러와 프롬프트에 끼우는 게 전부다. 새 기술이 아니라, 매번 손으로 하던 걸 함수 하나로 굳힌 거다. 80%만 먼저 만들고 나머지는 쓰면서 고쳤다.

3층 — 반복 지시는 스킬로 저장한다

마지막 층은 스킬이다. 스킬은 자주 치는 긴 지시를 슬래시 명령으로 저장해둔 거다. 전자레인지의 "자동" 버튼 같은 거다. 매번 시간과 출력을 맞추는 대신 버튼 하나 누른다.

예를 들어 글 발행 전 SEO 체크는 매번 같은 점검을 돈다. 제목, 메타 설명, alt 텍스트, 내부 링크. 이걸 매번 풀어 설명하는 대신 스킬 하나로 묶어두면 명령 한 줄로 같은 점검이 돈다.

MCP랑 헷갈리기 쉬운데 역할이 다르다. 스킬은 "지시의 재사용"이고, MCP는 "능력의 확장"이다. 스킬은 내가 할 말을 줄여주고, MCP는 Claude가 할 수 있는 일을 늘려준다.

셋이 합쳐지면

세 층이 같이 돌면 세션 시작이 이렇게 바뀐다. CLAUDE.md가 프로젝트 맥락을 깔고, MCP가 어제 흐름과 데이터를 끌어오고, 스킬이 반복 작업을 한 줄로 부른다.

예전엔 세션 열고 5분씩 설명했다. 지금은 열자마자 작업으로 들어간다. 세 개 다 "사람이 매번 들고 있던 걸 셋업으로 옮긴다"는 같은 원리다. 층만 다르다.

솔직한 한계

토큰을 더 쓴다. MCP 도구 목록과 CLAUDE.md가 매 세션 컨텍스트로 들어가니 공짜가 아니다. 그래서 안 쓰는 도구는 빼고, CLAUDE.md도 길어지면 줄인다.

유지보수도 든다. 앱 API가 바뀌면 MCP도 고쳐야 하고, CLAUDE.md가 현실과 어긋나면 오히려 방해가 된다. 셋업이 늘수록 손볼 게 늘어난다. 이건 알고는 있다. 근데 아낀 시간이 더 커서 지금은 안고 간다.

자주 묻는 것

CLAUDE.md는 어디에 둬야 하나?
세 곳이다. 홈의 글로벌엔 공통 스타일과 원칙을, 프로젝트 루트엔 그 레포 규칙을, 복잡한 하위 폴더엔 그 폴더 규칙을 둔다. Claude가 가까운 순서로 합쳐 읽는다.

커스텀 MCP는 어떻게 만드나?
도구 이름, 입력 스키마, 실행 함수를 정의한 작은 서버다. 공식 SDK로 선언하고 안에서 평소 쓰던 API를 부르면 된다.

스킬과 MCP는 뭐가 다른가?
스킬은 긴 지시를 슬래시 명령으로 저장한 것, MCP는 외부 기능을 꽂아주는 통로다. 스킬은 지시의 재사용, MCP는 능력의 확장이다.

이 셋업을 다 갖춰야 하나?
아니다. CLAUDE.md 한 장이면 대부분 해결된다. 스킬과 MCP는 매일 반복할 때만 더한다.

결론

세 층 다 같은 한 줄에서 나왔다. "매번 하던 걸 셋업으로 옮긴다." 설명은 CLAUDE.md로, 능력은 MCP로, 반복 지시는 스킬로 옮겼다.

처음부터 다 만들 필요는 없다. CLAUDE.md 한 장으로 시작해서, 같은 게 매일 반복되는 게 보이면 그때 MCP나 스킬로 뺐다. 귀찮은 게 보이면 그 층으로 옮기면 된다.

같이 보면 좋은 글

귀찮은개발자 · 모든 걸 자동화합니다