요약 · Claude Code를 설정 중심 도구로 운용하면 반복 작업이 줄고 품질이 올라갑니다. CLAUDE.md로 규칙을 고정하고, Skills와 Subagents로 검증 루프·병렬화를 붙이는 실전 절차를 정리했습니다.
왜 지금 Claude Code는 ‘설정’으로 완성되는가
Claude Code는 개발 흐름에 맞춰 도구 실행과 컨텍스트를 결합하는 작업 보조 환경이다. 같은 모델이라도 디렉터리 구조, CLAUDE.md, Skills, Subagents, MCP 설정에 따라 결과가 크게 달라진다.
프롬프트만 공들여도 초반에는 성과가 보이지만, 규모가 커지면 일관성과 안전성의 벽에 부딪힌다. 설정은 이 벽을 넘게 해준다. 규칙을 파일로 고정하고, 권한을 설계하고, 반복을 자동화하면 품질과 속도가 함께 오른다.
핵심은 “설정이 실행을 좌우한다”는 관점이다. 한 번 정리한 설정은 모든 세션의 초기 컨텍스트가 되어, 개인·팀의 습관을 도구의 행동으로 구체화한다.
검증 루프 한 줄 요약과 핵심 효과
검증 루프는 Claude에게 자기 출력을 시험할 수단(테스트·타입체크·실행)을 주고, 결과가 좋아질 때까지 반복하게 하는 구조다. 이때 실패 로그와 제한된 수정 권한은 학습 신호가 된다.
예를 들어 “끝나기 전 타입체크와 단위 테스트를 실행하라”를 규칙으로 고정하면, Claude는 실패를 감지하고 자체 수정 제안을 반복한다. 반복은 길어질 수 있지만 최종 산출물은 안정된다.
검증 루프는 설정 파일과 도구 권한으로 구현된다. 프롬프트 설명보다 “테스트를 실행할 수 있는 권한과 절차”를 제공하는 것이 효과적이다. 공식 문서의 개요는 이런 설계 철학을 전제로 기능을 소개한다.
CLAUDE.md란 무엇인가: 자동 로드되는 프로젝트 메모리
CLAUDE.md는 세션 시작 시 자동으로 컨텍스트에 포함되는 지침 파일이다. 위치는 프로젝트 루트(./CLAUDE.md)와 사용자 전역(~/.claude/CLAUDE.md)이며, 하위 디렉터리에도 둘 수 있다.
우선순위는 프로젝트가 전역보다 높게 적용되어, 동일 규칙이 충돌하면 프로젝트 규칙이 이긴다. 이 덕분에 개인 습관은 전역에, 저장소별 워크플로는 프로젝트 루트에 배치하면 명확해진다.
문서는 규칙·워크플로·주의점의 ‘핵심만’ 담는다. 길게 쓰기보다 누락 시 Claude가 실수할 내용에 집중해야 효과가 크다. 자세한 포맷과 동작은 공식 문서를 참조하면 된다.
CLAUDE.md 잘 쓰는 법: 짧게·Gotchas·워크플로
첫째, 짧게 쓴다. 규칙이 길어질수록 우선순위 판단이 어려워지며, 중요한 문장이 묻힌다. 빼면 실수할 내용을 남기고, 나머지는 저장소 문서나 템플릿으로 분리한다.
둘째, Gotchas를 축적한다. 과거에 발생한 실수(예: “테스트에서 외부 API 호출을 목으로 대체”)를 한 줄로 규정하면, 같은 오류 재발을 줄일 수 있다.
셋째, 워크플로를 명확히 쓴다. 예를 들어 “PR 생성 전 타입체크→테스트→리포트 요약→커밋 메시지 검토” 순서를 규칙화하면, 매 세션 동일 품질의 산출을 얻는다.
규칙을 Claude에게 쓰게 하기: 누적 규칙의 힘
같은 실수가 반복되면 Claude에게 “이걸 반복하지 않게 CLAUDE.md를 업데이트해”라고 요청한다. 모델이 스스로 규칙 문안을 제안하고, 당신은 수정·채택만 하면 된다.
이 방식은 규칙이 실제 문제에서 출발하도록 만든다. 문구는 간결하게, 테스트 가능하게 쓰고, 예외는 따로 적는다.
규칙 추가 후에는 꼭 최소 한 번의 검증 루프를 돌려 반영 효과를 확인한다. 실패 로그는 규칙 문구를 가다듬는 실증적 근거가 된다.
@path 임포트와 CLAUDE.local.md로 모듈화
@path 임포트로 다른 파일을 참조하면 CLAUDE.md를 모듈화할 수 있다. 공통 규칙은 별도 파일로 분리하고, 프로젝트 특화 규칙만 루트에 둔다.
개인 환경 규칙은 CLAUDE.local.md에 두고 보통 .gitignore에 포함한다. 예를 들어 개인 단축 메모, 사설 레지스트리 주소, 로컬 스크립트 경로 같은 항목이 여기에 적합하다.
모듈화의 목적은 유지보수다. 변경이 잦은 영역을 분리하고, 팀에 공유할 내용은 저장소에, 개인 메모는 로컬에 배치하면 충돌을 줄일 수 있다.
Skills란 무엇인가: 재사용 가능한 전문성
Skills는 반복되는 전문 작업을 재사용 블록으로 고정하는 구조다. 정의 위치는 .claude/skills/<이름>/SKILL.md이며, 보조 파일로 templates/와 examples/를 함께 둘 수 있다.
frontmatter에는 name과 description이 포함된다. description은 언제, 어떤 입력에 이 Skill을 적용할지 요약해 모델이 스스로 적합성을 판단하는 근거가 된다.
Skills는 프로젝트 간 이식이 쉽고, 팀 표준을 공유하기에도 적합하다. 공식 문서는 구조와 동작 방식을 상세히 안내한다.
Skill 만드는 법: SKILL.md·description·allowed-tools
SKILL.md에는 절차, 입력과 출력 기대치, 실패 시 대응을 작성한다. 예를 들어 “문서화 규칙 검사” Skill이라면 검사 항목과 예외 사례, 리포트 형식을 명시한다.
allowed-tools로 허용 도구를 제한해 안전 경계를 만든다. “검증만 하고 수정은 안 함” 같은 정책은 읽기 전용 도구만 열어 구현할 수 있다.
위험도가 있는 작업(배포 등)은 자동 호출을 끄고 명시 호출만 허용한다. 호출 정책은 description과 함께 문서에 명확히 적어 혼선을 줄인다.
자동 호출과 명시 호출: 안전 경계 설계
모델은 description을 보고 적절할 때 Skill을 자동 호출할 수 있다. 그러나 안전이 중요한 작업은 자동 호출을 비활성화하고, 사용자가 의식적으로 호출하도록 설계한다.
자동 호출은 생산성을 높이고, 명시 호출은 책임 경계를 또렷이 한다. 팀에서는 위험 작업 목록을 별도로 관리해 정책을 통일하는 편이 좋다.
도구 권한은 최소 권한 원칙으로 배치한다. 검증·리포트는 읽기 권한, 변경·배포는 별도 확인 절차를 통해 실행하는 식으로 단계를 분리한다.
언제 Skill로 만들까: 3회 반복 신호와 확장
같은 프롬프트를 세 번 이상 반복하면 Skill로 만들 때라는 신호다. 빈도가 높을수록 표준화의 이득이 커지고, 품질 편차가 줄어든다.
Skill에 예시 입력과 기대 출력 스냅샷을 함께 보관하면 검증 루프가 쉬워진다. 실패 시 차이를 요약하고, 문안을 고쳐 누적 개선을 만든다.
필요에 따라 Anthropic 공식 스킬과 플러그인 마켓플레이스를 통해 범위를 확장할 수 있다. 호환성이나 권한은 문서를 확인해 신중히 적용한다.
Subagents란 무엇인가: 격리 컨텍스트의 가치
Subagents(서브에이전트)는 .claude/agents/<이름>.md에 정의하는 격리 실행 단위다. frontmatter에는 name, description, tools, model 등을 둔다.
서브에이전트는 많은 파일을 읽는 작업을 독립 컨텍스트에서 수행하고, 결과 요약만 메인 세션으로 돌려준다. 이로써 메인 컨텍스트 부피가 불어나지 않는다.
여러 서브에이전트를 병렬로 돌리면, 구현·검토·문서화 같은 흐름을 동시에 전개할 수 있다. 각 결과는 메인 세션에서 통합 판단으로 이어진다.
Subagent 설계: tools 제한·model 선택·“지적 금지”
도구 권한을 꼼꼼히 제한하면 서브에이전트의 성격이 명확해진다. 예를 들어 리뷰 전용 에이전트에는 Read·Grep·Bash만 부여해 수정 권한을 제거한다.
description에는 역할 범위와 평가 기준, 산출 형식, 종료 조건을 적는다. “이런 건 지적하지 말 것” 섹션을 둬 스타일 취향 같은 잡음을 줄이면 리뷰 품질이 높아진다.
model 선택은 작업 성격과 비용, 지연을 고려해 정한다. 세부 모델 옵션과 호출 방식은 버전에 따라 다를 수 있으니 공식 문서를 참고한다.
코드 리뷰 서브에이전트 예시: 구현 절차
agents/code-review.md에 name, description, tools(Read·Grep·Bash), model을 정의한다. description에는 “수정은 제안만, 자동 변경 금지”를 명시한다.
리뷰 항목은 안전·테스트·타입·성능·가독성 순으로 고정하고, “취향 차이, 포맷터가 해결할 일은 지적 금지”를 둔다. 출력은 요약→심각도→근거 코드 스니펫→제안 순서로 표준화한다.
메인 세션에서는 이 서브에이전트 결과를 받아 우선순위를 정한다. 필요한 경우 별도의 수정 서브에이전트에 전달하거나, 직접 커밋하되 검증 루프를 다시 돌린다.
세 기능의 누적 효과: 함께 쓸 때의 시너지
CLAUDE.md가 규칙을 고정해 기준선 품질을 보장하고, Skills가 반복 절차를 표준화한다. Subagents가 병렬 처리로 시간을 벌어준다.
검증 루프는 이 세 축을 관통한다. 각 기능에서 실패 신호를 수집하고, 규칙·스킬·서브에이전트 설정을 갱신하면 다음 사이클의 초기 품질이 올라간다.
결과적으로 산출 속도는 빨라지고, 리뷰 비용과 회귀 오류가 줄어든다. 작은 개선이 누적되어 팀의 개발 체감이 서서히 좋아진다.
일상 워크플로 예시: 구현/검토 분리와 병렬 세션
먼저 CLAUDE.md에 “PR 전 타입체크·테스트·리포트 요약”을 고정한다. 이후 구현은 메인 세션, 리뷰·문서화는 서브에이전트 두 개로 분리해 병렬 실행한다.
구현 중 발견되는 반복 프롬프트는 바로 Skill로 승격한다. 예를 들어 “커밋 메시지 규칙 검사”를 스킬화해 모든 브랜치에서 같은 잣대를 적용한다.
세션 종료 전에는 검증 루프를 한 차례 더 돌려 실패 여부를 점검한다. 실패 로그는 CLAUDE.md Gotchas로 환류해 다음 사이클의 기준을 세운다.
시작하기 체크리스트
- 프로젝트 루트에 CLAUDE.md를 만들고, 전역 규칙은 ~/.claude/CLAUDE.md로 분리한다.
- 자주 반복한 프롬프트 3가지를 골라 .claude/skills/<이름>/SKILL.md로 스킬화한다.
- 리뷰 전용 Subagents를 .claude/agents/ 경로에 만들고 수정 권한을 제거한다.
- 검증 루프를 위한 테스트·타입체크·스크립트를 정리하고 실행 절차를 명문화한다.
- MCP나 필요한 도구 권한을 최소 권한 원칙으로 설계한다.
주의 사항과 버전 차이, 공식 문서 참고
경로·옵션·모델명은 버전과 플랫폼에 따라 다를 수 있다. 정책 플래그나 자동/명시 호출 설정도 업데이트될 수 있으므로 공식 문서를 수시로 확인하는 편이 안전하다.
단축키, 실행 버튼 위치 같은 UI 요소는 환경마다 차이가 있다. 문서에 있는 개념과 파일 구조를 우선 익히고, 세부 조작은 당신의 도구 버전에 맞춰 적용하자.
공식 문서는 CLAUDE.md(메모리), Skills, Subagents, 개요를 별도 항목으로 제공한다. 실전 팁은 참고 글을 보되, 보안·권한 설계는 프로젝트 맥락에 맞게 조정해야 한다.
자주 묻는 질문
- CLAUDE.md는 어디에 두나요?
- 프로젝트 루트(./CLAUDE.md)와 사용자 전역(~/.claude/CLAUDE.md)에 둡니다. 하위 디렉터리에도 둘 수 있으며, 프로젝트 규칙이 전역보다 우선합니다. 내용은 짧고 검증 가능한 규칙 위주로 유지하세요.
- Skill은 언제 만드나요?
- 같은 프롬프트를 세 번 이상 반복할 때가 신호입니다. .claude/skills/<이름>/SKILL.md에 name·description·절차를 정의하고, allowed-tools로 안전 경계를 설정하세요. 자동/명시 호출 정책도 함께 명시하면 좋습니다.
- Subagent는 메인 세션과 뭐가 다른가요?
- 격리된 컨텍스트에서 실행돼 메인 세션의 컨텍스트를 불리지 않습니다. 많은 파일을 읽는 분석을 병렬로 수행하고 요약만 반환하므로, 구현·검토·문서화를 분리해 속도를 올릴 수 있습니다.
- 리뷰 서브에이전트에 수정 권한을 줘도 되나요?
- 가능하지만 권장하지 않습니다. Read·Grep·Bash만 허용해 스스로 고치며 합리화하는 상황을 막고, “이런 건 지적하지 말 것” 규칙으로 잡음을 줄이는 편이 안정적입니다.
- Claude.md와 CLAUDE.md 중 무엇이 맞나요?
- CLAUDE.md가 맞습니다. 개인용 규칙은 CLAUDE.local.md에 두고 보통 .gitignore에 포함해 관리하세요. 프로젝트별 규칙은 루트 CLAUDE.md로 고정하면 충돌을 줄일 수 있습니다.
