나만의 Claude Code를 조직처럼 쓰는 법

같은 도구인데 왜 결과가 다를까?

Claude Code는 도구다. 그런데 같은 도구를 써도 사람마다 결과가 전혀 다르다.

차이는 설정에 있다. CLAUDE.md 에 뭘 써놓느냐, hooks를 어떻게 걸어놓느냐, Memory에 뭘 남겨놓느냐에 따라
Claude Code는 완전히 다른 동료 가 된다. 신입사원이 될 수도 있고, 10년 차 팀원이 될 수도 있다.

나는 6개월 동안 개인적으로 Claude Code Max ($200) 결제를 하면서 이 설정을 다듬어왔다.

그 과정에서 잡은 세 가지 축이 있다:

CLAUDE.md    →  AI가 "누구인지" 정의 (역할, 규칙, 워크플로우)
Hooks        →  AI가 "자동으로" 하는 행동 (안전장치, 자동화)
Memory       →  AI가 "기억하는" 것 (피드백, 프로젝트 맥락)

1. CLAUDE.md — AI에게 조직도를 심는다

계층 구조: 전역 → 프로젝트

Claude Code는 CLAUDE.md를 계층적으로 읽는다.

~/.claude/CLAUDE.md              ← 전역: 모든 프로젝트 공통 규칙
~/para-system/CLAUDE.md          ← 프로젝트: PARA 시스템 전용 규칙
~/repos/hrd-api/CLAUDE.md        ← 레포: 특정 코드베이스 전용 규칙

전역 설정은 4줄이면 충분하다:

# Claude Code 설정
## 기본 규칙
- 응답 언어: 한국어
- 코드 주석: 영어 허용
- 기술 용어: 원어 그대로 사용
- 간결하고 실용적인 답변

핵심은 프로젝트 레벨 CLAUDE.md에 있다. 여기에 조직도를 심는다.

조직도: 기획자 → 설계자 → 검토자 → 실행자

나는 기획자다. Claude Code는 나의 설계자이자 검토자이자 실행자다. 하지만 이 역할들을 구분하지 않으면 Claude는 물어보지도 않고 코드부터 짠다. 그래서 CLAUDE.md에 조직도를 명시한다.

            사용자 (기획자/PM)
                   │
      ┌────────────┼────────────┐
      │            │            │
   [기획자]      [설계자]      [검토자]
  사용자 직접   Claude        Claude
      │            │            │
      개요서 ──→ 설계서 ──→ 검토 완료 → 사용자 확정 → [실행자]

**기획자(나)**가 개요서를 만들면, **설계자(Claude)**가 설계서로 확장하고, **검토자(Claude)**가 디자인·기술·DX 관점에서 검증한 뒤, 내가 확정하면 **실행자(에이전트)**가 코드를 짠다.

각 단계에 어떤 스킬을 쓰는지도 CLAUDE.md에 적어둔다:

이렇게 해두면 "이 기능 만들어줘"라고 해도 Claude가 바로 코드를 짜지 않는다. 조직도에 따라 "먼저 개요서부터 정리할까요?"라고 물어온다.

실행자: 에이전트 Teams

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 켜면 에이전트를 역할별로 분리해서 병렬 투입할 수 있다.

에이전트 정의 파일

각 에이전트는 ~/.claude/agents/ 폴더에 마크다운 파일로 정의한다. 파일 하나가 팀원 한 명이다.

~/.claude/agents/
├── frontend.md    ← Next.js, React, TypeScript, Tailwind
├── backend.md     ← NestJS, MySQL, Prisma, Redis
├── devops.md      ← AWS, Terraform, Docker, CI/CD
├── designer.md    ← UI/UX, 디자인 시스템, 접근성
├── business.md    ← 사업 전략, EdTech/HRD
├── marketer.md    ← SEO, 콘텐츠 마케팅
└── planner.md     ← PARA, 태스크 관리

에이전트 정의 파일에는 역할, 기술 스택, 원칙, 출력 스타일을 적는다. 예를 들어 frontend.md:

# Frontend Developer
You are a senior frontend developer specializing in modern web applications.

## Tech Stack
- Framework: Next.js (App Router), React
- Language: TypeScript
- Styling: Tailwind CSS
- State: Zustand, TanStack Query

## Principles
- Component-driven development
- Mobile-first responsive design
- Performance budget: LCP < 2.5s, CLS < 0.1

## Output Style
- Clean, typed TypeScript code
- Comments in English, communication in Korean

이렇게 정의해두면 "frontend 에이전트에게 이 컴포넌트 만들어달라고 해"라고 할 때, 해당 에이전트가 자기 역할/스택/원칙에 맞게 동작한다.

CLAUDE.md에서의 에이전트 배치

에이전트 파일만으로는 부족하다. 언제 누구를 투입할지를 CLAUDE.md에서 관리한다:

실전: 병렬 투입

하나의 기능을 구현할 때 이런 식으로 동시에 투입할 수 있다:

"이 화면 만들어줘"
  → designer: 와이어프레임 설계
  → frontend: 컴포넌트 구현
  → backend: API 엔드포인트 생성

필요한 에이전트만 골라서 투입한다. 프론트엔드 화면을 만들 때 business 에이전트까지 깨울 필요는 없다.

Skill Routing: 요청을 스킬로 자동 매칭

CLAUDE.md에 라우팅 규칙을 적어두면, 자연어 요청이 자동으로 적절한 스킬로 연결된다:

## Skill routing
- 아이디어, 브레인스토밍 → /office-hours
- 버그, 에러, "왜 안 돼" → /investigate
- 배포, PR 생성 → /ship
- QA, 테스트 → /qa
- 코드 리뷰 → /review
- 디자인 시스템 → /design-consultation
- 아키텍처 검토 → /plan-eng-review

"이거 왜 안 돼?"라고 물으면 Claude가 직접 답하는 대신 /investigate 스킬을 실행한다. 스킬은 체계적인 4단계 디버깅(조사→분석→가설→구현)을 돌리기 때문에 즉답보다 훨씬 정확하다.

2. Hooks — AI의 자동 행동을 설계한다

Hooks는 특정 이벤트가 발생했을 때 자동으로 실행되는 스크립트다. 내가 설정해둔 Hooks는 4개다.

Hook 1: git push 전 자동 검증 (PreToolUse)

{
  "matcher": "Bash",
  "if": "Bash(git push*)",
  "hooks": [{
    "type": "agent",
    "prompt": "git push 전 변경사항 검증...",
    "model": "claude-haiku-4-5-20251001"
  }]
}

Claude가 git push를 실행하려고 하면, 자동으로 Haiku 모델이 diff를 분석한다. API 응답 필드명이 변경되거나 삭제된 게 있으면 차단한다.

이 Hook을 만든 이유가 있다. 한 번은 Claude가 "정리"한답시고 API 응답 필드명을 임의로 바꿔서 push한 적이 있다. 프론트엔드가 깨졌다. 그 뒤로 push 전에 반드시 검증을 걸어둔다.

검증 기준:

• 안전: 필드 추가, 새 엔드포인트, 주석 변경
• 위험: 필드명 변경/삭제, DB 컬럼 변경 → 차단

Hook 2: 세션 시작 시 일일 체크 (SessionStart)

#!/bin/bash
# daily-memory-review.sh
TODAY=$(date +%Y-%m-%d)
MARKER="$HOME/.claude/.daily-checks/daily-check-$TODAY"

# 이미 오늘 체크했으면 스킵
[ -f "$MARKER" ] && exit 0
touch "$MARKER"

하루에 한 번, 첫 세션이 시작될 때:

1. Memory 파일 수 확인 — feedback 타입 메모리 우선 확인 권고
2. /github:sync 미실행 알림 — 레포 동기화 권장

매일 아침 Claude를 켜면 "오늘 첫 세션입니다. 메모리 4개, feedback 확인하세요. 레포 동기화 아직 안 했습니다."라고 알려준다.

Hook 3: 작업 완료 알림 (Notification)

osascript -e 'display notification "Claude Code 작업 완료!" with title "Claude Code" sound name "Glass"'

긴 작업을 시켜놓고 다른 일을 할 때 유용하다. macOS 알림 + 소리로 완료를 알려준다.

Hook 4: gstack 설계서 자동 복사 (PostToolUse)

# gstack이 설계서를 쓰면 → PARA 폴더로 자동 복사
case "$FILE_PATH" in
  */.gstack/projects/*-design-*.md) ;;
  *) exit 0 ;;
esac
cp "$FILE_PATH" "$DEST/설계서.md"

gstack이 .gstack/projects/ 아래에 설계서를 생성하면, 자동으로 PARA의 해당 프로젝트 폴더(1_project/{name}/설계서.md)로 복사한다. gstack과 PARA 사이의 파일 동기화를 자동화한 것이다.

3. Memory — AI에게 실수를 기억시킨다

Claude Code의 Memory는 ~/.claude/projects/{프로젝트}/memory/ 에 마크다운 파일로 저장된다. 세션이 끝나도 유지되기 때문에, 다음 대화에서도 이전 맥락을 기억한다.

Memory 구조

memory/
├── MEMORY.md                          ← 인덱스 (자동 로드)
├── feedback_no_arbitrary_changes.md   ← "API 필드명 임의 변경 금지"
├── feedback_db_schema_first.md        ← "DB 스키마 먼저 확인"
├── feedback_simulator_calc.md         ← "시뮬레이터 단순 평균 사용"
└── project_employment_platform.md     ← 취업 플랫폼 설계 맥락

Memory 유형

실전: feedback 메모리가 가장 중요하다

feedback 메모리는 Claude가 한 번 틀린 것을 다시 틀리지 않게 하는 장치다.

실제 사례:

feedback: API 응답 필드명 임의 변경 금지

"Why: 이미 배포 중인 API의 응답 구조를 임의로 바꾸면 프론트엔드가 깨진다."

"How to apply: 필드명 변경이 필요해 보일 때 → 코드 수정 전에 사용자에게 확인."

feedback: 목업/API 설계 전 DB 스키마 먼저 확인

"Why: KDT 성과관리에서 임의 카테고리를 넣었는데, 실제 DB에는 다른 값이 있었음."

"How to apply: 샘플 데이터 넣기 전 → DB 테이블 구조 확인."

이 두 개의 feedback은 실제로 사고가 났던 경험에서 나온 것이다. Memory에 저장해두면 Claude가 매 세션마다 이걸 읽고, 같은 실수를 반복하지 않는다.

Memory 운영 원칙

1. 코드에서 읽을 수 있는 것은 저장하지 않는다 — 파일 구조, git 히스토리는 코드가 진실
2. feedback은 반드시 Why와 How to apply를 적는다 — 이유 없는 규칙은 엣지 케이스에서 깨진다
3. SessionStart Hook으로 매일 리마인드 — Memory가 있어도 확인하지 않으면 의미 없다
4. 오래된 Memory는 검증 후 갱신 — 시스템이 바뀌면 Memory도 바뀌어야 한다

4. gstack + Pencil — 실행력을 만드는 스킬들

주로 사용하는 스킬 — 단계별

기획 단계: "머릿속 → 문서"

/knowledge-interviewer가 특히 강력하다. 내가 "취업 관리 시스템 만들고 싶어"라고 하면, Claude가 구조화된 질문을 던져서 머릿속에 흩어진 생각을 원페이퍼 개요서로 정리해준다.

knowledge-interviewer 는 직접 만든 스킬인데, 아주 유용하다. 내 머리속을 말끔하게 비워주고있다.

혹시 댓글이 많아지면 skills 내용을 그대로 공유하겠습니다.

설계/검토 단계: "개요서 → 설계서 → 검증"

/autoplan은 CEO 리뷰 → 디자인 리뷰 → 기술 리뷰를 순차적으로 자동 실행한다. 15~30개 중간 질문에 일일이 답할 필요 없이 한 번에 검토가 끝난다.

실행 단계: "코드 구현"

Pencil: .pen 파일로 디자인하기

Pencil은 .pen 파일 형식의 디자인 도구다. MCP 서버로 연결되어 Claude Code 안에서 직접 디자인을 만들고 수정할 수 있다.

"로그인 화면 목업 만들어줘"
  → /design-pencil 실행
  → .pen 파일 생성 → 스크린샷으로 확인
  → 피드백 반영 → 수정 → PNG/PDF 내보내기

일반적인 디자인 도구(Figma 등)와 다른 점은 대화로 디자인한다는 것이다. "버튼을 좀 더 크게", "여백 줄여줘", "색상 톤 따뜻하게" — 이런 자연어 지시로 디자인을 수정한다.

Pencil로 할 수 있는 것:

• 와이어프레임/목업 — 화면 구조 잡기
• 디자인 변형 비교 — /design-shotgun으로 여러 시안 동시 생성
• 디자인 시스템 수립 — /design-consultation으로 컬러, 타이포, 레이아웃 결정
• 비주얼 QA — /design-review로 완성된 화면의 간격, 계층, 일관성 점검
• PNG/PDF 내보내기 — 최종 산출물 추출

기획자인 내가 직접 Figma를 열지 않아도 이런 **"느낌으로 만들어줘"**로 목업을 받아볼 수 있다는 게 핵심이다.

품질/배포 단계: "테스트 → 배포 → 모니터링"

운영/회고 단계

커스텀 슬래시 커맨드

직접 만든 커맨드들:

5. MCP 서버 — 외부 시스템 연결

Notion은 조회 전용으로 설정해두었다. CLAUDE.md에 "회사 Notion 데이터 수정/생성/삭제는 사용자 명시적 요청 시에만 허용"이라고 명시한다. Claude가 멋대로 회사 문서를 수정하는 일은 없어야 한다.

6. 전체 워크플로우: PARA + Claude Code + gstack

[기획]  /knowledge-interviewer 또는 /office-hours
           → 1_project/{name}/개요서.md

[설계]  /plan-ceo-review, /autoplan
           → 1_project/{name}/설계서.md
           → gstack 설계서는 Hook이 PARA로 자동 복사

[검토]  /plan-design-review, /plan-eng-review, /plan-devex-review
           → 사용자 확정

[실행]  에이전트 Teams 병렬 투입
           → 코드 레포에서: /review, /qa, /ship

[회고]  /retro, /handoff
           → 1_project/{name}/회고.md
           → 완료 시 4_archive/로 이동

PARA가 폴더 구조를, CLAUDE.md가 역할과 규칙을, Hooks가 자동화를, Memory가 기억을, gstack이 실행력을 담당한다. 이 다섯 가지가 맞물려야 "AI를 조직처럼 쓰는" 워크플로우가 완성된다.

시작하기

Step 1. 폴더 구조

mkdir -p ~/para-system/{1_project,2_area,3_resource,4_archive}

Step 2. CLAUDE.md 작성

최소한으로 시작하되, 반드시 넣을 것:

1. 소유자 프로필 — 역할, 강점
2. 응답 규칙 — 언어, 톤
3. 금지 사항 — 삭제 금지, 자동 커밋 금지
4. (선택) 조직도, Skill routing

Step 3. settings.json 설정

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "hooks": {
    "Notification": [{
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"작업 완료!\" with title \"Claude Code\" sound name \"Glass\"'"
      }]
    }]
  }
}

Step 4. 실행하고 Memory 쌓기

cd ~/para-system && claude

Claude가 틀릴 때마다 교정하면 된다. 교정할 때마다 Memory에 feedback이 쌓이고, 점점 나에게 맞는 동료가 된다.

마무리

CLAUDE.md는 채용 공고이고, Hooks는 사내 규정이고, Memory는 업무 일지다. 이 세 가지를 잘 쓰면 Claude Code는 도구가 아니라 조직원이 된다.

댓글이 많아지면
직접 설치부터 설정하는 단계별 포스팅을 진행 해볼게요. 최소 20개 쌓이면...?