클로드 코드 확장 3가지: CLAUDE.md, 스킬, 서브에이전트 켜는 순서
CLAUDE.md 한 파일에 모든 걸 몰아넣어 클로드가 지시를 놓치는 분께 맞는 글입니다. 규칙, 절차, 하위 작업을 나눠 담는 세 가지 장치와 켜는 방법을 정리했습니다.
CLAUDE.md는 항상 지킬 규칙, 스킬은 가끔 쓰는 절차, 서브에이전트는 메인 대화를 어지럽히지 않고 따로 시키는 일을 맡습니다. 세 가지는 서로 다른 문제를 풀기 때문에 하나만 쓰면 나머지 두 문제가 남습니다.
내 CLAUDE.md를 점검해서 아래 셋으로 나눠 줘. - 항상 지켜야 하는 규칙: CLAUDE.md에 남길 것 (200줄 미만) - 가끔만 쓰는 절차나 참고 자료: 스킬로 옮길 것 - 결과가 길어서 메인 대화에 남기고 싶지 않은 작업: 서브에이전트에 맡길 것 분류한 결과와 옮기는 순서를 정리해 줘.
클로드 코드에는 CLAUDE.md(규칙 파일)·스킬(작업 절차 파일)·서브에이전트(하위 작업자) 세 가지 기본 확장 장치가 있습니다.
공식 문서는 이 세 가지를 "어디에 뭘 쓸지" 표로 정리해 두고 있고, 실제로 팀들이 이 순서대로 하나씩 켠다고 안내합니다.
왜 3개가 다 필요한가요
셋은 서로 다른 문제를 풉니다.
저는 처음엔 전부 CLAUDE.md 한 파일에 몰아넣었습니다. 규칙도, 배포 절차도, API 문서도 한 파일에 다 적었습니다. 파일이 300줄을 넘어가면서 클로드가 지시를 놓치는 일이 잦아졌습니다.
CLAUDE.md 켜기
/init을 실행하면 코드베이스를 훑어 자동으로 만들어 줍니다. 이미 있으면 개선안을 제안합니다. 공식 권고는 200줄 미만입니다.
/init스킬 만들기
같은 프롬프트를 두 번 넘게 입력했거나, 같은 절차를 대화에 세 번 넘게 붙여넣었다면 스킬로 만들 시점입니다. /<이름>으로 직접 부르거나, 클로드가 알아서 관련 있다고 판단하면 자동으로 불러옵니다.
서브에이전트 쓰기
검색 결과·로그·파일 내용처럼 다시 볼 일 없는 방대한 출력이 나오는 작업을 따로 시킬 때 씁니다. 별도 컨텍스트에서 일하고 요약만 돌려줍니다.
켜기 전후, 무엇이 달라졌나요
CLAUDE.md만 쓸 때는 배포 절차 같은 참고 자료까지 매 세션 로드돼 컨텍스트를 갉아먹었습니다. 자주 안 쓰는 내용을 스킬로 옮기고 나서 CLAUDE.md가 짧아졌고, 필요할 때만 그 절차가 불려 왔습니다.
서브에이전트를 쓰기 전에는 로그 몇백 줄을 메인 대화에 그대로 붙여넣은 적이 많았습니다. 지금은 로그 분석처럼 결과가 긴 작업은 서브에이전트에 맡기고, 메인 대화에는 요약만 받습니다.
자주 하는 실수
서브에이전트를 켜면 무조건 컨텍스트가 절약되는 줄 알았습니다. 실제로는 서브에이전트도 자기 컨텍스트에서 토큰을 씁니다. 짧은 작업까지 매번 서브에이전트로 넘기면 오히려 오가는 데 시간과 토큰이 더 들 때도 있었습니다.
지금은 "결과가 길어서 메인 대화에 남기고 싶지 않은 작업"에만 서브에이전트를 씁니다. 짧게 끝날 일은 그냥 메인에서 처리합니다.
자주 묻는 질문
CLAUDE.md와 스킬 중 뭐부터 만들어야 하나요?
CLAUDE.md가 먼저입니다. 프로젝트 관례처럼 매번 필요한 것부터 담고, 가끔만 필요한 절차가 늘어나면 그때 스킬로 분리하면 됩니다.
서브에이전트는 아무 때나 쓰면 좋나요?
아닙니다. 결과가 방대하거나 메인 대화와 무관한 조사·검증 작업에 적합합니다. 짧고 간단한 일까지 서브에이전트로 넘기면 왔다갔다하는 비용이 더 들 수 있습니다.
셋을 다 켜면 끝인가요?
아닙니다. 이 글의 3개는 공식 문서가 안내하는 기본 확장 순서를 근거로 저희가 고른 것으로, 팀 상황에 따라 우선순위는 달라질 수 있습니다.
정리
CLAUDE.md·스킬·서브에이전트는 각자 다른 문제를 풉니다. 하나만 쓰면 나머지 두 문제는 여전히 남습니다.