Claude Code 팀 사용법 1편: 첫날 30분 세팅과 꼭 기억할 여덟 가지 규칙
요약. 여럿이 같은 저장소에서 Claude Code(클로드 코드)를 쓰면 같은 요청에도 결과가 갈립니다. 저희 팀은 CLAUDE.md·권한·스킬을 저장소에 넣어 클론만 하면 따라오게 했고, 사람이 직접 할 일은 플러그인 켜기와 개발 환경 두 가지로 줄였습니다. 이 글은 첫날 세팅 30분과 모든 규칙의 바탕인 여덟 가지를 정리합니다.
이 글은 "Claude Code 팀 사용법" 4편 연재 중 1편입니다. 프론트엔드·백엔드가 있는 웹 시스템을 여러 명이 함께 개발하는 팀 기준입니다. 데이터 분석이나 문서 작업, 혼자 쓰는 작은 스크립트처럼 상황이 다르면 맞지 않는 규칙도 있습니다.
팀에서 Claude Code를 쓰면 결과가 갈리는 이유
혼자 쓸 때는 각자 방식이면 충분했습니다. 팀이 같은 저장소에서 쓰기 시작하자 같은 요청에도 결과가 갈렸습니다. 누구는 계획부터 받았고, 누구는 바로 코드를 받았습니다. 비슷한 일을 하는 스킬이 여럿 깔려 있어서, 어떤 스킬이 불리느냐에 따라 절차가 달라졌습니다.
그래서 팀 안내 문서를 썼습니다. 설정은 저장소 안에 이미 들어 있어서, 클론하면 규칙도 권한도 스킬도 따라옵니다. 사람이 직접 해야 하는 건 두 가지뿐입니다. 나머지는 일하는 방법입니다. 어떤 순서로 일을 시킬지, 어떻게 말을 걸지, 무엇을 파일로 남길지, 그리고 Claude가 "다 했습니다"라고 할 때 무엇으로 확인할지를 정리했습니다.
규칙이 깐깐해 보인다면, 대부분 한 번씩 크게 데이고 나서 생긴 것이라 그렇습니다. 그때 있었던 일도 같이 적었습니다. 원래 문서는 읽는 데 20분, 세팅에 30분이 걸립니다. 그 문서에서 회사 이야기만 빼고, 나머지를 네 편에 나눠 담았습니다.
먼저 알아 둘 용어 10개
| 용어 | 뜻 |
|---|---|
| 스킬 | "이런 일은 이렇게 하라"를 적어 둔 설명서. 이름을 부르면 Claude가 그 절차대로 움직입니다. 직접 쓴 것도, 받아 온 것도 있습니다 |
| 플러그인 | 스킬 여러 개를 묶어 한 번에 설치하는 단위 |
| 에이전트 | 내 세션이 따로 띄운 Claude. 자기 컨텍스트를 따로 갖고 한 가지 일만 합니다. 일을 맡겨 두고 나는 다른 일을 할 수 있습니다 |
| 메인 에이전트 | 내가 직접 말을 거는 세션. 일을 쪼개 나눠 주고, 진행을 확인하고, 안 되면 대신 마무리합니다. 이 연재에서 "맡긴다"는 메인 에이전트가 다른 에이전트에게 일을 준다는 뜻입니다 |
| 컨텍스트 | 지금 Claude가 들고 있는 대화와 파일 전부. 무한하지 않아서, 큰 파일을 통째로 읽히면 금방 차고 앞쪽 내용부터 흐려집니다 |
| 워크트리 | 같은 저장소를 다른 폴더에 하나 더 펼친 것(git worktree). 한 폴더를 여러 세션이 같이 쓰면 옆 세션이 고친 파일이 내 커밋에 섞이는데, 워크트리로 떼어 놓으면 원래 폴더는 그대로입니다 |
| MCP | Claude에 바깥 도구를 붙이는 규격. 브라우저를 다루는 크롬 확장도 이 방식으로 붙습니다 |
| 게이트 | 배포 전에 반드시 통과해야 하는 검사 묶음. 저희 팀은 명령 하나로 묶었습니다 |
| 빨강 / 초록 | 테스트·검사가 실패하면 빨강, 통과하면 초록. "빨개진다"는 실패한다는 뜻입니다 |
| TDD | 기능보다 테스트를 먼저 쓰는 방식. 아직 기능이 없으니 테스트는 실패하고, 그 실패를 눈으로 확인하는 것이 핵심입니다. 처음부터 통과하는 테스트는 아무것도 검사하지 않는 테스트일 수 있습니다 |
첫날 30분: 클론하면 따라오는 것과 직접 할 두 가지
클론하면 따라오는 것 (손댈 것 없음)
CLAUDE.md: 팀 규칙입니다. 세션마다 자동으로 읽힙니다..claude/settings.json: 권한입니다. 무엇을 묻고 무엇을 막을지 이미 정해져 있습니다..claude/skills/: 이 저장소 전용 스킬 한 벌입니다.- 디자인 문맥 파일(
.impeccable.md): 화면을 만들 때 읽는 디자인 기준입니다. 4편에서 자세히 다룹니다.
직접 할 두 가지 (한 번만)
- 플러그인 켜기
- 개발 환경 갖추기(DB, 파이썬, 프론트). 이건 다른 프로젝트와 같습니다.
그림 1. 사람이 할 일은 두 가지뿐입니다.
플러그인: 실제로 쓰는 건 넷, 그리고 확장 하나
| 이름 | 없으면 | 우선순위 |
|---|---|---|
| superpowers | 문서의 절차가 전부 안 돌아갑니다. 계획·TDD·리뷰·검증이 다 여기 있습니다 | 필수 |
| claude-in-chrome (플러그인이 아니라 크롬 확장) | 화면을 눈으로 못 봅니다. 가장 많이 쓰는 도구입니다 | 필수 |
| claude-mem | 세션을 새로 열 때마다 "전에 뭐 했더라"를 다시 설명해야 합니다 | 권장 |
| claude-dashboard | 사용량과 한도가 안 보입니다(터미널 상태줄) | 권장 |
| context7 | 라이브러리 사용법을 기억에 의존해 답합니다. 틀릴 때가 있습니다 | 있으면 좋음 |
순서는 superpowers와 크롬 확장 둘만 켜고 시작하는 것입니다. 나머지는 쓰다가 불편할 때 하나씩 켭니다. 한 번에 다 켜면 무엇이 무슨 일을 하는지 구분이 안 됩니다. claude-dashboard는 /plugin으로 설치한 뒤 상태줄까지 붙여야 보입니다. 설치 후 /statusline을 쓰거나 플러그인의 setup을 한 번 돌립니다.
그림 2. 필수 둘로 시작하고, 나머지는 불편할 때 하나씩.
제대로 됐는지 확인하는 법 세 가지
- "superpowers 스킬 목록 보여 주세요"라고 합니다. brainstorming, writing-plans 같은 이름이 나오면 플러그인은 됐습니다.
- "로컬 화면 열어서 스크린샷 보여 주세요"라고 합니다. 화면이 오면 크롬 확장은 됐습니다.
- 검사 명령(게이트)을 끝까지 돌려 초록이 나오면 개발 환경은 됐습니다. 시간이 좀 걸리니 커피 한 잔.
세팅이 끝나면: 작은 일 하나를 끝까지
"코드는 아직 쓰지 말고"로 시작해 계획, 테스트 먼저, 검사, 커밋까지 갑니다. 문서를 여러 번 읽는 것보다 한 번 해 보는 게 빠릅니다.
따라 하지 말 것: 남의 settings.local.json
.claude/settings.local.json은 개인 파일입니다. 배포 권한 같은 것이 들어 있어서, 남의 것을 복사해 오면 안 됩니다. 필요한 권한은 쓰다 보면 Claude가 묻습니다. 그때 허용하면 자동으로 쌓입니다.
팀에서 Claude Code를 쓸 때 꼭 기억할 여덟 가지
문서의 나머지 섹션은 전부 이 여덟 가지를 풀어 쓴 것입니다.
| 규칙 | 왜 | |
|---|---|---|
| 1 | 일을 시작하기 전에 "어떤 스킬을 쓸지"부터 정합니다 | 바로 파일부터 열지 않습니다. 스킬은 "무엇을 할지"뿐 아니라 "어떻게 찾아볼지"까지 정해 줍니다 |
| 2 | 절차는 superpowers 하나로 통일합니다 | 비슷한 스킬이 여럿 있습니다. 같은 일을 두 스킬이 다르게 시키면 사람마다 결과가 갈립니다 |
| 3 | 화면은 브라우저로 직접 봅니다 | 테스트가 초록이어도 화면은 그대로일 수 있습니다. 크롬 확장으로 실제 화면을 여는 것이 마지막 확인입니다 |
| 4 | 정한 건 머리가 아니라 파일에 남깁니다 | 명세 → 계획 → 보고 순으로 정해진 폴더에 쌓습니다. 세션은 끊겨도 파일은 남고, 다음 사람은 그 파일만 읽고 이어받습니다 |
| 5 | 맡긴 일이 됐는지는 git으로 확인합니다 | "다 했습니다" 알림이 안 올 수도 있습니다. 커밋이 생겼는지가 유일하게 믿을 수 있는 증거입니다. 이 규칙이 세 번 바뀐 과정은 3편에서 다룹니다 |
| 6 | "됐습니다" 전에 검사를 돌리고 그 출력을 봅니다 | 테스트가 "있다"는 건 증거가 아닙니다. 실제로 돌려서 통과한 결과가 증거입니다 |
| 7 | 현업에 나갈 자료는 문서로 만들어 git에도 같이 둡니다 | 터미널에만 정리해 둔 내용은 이틀 뒤에 못 찾습니다. 실제로 메일 초안 하나를 그렇게 날린 적이 있습니다 |
| 8 | 배포·푸시·되돌리기는 항상 사람에게 묻게 해 둡니다 | 되돌리기 어려운 일은 자동으로 하지 않습니다. 사람의 기억에 맡기지 않고, 설정이 대신 막게 해 뒀습니다 |
스스로 점검: 한 번 해 봤다면 바로 답할 세 질문
- 일을 시작하기 전에 Claude에게 뭐라고 말을 걸까요?
- 맡긴 일이 되고 있는지 어떻게 확인할까요?
- "끝났습니다"라고 하려면 무엇을 보여야 할까요?
막히면 여덟 가지 중 1번, 5번, 6번을 다시 보면 됩니다.
설정이 왜 이렇게 돼 있나
권한 세 등급
| 등급 | 무엇이 | 왜 |
|---|---|---|
| 안 묻고 함 (allow) | 검사·빌드 명령, 파이썬 실행, git add/commit/status/diff/log, ls/cat/grep/find, 로컬 서버 호출, 파일 편집 | 되돌릴 수 있고 하루에 수십 번 하는 일입니다. 이런 것까지 물으면 아무도 규율을 지키지 않습니다 |
| 매번 물음 (ask) | 배포, git push, git reset, git checkout, 클라우드 명령 | 바깥으로 나가거나 남의 작업을 덮는 일입니다. 폴더를 같이 쓰기 때문에 checkout도 여기 넣었습니다 |
| 아예 막음 (deny) | rm -rf, git push --force, DB 삭제 | 되돌릴 방법이 없는 세 가지입니다. 예외는 없습니다 |
그림 3. 되돌릴 수 있으면 묻지 않고, 바깥으로 나가면 묻고, 되돌릴 수 없으면 막습니다.
기억이 세 군데에 나뉘어 있다
| 어디에 | 무엇이 | 규칙 |
|---|---|---|
| CLAUDE.md | 팀 규칙. git에 들어갑니다 | 고치면 모두에게 적용됩니다 |
| 개인 메모(Claude Code 메모리) | 파일 하나에 사실 하나, 그리고 왜·어떻게 적용하는지 | 색인 파일에는 한 줄만 적습니다. 본문을 거기 쓰지 않습니다 |
| claude-mem | 세션에서 있었던 일이 자동으로 기록됩니다 | "전에 이거 풀었나?"는 검색으로 찾습니다 |
그림 4. 팀 규칙, 개인 메모, 세션 기록은 따로 둡니다.
개인 설정 중 알아 두면 좋은 것 (취향, 필수 아님)
settings.json에 넣는 값입니다. 이름과 뜻은 공식 설정 문서(settings reference) 기준입니다.
| 설정 | 값 | 무엇을 하나 | 왜 썼나 |
|---|---|---|---|
effortLevel |
"high" |
effort(추론 강도)의 기본값. 높을수록 복잡한 문제를 더 깊게 생각하고, 대신 느리고 비쌉니다. 세션 중에는 /effort high로도 바꿀 수 있습니다 |
잘못 고치는 비용이 큰 저장소라서 |
alwaysThinkingEnabled |
true |
확장 사고(답하기 전에 생각하는 단계)를 켜 둡니다. 지금 버전은 사고가 기본으로 켜져 있어서 true는 바꾸는 게 없고, false로 끌 때만 의미가 있습니다 |
항상 생각하고 답하게 하려고 |
skillOverrides |
스킬별로 "off" |
잘 안 쓰는 스킬을 Claude의 후보 목록과 / 자동완성에서 숨깁니다. SKILL.md를 고치지 않아도 됩니다 |
후보가 많으면 정작 필요한 스킬이 안 뜬다 |
teammateMode |
"tmux" |
에이전트 팀의 팀원 에이전트를 tmux 분할 화면에 띄웁니다. 기본값은 메인 터미널 안("in-process")입니다 |
3편의 에이전트 정리 순서와 이어진다 |
권장하는 방법은 이렇습니다. 처음엔 아무것도 바꾸지 말고 한 달쯤 써 본 뒤, 안 맞는 걸 하나씩 바꿉니다. 남의 설정을 통째로 복사하면 왜 그렇게 돼 있는지 몰라서 나중에 못 고칩니다.
따라 해 보기
오늘 하나만 해 본다면, superpowers를 켜고 작은 일 하나를 "코드는 아직 쓰지 말고"로 시작해 보세요. 커밋까지 한 바퀴 돌고 나면 여덟 가지 중 몇 개는 설명 없이도 이해됩니다.
더 깊이: 공식 문서로 보는 팀 세팅
CLAUDE.md는 어디서 읽히나. Claude Code 공식 문서 Memory 페이지는 CLAUDE.md를 세션 시작 때 읽는 지침 파일로 설명합니다. 저장소에 두면 git으로 팀 전체가 같은 지침을 공유합니다.
권한 세 등급은 설정 규칙 그대로입니다. Configure permissions 문서는 권한 규칙을 allow, ask, deny 세 종류로 나눕니다. 팀 표의 "안 묻고 함 / 매번 물음 / 아예 막음"이 각각 여기에 대응합니다. Settings 문서는 저장소에 공유하는 .claude/settings.json과 개인용 .claude/settings.local.json을 구분합니다. 남의 settings.local.json을 복사하지 말라는 규칙이 이 구분에서 나옵니다. 개인 설정 네 가지의 이름과 값은 Settings reference 문서에서 하나씩 확인할 수 있습니다.
스킬, 플러그인, 에이전트. Skills 문서는 스킬을 SKILL.md에 절차를 적어 두고 필요할 때 불러 쓰는 기능으로, Plugins 문서는 이를 묶어 배포하는 단위로 설명합니다. Subagents 문서의 서브에이전트가 이 글의 "에이전트"입니다.
superpowers. 절차를 통일하는 데 쓴 superpowers는 MIT 라이선스 공개 저장소입니다. skills 폴더에 brainstorming, writing-plans, using-git-worktrees, test-driven-development, systematic-debugging, requesting-code-review, verification-before-completion, finishing-a-development-branch 같은 스킬이 들어 있습니다(2026-10-02 확인). 순서는 2편에서 다룹니다.
워크트리. git 공식 문서의 git-worktree는 한 저장소에 작업 폴더를 여러 개 붙이는 기능입니다. 폴더마다 다른 브랜치를 둘 수 있습니다.
자주 묻는 질문
Q. 플러그인을 처음부터 다 켜 두면 안 되나요? 권하지 않습니다. 어떤 결과가 어느 플러그인에서 나왔는지 구분이 안 됩니다. 필수 둘로 시작해 불편할 때 하나씩 켭니다.
Q. 왜 git checkout까지 매번 묻게 했나요? 여러 세션이 같은 폴더를 쓰기 때문입니다. 한 세션이 브랜치를 바꾸면 옆 세션의 작업이 덮일 수 있습니다.
Q. 개인 습관은 어디에 두나요? 개인 메모(Claude Code 메모리)에 둡니다. 지난 세션 일은 claude-mem 검색으로 찾습니다.
다음 편 예고: 2편: 일의 흐름 9단계와 요청 문장. 단계마다 부르는 스킬과 실제 요청 문장을 정리합니다.
연재 목차: Claude Code 팀 사용법
- 1편: 첫날 세팅 30분과 꼭 지킬 규칙 8가지 (지금 읽는 글)
- 2편: 워크플로 9단계와 요청 프롬프트 10개
- 3편: 서브에이전트에게 맡기고 검증하는 법
- 4편: 설계는 숫자로 고르고, 화면은 디자인 기준 파일로
출처
- Claude Code 문서, Memory: https://code.claude.com/docs/en/memory
- Claude Code 문서, Settings reference: https://code.claude.com/docs/en/settings-reference
- Claude Code 문서, Settings: https://code.claude.com/docs/en/settings
- Claude Code 문서, Configure permissions: https://code.claude.com/docs/en/permissions
- Claude Code 문서, Subagents: https://code.claude.com/docs/en/sub-agents
- Claude Code 문서, Skills: https://code.claude.com/docs/en/skills
- Claude Code 문서, Plugins: https://code.claude.com/docs/en/plugins
- obra/superpowers (MIT): https://github.com/obra/superpowers
- git 공식 문서(git 저장소 Documentation 폴더의 git-worktree): https://github.com/git/git/tree/master/Documentation