Claude Code 시작 가이드에서 설치·인증·첫 커밋까지 마쳤다면, 다음은 이 도구를 팀의 평소 워크플로에 맞추는 단계입니다. 이 문서는 네 가지를 다룹니다 — 대화형 Git을 실무 흐름으로 굳히는 법, 저장소 규약을 CLAUDE.md에 고정하는 법, MCP로 내장 도구 너머까지 확장하는 개념, 그리고 권한·가드레일을 어디까지 풀고 어디서 멈출지입니다. 각 절은 명령 → 그 명령이 하는 일 → 다음 명령의 순서로 짚습니다. 시작 가이드를 아직 안 봤다면 먼저 Claude Code 시작 가이드를 거치세요.
대화형 Git을 실무 흐름으로
Claude Code는 터미널에서 git status·git log·git diff를 읽고, 그 결과를 바탕으로 커밋과 브랜치를 제안합니다. 실제 반영은 사람이 승인합니다. 평소 쓰던 Git 명령을 자연어 요청으로 바꾸면 됩니다.
내 변경 파일은? 적절한 메시지로 커밋해줘 feature/quickstart 브랜치 만들어 최근 5개 커밋 보여줘 머지 충돌 해결 도와줘
첫 요청에 Claude는 git status와 git diff를 읽어 변경 묶음을 확인하고, 컨벤션에 맞춘 커밋 메시지를 제안합니다. 메시지를 확인·수정해 승인하면 커밋이 만들어집니다. 시작 가이드에서 다루지 않은 브랜치 생성도 같은 식입니다 — "feature/quickstart 브랜치 만들어"라고 하면 브랜치를 끊고 작업을 그 위로 옮깁니다. 충돌이 났을 때 "머지 충돌 해결 도와줘"라고 하면 충돌 구간을 읽어 해소안을 제시하고, 적용 전 사람이 확인합니다. 흐름의 주는 터미널 워크플로(git commit·git push)입니다.
커밋과 push는 위험도가 다르므로 권한도 다르게 두는 편이 좋습니다. 커밋은 로컬에 쌓이고 되돌리기 쉬우므로, Bash(git commit *)를 허용해도 커밋 범위로 한정돼 비교적 안전합니다. 반면 push는 공유 저장소에 비가역으로 반영되므로, Bash(git push *)는 승인을 거치도록(ask) 두고 사람이 검토하는 편이 안전합니다.
{
"permissions": {
"allow": ["Bash(git commit *)"],
"ask": ["Bash(git push *)"]
}
}
권한을 거는 자리는 아래 가드레일 절에서 다룹니다.
Claude가 제안한 변경이라도, 커밋하는 순간 커밋 author는 사람입니다 — 리뷰하고 커밋하면 그건 내 코드이자 내 책임입니다. 커밋 전 무엇을 어떤 순서로 검토하는지는 검증 워크플로, 출력을 어디까지 믿을지의 근거는 출력 검증에서 다룹니다.
worktree로 병렬 작업
하나의 claude 세션은 실행한 디렉토리에 묶입니다. 그래서 한 저장소에서 두 가지 작업을 동시에 굴리려면, 브랜치마다 별도 작업 디렉토리를 두는 표준 git worktree를 씁니다.
git worktree add ../proj-feature-a feature/a git worktree add ../proj-feature-b feature/b
각 디렉토리에서 claude를 따로 실행하면, 두 세션이 서로 컨텍스트를 공유하지 않은 채 병렬로 돕니다. 한쪽에서 리팩터링을, 다른 쪽에서 버그 수정을 진행하고, 결과는 평소처럼 Git으로 머지하면 됩니다.
worktree는 git 기능입니다 — claude --worktree 같은 별도 플래그는 없습니다. Claude Code는 각 worktree 디렉토리에서 평범하게 실행될 뿐입니다. 세션을 다시 열 때 /resume 피커는 기본적으로 현재 worktree의 세션을 보여 주고, 단축키로 다른 worktree나 저장소의 세션까지 범위를 넓힐 수 있습니다.
CLAUDE.md로 규약을 고정하기
CLAUDE.md는 세션 시작 시 자동으로 로드되는 영속 지시 파일입니다. 빌드·테스트·코드 스타일 규칙을 여기 적어 두면 이후 모든 세션이 그 규약 위에서 동작합니다. 저장소에 처음 도입할 때는 시작 가이드에서 쓴 /init이 코드베이스를 분석해 초안을 만들어 줍니다 — 생성된 규약을 200줄 안으로 다듬어 커밋하면, 같은 저장소를 받은 팀 전체가 같은 규약을 공유합니다.
로드 순서
여러 위치의 CLAUDE.md가 넓은 범위부터 구체적인 범위 순으로 로드되고, 충돌하면 나중에 로드된 파일이 우선합니다.
| 범위 | 위치 | 비고 |
|---|---|---|
| Managed policy | 조직 전역 (IT/DevOps 관리) | 개인 설정으로 제외 불가 |
| User | ~/.claude/CLAUDE.md | 내 모든 저장소에 적용 |
| Project | ./CLAUDE.md 또는 ./.claude/CLAUDE.md | 팀 공유 (VCS 커밋) |
| Local | ./CLAUDE.local.md | 개인용(gitignore), 가장 나중 = 최우선 |
여기서 Project는 저장소 루트의 ./CLAUDE.md를 가리키는 스코프 이름이며, Claude.ai 웹의 Projects와는 다른 개념입니다.
구체적으로 쓰기
200줄 안쪽을 권장합니다 — 길어지면 컨텍스트를 소모하고 준수도가 떨어집니다. 지시는 모호한 형용사 대신 검증 가능한 규칙으로 적습니다.
# 좋음 — 구체적 들여쓰기는 스페이스 2칸을 쓴다. 컴포넌트 테스트는 vitest로 작성한다. # 나쁨 — 모호함 코드 포맷을 잘 지킨다.
공통 규약을 한 파일에 두고 여러 CLAUDE.md에서 끌어다 쓰려면 @경로 문법으로 import합니다(최대 4 hop).
auto memory와의 차이
CLAUDE.md는 사람이 쓰고 전체가 로드됩니다. 이와 별개로 Claude가 스스로 적는 auto memory가 있습니다 — Claude는 ~/.claude/projects/<project>/memory/MEMORY.md에 작업 메모를 자동 저장하고 그 앞부분(첫 200줄/25KB)을 로드합니다. 규약은 사람이 CLAUDE.md에, 작업 메모는 Claude가 auto memory에 두는 분담입니다.
큰 저장소는 .claude/rules/로 분할
규약이 커지면 토픽별 파일로 쪼개 .claude/rules/에 둡니다. front-matter의 paths:로 path-scoped 조건 로딩을 걸면, 매칭되는 파일을 읽을 때만 해당 rule이 로드돼 컨텍스트를 아낍니다.
--- paths: - "src/api/**" --- API 핸들러는 모든 입력을 스키마로 검증한다.
paths가 없는 rule은 세션 시작 시 로드되며, 우선순위는 .claude/CLAUDE.md와 같습니다. 로드된 규약은 /memory로 보고 편집할 수 있습니다.
MCP로 도구 확장하기
Claude Code의 내장 도구는 파일 읽기·쓰기, Bash 실행, Git입니다. 그 너머 — 사내 DB 질의, 이슈 트래커, 브라우저 같은 — 도구까지 닿게 하려면 MCP(Model Context Protocol)로 외부 서버를 붙입니다. MCP는 AI를 외부 도구·데이터에 연결하는 오픈 표준 프로토콜입니다.
서버를 붙이는 명령은 전송 방식(transport)에 따라 두 형태입니다.
# HTTP 서버 claude mcp add --transport http <name> <url> # stdio (로컬 프로세스) claude mcp add <name> -- <command> <args>
stdio 형태에서 -- 뒤는 서버를 띄우는 실행 명령입니다. 연결 상태는 claude mcp list로 확인합니다 — 각 서버 옆에 상태가 표시됩니다.
| 표시 | 의미 |
|---|---|
✓ Connected | 정상 연결 |
! Needs authentication | 브라우저 sign-in 또는 --header 토큰 필요 |
✗ Failed to connect | 연결 실패 |
✗ Connection error | 연결 오류 |
⏸ Pending approval | 승인 대기 |
서버 설정은 스코프를 가집니다.
| 스코프 | 저장 위치 | 공유 범위 |
|---|---|---|
| local | ~/.claude.json | 기본값, 현재 저장소만 |
| project | .mcp.json | 팀 공유 (VCS 커밋) |
| user | 사용자 범위 설정 | 전 저장소 |
팀이 함께 쓸 서버는 project 스코프로 두어 .mcp.json을 커밋하면, 같은 저장소를 받은 동료가 동일 구성을 공유합니다. OAuth가 필요한 서버는 세션 안에서 /mcp를 열어 Authenticate를 거칩니다.
여기까지가 MCP의 개념과 추가 형태입니다. 특정 사내 서버를 단계별로 추가·인증하는 구체 커넥터 연동은 MCP 커넥터·사내 도구 페이지에서 다룹니다. 어떤 사내 서버를 어느 스코프로 허용할지는 조직 계정·정책에 따라 다릅니다.
슬래시 명령과 가드레일
실무에서 자주 쓰는 슬래시 명령을 한자리에 모으면 다음과 같습니다.
| 명령 | 하는 일 |
|---|---|
/memory | 로드된 CLAUDE.md·규약 보기·편집 |
/mcp | MCP 서버 보기·OAuth 인증 |
/permissions | 권한 규칙 보기·조정 |
/config | 설정 보기·변경 |
/plan | 실행 전 계획 모드로 전환 |
/model | 모델 선택 |
/clear · /compact | 대화 컨텍스트 비우기·압축 |
/help | 사용 가능한 명령 보기 |
권한 모드는 Shift+Tab으로 순환합니다 — Default → Auto-accept edits → Plan → Auto(research preview). 세부 규칙은 .claude/settings.json의 permissions에서 deny/ask/allow로 지정합니다. 앞서 Git 절에서 본 Bash(git commit *) 허용과 Bash(git push *) 승인 요구가 바로 이 자리에 들어갑니다. 설정은 조직 정책(managed)부터 개인까지 스코프되며, deny는 어느 레벨에서든 차단합니다.
bypassPermissions 모드와 --dangerously-skip-permissions 플래그는 격리된 VM이나 컨테이너에서만 쓰고, 회사 저장소에는 쓰지 마세요. 둘 다 모든 승인 단계를 건너뜁니다. 왜 승인 게이트를 건너뛰는 것이 위험한지 — 그 배경은 에이전트 개념·3원칙에서 다룹니다. 라이프사이클을 강제하는 훅(hooks)이나 격리 컨텍스트에서 도는 서브에이전트 같은 장치도 있지만, 만드는 법은 이 문서 범위 밖입니다(에이전트 가드레일).
마지막으로, Claude Code에 자사 소스코드를 넣는 기준 — 무엇을 넣어도 되고 무엇은 안 되는지 — 은 안전·소스코드 입력에 정리돼 있습니다. 소스에는 시크릿이 코드·.env·설정 파일에 섞여 들기 쉬우므로, 붙이기 전에 그 기준을 먼저 확인하세요. 여기서 더 나아갈 곳을 모았습니다.
- Claude Code 시작 가이드 — 설치·인증·첫 커밋. 이 문서의 출발점입니다.
- 에이전트 개념·3원칙 — 에이전트 안전 원칙과 가드레일이 왜 필요한지의 근거.
- 안전·소스코드 입력 — 무엇을 넣어도 되고 무엇은 안 되는지.
- 출력 검증 — 출력을 어디까지 믿을지, 환각의 배경.
- 검증 워크플로 — 커밋 전 사람이 검토하는 표준 절차.
- 용어집 — 낯선 용어는 여기서 한 줄로 확인.