한장에 정리한 Claude Code Workflow

소스 : https://www.reddit.com/r/learn_tech/comments/1rtsbtl/claude_code_workflow_cheat_sheet/#lightbox

Reddit의 learn_tech 커뮤니티: Claude code workflow cheat sheet!

 

이 치트시트는 Claude Code를 실무에서 제대로 활용하기 위한 핵심 개념 12가지를 담고 있습니다. 하나씩 깊이 있게 살펴보겠습니다.

---

1️⃣ Getting Started — 시작하기

curl -fsSL https://claude.ai/install.sh | bash

cd your_project
claude
/init

• Node.js 18 이상 필요
• /init 명령을 실행하면 Claude가 현재 코드베이스를 스캔하고 스타터 메모리 파일(CLAUDE.md) 을 자동 생성
• 프로젝트를 처음 시작할 때 반드시 /init부터 실행하는 것이 핵심

---

2️⃣ Understanding CLAUDE.md — 핵심 메모리 파일

CLAUDE.md = Claude의 프로젝트 장기 기억

세션이 시작될 때마다 자동으로 로드되는 파일입니다.

항목 내용

WHAT (무엇을)	기술 스택, 디렉터리 구조, 아키텍처
WHY (왜)	각 모듈의 목적, 설계 결정 이유
HOW (어떻게)	빌드/테스트/린트 명령어, 워크플로우, 주의사항(Gotchas)

예시 구조

# Project: MyApp
FastAPI REST API + React SPA + Postgres

## Commands
npm run dev
npm run test
npm run lint

## Architecture
/app   → Next.js App Router pages
/lib   → shared utilities
/prisma → DB schema & migrations

💡 핵심: CLAUDE.md가 잘 작성될수록 Claude의 코드 이해도와 응답 품질이 비약적으로 향상됩니다.

---

3️⃣ Memory File Hierarchy — 메모리 계층 구조

Claude Code는 4단계 CLAUDE.md 계층을 지원합니다:

~/.claude/CLAUDE.md          ← 전역 (모든 프로젝트 공통)
~/CLAUDE.md                  ← 모노레포 루트
./CLAUDE.md                  ← 현재 프로젝트 (Git 공유용)
./frontend/CLAUDE.md         ← 서브폴더 (범위 한정 컨텍스트)

운영 원칙

• 각 파일은 200줄 이하 유지
• 하위 파일은 상위 컨텍스트에 추가(append) 방식으로 동작
• 상위 파일을 절대 덮어쓰지 않음

---

4️⃣ CLAUDE.md Best Practices — 작성 노하우

1. /init 먼저 실행 후 출력 결과를 다듬는다
2. 명령어는 구체적으로 작성 (Claude가 추론하게 두지 말 것)
3. Claude가 스스로 유추할 수 없는 Gotchas(함정/주의사항) 를 반드시 추가
4. @파일명 형식으로 참조 문서 연결
5. 워크플로우 규칙 명시 (예: "PR 전에 반드시 lint 실행")
6. 메모리는 간결하게 유지
7. Git으로 커밋해서 팀 전체가 공유

---

5️⃣ Project File Structure — 권장 파일 구조

your_project/
├── CLAUDE.md
├── .claude/
│   ├── settings.json
│   ├── settings.local.json
│   └── skills/
│       ├── code-review/
│       │   └── SKILL.md
│       └── testing/
│           ├── SKILL.md
│           └── helpers.py
├── commands/
│   └── deploy.md
└── agents/
    └── security-reviewer.md

• .claude/ 디렉터리가 프로젝트 전용 AI 설정의 홈베이스
• skills/, commands/, agents/ 는 각각의 역할별로 분리

---

6️⃣ Adding Skills (The Superpower) — 스킬 시스템

Skills = Claude가 자연어로 자동 호출하는 마크다운 가이드

스킬 위치

종류 경로

프로젝트 스킬	.claude/skills/<name>/SKILL.md
개인(전역) 스킬	~/.claude/skills/<name>/SKILL.md

⚠️ 핵심 포인트

Description 필드가 자동 활성화(auto-activation)의 핵심입니다!

스킬 파일 예시:

---
name: testing patterns
description: Jest 테스트 패턴 (Read, Grep, Glob 도구 허용)
allowed tools: Read, Grep, Glob
---

# Testing Patterns
- describe + it + AAA 패턴 사용
- Factory mock 활용

Claude가 테스트 관련 작업을 감지하면 이 스킬을 자동으로 불러와 참조합니다.

---

7️⃣ Skill Ideas for AI Engineers — 추천 스킬 목록

즉시 만들어 쓸 수 있는 실용적인 스킬들:

스킬 용도

code-review	코드 리뷰 가이드라인
testing-patterns	테스트 작성 패턴
commit-messages	커밋 메시지 컨벤션
docker-deploy	도커 배포 절차
codebase-visualizer	코드베이스 시각화
api-design	API 설계 원칙

---

8️⃣ Setting Up Hooks — 자동화 훅

Hooks = 결정론적 콜백 (AI가 아닌 확실한 자동 실행)

3가지 훅 타입:

• PreToolUse — 도구 실행 전
• PostToolUse — 도구 실행 후
• Notification — 알림

예시: 보안 스크립트 자동 실행

"hooks": {
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "scripts/sec.sh",
          "timeout": 5
        }
      ]
    }
  ]
}

Exit 코드 규칙

• 0 → 허용(allow)
• 2 → 차단(block)

Bash 명령 실행 전에 보안 검사, 린트, 포맷팅 등을 자동으로 강제 실행시킬 수 있습니다.

---

9️⃣ Permissions & Safety — 권한 및 보안

세밀한 파일/명령 권한 제어:

{
  "permissions": {
    "allow": [
      "Read:*",
      "Bash:git:*",
      "Write:*:*.md"
    ],
    "deny": [
      "Read:env:*",
      "Bash:sudo:*"
    ]
  }
}

• .env 파일 읽기 차단, sudo 명령 차단 등
• 팀 환경에서 AI의 행동 범위를 명확히 제한할 수 있어 안전

---

🔟 The 4-Layer Architecture — 4계층 구조

Claude Code의 작동 원리를 이해하는 핵심 프레임워크:

L1 — CLAUDE.md
     지속적 컨텍스트와 규칙

L2 — Skills
     자동 호출되는 지식 팩

L3 — Hooks
     안전 장치와 자동화

L4 — Agents
     독립적 컨텍스트를 가진 서브에이전트

각 계층이 유기적으로 결합되어 일관되고 안전한 AI 개발 환경을 만듭니다.

---

1️⃣1️⃣ Daily Workflow Pattern — 일일 작업 패턴

실무에서 매일 반복하는 워크플로우:

1. cd project && claude          ← 프로젝트 진입
2. Shift + Tab + Tab             ← Plan Mode 활성화
3. 기능 의도(feature intent) 설명
4. Shift + Tab → Auto Accept    ← 자동 수락 모드
5. /compact                      ← 컨텍스트 압축
6. Esc Esc → rewind             ← 되감기(실수 복구)
7. 자주 커밋
8. 기능별로 새 세션 시작

💡 기능 단위로 세션을 나누는 것이 컨텍스트 오염을 막는 핵심 습관입니다.

---

1️⃣2️⃣ Quick Reference — 빠른 명령어 참조

명령어 기능

/init	CLAUDE.md 자동 생성
/doccat	설치 상태 확인
/compact	컨텍스트 압축
Shift + Tab	모드 전환 (Plan ↔ Auto)
Tab	확장 사고(Extended Thinking) 토글
Esc Esc	Rewind 메뉴

---

📌 정리: Claude Code를 잘 쓰는 핵심 원칙

1. CLAUDE.md를 잘 쓰는 것이 모든 것의 시작 — AI의 품질은 컨텍스트 품질에 비례
2. Skills로 반복 작업을 자동화 — description 필드를 정성스럽게 작성
3. Hooks로 안전망 구축 — 보안과 코드 품질을 자동으로 강제
4. 4계층 구조를 이해하고 활용 — 각 레이어의 역할에 맞게 설정 분리
5. 기능 단위로 세션 관리 — /compact와 새 세션으로 컨텍스트를 깔끔하게 유지

Claude Code는 단순한 AI 코딩 도우미가 아니라, 잘 설계된 메모리·스킬·훅·에이전트 시스템을 통해 팀 전체의 개발 방식을 표준화할 수 있는 강력한 플랫폼입니다. 이 치트시트 하나만 제대로 이해해도 생산성이 크게 달라질 것입니다.