Claude Code 팀 온보딩 2026 — AGENTS.md·SKILL.md·hooks를 어떤 순서로 깔아야 덜 망할까

처음엔 hooks부터 손대고 싶다.

알림도 받고 싶고, 자동화도 하고 싶고, 멋있어 보이니까.

근데 팀 온보딩은 늘 반대로 가야 덜 망한다.

AGENTS.md로 누가 뭘 하는지 먼저 정하고, SKILL.md로 반복 절차를 얇게 고정하고, 그다음에 hooks로 자동 반응을 붙여야 한다.

이 순서가 뒤집히면, 자동화는 빨라지는데 팀은 더 멍청해진다.

Quick Answer
Claude Code 팀 온보딩의 기본 순서는 AGENTS.md → SKILL.md → hooks다.
먼저 역할과 경계를 정하고, 그다음 반복 작업의 절차를 파일로 고정하고, 마지막에 자동 알림·검사·차단을 붙여야 한다.
반대로 hooks부터 깔면 자동화가 규칙을 앞질러서, 결국 사람이 뒤에서 수습하게 된다.

이 글이 필요한 사람

• Claude Code를 혼자 말고 팀으로 굴리려는 사람
• AGENTS.md, SKILL.md, hooks가 각각 뭐 하는지 감이 섞인 사람
• 자동화부터 붙였다가 오히려 운영이 더 피곤해진 사람
• 팀 온보딩 문서를 만들고 싶은데 어떤 순서로 써야 할지 막힌 사람
• 권한, 절차, 자동화가 따로 놀지 않게 정리하고 싶은 사람

지금 결론

1. 먼저 AGENTS.md로 팀의 역할, 책임, 금지선을 고정한다.
2. 그다음 SKILL.md로 자주 반복되는 절차를 얇고 명확하게 만든다.
3. 마지막에 hooks로 알림, 검사, 승인 루프를 자동화한다.
4. subagents는 보통 SKILL 뒤나 hooks 앞에서 필요할 때만 붙인다.
5. 자동화는 온보딩을 대체하지 못하고, 온보딩이 자동화의 품질을 결정한다.

왜 순서가 중요한가

Claude Code를 팀에 넣을 때 제일 흔한 착각은 이거다.

도구가 좋으면 알아서 굴러가겠지

현실은 다르다.

도구가 좋아도, 팀이 무엇을 믿고, 누가 어디까지 하고, 어디서 멈춰야 하는지 없으면 오히려 더 자주 흔들린다.

기능은 늘어났는데 운영은 더 피곤해지는 이유가 딱 이거다.

그래서 온보딩은 기능 추가가 아니라 운영 질서 만들기다.

추천 순서 한 장 요약

순서	파일	역할	먼저 정할 것
1	AGENTS.md	역할/책임/경계	누가 무엇을 책임지는가
2	SKILL.md	반복 절차/실행 지식	어떤 작업을 같은 방식으로 반복할 것인가
3	hooks	자동 알림/검사/차단	어디서 자동 반응을 붙일 것인가
4	subagents	좁은 역할 분리	어떤 일을 작은 워커로 나눌 것인가

이 표를 거꾸로 읽으면 실패 패턴이 보인다.

hooks 먼저 → 자동화만 많고 책임은 흐림

SKILL 먼저 → 절차는 있는데 누가 뭘 책임지는지 없음

AGENTS 먼저 → 다소 심심하지만 제일 안전함

1단계: AGENTS.md부터 깔아야 하는 이유

AGENTS.md는 팀의 운영 헌법이다.

여기서 정해야 하는 건 기능이 아니다.

• 누가 무엇을 맡는가
• 어떤 파일을 누가 만지는가
• 승인 없이 해도 되는 일과 안 되는 일은 무엇인가
• 실패했을 때 누구에게 되돌리는가

이걸 먼저 고정하지 않으면, 뒤의 SKILL도 hooks도 전부 방향을 잃는다.

AGENTS.md에 꼭 들어가야 하는 것

• 역할 정의
• 책임 범위
• 금지 행동
• 승인 필요한 행동
• 산출물 형식
• 리뷰 기준
• fallback 규칙

AGENTS.md에 너무 많이 넣지 말 것

• 도구 사용법 장문 설명
• 반복 절차 세부 단계
• 코드 조각 과다
• 예외 케이스 전체 나열

AGENTS.md는 두꺼운 매뉴얼이 아니다.

팀이 이 프로젝트에서 무엇을 믿어야 하는지 말해주는 얇은 선언문에 가깝다.

AGENTS.md 최소 구조 예시

# AGENTS.md

## 역할
- Operator: 원고 구조와 내부링크 관리
- Reviewer: 채널 적합성 검수
- Publisher: 발행과 상태 반영

## 원칙
- source of truth는 Sheets다
- 외부 발행은 승인 후에만 한다
- 실패하면 원인과 복구 단계를 남긴다

## 금지
- 임의로 허브를 새로 만들지 않는다
- 중복 제목을 발행하지 않는다
- 링크가 깨진 상태로 넘기지 않는다

이 정도만 있어도 팀이 어디서 멈춰야 하는지 훨씬 덜 헷갈린다.

AGENTS.md에서 흔히 하는 실수

1. 도구 설명만 잔뜩 넣고 역할이 없음
2. 예외 케이스가 너무 많아져서 읽기 싫어짐
3. “다 알아서 해줘” 식으로 책임이 흐려짐
4. 팀마다 다른 뜻으로 읽히는 추상 표현을 많이 씀
5. 파일은 있는데 실제 운영에서 한 번도 안 봄

2단계: SKILL.md는 그다음이다

AGENTS.md가 누가라면, SKILL.md는 어떻게다.

근데 여기서도 함정이 있다.

SKILL.md를 두껍게 만들수록 친절해 보이지만, 실전에서는 보통 더 느려진다.

그래서 SKILL.md는 설명서가 아니라 라우터처럼 써야 한다.

즉, 긴 지식은 references/나 관련 노트로 빼고, SKILL.md는 판단과 경로만 남기는 편이 낫다.

SKILL.md가 맡아야 하는 것

• 이 스킬이 언제 호출되는가
• 입력은 무엇인가
• 출력은 무엇인가
• 필요한 참조는 어디 있는가
• 작업 순서는 무엇인가

SKILL.md가 맡지 말아야 하는 것

• 모든 배경지식을 본문에 다 넣기
• 수십 가지 예외를 한 파일에 때려넣기
• 후처리 규칙을 함수처럼 길게 늘어놓기

이건 특히 팀 온보딩에서 중요하다.

왜냐면 팀이 들어오면 들어올수록 SKILL.md는 작아야 지속 가능해지기 때문이다.

SKILL.md 최소 구조 예시

# SKILL.md

## 언제 쓰는가
- 새 원고 작성
- 기존 원고 리프레시
- 허브 확장 후보 판별

## 입력
- 주제
- 채널
- 기존 허브

## 출력
- 초안
- 체크리스트
- 내부링크 후보

## 참조
- references/channel-rubric.md
- references/template.md

SKILL.md를 먼저 크게 만들면 생기는 일

• 찾기 힘들다
• 수정하기 귀찮다
• 팀마다 다른 버전이 생긴다
• 최신 규칙이 묻힌다
• 결국 아무도 안 본다

그래서 SKILL.md는 짧게 읽히고 깊이는 참조로 빼는 구조 가 좋다.

SKILL.md와 AGENTS.md의 차이

구분	AGENTS.md	SKILL.md
목적	역할/경계	절차/실행
질문	누가 무엇을 하나	어떻게 처리하나
성격	헌법	작업 매뉴얼
길이	더 짧아도 좋음	짧고 명확할수록 좋음

이 둘을 섞으면 안 된다.

AGENTS.md가 절차까지 다 먹어버리면 팀 규칙이 금방 질식한다.

SKILL.md가 책임까지 다 먹어버리면 누가 뭘 책임지는지 흐려진다.

3단계: hooks는 제일 마지막에 붙여라

여기가 진짜 중요하다.

hooks는 강력하다.

그래서 먼저 붙이고 싶다.

근데 먼저 붙이면 안 된다.

왜냐면 hooks는 규칙이 이미 정해졌을 때 가장 잘 작동하기 때문이다.

AGENTS.md와 SKILL.md가 비어 있는데 hooks부터 붙이면 자동화는 생기는데 질서는 안 생긴다.

hooks에 잘 맞는 것

• 알림
• 포맷 검사
• 가벼운 정책 차단
• 세션 종료 메모
• 수정 후 빠른 검증

hooks에 안 맞는 것

• 복잡한 업무 판단
• 장문의 정책 토론
• 외부 발행의 최종 책임
• 비밀정보가 섞인 무거운 처리

hooks는 실행 경비원에 가깝다.

운영 헌법을 대신 쓰는 자리가 아니다.

hooks를 마지막에 붙여야 하는 이유

1. 먼저 규칙이 있어야 훅이 무엇을 감시할지 정해진다.
2. 먼저 절차가 있어야 훅이 어디에서 개입할지 정해진다.
3. 먼저 역할이 있어야 훅이 누굴 깨워야 할지 정해진다.

즉 hooks는 전략이 아니라 집행이다.

hooks와 sync / async의 차이

이건 초반에 꼭 나눠야 한다.

종류	쓰임	주의점
sync	차단, 승인, 정책	무거우면 전체 흐름이 느려짐
async	알림, 로그, 후처리	이미 진행된 행동은 못 막음

팀이 흔히 하는 실수는 무거운 검증까지 async로 보내놓고 막히길 기대하는 거다.

그건 기대가 아니라 오해다.

hooks 순서 예시

1. Notification
2. PostToolUse 포맷/가벼운 검증
3. SessionStart 메타 브리핑
4. PermissionRequest 정책 차단
5. SessionEnd 요약 로그

이 순서가 좋은 이유는 가장 낮은 위험부터 잡기 때문이다.

subagents는 언제 끼우나

subagents는 제목에는 없지만 실제 팀 온보딩에선 빼기 어렵다.

내 추천은 이렇다.

• AGENTS.md에서 역할 경계를 먼저 만든다
• SKILL.md에서 반복 절차를 만든다
• 그다음 subagent를 작업 단위로 쪼갠다
• 마지막에 hooks로 감시와 알림을 붙인다

즉 subagents는 SKILL 이후가 자연스럽다.

왜냐면 뭘 맡길지 정의가 있어야 작은 워커를 쪼갤 수 있기 때문이다.

팀 온보딩 실제 순서

작은 팀

1. AGENTS.md
2. SKILL.md
3. Notification hook
4. PostToolUse hook

중간 팀

1. AGENTS.md
2. SKILL.md
3. subagents
4. hooks
5. review gate

큰 팀

1. AGENTS.md
2. shared SKILL.md references
3. per-skill playbook
4. hooks
5. permission lane
6. logs / audit

왜 hooks보다 AGENTS.md가 먼저인가

팀 온보딩에서 제일 비싼 건 실수다.

실수의 대부분은 자동화가 없어서가 아니라 자동화가 어디까지 책임지는지 몰라서 난다.

AGENTS.md는 그 책임의 경계를 먼저 그어준다.

그래서 팀은 “뭐가 자동이고 뭐가 수동인지”부터 안다.

왜 SKILL.md가 hooks보다 먼저인가

hooks는 절차를 자동 반응으로 바꾼다.

근데 절차가 없는데 반응만 자동이면 움직임은 빨라져도 방향이 없다.

SKILL.md는 반복 절차를 고정한다.

그래서 훅이 붙을 때 무엇을 감시하고 무엇을 로그로 남겨야 하는지 정해진다.

실수 TOP

1. hooks부터 붙인다

자동 반응이 앞서면 규칙이 늦는다.

2. AGENTS.md에 절차를 다 넣는다

헌법과 매뉴얼이 뒤섞인다.

3. SKILL.md를 백과사전처럼 만든다

라우터가 아니라 창고가 된다.

4. subagents를 먼저 늘린다

작은 일감이 아니라 작은 혼란이 늘어난다.

5. 알림과 차단을 같은 훅에 섞는다

도착과 제어는 다른 일이다.

6. 외부 write를 local write처럼 다룬다

이건 나중에 꼭 큰일 난다.

7. 세션이 길어졌는데도 계약서를 안 갱신한다

그러면 팀은 어제의 규칙으로 오늘을 굴린다.

실제 온보딩 체크리스트

• AGENTS.md에 역할과 금지선을 썼는가
• SKILL.md가 라우터처럼 얇은가
• 반복 절차가 reference로 분리됐는가
• hooks는 알림과 가벼운 검증부터 시작했는가
• sync와 async를 구분했는가
• 외부 발행 lane을 따로 뒀는가
• subagents를 역할 단위로만 나눴는가
• 실패 시 되돌림 기준이 있는가

팀 온보딩에서 바로 써먹는 질문

1. 이 작업은 누가 책임지나

AGENTS.md에서 답한다.

2. 이 작업은 어떤 절차로 반복하나

SKILL.md에서 답한다.

3. 이 작업은 어디서 자동으로 알리고 막나

hooks에서 답한다.

4. 이 작업을 작은 워커로 나눌 수 있나

subagents에서 답한다.

FAQ

Q1. AGENTS.md와 SKILL.md를 한 파일에 합치면 안 되나

안 되는 건 아니지만 팀 온보딩에선 비추천이다. 역할과 절차가 섞이면 결국 둘 다 길어지고 둘 다 안 읽는다.

Q2. hooks를 먼저 깔고 나중에 규칙을 정하면 안 되나

운영 초반엔 그럴 수 있어 보이지만 오래 가면 피곤해진다. 규칙 없는 자동화는 결국 예외 처리 공장이다.

Q3. subagents는 꼭 필요한가

필수는 아니다. 하지만 팀이 커질수록 작업 단위 분리에 도움 된다. 다만 AGENTS.md와 SKILL.md가 먼저다.

Q4. hooks는 몇 개부터 시작하는 게 좋나

처음엔 많지 않아도 된다. 알림 1개, 가벼운 후처리 1개, 차단 1개 정도면 충분하다.

Q5. 큰 팀일수록 뭐가 제일 중요하나

역할 분리와 실패 복구다. 화려한 자동화보다 재현 가능한 온보딩이 더 중요하다.

실패했을 때 보이는 신호

• 팀마다 다른 AGENTS.md 해석이 나온다
• 같은 작업인데 SKILL.md 경로가 여러 개다
• hooks가 너무 많은 일을 한다
• 알림이 많아서 누구도 안 본다
• 승인 루프가 길어져서 작업이 멈춘다

이 신호가 보이면 도구를 더 추가할 때가 아니라 순서를 다시 볼 때다.

내가 추천하는 최소 버전

Day 1

• AGENTS.md 1개
• SKILL.md 1개
• Notification hook 1개

Day 2

• PostToolUse hook 1개
• review gate 1개
• 실패 로그 규칙 1개

Day 3

• subagents 도입 여부 판단
• 역할별 파일 분리
• 팀별 체크리스트 추가

이 정도면 온보딩의 뼈대는 꽤 단단하다.

다음에 읽을 글

• Claude Code 권한 설계 체크리스트 2026 — hooks·subagents·세션 분리 어디서부터 막아야 하나
• Claude Code hooks 실전 2026 — 승인 루프·로그·알림 자동화 어디까지 붙여도 되나
• Claude Code MCP vs script 2026 — 내부 도구 연결할 때 언제 커스텀 툴이 과하고 언제 셸이면 충분할까
• LLM Wiki 2026 — RAG 안 붙이고도 개인 위키가 굴러가는 조건, second brain 운영 체크리스트

한 줄 정리

Claude Code 팀 온보딩은 AGENTS.md로 경계를 먼저 세우고, SKILL.md로 절차를 얇게 고정한 뒤, hooks로 자동 반응을 붙이는 순서가 제일 덜 망한다.

순서를 뒤집으면 자동화는 멋져 보이는데, 운영은 점점 사람 손이 더 많이 든다.

마무리

도구는 늘어도 된다.

근데 순서는 늘어나면 안 된다.

팀 온보딩은 기능 추가 게임이 아니라 질서 고정 게임이기 때문이다.

AGENTS.md가 먼저고, SKILL.md가 그다음이고, hooks는 마지막이다.

이 순서면 적어도 팀이 “이게 왜 돌아가고, 왜 멈추는지” 설명할 수 있는 상태까지는 간다.