CLAUDE.md, commands, skills, agents를 언제 나눠야 할까 2026 — 팀용 .claude 폴더 운영분리 체크리스트

Posted on by

2026년 4월 20일 기준 Claude Code를 팀에서 굴릴 때 제일 먼저 헷갈리는 건 모델이 아니다.

어디에 무엇을 적어야 하는가다.

처음에는 전부 CLAUDE.md에 넣고 싶다.

팀 규칙도 넣고, 자주 쓰는 명령도 넣고, 리뷰 절차도 넣고, 블로그 발행 플로우도 넣고, 트레이딩 금지선도 넣고, 거기에 개인 취향까지 살짝 얹고 싶다.

그런데 이 방식은 초반에는 편하고, 중반부터는 아주 조용히 피곤해진다.

CLAUDE.md가 커질수록 Claude는 매번 들고 다녀야 할 짐이 많아진다.

사람도 마찬가지다.

새 팀원이 들어왔을 때 한 파일에 모든 규칙이 있으면 좋아 보이지만, 실제로는 어떤 규칙이 항상 적용되는지, 어떤 절차가 특정 작업에서만 필요한지, 어떤 역할이 별도 에이전트로 분리돼야 하는지 구분하기 어려워진다.

팀용 .claude 폴더는 프롬프트 보관함이 아니다.

AI 협업의 운영 경계선이다.

이 글은 그 경계선을 나누는 글이다.

CLAUDE.md에 남길 것, .claude/rules/로 뺄 것, commands나 skills로 승격할 것, 그리고 agents로 분리할 것을 실제 운영 기준으로 정리한다.

우리 볼트의 .claude 구조도 같이 본다.

이미 이 워크스페이스에는 .claude/commands/, .claude/rules/, .claude/skills/, .claude/agents/, .claude/scripts/, .claude/MEMORY/, .claude/TELOS/가 같이 있다.

말하자면 이론만 있는 글은 아니다.

이미 조금 복잡해진 집을 보면서, 가구 배치를 다시 하는 글에 가깝다.

그리고 가구 배치는 생각보다 중요하다.

소파가 부엌에 있으면 웃기긴 한데, 라면 먹을 때마다 인생이 이상해진다.

짧은 결론

CLAUDE.md는 매 세션 Claude가 반드시 알아야 하는 짧고 안정적인 기준만 담는다.

작업별 규칙은 .claude/rules/로 나눈다.

사람이 자주 부르는 반복 작업은 commands 또는 skills로 뺀다.

절차와 참고 파일이 필요한 반복 워크플로우는 skills가 더 낫다.

역할, 판단, 독립 컨텍스트가 필요한 일은 agents로 분리한다.

실행 신뢰성이 필요한 일은 scripts로 내려보낸다.

한 문장으로 말하면 이렇다.

매번 알아야 하는 것은 CLAUDE.md, 상황별로 적용할 규칙은 rules, 부르는 버튼은 commands, 재사용 절차는 skills, 따로 생각할 사람은 agents, 반드시 실행돼야 하는 것은 scripts다.

이 기준만 있어도 .claude 폴더가 꽤 덜 무서워진다.

먼저 봐야 할 분리표

팀에서 제일 먼저 정해야 할 것은 파일 이름이 아니다.

정보의 성격이다.

같은 문장이라도 성격에 따라 들어갈 위치가 달라진다.

넣을 곳 어울리는 내용 빼야 할 신호
CLAUDE.md 모든 세션에 필요한 프로젝트 공통 기준 200줄을 넘고 절차 설명이 길어진다
.claude/rules/ 주제별, 경로별, 도메인별 규칙 한 파일에서 여러 팀 정책이 뒤섞인다
.claude/commands/ 사람이 /blog, /ops처럼 직접 부르는 단축 작업 명령 안에 긴 매뉴얼과 예외가 늘어난다
.claude/skills/ 반복 절차, 체크리스트, 템플릿, 참고자료, 스크립트를 묶은 작업 능력 단순 버튼인데 과하게 복잡해진다
.claude/agents/ 역할, 책임, 판단 기준, 독립 컨텍스트가 필요한 작업자 그냥 한 번 쓰는 프롬프트다
.claude/scripts/ 재현 가능한 실행, 외부 API 연동, 검증, 발행, 동기화 사람이 매번 수동으로 해도 충분하다
.claude/docs/ 에이전트와 스킬 제작 가이드, 운영 문서 매 세션 Claude에게 전부 읽히고 있다
.claude/MEMORY/ 장기 패턴, 따뜻한 운영 맥락, 최근 반복 신호 지금 당장 실행해야 할 명령이다

이 표에서 중요한 건 상하관계가 아니라 역할이다.

skills가 commands보다 무조건 고급이라는 뜻이 아니다.

agents가 있다고 팀 운영이 자동으로 좋아진다는 뜻도 아니다.

오히려 너무 빨리 나누면 폴더만 화려해지고 작업은 느려진다.

운영 분리는 멋으로 하는 게 아니다.

반복 비용을 줄이기 위해 한다.

공식 문서가 말하는 기본선

Anthropic의 Claude Code 문서를 보면 큰 원칙은 꽤 분명하다.

CLAUDE.md는 Claude에게 지속적인 프로젝트 지시와 맥락을 주는 파일이다.

공식 문서는 CLAUDE.md를 매 세션에 로드되는 지시 파일로 설명한다.

그리고 같은 실수를 반복해서 고쳐야 하거나, 새 팀원이 알아야 할 프로젝트 기준이 있거나, 매번 다시 설명하는 내용이 있으면 CLAUDE.md에 넣으라고 안내한다.

반대로 다단계 절차이거나 특정 작업에서만 필요한 내용이면 skill이나 path-scoped rule로 옮기는 편이 낫다고 설명한다.

설정도 scope가 있다.

Claude Code settings 문서는 User, Project, Local, Managed 같은 범위를 나눈다.

팀에 공유할 설정은 프로젝트의 .claude/settings.json에 둔다.

개인 실험과 머신별 설정은 .claude/settings.local.json에 둔다.

로컬 설정은 팀 공유 대상이 아니고, 일반적으로 gitignore 쪽에 가깝다.

skills 문서도 중요한 힌트를 준다.

SKILL.md는 Claude가 필요할 때 로드하는 작업 지식이다.

반복해서 붙여 넣던 플레이북, 체크리스트, 다단계 절차가 있다면 skill로 만들라는 흐름이다.

그리고 기존 .claude/commands/ 파일은 계속 동작하지만, 요즘 구조에서는 skills가 custom command 역할까지 흡수하고 있다.

subagents 문서는 또 다른 기준을 준다.

subagent는 별도 역할과 컨텍스트를 가진 작업자에 가깝다.

특정 skill을 subagent에 미리 주입할 수도 있고, skill을 forked context에서 실행할 수도 있다.

즉 skill은 절차이고, agent는 역할이다.

이 둘을 섞으면 운영이 갑자기 흐릿해진다.

절차가 필요한데 agent를 만들면 과하다.

역할 판단이 필요한데 skill만 만들면 답답하다.

우리 .claude 폴더를 보면 바로 보인다

이 워크스페이스의 .claude 폴더는 이미 작은 운영체제처럼 굴러간다.

.claude/commands/에는 /blog, /morning, /ops, /wiki, /btc, /trade, /summary 같은 호출점이 있다.

사람이 대화 중에 짧게 부르는 버튼이다.

.claude/rules/에는 블로그, 트레이딩, 보안, AI 행동 원칙처럼 계속 지켜야 할 정책이 있다.

이건 버튼이라기보다 헌법에 가깝다.

물론 헌법도 너무 길면 아무도 안 읽는다.

그래서 주제별 파일로 쪼개야 한다.

.claude/skills/에는 URL 요약, 블로그 리뷰, LLM Wiki lint, Notion inbox sync 같은 실행 절차가 있다.

여기에는 단순 지시보다 “어떤 순서로 무엇을 확인할지”가 들어간다.

.claude/agents/에는 morning briefing team, blog pipeline team, blog idea capture team, trading coach 같은 역할이 있다.

이건 절차 하나가 아니라 관점과 책임을 가진 작업자다.

.claude/scripts/에는 실제로 데이터를 읽고 쓰는 코드가 있다.

블로그 시트 동기화, 발행, preflight, GA4, Search Console, 트레이딩 데이터 조회처럼 사람이 손으로 반복하면 사고 나기 쉬운 부분이다.

여기서 교훈이 하나 나온다.

팀용 .claude는 문서만으로는 부족하고, 문서만 없어서도 안 된다.

규칙은 문서에, 반복 절차는 skill에, 실행은 script에, 판단은 agent에 둬야 오래 간다.

한 곳에 다 넣으면 처음에는 빠르다.

나중에는 이거 어디 있더라 게임을 매일 하게 된다.

이 게임은 재미가 없다.

점수판도 없다.

CLAUDE.md에 남길 것

CLAUDE.md는 팀의 첫 화면이다.

여기에 들어갈 내용은 짧고, 안정적이고, 모두에게 적용돼야 한다.

예를 들면 이런 것들이다.

프로젝트 구조.

핵심 명령.

테스트와 빌드 기준.

절대 하지 말아야 할 위험 행동.

채널별 말투나 호칭처럼 팀 전체에 필요한 기본 규칙.

에이전트와 스킬을 어디에 둬야 하는지 같은 운영 정책.

반대로 아래 내용은 CLAUDE.md에 오래 두면 부담이 된다.

특정 기능의 긴 디버깅 절차.

한 채널에만 적용되는 상세 체크리스트.

자주 바뀌는 실험 설정.

개인 취향.

외부 서비스 토큰과 비밀값.

특정 작업에서만 필요한 긴 참고자료.

공식 문서도 CLAUDE.md가 너무 커지면 지시 준수성이 떨어질 수 있다고 본다.

Claude가 매번 읽어야 할 내용이 많아지면, 중요한 기준이 잡음 속에 묻힌다.

그래서 나는 CLAUDE.md를 “매번 다시 설명하기 싫은 핵심” 정도로 본다.

매번 설명해야 하면 넣는다.

가끔 필요한 절차면 뺀다.

설명서가 아니라 내비게이션이어야 한다.

rules로 빼는 순간

.claude/rules/는 프로젝트 규칙을 모듈화하는 장소다.

Claude Code memory 문서도 큰 프로젝트에서는 .claude/rules/로 지시를 나누라고 안내한다.

특히 path-specific rule을 쓰면 특정 파일이나 경로를 다룰 때만 규칙이 로드되게 만들 수 있다.

팀 운영에서는 이게 꽤 중요하다.

블로그 글쓰기 규칙이 트레이딩 코드 수정 때마다 전부 떠오르면 피곤하다.

트레이딩 리스크 규칙이 블로그 메타 설명을 고칠 때마다 끼어들어도 이상하다.

규칙은 필요할 때 나타나야 한다.

계속 나타나야 할 규칙과, 상황별로 나타나야 할 규칙을 나누는 게 rules의 역할이다.

이 워크스페이스도 비슷하다.

블로그 작성 시에는 .claude/rules/blog-writing.md를 본다.

트레이딩 작업 시에는 .claude/rules/trading.md를 본다.

보안 기준은 별도 규칙으로 둔다.

이렇게 하면 CLAUDE.md가 팀 전체 운영 안내판 역할을 하고, rules가 현장별 세부 규정 역할을 한다.

좋은 분리 신호는 이거다.

한 규칙이 특정 도메인에서만 중요하다.

파일 경로나 작업 종류에 따라 적용 여부가 달라진다.

규칙이 길어져서 CLAUDE.md에서 읽기 흐름을 방해한다.

그때는 rules로 빼는 편이 낫다.

commands로 빼는 순간

commands는 사람이 직접 부르는 버튼이다.

예전 Claude Code custom slash command 구조에서는 .claude/commands/에 markdown 파일을 두고 /name으로 호출했다.

공식 SDK slash command 문서도 .claude/commands/를 legacy 형식으로 설명하면서, 현재는 .claude/skills/<name>/SKILL.md 형식을 더 권장한다.

그렇다고 기존 commands가 쓸모없다는 뜻은 아니다.

팀 워크플로우에서는 여전히 사람이 이해하기 쉬운 단축키 역할을 한다.

우리 볼트의 /blog는 글감 수집과 아이디어 업데이트를 부르는 입구다.

/ops는 운영 점검을 부르는 입구다.

/wiki는 LLM Wiki 반영과 lint를 부르는 입구다.

이런 명령은 대화 중에 손이 먼저 간다.

사람이 부르기 쉽다는 건 중요하다.

자동화가 아무리 좋아도, 호출 이름이 기억나지 않으면 안 쓰게 된다.

commands로 빼기 좋은 신호는 세 가지다.

첫째, 같은 요청을 두세 번 이상 반복했다.

둘째, 작업 이름이 사람의 입에서 짧게 나와야 한다.

셋째, 긴 설명보다 “이거 해줘”가 더 자연스럽다.

예를 들어 “오늘 블로그 글감 체크하고 발행 계속해”는 command 입구가 있어야 한다.

반대로 “이번 한 번만 이 파일 요약해줘”는 command까지 만들 필요가 없다.

명령은 버튼이다.

버튼을 너무 많이 만들면 리모컨이 된다.

리모컨에 버튼이 80개 있으면 결국 전원 버튼만 누른다.

skills로 빼는 순간

skills는 단순 버튼보다 더 진한 운영 단위다.

공식 문서의 핵심은 이렇다.

반복해서 붙여 넣는 플레이북, 체크리스트, 다단계 절차, 지원 파일, 템플릿, 스크립트가 있으면 skill로 만든다.

skill은 SKILL.md가 중심이고, 필요하면 scripts/, references/, examples/, assets/ 같은 지원 파일을 같이 둘 수 있다.

이게 CLAUDE.md와 가장 큰 차이다.

CLAUDE.md는 매번 로드되는 기본 지시다.

skill 본문은 필요할 때만 로드된다.

그래서 긴 운영 절차를 CLAUDE.md에서 빼내기 좋다.

블로그 채널 QC가 좋은 예다.

TECHTAEK, TAEK2, 배당노마드 중 어디에 맞는지 판단하는 기준은 중요하다.

하지만 모든 세션에서 항상 전문을 들고 있을 필요는 없다.

블로그 초안 리뷰를 할 때만 로드되면 된다.

LLM Wiki lint도 마찬가지다.

위키 반영 작업이 아닐 때는 굳이 계속 떠 있을 필요가 없다.

skill로 빼기 좋은 신호는 다음과 같다.

절차가 5단계 이상이다.

참고 문서나 템플릿을 같이 봐야 한다.

사람이 매번 같은 체크리스트를 붙여 넣는다.

출력 형식이 중요하다.

검증 스크립트가 붙으면 더 좋다.

여기서 실무 감각 하나.

skill은 “잘 쓴 프롬프트”가 아니다.

작업을 재현 가능하게 만드는 작은 작업 매뉴얼이다.

그래서 skill 안에는 미사여구보다 순서, 입력, 출력, 검증 기준이 더 중요하다.

멋진 문장보다 덜 까먹는 구조가 이긴다.

agents로 빼는 순간

agents는 역할이다.

skills가 “어떻게 할지”라면, agents는 “누가 어떤 관점으로 판단할지”에 가깝다.

Claude Code subagents 문서에서도 custom subagents는 별도의 시스템 프롬프트, 도구, 컨텍스트를 가진 작업자로 다룬다.

또 subagent에 skills를 미리 넣을 수 있다.

이 조합이 꽤 강하다.

예를 들어 blog-pipeline-team은 그냥 글쓰기 절차 하나가 아니다.

글감 확인, 채널 적합도, 초안 작성, 리뷰, 발행, 시트 동기화까지 이어지는 운영 책임이다.

이건 skill 하나보다 agent 쪽에 가깝다.

반대로 “SEO 메타 설명 작성 규칙”은 agent가 아니라 skill이나 rule이 더 자연스럽다.

에이전트로 빼기 좋은 신호는 이렇다.

역할 이름을 붙일 수 있다.

판단 기준이 있다.

독립적으로 조사하거나 리뷰해야 한다.

작업이 여러 단계로 이어진다.

다른 skill이나 script를 조합해야 한다.

실패했을 때 복구 판단이 필요하다.

여기서 조심할 점도 있다.

모든 작업을 agent로 만들면 팀이 좋아지는 게 아니라 회의가 많아진다.

AI도 조직도가 과하면 느려진다.

작은 작업은 skill이 낫고, 명확한 버튼은 command가 낫고, 실행은 script가 낫다.

agent는 진짜 역할이 필요할 때만 만든다.

이름 붙였을 때 사람이 “아, 얘는 이걸 책임지는구나”라고 이해하면 통과다.

이름 붙였는데 “그래서 뭐 하는 애지”가 나오면 아직 이르다.

settings.json과 local 파일을 나누는 법

.claude/settings.json과 .claude/settings.local.json은 팀 운영에서 조용히 중요하다.

공식 settings 문서에 따르면 project scope의 .claude/settings.json은 저장소에 커밋해서 팀과 공유하는 설정이다.

local scope의 .claude/settings.local.json은 이 저장소에서 나에게만 적용되는 설정이고, 팀과 공유하지 않는다.

이 구분을 놓치면 사고가 난다.

팀 공통 권한, 공통 hook, 공통 MCP 서버 설정처럼 모두가 같은 기준을 써야 하는 것은 프로젝트 설정으로 둔다.

개인 실험, 머신별 경로, 임시 허용, 개인 도구 연결은 local로 둔다.

API key나 인증 정보는 공유 설정에 넣지 않는다.

이건 취향 문제가 아니다.

생존 문제다.

팀이 같이 쓰는 .claude/settings.json에 개인 경로나 토큰이 들어가면, 다음 사람의 환경에서 깨지거나 보안 사고가 된다.

따라서 팀 도입 때는 설정 파일부터 이렇게 물어봐야 한다.

이 설정이 모든 팀원에게 동일하게 적용돼도 괜찮은가.

커밋돼도 괜찮은가.

다른 OS나 다른 머신에서도 작동하는가.

아니라면 local로 둔다.

docs와 scripts는 왜 따로 있어야 하나

.claude/docs/는 지식 저장고다.

에이전트 구조, 스킬 구조, 검증 체크리스트, 운영 가이드처럼 사람이 참고해야 하는 긴 설명을 둔다.

하지만 docs는 실행자가 아니다.

docs에 적혀 있다고 자동으로 지켜지지는 않는다.

그래서 자주 쓰는 절차는 skill로 승격하고, 반드시 실행돼야 하는 검증은 script로 내리는 게 좋다.

예를 들어 “블로그 발행 전 FAQ와 참고 자료가 있어야 한다”는 규칙이다.

그 규칙이 문서에만 있으면 까먹을 수 있다.

하지만 blog_preflight_check.py 같은 script가 있으면 발행 전에 실제로 막아준다.

이게 문서와 하네스의 차이다.

문서는 기억을 돕고, 스크립트는 실수를 막는다.

팀 운영에서 안정성이 필요하면 마지막에는 코드가 있어야 한다.

AI가 아무리 똑똑해도, 체크리스트를 100번 중 100번 기억한다고 보장할 수는 없다.

그래서 “중요한 규칙”은 문서에만 남기지 말고, 가능하면 실행 검증으로 내려야 한다.

TECHTAEK 발행 파이프라인도 그래서 preflight, publisher, sheet sync가 따로 있다.

글은 사람이 쓰지만, 발행 계약은 코드가 본다.

마음은 따뜻하게, 검증은 차갑게.

이 조합이 오래 간다.

팀 도입 순서

처음부터 .claude 폴더를 풀세트로 만들 필요는 없다.

오히려 처음부터 다 만들면 대부분 빈 껍데기가 된다.

추천 순서는 이렇다.

1단계.

CLAUDE.md를 한 장으로 만든다.

프로젝트 구조, 빌드와 테스트, 금지 행동, 공통 말투, 중요한 경로만 적는다.

2단계.

공유 설정과 개인 설정을 나눈다.

.claude/settings.json에는 팀 공통만 둔다.

.claude/settings.local.json에는 개인 실험과 머신별 값을 둔다.

3단계.

사람이 자주 부르는 작업을 command로 만든다.

이름은 짧게 한다.

동사 하나면 더 좋다.

4단계.

CLAUDE.md가 길어지기 시작하면 rules로 나눈다.

블로그, 트레이딩, 보안, 프론트엔드, 테스트처럼 주제별로 쪼갠다.

5단계.

반복 절차가 생기면 skill로 만든다.

여기에는 입력, 출력, 순서, 검증 기준을 적는다.

6단계.

역할이 생기면 agent로 만든다.

리뷰어, 리서처, 발행 담당, 운영 점검 담당처럼 책임이 분명해야 한다.

7단계.

실패하면 곤란한 작업은 script로 내린다.

검증, 발행, 동기화, 리포트 생성 같은 작업이 여기에 해당한다.

이 순서의 핵심은 단순하다.

문서로 시작하고, 반복을 분리하고, 판단을 역할화하고, 실행을 코드화한다.

이 순서가 뒤집히면 도구가 먼저 생기고 운영은 나중에 따라간다.

그 상태에서는 팀이 도구를 쓰는 게 아니라, 도구가 팀을 숙제처럼 만든다.

숙제는 우리도 충분히 했다.

이제 그만해도 된다.

승격 기준 체크리스트

아래 질문에 예가 많아질수록 분리해야 한다.

CLAUDE.md에서 rules로 뺄까?

이 규칙이 특정 파일, 특정 도메인, 특정 채널에서만 중요한가.

이 규칙 때문에 CLAUDE.md가 길어지는가.

팀원이 이 규칙을 독립적으로 수정해야 하는가.

그렇다면 rules로 뺀다.

CLAUDE.md에서 skill로 뺄까?

이 내용이 절차인가.

순서가 중요한가.

입력과 출력이 있는가.

참고 파일이나 템플릿이 붙는가.

검증 명령이 있는가.

그렇다면 skill로 뺀다.

command에서 skill로 올릴까?

단순 호출을 넘어 지원 파일이 필요해졌는가.

프론트매터로 호출 조건을 제어하고 싶은가.

Claude가 자동으로 필요성을 판단해 불러도 되는가.

그렇다면 skill이 더 낫다.

skill에서 agent로 올릴까?

이 작업에 독립적인 관점이 필요한가.

실패했을 때 스스로 판단해야 하는가.

다른 skill과 script를 조합해야 하는가.

결과를 리뷰하거나 책임져야 하는가.

그렇다면 agent가 맞다.

agent에서 script로 내릴까?

결과가 매번 같아야 하는가.

데이터를 안전하게 쓰거나 동기화해야 하는가.

실패 로그와 재시도가 필요한가.

사람의 기억에 맡기면 위험한가.

그렇다면 script가 맞다.

이 체크리스트는 완벽한 법전이 아니다.

다만 팀이 “이거 어디에 둬?”라고 물을 때, 회의를 30분 줄여주는 정도의 도구다.

그 정도면 밥값은 한다.

흔한 실수

첫 번째 실수는 CLAUDE.md에 다 넣는 것이다.

초기에는 제일 쉬운 선택이다.

하지만 200줄, 300줄, 500줄이 되면 Claude도 사람도 집중력이 떨어진다.

중요한 규칙이 많이 있는 파일은, 중요한 규칙이 잘 안 보이는 파일이 되기 쉽다.

두 번째 실수는 agent를 너무 빨리 만드는 것이다.

역할이 안정되기 전에 agent를 만들면, 그 agent는 사실상 긴 프롬프트 이름표가 된다.

먼저 skill로 절차를 고정하고, 그 절차를 실제로 책임질 역할이 생겼을 때 agent로 올리는 편이 낫다.

세 번째 실수는 command와 skill을 중복으로 만드는 것이다.

/blog 명령이 있는데 blog skill도 있고, 둘이 다른 말을 하면 사람이 먼저 헷갈린다.

중복 자체가 나쁜 건 아니지만, 우선순위와 진짜 entrypoint가 정해져 있어야 한다.

네 번째 실수는 local과 project 설정을 섞는 것이다.

개인 실험을 공유 설정에 넣으면 팀 전체가 실험실이 된다.

실험실은 좋다.

하지만 모두의 책상이 실험실이면 컵라면도 위험하다.

다섯 번째 실수는 archive를 안 하는 것이다.

오래된 commands, 죽은 skills, 이제 안 쓰는 agents를 계속 active 폴더에 두면 Claude의 선택지도 사람의 선택지도 지저분해진다.

쓰지 않는 것은 archived로 보내고, active에는 지금 쓰는 것만 남기는 게 좋다.

TECHTAEK식 운영 결론

TECHTAEK 관점에서 .claude 폴더는 AI 생산성 도구가 아니라 운영 설계다.

좋은 도구를 붙이는 것도 중요하지만, 도구가 어디에 붙어야 하는지 정하는 일이 더 중요하다.

CLAUDE.md는 팀의 기본 약속이다.

rules는 분야별 규칙이다.

commands는 사람이 부르는 호출점이다.

skills는 반복 가능한 작업 능력이다.

agents는 책임과 관점을 가진 작업자다.

scripts는 실행 신뢰성이다.

이렇게 나누면 팀원이 늘어나도 구조가 버틴다.

작업이 늘어나도 어디를 고쳐야 하는지 보인다.

무엇보다 Claude에게 매번 모든 것을 한꺼번에 떠먹이지 않아도 된다.

AI 협업에서 컨텍스트는 공짜가 아니다.

사람의 주의력도 공짜가 아니다.

둘 다 아껴 써야 한다.

그래서 .claude 폴더 운영의 핵심은 더 많이 넣는 게 아니라, 덜 헷갈리게 나누는 것이다.

작게 시작한다.

반복되면 분리한다.

검증이 필요하면 코드화한다.

역할이 필요하면 agent로 둔다.

그리고 더 이상 안 쓰면 치운다.

깔끔한 .claude 폴더는 멋있어서 좋은 게 아니다.

내일의 내가 덜 씩씩거리게 해준다.

이 정도면 꽤 큰 복지다.

FAQ

CLAUDE.md와 AGENTS.md를 둘 다 써야 하나?

Claude Code 기준으로는 CLAUDE.md가 기본이다.

공식 memory 문서도 Claude Code는 CLAUDE.md를 읽는다고 설명한다.

다만 다른 에이전트 런타임이 AGENTS.md를 쓰는 팀이라면, CLAUDE.md에서 AGENTS.md를 import하는 방식으로 중복을 줄일 수 있다.

이 워크스페이스도 여러 런타임이 공통 규칙을 읽는 구조라서, 중복보다 단일 원본을 유지하는 쪽이 더 중요하다.

commands와 skills 중 무엇을 먼저 만들까?

사람이 직접 자주 부르는 짧은 버튼이면 command 감각으로 시작해도 된다.

하지만 절차, 참고자료, 스크립트, 검증 기준이 붙기 시작하면 skill이 더 자연스럽다.

Claude Code 최신 문서 흐름도 custom command보다 skills 쪽을 더 권장하는 방향이다.

기존 .claude/commands/는 계속 동작하므로, 당장 모두 옮기기보다 새 워크플로우부터 skill 중심으로 설계하는 편이 안전하다.

skill과 agent의 가장 쉬운 구분은 무엇인가?

skill은 절차다.

agent는 역할이다.

“이 순서대로 해”는 skill에 가깝다.

“이 관점으로 판단하고 책임져”는 agent에 가깝다.

예를 들어 발행 전 체크리스트는 skill이다.

블로그 파이프라인 전체를 보고 글감, 초안, 리뷰, 발행, 동기화를 이어가는 책임자는 agent다.

.claude/settings.json에 개인 설정을 넣어도 되나?

팀과 공유돼도 되는 설정만 넣는 게 좋다.

공식 settings 문서 기준으로 .claude/settings.json은 project scope이고, 저장소에 커밋해 팀과 공유하는 설정이다.

개인 실험, 머신별 경로, 개인 도구 연결은 .claude/settings.local.json로 빼는 편이 안전하다.

비밀값은 공유 설정에 넣지 않는다.

이건 진짜로 농담 없이 중요하다.

처음 팀 도입 때 최소 구성은 무엇이면 충분할까?

처음에는 CLAUDE.md, .claude/settings.json, 그리고 아주 적은 수의 command나 skill이면 충분하다.

처음부터 agents와 scripts까지 풀세트로 만들 필요는 없다.

한 달 정도 반복 작업을 보면서, 자주 쓰는 절차를 skill로 빼고, 역할이 안정된 뒤 agent로 올리는 흐름이 더 낫다.

도구는 팀의 반복을 보고 만들어야지, 팀이 도구 목록에 맞춰 움직이면 금방 피곤해진다.

참고 자료

관련 글