Claude를 활용한 프로젝트 운영
Claude를 개발 프로젝트에 통합해 생산성과 품질을 높이는 운영 방법론.
공식 문서
.claude/ 폴더 구조
프로젝트 루트의 .claude/ 폴더에 Claude Code 관련 설정과 리소스를 관리한다.
# 프로젝트 루트
.claude/
├── CLAUDE.md # 프로젝트 컨텍스트 (매 대화마다 자동 로드)
├── settings.json # 공유 설정 (git 추적)
├── settings.local.json # 로컬 전용 설정 (gitignore 권장)
├── mcp.json # MCP 서버 설정
├── docs/ # Claude가 참조하는 문서
└── skills/ # 슬래시 커맨드
└── <skill-name>/
└── SKILL.md
# 글로벌 (사용자 홈)
~/.claude/projects/<project-path>/
└── memory/ # 프로젝트별 장기 기억
├── MEMORY.md # 인덱스 (매 대화에 자동 로드)
└── <type>_<name>.md # 개별 메모리 파일
CLAUDE.md
Claude가 모든 대화에서 자동으로 읽는 프로젝트 컨텍스트 파일.
프로젝트 구조, 작업 규칙, 주의사항 등을 기술한다.
settings.json
팀 전체가 공유하는 Claude Code 설정. git에 커밋한다.
{
"language": "korean",
"model": "sonnet",
"permissions": {
"allow": ["Write(**)", "Edit(**)", "Read(**)"],
"deny": ["Bash(rm *)", "Bash(git reset --hard*)"]
}
}주요 필드:
| 필드 | 설명 |
|---|---|
language |
응답 언어 |
model |
사용할 Claude 모델 (sonnet, opus, haiku) |
permissions.allow |
자동 허용할 툴/커맨드 패턴 |
permissions.deny |
자동 거부할 툴/커맨드 패턴 |
settings.local.json
로컬 환경에서만 적용되는 설정. .gitignore에 추가 권장.
settings.json과 동일한 구조이며, 같은 키는 로컬 값이 우선한다.
mcp.json
MCP(Model Context Protocol) 서버 설정.
외부 툴(Gmail, Google Calendar 등)을 Claude에 연결할 때 사용.
{
"mcpServers": {
}
}docs/
Claude가 참조용으로 읽을 Markdown 문서를 두는 폴더.
API 스펙, 도메인 용어집, 아키텍처 설명 등 컨텍스트 보강에 활용.
skills/
/skill-name 형태의 슬래시 커맨드를 정의하는 폴더.
각 스킬은 SKILL.md 파일 하나로 구성된다.
---
name: <skill-name>
description: 스킬 설명
user-invocable: true
allowed-tools: Bash, Read, Glob
---
# 스킬 본문 (Claude에게 전달되는 프롬프트)프로젝트 공통 작업(커밋, 일일 노트 생성 등)을 슬래시 커맨드로 표준화할 수 있다.
/memory 구조
프로젝트별 장기 기억을 파일로 관리한다.
경로: ~/.claude/projects/<project-path>/memory/
memory/
├── MEMORY.md # 인덱스 (매 대화에 자동 로드)
├── user_*.md # 사용자 프로필/선호
├── feedback_*.md # 작업 방식 피드백
├── project_*.md # 프로젝트 맥락/결정사항
└── reference_*.md # 외부 리소스 포인터
MEMORY.md
메모리 파일들의 인덱스. 각 항목은 한 줄로 유지한다.
# MEMORY
- [제목](file.md) — 한 줄 요약- 200줄 초과 시 잘림 → 간결하게 유지
- 내용은 직접 쓰지 않고 개별 파일로 분리
메모리 파일 형식
---
name: 메모리 이름
description: 한 줄 설명 (인덱스에서 관련성 판단에 사용)
type: user | feedback | project | reference
---
내용...
**Why:** 이유
**How to apply:** 적용 방법메모리 타입
| 타입 | 저장 내용 |
|---|---|
user |
사용자 역할, 선호, 지식 수준 |
feedback |
작업 방식 교정/확인 사항 |
project |
진행 중인 작업, 결정, 마감 |
reference |
외부 시스템 위치 (Jira, Slack 채널 등) |
저장하지 않는 것
- 코드 패턴, 파일 구조 (코드에서 직접 읽을 수 있음)
- git 히스토리 (git log로 확인)
- 현재 대화 내 임시 상태
스킬 목록
/commit
변경사항을 git commit한다.
---
name: commit
description: 변경사항을 git commit한다
user-invocable: true
allowed-tools: Bash, Read, Glob
---
# Commit
## 절차
1. `git status`로 변경된 파일 확인
2. `git diff` (staged/unstaged 모두)로 변경 내용 파악
3. 변경 내용을 분석해 커밋 메시지 작성 (아래 컨벤션 참고)
4. 관련 파일을 staging하고 커밋 실행
## 커밋 메시지 컨벤션
```
<type>: <subject>
```
### type 목록
| type | 사용 상황 |
|------|-----------|
| `feat` | 새로운 기능 추가 |
| `fix` | 버그 수정 |
| `docs` | 문서 추가/수정 |
| `refactor` | 기능 변경 없는 코드 구조 개선 |
| `test` | 테스트 추가/수정 |
| `chore` | 빌드, 설정, 패키지 등 기타 변경 |
| `ci` | CI/CD 파이프라인 변경 |
| `perf` | 성능 개선 |
| `style` | 코드 포맷, 세미콜론 등 스타일 변경 (동작 무관) |
### 규칙
- subject는 명령형으로 간결하게 (예: "add login page", "로그인 페이지 추가")
- 마침표 없이 작성
- 한국어 또는 영어 모두 허용
## 커밋 실행 방법
```bash
git add <파일들>
git commit -m "<type>: <subject>"
```
- `git add -A`나 `git add .`는 사용하지 않는다 — 파일을 명시적으로 지정
- `.env`, 시크릿, 민감한 파일이 포함되지 않았는지 확인
- 확인 없이 바로 커밋을 실행한다Subagent
복잡한 작업을 독립적인 하위 에이전트에게 위임하는 기능.
메인 컨텍스트를 오염시키지 않고 병렬/격리 실행이 가능하다.
에이전트 타입
| 타입 | 용도 |
|---|---|
general-purpose |
복잡한 멀티스텝 작업, 키워드/파일 검색 (모든 툴 사용 가능) |
Explore |
코드베이스 탐색, 패턴 검색, 구조 파악 |
Plan |
구현 전략 설계, 아키텍처 검토 |
claude-code-guide |
Claude Code/API/SDK 관련 질문 |
실행 모드
| 모드 | 옵션 | 설명 |
|---|---|---|
| 포그라운드 | 기본 | 결과를 받아야 다음 작업 진행 가능할 때 |
| 백그라운드 | run_in_background: true |
독립적인 작업 병렬 실행, 완료 시 자동 알림 |
| 워크트리 격리 | isolation: "worktree" |
임시 git worktree에서 실행, 변경 없으면 자동 정리 |
언제 사용하나
- 여러 독립 쿼리를 병렬로 처리할 때
- 광범위한 코드베이스 탐색으로 메인 컨텍스트가 커질 때
- 사용자가 명시적으로 subagent 사용을 요청할 때
주의사항
- 단순한 파일 읽기/검색은 Glob·Grep·Read 직접 사용 (subagent는 콜드 스타트)
- 이미 파악한 내용을 subagent에 다시 위임하지 않는다
- "결과를 바탕으로 구현해줘" 같은 합성 작업은 직접 수행