1. Claude Code는 왜 기억을 못 할까?

Claude Code를 쓰다 보면 이런 경험을 하게 됩니다.

"어제 분명히 pnpm 쓰라고 했는데 오늘 또 npm을 써버렸어..."
"커밋 전에 테스트 실행하라고 했잖아, 왜 또 빠뜨려..."
"매번 같은 설명을 반복해야 하다니..."

이유는 단순합니다. Claude Code의 각 세션(대화)은 완전히 독립적으로 시작되기 때문입니다. 어제 한 대화 내용은 오늘 새 세션에서 전혀 없는 것처럼 시작돼요.

마치 매일 아침 기억을 잃는 개발자 동료와 일하는 것처럼요.

이 문제를 해결하는 두 가지 메커니즘이 바로 CLAUDE.md와 자동 메모리입니다.

2. 두 가지 메모리 시스템 한눈에 보기

구분 CLAUDE.md 자동 메모리

두 시스템은 서로 보완 관계입니다. CLAUDE.md는 내가 규칙을 정해주고, 자동 메모리는 Claude가 스스로 유용한 정보를 축적합니다.

3. CLAUDE.md — 개발자가 작성하는 규칙 파일

CLAUDE.md란?

세션이 시작될 때 Claude가 자동으로 읽는 마크다운 파일입니다.

한 번 작성해 두면 매 대화에서 Claude가 이 파일을 먼저 읽고 규칙을 따릅니다.

# CLAUDE.md 예시

## 패키지 매니저
- npm 대신 반드시 pnpm을 사용하세요

## 커밋 규칙
- 커밋 전에 반드시 `pnpm test`를 실행하세요
- 커밋 메시지는 한국어로 작성합니다

## 코드 스타일
- 들여쓰기는 2칸(space)으로 통일합니다
- 함수형 컴포넌트만 사용합니다

## 프로젝트 구조
- API 핸들러는 src/api/handlers/ 폴더에 위치합니다
- 공통 유틸리티는 src/utils/ 폴더에 위치합니다

언제 CLAUDE.md에 추가해야 할까?

• ✅ Claude가 같은 실수를 두 번 반복할 때
• ✅ 지난 세션과 동일한 설명을 또 입력하게 될 때
• ✅ 새 팀원이 합류해서 공통 규칙이 필요할 때
• ✅ 코드 리뷰에서 발견한 팀 표준을 문서화하고 싶을 때

핵심 원칙: "매번 말해야 한다면 파일에 적어두자!"

/init으로 자동 생성하기

CLAUDE.md를 처음 만들 때 직접 쓰기 어렵다면 /init 명령을 써보세요.

/init

Claude가 프로젝트를 분석해서 빌드 명령, 테스트 방법, 발견한 규칙들을 자동으로 채워줍니다. 이미 CLAUDE.md가 있다면 덮어쓰지 않고 개선 사항만 제안합니다.

4. CLAUDE.md 파일 위치와 범위

CLAUDE.md는 여러 위치에 둘 수 있고, 위치에 따라 적용 범위가 달라집니다.

파일 위치 적용 범위 주요 용도 git 공유

파일 로드 순서

프로젝트 실행 시
  ↓
상위 디렉토리부터 찾기 시작 (루트까지 올라가며)
  ↓
각 위치의 CLAUDE.md → CLAUDE.local.md 순서로 로드
  ↓
하위 디렉토리 파일은 해당 폴더 작업 시 추가 로드

💡 팁: CLAUDE.local.md는 반드시 .gitignore에 추가하세요. 팀과 공유하면 안 되는 개인 설정(로컬 DB 주소, 개인 API 키 등)을 여기에 보관하세요.

5. 효과적인 지침 작성법

CLAUDE.md 지침은 구체적일수록 잘 따릅니다. 모호한 표현은 Claude가 자의적으로 해석할 수 있어요.

구체적 vs 모호한 지침 비교

❌ 모호한 표현:
"코드를 제대로 포맷합니다"
"변경 사항을 테스트합니다"
"파일을 정리된 상태로 유지합니다"

✅ 구체적인 표현:
"들여쓰기는 2칸(space)으로 통일합니다"
"커밋하기 전에 pnpm test를 실행합니다"
"API 핸들러는 src/api/handlers/에 저장합니다"

좋은 CLAUDE.md 작성 팁

크기 관리: 파일당 200줄 이내를 목표로 하세요.

너무 길면 Claude가 중요한 규칙을 놓칠 수 있고, 컨텍스트 윈도우를 많이 소비해서 오히려 효율이 떨어집니다.

구조화: 마크다운 헤더와 목록을 활용해 섹션을 나눠주세요.

## 패키지 매니저
## 코드 스타일
## 테스트 규칙
## 폴더 구조

일관성: 서로 충돌하는 규칙이 없는지 주기적으로 검토하세요. 두 규칙이 충돌하면 Claude가 임의로 선택합니다.

HTML 주석 활용: 유지보수자를 위한 메모를 남기고 싶지만 Claude가 읽지 않아도 되는 내용은 HTML 주석으로 작성하세요. 컨텍스트 토큰을 소비하지 않습니다.

<!-- 이 규칙은 2025년 3월 팀 회의에서 결정됨 -->
- API 응답은 항상 JSON 형태로 반환합니다

6. 파일 가져오기(@import) 기능

CLAUDE.md에서 다른 파일을 불러올 수 있습니다.

# CLAUDE.md

프로젝트 개요는 @README를 참조하세요.
사용 가능한 명령어는 @package.json을 참조하세요.

# 추가 지침
- git 워크플로우: @docs/git-instructions.md
- 배포 절차: @docs/deploy-guide.md

@경로/파일명 형식으로 참조하면 해당 파일 내용이 세션 시작 시 함께 로드됩니다.

⚠️ 주의: 가져온 파일도 컨텍스트에 전부 로드되므로, 파일이 많을수록 컨텍스트를 더 소비합니다. 꼭 필요한 파일만 가져오세요.

다른 에이전트 도구의 AGENTS.md 활용

다른 AI 도구가 사용하는 AGENTS.md가 있다면, CLAUDE.md에서 가져와서 두 도구가 같은 규칙을 공유하게 할 수 있습니다.

# CLAUDE.md
@AGENTS.md

## Claude Code 전용 추가 설정
- src/billing/ 변경 시 반드시 계획 모드(Plan Mode) 사용

7. .claude/rules/로 규칙 주제별 분리하기

CLAUDE.md가 200줄을 넘어서기 시작하면 주제별로 파일을 분리할 때입니다.

my-project/
├── CLAUDE.md                  ← 핵심 규칙만 (200줄 이하)
└── .claude/
    └── rules/
        ├── code-style.md      ← 코딩 스타일 규칙
        ├── testing.md         ← 테스트 관련 규칙
        ├── security.md        ← 보안 요구사항
        └── api-design.md      ← API 설계 규칙

.claude/rules/ 안의 모든 .md 파일은 자동으로 인식됩니다. 하위 폴더로도 구성할 수 있어요.

.claude/rules/
├── frontend/
│   ├── react.md
│   └── css.md
└── backend/
    ├── spring.md
    └── database.md

팀 간 규칙 공유 (심볼릭 링크)

여러 프로젝트에서 공통 규칙을 쓰고 싶다면 심볼릭 링크를 활용하세요.

# 공유 규칙 폴더를 현재 프로젝트에 링크
ln -s ~/shared-claude-rules .claude/rules/shared

# 특정 파일만 링크
ln -s ~/company-standards/security.md .claude/rules/security.md

8. 경로별 규칙 — 특정 파일에만 적용하기

규칙에 paths 설정을 추가하면 해당 경로의 파일을 작업할 때만 로드됩니다. 컨텍스트를 절약하고 노이즈를 줄일 수 있습니다.

---
paths:
  - "src/api/**/*.ts"
---

# API 개발 규칙
# (TypeScript API 파일 작업 시에만 자동 적용)

- 모든 API 엔드포인트는 입력 검증을 포함해야 합니다
- 표준 오류 응답 형식을 사용합니다: { success, data, message }
- OpenAPI 문서 주석을 포함합니다

여러 경로를 지정할 수도 있습니다.

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

자주 쓰는 경로 패턴

패턴 적용 대상

💡 paths 설정이 없는 규칙은 항상 로드됩니다. 자주 쓰지 않는 규칙은 경로를 지정해서 필요할 때만 로드되게 하면 효율적입니다.

9. 자동 메모리 — Claude가 스스로 쓰는 메모장

자동 메모리란?

Claude가 작업하면서 유용하다고 판단한 정보를 스스로 파일에 저장하는 기능입니다.

개발자가 아무것도 안 해도 Claude가 알아서 기록합니다.

저장되는 내용 예시:

• 이 프로젝트의 빌드 명령어
• 디버깅 과정에서 발견한 노하우
• 자주 사용하는 코드 패턴
• 아키텍처 관련 발견

ℹ️ Claude Code v2.1.59 이상에서 사용 가능합니다. claude --version으로 확인하세요.

저장 위치

~/.claude/projects/<프로젝트명>/memory/
├── MEMORY.md          ← 핵심 인덱스 (매 세션 처음 200줄 자동 로드)
├── debugging.md       ← 디버깅 관련 상세 메모
├── api-conventions.md ← API 설계 발견 사항
└── ...                ← Claude가 필요에 따라 생성하는 주제 파일들

MEMORY.md는 인덱스 역할을 하며, 처음 200줄만 매 세션에 자동 로드됩니다. 상세 내용은 주제별 파일로 분리해서 필요할 때만 읽어요.

⚠️ 자동 메모리는 컴퓨터 로컬에만 저장됩니다. 팀원과 공유되지 않으며, 다른 기기에도 동기화되지 않습니다.

Claude에게 직접 기억 요청하기

자동 저장 외에 직접 요청도 가능합니다.

"항상 npm이 아닌 pnpm을 쓴다는 걸 기억해줘"
→ Claude가 MEMORY.md에 자동으로 저장

"이것을 CLAUDE.md에 추가해줘"
→ 팀과 공유되는 규칙 파일에 직접 추가

자동 메모리 켜기/끄기

기본적으로 켜져 있습니다. 끄고 싶다면:

# 세션 내에서 끄기
/memory  → 토글 사용

# 설정 파일로 끄기
# .claude/settings.json
{
  "autoMemoryEnabled": false
}

# 환경 변수로 끄기
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

10. /memory 명령으로 메모리 관리하기

/memory

이 명령 하나로 현재 메모리 상태를 모두 확인하고 관리할 수 있습니다.

기능 설명

Claude가 메모리 파일을 읽거나 쓸 때 인터페이스에 "Writing memory" 또는 "Recalled memory" 메시지가 표시됩니다.

11. 자주 겪는 문제와 해결법

❓ "Claude가 CLAUDE.md 규칙을 자꾸 무시해요"

체크리스트:

# 1. /memory 실행해서 파일이 로드됐는지 확인
/memory
# 목록에 없으면 Claude가 못 보는 것

# 2. 지침을 더 구체적으로 수정
"코드를 정리합니다" → "2칸 space 들여쓰기 사용"

# 3. 서로 충돌하는 규칙 찾기
# 같은 동작에 다른 규칙이 있으면 Claude가 임의로 선택

💡 CLAUDE.md는 시스템 프롬프트가 아니라 사용자 메시지로 전달됩니다. 100% 강제 준수가 아닌 "강력한 권고" 수준입니다. 구체적일수록 잘 따릅니다.

❓ "CLAUDE.md가 너무 길어졌어요"

해결책 3가지:

1. 경로별 규칙 활용
   → paths 설정으로 필요할 때만 로드

2. .claude/rules/로 분리
   → 주제별 파일로 나누기

3. Skills로 이동
   → 항상 필요하지 않은 내용은 Skills에 저장
      (필요할 때만 로드됨)

❓ "/compact 후 규칙이 사라졌어요"

프로젝트 루트의 CLAUDE.md는 압축 후에도 살아남습니다. /compact 후에 Claude가 자동으로 다시 읽고 주입합니다.

사라진 경우는 두 가지 중 하나입니다:

• 대화 중에만 말하고 파일에 저장하지 않은 경우
• 하위 폴더의 중첩된 CLAUDE.md인 경우 (아직 재로드 안 됨)

해결: 중요한 규칙은 반드시 파일로 저장하세요.

❓ "자동 메모리가 뭘 저장했는지 모르겠어요"

/memory
→ 자동 메모리 폴더 선택
→ 저장된 파일 목록 확인
→ 원하는 파일 열어서 읽기/편집/삭제

모든 메모리 파일은 일반 마크다운이라 직접 편집하거나 삭제할 수 있습니다.

12. 마무리 — 어떻게 시작할까?

Claude Code 메모리 시스템을 한 줄로 요약하면:

"반복해서 말하게 되는 것은 파일에 적어두고, Claude가 발견하는 것은 Claude가 스스로 기록하게 하라"

핵심 정리

• CLAUDE.md: 매 세션 자동 로드되는 팀 규칙 파일. 200줄 이내 유지
• CLAUDE.local.md: 나만 쓰는 개인 로컬 설정. .gitignore에 추가
• .claude/rules/: 주제별 규칙 분리. 경로 지정으로 필요 시만 로드
• 자동 메모리: Claude가 스스로 쌓는 노하우. /memory로 확인
• /init: CLAUDE.md 자동 생성 명령. 처음 시작할 때 유용

초보자 권장 시작 순서

1단계: /init 실행 → CLAUDE.md 자동 생성
         ↓
2단계: 반복되는 지시사항 → CLAUDE.md에 추가
         ↓
3단계: 파일 길어짐 → .claude/rules/로 분리
         ↓
4단계: /memory로 자동 메모리 확인 및 정리

처음에는 간단하게 /init으로 시작하고, 개발하면서 불편한 점이 생길 때마다 CLAUDE.md에 한 줄씩 추가해나가는 방식을 추천합니다. 🚀

📌 참고 문서: Claude Code 메모리 공식 한국어 문서

1. 확장 기능이 왜 필요할까?

기본 Claude Code는 이미 강력합니다. 파일 읽기, 코드 수정, 터미널 명령 실행 등 많은 것을 할 수 있죠.

그런데 실제 개발 현장에서는 이런 상황이 생깁니다.

• "이 프로젝트에서는 항상 pnpm을 써줘" → 매번 말하기 귀찮다
• "배포할 때마다 이 체크리스트를 따라줘" → 반복 작업이 너무 많다
• "슬랙 채널에 알림도 보내줘" → Claude 혼자서는 외부 서비스를 못 건드린다
• "파일 1,000개를 분석해줘" → 대화가 너무 길어져서 기억을 잃는다

이런 한계를 해결하기 위해 확장 기능이 존재합니다.

핵심 에이전트 루프(읽고→수정하고→검증하는 반복) 위에 레이어를 얹는 방식이에요.

┌─────────────────────────────────┐
│  Plugins / Marketplaces         │  ← 패키징 & 배포
├─────────────────────────────────┤
│  Agent Teams                    │  ← 다중 세션 협력
├──────────────┬──────────────────┤
│  Subagents   │  Hooks           │  ← 위임 & 자동화
├──────────────┴──────────────────┤
│  Skills           MCP           │  ← 지식 & 외부 연결
├─────────────────────────────────┤
│  CLAUDE.md                      │  ← 항상 켜진 컨텍스트
├─────────────────────────────────┤
│  핵심 에이전트 루프 (내장 도구)   │  ← 기본 엔진
└─────────────────────────────────┘

2. 7가지 확장 기능 한눈에 보기

기능 한 줄 요약 실생활 비유

💡 공식 문서 추천: "처음이라면 CLAUDE.md부터 시작하세요. 필요에 따라 다른 기능을 추가하세요."

3. CLAUDE.md — 사무실 공지판 📌

CLAUDE.md란?

세션이 시작될 때 Claude가 자동으로 읽는 프로젝트 규칙 파일입니다.

매번 대화를 시작할 때 "이 프로젝트에서는 pnpm 써줘"라고 하는 대신, 한 번 파일에 써두면 Claude가 항상 기억합니다.

# CLAUDE.md 예시

## 패키지 매니저
- npm 대신 반드시 pnpm을 사용하세요

## 커밋 규칙
- 커밋 전에 반드시 테스트를 실행하세요
- 커밋 메시지는 한국어로 작성합니다

## 코딩 스타일
- 들여쓰기는 2칸(space)으로 통일합니다
- 컴포넌트는 함수형으로만 작성합니다

언제 쓸까?

• ✅ "항상 X를 해줘" 규칙
• ✅ 빌드/테스트 명령어
• ✅ 프로젝트 폴더 구조 설명
• ✅ "절대 Y는 하지 마" 규칙

주의사항

⚠️ 200줄 이내로 유지하세요! 너무 길면 컨텍스트를 많이 차지해서 오히려 Claude의 성능이 떨어집니다. 참조 자료는 Skills로 분리하는 게 좋습니다.

파일 구조 팁

프로젝트가 커지면 .claude/rules/ 폴더를 활용하세요.

my-project/
├── CLAUDE.md                  ← 핵심 규칙 (200줄 이하)
└── .claude/
    └── rules/
        ├── frontend.md        ← React 관련 규칙
        ├── backend.md         ← Spring Boot 관련 규칙
        └── database.md        ← DB 관련 규칙

언어별, 디렉토리별로 규칙을 분리하면 해당 파일 작업 시에만 로드되어 효율적입니다.

4. Skills — 업무 매뉴얼 📖

Skills란?

Claude가 필요할 때 꺼내 쓸 수 있는 지식이나 워크플로우를 담은 마크다운 파일입니다.

CLAUDE.md와 달리, 세션 시작 시 설명(제목)만 읽고 실제 내용은 필요할 때만 불러옵니다.

Skills의 두 가지 종류

① 참조형 Skill — Claude가 알아서 참고하는 지식

# api-style-guide.md (Skill 파일)
---
name: api-style-guide
description: REST API 엔드포인트 설계 규칙과 응답 형식 가이드
---

## 엔드포인트 규칙
- URL은 소문자와 하이픈 사용: /user-profiles (O), /userProfiles (X)
- 복수형 명사 사용: /users (O), /user (X)
- 버전 포함: /v1/users

## 응답 형식
{
  "success": true,
  "data": { ... },
  "message": "성공"
}

② 호출형 Skill — /명령어로 직접 실행하는 워크플로우

# deploy.md (Skill 파일)
---
name: deploy
description: 프로덕션 배포 전 체크리스트를 실행합니다
---

## 배포 순서
1. 테스트 전체 실행: `pnpm test`
2. 빌드 확인: `pnpm build`
3. 환경변수 확인
4. 스테이징 배포 후 검증
5. 프로덕션 배포

사용자: /deploy
Claude: 배포 체크리스트를 시작합니다.
  ✅ 테스트 실행 완료 (42/42 통과)
  ✅ 빌드 성공
  ⚠️  환경변수 DB_HOST가 설정되지 않았습니다!

CLAUDE.md vs Skills — 뭘 어디에 넣을까?

넣어야 할 내용 위치

💡 경험 법칙: CLAUDE.md가 200줄을 넘기 시작하면 참조 자료를 Skills로 빼세요.

5. MCP — 외부 서비스 연결 허브 🔌

MCP란?

Claude가 외부 시스템과 소통할 수 있게 해주는 연결 프로토콜입니다.

MCP 없이는 Claude는 프로젝트 파일만 볼 수 있습니다. MCP가 있으면 외부 세계와 연결됩니다.

MCP 없을 때:  Claude ↔ 프로젝트 파일만

MCP 있을 때:  Claude ↔ 프로젝트 파일
                     ↔ 슬랙 채널
                     ↔ 데이터베이스
                     ↔ 브라우저
                     ↔ Google Drive
                     ↔ GitHub 이슈
                     ↔ ...기타 외부 서비스

MCP + Skills 조합 예시

MCP는 연결만 제공하고, Skills는 그 연결을 잘 쓰는 방법을 알려줍니다.

[MCP]   → 데이터베이스에 연결하는 "능력" 제공
[Skill] → "우리 DB 스키마는 이렇고, 자주 쓰는 쿼리는 이거야" 지식 제공

→ 결합하면: DB에 연결해서 우리 팀 방식대로 쿼리를 작성!

주의사항

⚠️ MCP 서버는 컨텍스트를 먹습니다. 사용하지 않는 서버는 연결 해제하세요.
/mcp 명령으로 서버별 컨텍스트 비용을 확인할 수 있습니다.

6. Subagents — 부하 직원에게 위임하기 🤝

Subagents란?

별도의 컨텍스트(기억 공간)에서 독립적으로 작업하고, 결과 요약만 메인 Claude에게 보고하는 보조 AI입니다.

[메인 Claude]
     │
     ├─ "파일 200개 분석해서 문제점 찾아줘" ──→ [Subagent]
     │                                              ├─ 파일 1 읽기
     │                                              ├─ 파일 2 읽기
     │                                              ├─ ... (200개)
     │                                              └─ 요약 작성
     │
     ←─ "발견된 문제: 3가지 (보안 이슈 1, 성능 이슈 2)"
          (200개 파일 내용은 메인 Claude 메모리에 없음!)

언제 Subagents를 쓸까?

• ✅ 파일을 대량으로 읽어야 할 때
• ✅ 메인 대화를 깔끔하게 유지하고 싶을 때
• ✅ 여러 작업을 병렬로 처리할 때

병렬 Subagents 예시

/audit 명령 실행
     │
     ├──→ [보안 검토 Subagent] ─ 보안 취약점 분석
     ├──→ [성능 분석 Subagent] ─ 병목 구간 찾기
     └──→ [테스트 커버리지 Subagent] ─ 미테스트 코드 탐색
              ↓ (세 작업이 동시에 실행!)
     [메인 Claude] ← 세 가지 요약 결과 취합

7. Agent Teams — 프로젝트 팀 구성하기 👥

Agent Teams란?

여러 Claude Code 세션이 서로 직접 소통하며 협력하는 구조입니다.

Subagents와 헷갈리기 쉬운데, 핵심 차이는 이렇습니다.

Subagents Agent Teams

Subagents 선택: 빠르고 집중된 작업, 결과만 중요할 때
Agent Teams 선택: 팀원들이 결과를 공유하고 서로 검토하고 의견을 나눠야 할 때

⚠️ 현재 실험적 기능이며 기본 비활성화 상태입니다.

8. Hooks — 자동 알람과 트리거 ⚡

Hooks란?

특정 이벤트가 발생하면 자동으로 실행되는 결정론적 스크립트입니다.

"결정론적"이란 AI가 판단하지 않고, 항상 같은 결과가 나오는 스크립트라는 뜻입니다.

파일 편집 완료 이벤트 → Hook 실행 → ESLint 자동 검사
커밋 시도 이벤트 → Hook 실행 → 테스트 자동 실행
중요 파일 수정 이벤트 → Hook 실행 → Slack 알림 발송
세션 시작 이벤트 → Hook 실행 → 환경 변수 체크

Hooks의 큰 장점

컨텍스트 비용이 0입니다! Claude AI를 거치지 않고 스크립트가 직접 실행되기 때문입니다. Claude의 기억 공간을 전혀 차지하지 않아요.

언제 Hooks를 쓸까?

• ✅ 파일 저장 후 자동 린팅
• ✅ 커밋 전 자동 테스트
• ✅ 코드 변경 시 팀 슬랙 알림
• ✅ 세션 시작/종료 시 로깅

9. Plugins — 기능 묶음 패키지 📦

Plugins란?

Skills + Hooks + Subagents + MCP를 하나로 묶어서 설치/배포할 수 있는 단위입니다.

my-team-plugin/
├── skills/
│   ├── deploy.md          ← /my-team-plugin:deploy
│   └── code-review.md     ← /my-team-plugin:code-review
├── hooks/
│   └── pre-commit.sh      ← 커밋 전 자동 실행
└── mcp/
    └── server.json        ← Slack 연결 설정

💡 플러그인 Skill은 네임스페이스됩니다. /deploy 대신 /my-team-plugin:deploy 형태로 호출되어, 여러 플러그인이 충돌 없이 공존할 수 있습니다.

언제 Plugins를 쓸까?

• ✅ 여러 프로젝트에 동일한 설정을 재사용할 때
• ✅ 팀 전체가 같은 워크플로우를 쓸 때
• ✅ Claude Directory(마켓플레이스)에 공유하고 싶을 때

10. 헷갈리는 기능 비교표

① Skills vs Subagents — 뭐가 달라?

측면 Skills Subagents

② CLAUDE.md vs Skills — 뭘 어디에 넣어?

넣을 내용 CLAUDE.md Skills

③ MCP vs Skills — 둘 다 뭔가 추가하는 거 아닌가?

MCP Skills

→ 결론: 둘은 함께 써야 시너지가 납니다.

11. 컨텍스트 비용 이해하기

각 기능이 Claude의 메모리(컨텍스트 윈도우)를 얼마나 차지하는지 알아야 효율적으로 사용할 수 있습니다.

기능 로드 시점 컨텍스트 비용

컨텍스트 절약 팁

# 현재 컨텍스트 사용량 확인
/context

# MCP 서버별 비용 확인
/mcp

# 대화 압축 (포커스 지정 가능)
/compact focus on the API changes

Skills 컨텍스트 완전히 숨기기: 사용자가 직접 호출할 때만 쓰는 Skills에는 disable-model-invocation: true를 설정하세요. 호출 전까지 컨텍스트 비용이 0이 됩니다.

---
name: deploy
description: 프로덕션 배포 체크리스트
disable-model-invocation: true   ← 이 설정!
---

12. 초보자 권장 시작 순서

모든 기능을 한꺼번에 사용할 필요가 없습니다. 단계적으로 늘려가세요.

✅ 1단계: CLAUDE.md 작성
   → 프로젝트 기본 규칙, 빌드 명령어, 코딩 컨벤션 기록

✅ 2단계: Skills 만들기
   → 자주 반복하는 작업(배포, 코드 리뷰 등)을 매뉴얼화

✅ 3단계: MCP 연결
   → 필요한 외부 서비스 추가 (슬랙, DB 등)

✅ 4단계: Hooks 설정
   → 반복 자동화 (린팅, 테스트 등)

⬜ 5단계: Subagents 활용
   → 대용량 작업, 병렬 처리가 필요해질 때

⬜ 6단계: Agent Teams / Plugins
   → 팀 협업, 설정 공유가 필요해질 때

13. 마무리

Claude Code의 확장 기능을 한 줄로 요약하면:

기본 기능이 "무엇을 할 수 있느냐"라면, 확장 기능은 "어떻게 더 잘 할 수 있느냐"입니다.

핵심 정리:

• CLAUDE.md: 항상 기억해야 할 규칙. 200줄 이내로 유지
• Skills: 온디맨드 지식과 워크플로우. 컨텍스트 효율적
• MCP: 외부 서비스 연결. Skills와 함께 써야 시너지
• Subagents: 대용량 작업 위임. 메인 컨텍스트 보호
• Agent Teams: 복잡한 협력 작업. 실험적 기능
• Hooks: AI 없이 자동 실행. 컨텍스트 비용 0
• Plugins: 설정 묶음. 팀 공유/재사용에 최적

처음엔 CLAUDE.md 하나만 잘 써도 생산성이 크게 올라갑니다. 익숙해지면 Skills를 추가하고, 그다음 MCP와 Hooks를 붙여가는 방식을 추천합니다. 🚀

📌 참고 문서: Claude Code 확장하기 공식 한국어 문서

1. Claude Code란 무엇인가?

Claude Code는 터미널(명령줄)에서 실행되는 AI 개발 어시스턴트입니다.

단순히 "코드를 짜줘"라고 대답만 하는 채팅 AI가 아닙니다. 직접 파일을 열고, 수정하고, 테스트를 실행하고, Git 커밋까지 할 수 있는 행동하는 AI입니다.

코딩은 물론 다음과 같은 작업도 도와줍니다:

• 문서 작성 및 검토
• 빌드/배포 실행
• 파일 검색 및 정리
• 웹 검색 및 정보 조사

2. 핵심 개념: 에이전트 루프

Claude Code의 가장 중요한 개념은 에이전트 루프(Agentic Loop) 입니다.

작업을 받으면 아래 세 단계를 완료될 때까지 반복합니다.

┌──────────────────────────────────────────────────┐
│                                                  │
│  [1단계] 컨텍스트 수집                              │
│          → 관련 파일을 읽고 상황을 파악              │
│                  ↓                               │
│  [2단계] 작업 수행                                 │
│          → 파일 수정, 명령어 실행                   │
│                  ↓                               │
│  [3단계] 결과 검증                                 │
│          → 테스트 실행, 오류 확인                   │
│                  ↓                               │
│         완료? → YES → 종료                        │
│                ↓ NO                              │
│         다시 1단계부터 반복                         │
│                                                  │
└──────────────────────────────────────────────────┘

실제 예시로 이해하기

"테스트가 실패해, 고쳐줘" 라고 입력하면?

1. 테스트를 실행해서 무엇이 실패하는지 확인
2. 오류 메시지를 읽음
3. 관련 소스 파일을 검색해서 찾아냄
4. 파일을 읽고 코드를 이해
5. 코드를 수정
6. 테스트를 다시 실행해서 검증

이 모든 과정을 Claude가 스스로 판단하며 진행합니다. 중간에 방향을 잡아주면 즉시 조정도 가능합니다.

💡 핵심 포인트: 에이전트 루프는 "자율적으로 작동하지만 사용자 입력에 반응"합니다. 언제든지 중단하거나 방향을 바꿀 수 있어요.

3. AI의 손과 눈 — 도구(Tools)

도구가 없으면 Claude는 텍스트로만 응답하는 AI입니다. 도구가 있으면 실제로 행동할 수 있는 AI가 됩니다.

각 도구 사용 결과는 루프에 다시 피드백되어 다음 판단의 근거가 됩니다.

내장 도구 외에도 다음으로 기능을 확장할 수 있습니다:

• Skills: Claude가 알 수 있는 지식 확장
• MCP: 외부 서비스 연결 (Google Drive, Slack 등)
• Hooks: 워크플로우 자동화
• Subagents: 작업 위임

4. Claude가 볼 수 있는 것

프로젝트 폴더에서 claude를 실행하면 다음에 접근할 수 있습니다.

📂 프로젝트 폴더
  ├── 프로젝트 파일 전체       ← 현재 폴더 + 하위 폴더 모두
  ├── 터미널 명령어 실행 권한   ← 명령줄에서 되는 건 다 가능
  ├── Git 상태               ← 현재 브랜치, 변경 파일, 커밋 내역
  ├── CLAUDE.md              ← "이 프로젝트 규칙" 저장 파일
  └── 자동 메모리             ← 이전 세션에서 기억한 것들

일반 코드 어시스턴트와의 차이

💡 예시: "인증 버그를 수정해줘" 라고 하면, 관련 파일을 스스로 찾아서, 여러 파일을 읽고, 조정된 편집을 수행하고, 테스트로 검증하고, 요청하면 커밋까지 합니다.

5. 세션으로 작업하기

Claude Code는 작업 내용을 세션(Session) 단위로 저장합니다.

세션의 특징

• 세션은 독립적입니다. 새 세션은 이전 대화 내용 없이 시작됩니다.
• 자동 메모리로 프로젝트 패턴, 선호도를 세션 간에 유지할 수 있습니다.
• 파일 변경 전 스냅샷을 찍어 되돌리기가 가능합니다.

세션 명령어

# 이전 세션 이어서 계속
claude --continue

# 특정 세션 선택해서 재개
claude --resume

# 원본은 그대로, 다른 방향으로 실험
claude --continue --fork-session

세션 재개 vs 포크

[원본 세션] ──────────────────────────────→ (재개)
              │
              └──→ [포크 세션 A] (다른 접근법 시도)
              └──→ [포크 세션 B] (또 다른 시도)

포크는 구글 문서의 "사본 만들기" 와 같습니다. 원본은 그대로 두고 복사본에서 실험할 수 있어요.

⚠️ 주의: 여러 터미널에서 동일한 세션을 동시에 사용하면 대화가 뒤섞일 수 있습니다. 병렬 작업 시에는 --fork-session을 사용하세요.

6. 컨텍스트 윈도우 이해하기

컨텍스트 윈도우는 Claude의 단기 기억 같은 개념입니다.

컨텍스트 윈도우에 담기는 것들:

• 대화 기록
• 읽은 파일 내용
• 실행한 명령어 결과
• CLAUDE.md 내용
• 자동 메모리
• 로드된 Skills

대화가 길어지면 오래된 내용이 자동으로 압축/삭제될 수 있습니다.

컨텍스트 관리 팁

# 현재 컨텍스트 사용량 확인
/context

# MCP 서버별 컨텍스트 비용 확인
/mcp

# 대화 압축 (포커스 지정 가능)
/compact focus on the API changes

💡 팁: 대화 초반에 설정한 규칙이 나중에 잊혀질 수 있습니다. 중요한 규칙은 반드시 CLAUDE.md에 저장하세요.

7. 안전 장치: 체크포인트와 권한 모드

"AI가 실수로 코드를 망가뜨리면 어떡하지?"라는 걱정, 당연합니다.
두 가지 안전 장치가 있어요.

체크포인트 — 언제든 되돌리기

파일을 수정하기 전에 자동으로 스냅샷을 찍어둡니다.

파일 수정 시작
  ↓
📸 스냅샷 자동 저장
  ↓
파일 수정 완료
  ↓
문제 발생? → Esc 두 번 또는 "취소해줘" → 이전 상태로 복원

⚠️ 주의: 체크포인트는 파일 변경만 다룹니다. 데이터베이스나 API 호출 같은 외부 시스템은 되돌릴 수 없어요.

권한 모드 — Shift+Tab으로 전환

8. 실전 활용 팁

✅ 처음부터 구체적으로 작성하기

❌ 나쁜 예:
"로그인 버그 수정해"

✅ 좋은 예:
"체크아웃 흐름이 만료된 카드를 가진 사용자에게 오류가 납니다.
관련 코드는 src/payments/ 폴더에 있어요.
먼저 실패하는 테스트를 작성한 다음 수정해주세요."

✅ 중간에 방향 수정하기

완벽한 프롬프트 없어도 됩니다. 대화하면서 조금씩 수정하면 됩니다.

나: "로그인 버그 수정해"
Claude: [조사하고 시도]
나: "그 방향이 아닌 것 같아요. 세션 처리 쪽을 봐주세요."
Claude: [접근 방식 조정]

✅ 검증 가능한 것 함께 제공하기

"validateEmail 함수를 구현해줘.
테스트 케이스: 
- 'user@example.com' → true
- 'invalid' → false  
- 'user@' → false
구현 후 테스트도 바로 실행해줘."

✅ 복잡한 기능은 계획 먼저

1. Shift+Tab 두 번 → 계획 모드 진입
2. "src/auth/를 읽고 OAuth 추가 계획을 세워줘"
3. 계획 검토 후 대화로 개선
4. 계획이 마음에 들면 실행 모드로 전환

✅ 위임하기 (단계별 지시 대신)

❌ 지시하는 방식:
"user.js 열고, validateEmail 함수 찾아서, 정규식 수정해"

✅ 위임하는 방식:
"이메일 유효성 검증 버그가 있어요. 관련 코드는 src/user/에 있습니다.
조사하고 수정해주실 수 있나요?"

9. 마무리

Claude Code의 핵심을 한 줄로 요약하면:

"읽고 → 수정하고 → 확인하는 루프를 반복하는, 실제로 행동할 수 있는 AI 개발 어시스턴트"

핵심 정리:

• 에이전트 루프: 컨텍스트 수집 → 작업 수행 → 결과 검증을 반복
• 도구: 파일 작업, 검색, 실행, 웹 등 실제로 행동 가능
• 세션: 대화 단위로 저장, 재개/포크 가능
• 컨텍스트 윈도우: AI의 단기 기억, CLAUDE.md로 중요 규칙 유지
• 안전 장치: 체크포인트(되돌리기) + 권한 모드(제어)

처음에는 계획 모드로 시작해서 Claude의 판단을 확인하고, 신뢰가 쌓이면 자동 모드로 전환하는 방식을 추천합니다.

📌 참고 문서: Claude Code 공식 한국어 문서

2026년 AI 개발의 핵심 패러다임 전환: 프롬프트 → 컨텍스트 → 하네스

1. 들어가며 - 왜 지금 하네스 엔지니어링인가? 

2022년에는 프롬프트 엔지니어링이 화제였습니다. "어떻게 질문하느냐"가 AI 품질을 결정한다고 했죠. 2025년에는 컨텍스트 엔지니어링으로 무게중심이 이동했습니다. Andrej Karpathy가 이 개념을 체계화하고, Shopify CEO 토비 루트케가 "LLM에게 작업을 풀 수 있도록 모든 맥락을 제공하는 기술"이라고 정의하면서 주목받기 시작했습니다.

그리고 2026년 초, 하네스 엔지니어링(Harness Engineering) 이라는 개념이 등장했습니다. Terraform과 Ghostty의 창시자 Mitchell Hashimoto가 명명하고, OpenAI 엔지니어링팀의 실제 사례가 공개되면서 빠르게 확산됐습니다.

이 글은 다음 분들을 위해 씁니다.

• AI 코딩 에이전트(Claude Code, Copilot Workspace 등)를 실무에 활용 중인 개발자
• 프롬프트를 열심히 다듬었는데 결과가 들쭉날쭉한 경험을 하신 분
• "컨텍스트 엔지니어링"과 "하네스 엔지니어링"의 차이가 헷갈리는 분

2. 컨텍스트 엔지니어링이란? 

한 줄 정의

AI 모델이 추론하는 시점에 컨텍스트 창(Context Window)에 무엇을 담을지 설계하는 기술

등장 배경

프롬프트 엔지니어링의 한계는 명확했습니다. "지시문을 잘 쓰는 것"만으로는 복잡한 작업을 안정적으로 수행할 수 없었죠. 모델이 할루시네이션을 일으키는 가장 큰 이유는 모델이 멍청해서가 아니라, 잘못된 정보 위에서 올바르게 추론하기 때문입니다.

컨텍스트 엔지니어링은 이 문제를 "모델에게 무엇을 보여주느냐"로 해결합니다.

핵심 구성요소

컨텍스트 엔지니어링의 범위

[단일 세션 / 단일 에이전트]

사용자 요청
    ↓
[컨텍스트 조립]
  - 시스템 프롬프트
  - RAG 검색 결과
  - 이전 대화 요약
  - 도구 결과
    ↓
모델 추론
    ↓
응답

핵심은 "모델이 보는 것"에 집중한다는 점입니다. 단일 추론, 단일 세션의 품질을 높이는 데 강력하지만, 에이전트가 여러 세션에 걸쳐 장시간 작업할 때의 신뢰성은 별개 문제입니다.

3. AI 하네스 엔지니어링이란? 

한 줄 정의

AI 에이전트를 감싸는 제어 시스템(환경) 전체를 설계하고 운영하는 공학 분야

핵심 공식

Agent = Model + Harness

모델이 CPU라면, 컨텍스트는 RAM, 하네스는 운영체제(OS) 입니다.

왜 등장했나?

OpenAI 엔지니어링팀은 2025년 하반기에 충격적인 실험을 시작했습니다. 인간이 코드를 한 줄도 쓰지 않고, Codex 에이전트만으로 프로덕션 제품을 만드는 것이었죠.

5개월 후 결과: 약 100만 줄의 코드, 1,500개 이상의 PR이 머지됐습니다.

이 팀이 배운 가장 중요한 교훈은 모델 성능이 아니었습니다. "에이전트가 실수할 때, 더 잘하라고 말하지 말고, 그 실수가 구조적으로 불가능하게 만들어라" 는 것이었습니다. 이것이 하네스 엔지니어링의 본질입니다.

하네스의 두 가지 핵심 컴포넌트

Guides (가이드) - 사전 제어

• 에이전트가 행동하기 전에 작동
• 허용된 행동 범위 정의
• 예: CLAUDE.md 규칙, 아키텍처 제약, 커스텀 린터

Sensors (센서) - 사후 관찰

• 에이전트가 실제로 한 일을 검증
• 예: 테스트, CI/CD 파이프라인, 정적 분석, 로그

[다중 세션 / 다중 에이전트 환경]

┌─────────────────────────────────┐
│         HARNESS (하네스)         │
│                                 │
│  ┌──────────┐  ┌─────────────┐  │
│  │ Guides   │  │  Sensors    │  │
│  │(사전 제어)│  │ (사후 관찰) │  │
│  │- CLAUDE.md│  │- 테스트     │  │
│  │- 린터     │  │- CI 파이프  │  │
│  │- MCP 서버 │  │- 로그 수집  │  │
│  └────┬─────┘  └──────┬──────┘  │
│       │               │         │
│  ┌────▼───────────────▼──────┐  │
│  │     Context Engineering   │  │
│  │   (컨텍스트 엔지니어링)    │  │
│  └────────────┬──────────────┘  │
│               │                 │
│  ┌────────────▼──────────────┐  │
│  │        Model (LLM)        │  │
│  └───────────────────────────┘  │
└─────────────────────────────────┘

AI 팩토리(AI Factory)의 7개 레이어

하네스 엔지니어링이 성숙해지면 조직 단위의 AI 팩토리로 발전합니다.

4. 핵심 비교 분석 

한눈에 보는 비교표

세 개념의 진화 흐름

2022~2024           2025              2026
─────────────────────────────────────────────→
프롬프트 엔지니어링  컨텍스트 엔지니어링   하네스 엔지니어링
"무엇을 물어볼까?"  "무엇을 보여줄까?"   "어떤 환경을 만들까?"
단일 턴 최적화      단일 세션 최적화      시스템 레벨 최적화

신입사원 비유

온보딩 문서(컨텍스트)는 유용하고 필요하지만, 그것만으로는 부족합니다.
신입사원에게는 실수해도 시스템이 잡아주는 구조가 필요합니다.

자동차 비유 (가장 명쾌한 설명)

모델(LLM)      = 엔진
컨텍스트       = 연료 + 계기판 정보
하네스         = 핸들 + 브레이크 + 차선 + 경고등 + 정비 일정

엔진과 연료에만 집중해도 자동차는 굴러갑니다.
하지만 브레이크 없이 고속도로를 달리면 어떻게 될까요?

5. 두 개념의 관계 - 포함인가, 교집합인가? 

커뮤니티 내에서도 의견이 갈립니다. 양쪽 시각을 모두 정리합니다.

시각 ①: 하네스 ⊃ 컨텍스트 (주류 관점)

컨텍스트 엔지니어링은 하네스의 레이어 3에 해당합니다. 하네스가 컨텍스트 엔지니어링을 포함하고 조율합니다.

HARNESS
  └── Context Engineering  ← 여기가 컨텍스트 엔지니어링의 위치
  └── Tool Management
  └── Memory & State
  └── Safety Enforcement
  └── Feedback Loops

시각 ②: 컨텍스트 ⊃ 하네스 (일부 실무자 관점)

"하네스 설정 자체도 결국 컨텍스트를 어떻게 관리할지에 관한 것"이라는 시각. 하네스 엔지니어링을 컨텍스트 엔지니어링의 코딩 에이전트 특화 부분집합으로 봅니다.

📌 결론: 어떻게 보든 함께 씁니다

두 개념은 분리해서 쓸 수 없습니다. 하네스 안의 각 에이전트는 여전히 좋은 컨텍스트를 필요로 하고, 컨텍스트 엔지니어링이 아무리 잘 돼 있어도 피드백 루프·제약·검증이 없으면 다중 세션에서 무너집니다.

6. 실전 적용 - Claude Code / CLAUDE.md 예시

실제 Claude Code를 사용하는 개발 환경에서 두 개념이 어떻게 적용되는지 정리합니다.

컨텍스트 엔지니어링에 해당하는 것들

# CLAUDE.md (컨텍스트 엔지니어링 부분)

## 프로젝트 개요
Spring Boot 3.x + MariaDB + React 기반 대학 LMS 시스템

## 코드 스타일
- Java: 카멜케이스, 탭 대신 스페이스 4칸
- 패키지 구조: com.sdu.lms.{domain}.{layer}

## 자주 쓰는 패턴
- Repository: JPA + QueryDSL 병행
- DTO 변환: MapStruct 사용

## 현재 작업 컨텍스트
- 2026년 2학기 모집 사이트 UI 개선 중
- 외부 업체 낫에그와 협업 중

// 컨텍스트 엔지니어링: Few-shot 예시로 패턴 제공
// 에이전트에게 "우리 팀이 선호하는 응답 형태"를 직접 보여주기

// 좋은 예 (우리 팀 스타일)
public ApiResponse<CourseDto> getCourse(Long id) {
    return courseService.findById(id)
        .map(ApiResponse::success)
        .orElseThrow(() -> new ResourceNotFoundException("Course", id));
}

하네스 엔지니어링에 해당하는 것들

# CLAUDE.md (하네스 엔지니어링 부분)

## 절대 하지 말 것 (Guides - 제약)
- application.yml의 DB 비밀번호 직접 수정 금지
- /api/admin/** 엔드포인트 인증 로직 임의 변경 금지
- 마이그레이션 파일(V*.sql) 수정 금지 (새 파일 추가만 가능)

## 완료 기준 (Sensors - 검증)
- 모든 변경 후 반드시 ./gradlew test 실행
- 빌드 실패 시 수정 후 재시도
- 컨트롤러 추가 시 통합테스트 파일도 함께 생성

## 아키텍처 규칙 (구조적 제약)
- Controller → Service → Repository 방향만 허용
- Service가 Controller를 import하는 것 절대 금지

# 하네스 엔지니어링: 구조적 제약을 코드로 강제
# (커스텀 린터 예시 - 레이어 의존성 검사)

#!/bin/bash
# check-layer-dependency.sh
# CI에서 실행 - Service가 Controller를 import하면 빌드 실패

if grep -r "import.*controller" src/main/java/**/*Service.java; then
    echo "❌ 레이어 위반: Service가 Controller를 import하고 있습니다."
    exit 1
fi
echo "✅ 레이어 의존성 검사 통과"

# GitHub Actions - 하네스의 Sensor 역할
name: Agent Code Validation

on: [pull_request]

jobs:
  validate:
    steps:
      - name: 레이어 의존성 검사
        run: bash scripts/check-layer-dependency.sh

      - name: 테스트 실행
        run: ./gradlew test

      - name: 아키텍처 테스트 (ArchUnit)
        run: ./gradlew archTest

두 개념을 함께 적용한 CLAUDE.md 전체 구조

# CLAUDE.md

## [컨텍스트 영역] 프로젝트 이해
- 기술 스택, 도메인 지식, 코딩 컨벤션
- 현재 스프린트 목표, 알려진 이슈

## [컨텍스트 영역] 참고 문서 위치
- 설계 문서: docs/architecture/
- API 명세: docs/api/
- DB 스키마: docs/schema/

## [하네스 영역] 행동 제약 (Guides)
- 금지 행동 명시
- 승인 없이 변경 불가한 파일 목록
- 의존성 방향 규칙

## [하네스 영역] 완료 검증 (Sensors)
- 필수 실행 명령어
- 성공 기준
- 실패 시 대응 방법

7. 어떤 것부터 시작해야 할까? 

단계별 도입 순서

Phase 1: 컨텍스트 엔지니어링부터 (즉시 효과)

✅ CLAUDE.md 작성 - 프로젝트 개요, 코딩 스타일
✅ 자주 쓰는 패턴 예시 추가
✅ 현재 작업 컨텍스트 항상 업데이트

Phase 2: 하네스 기초 (1~2주)

✅ "절대 하지 말 것" 섹션 추가 (Guides)
✅ 완료 기준 명시 (Sensors)
✅ 에이전트가 같은 실수를 반복하면 → CLAUDE.md에 규칙 추가

Phase 3: 하네스 심화 (1개월)

✅ 커스텀 린터 작성 (아키텍처 규칙 강제)
✅ CI에서 에이전트 출력 자동 검증
✅ MCP 서버 연결 (도구 접근 관리)
✅ 서브에이전트로 컨텍스트 격리

핵심 원칙 하나

"에이전트가 같은 실수를 두 번 하면, 세 번째는 구조적으로 불가능하게 만들어라."
— Mitchell Hashimoto (하네스 엔지니어링 명명자)

8. 마무리

핵심 요약

세 개념은 경쟁 관계가 아닙니다. 중첩된 레이어입니다. 좋은 AI 개발 워크플로우는 세 가지를 모두 포함합니다.

특히 Claude Code 같은 코딩 에이전트를 실무에 활용할수록, 컨텍스트를 아무리 잘 짜도 하네스 없이는 신뢰성을 담보할 수 없다는 것을 경험하게 됩니다. CLAUDE.md에 규칙을 쌓고, CI로 검증하고, 실패에서 구조적 제약을 도출하는 것—이것이 2026년 AI 시대의 핵심 엔지니어링 역량입니다.

💡 AI를 잘 다루는 두 가지 핵심 역량 — 프롬프트 엔지니어링과 컨텍스트 엔지니어링. 비슷해 보이지만 범위와 철학이 완전히 다릅니다. 이 글에서 두 개념을 명확히 정리하고, 실전에서 언제 무엇을 써야 하는지 알아봅니다.

1. 등장 배경 — 왜 지금 이 개념인가?

AI 활용이 일상화되면서 "AI를 얼마나 잘 다루느냐"가 핵심 역량이 되었습니다.

초기 GPT-3 시대에는 프롬프트 엔지니어링이 AI 활용 능력의 전부였습니다. "어떻게 말하면 AI가 잘 대답하나?"에 집중했죠.

하지만 LLM이 점점 더 복잡한 작업을 수행하게 되고, 에이전트(Agent) 기반 시스템이 등장하면서 새로운 개념이 주목받기 시작했습니다. 바로 컨텍스트 엔지니어링입니다.

2. 프롬프트 엔지니어링 (Prompt Engineering)

LLM에 전달하는 입력 텍스트(프롬프트) 자체를 정교하게 설계하여 원하는 출력을 이끌어내는 기법입니다.

핵심 특징

• 범위: 단일 프롬프트 또는 몇 개의 메시지 교환
• 초점: 지시문의 표현, 어조, 구조, 예시 제공 방식
• 목표: 정확하고 일관된 출력 유도
• 토큰 범위: 수백 ~ 수천 토큰

주요 기법

실전 예시

# 역할 + 형식 지정 + 예시 제공 (Few-shot)

당신은 Spring Boot REST API 설계 전문가입니다.
아래 기능 설명을 보고 엔드포인트를 설계해주세요.

[예시]
기능: 사용자 목록 조회
→ GET /api/users → { users: [...] }

[요청]
기능: 특정 게시글 상세 조회
→ ?

3. 컨텍스트 엔지니어링 (Context Engineering)

단순히 "어떻게 말할까"를 넘어서, 모델이 처리하는 전체 정보 환경을 설계합니다. 시스템 프롬프트, 대화 이력, 외부 문서, 도구 결과, 메모리 등 모델이 보는 모든 것을 구성하는 공학적 접근입니다.

핵심 특징

• 범위: 컨텍스트 윈도우 전체 (수만 ~ 수십만 토큰)
• 초점: 정보의 선택, 배치, 압축, 우선순위
• 목표: 모델이 올바른 판단을 내릴 수 있는 정보 환경 구성
• 핵심 역량: 시스템 설계 능력

주요 구성 요소

• System Prompt: 모델의 역할, 규칙, 제약을 장기적으로 정의
• RAG (Retrieval-Augmented Generation): 관련 문서를 동적으로 주입
• Memory 관리: 장기/단기 메모리 설계 (대화 요약, 사용자 프로필 등)
• Tool Use 결과 주입: 검색·DB 조회·API 호출 결과를 컨텍스트로 삽입
• Multi-turn 이력 관리: 어디까지 대화를 유지할 것인지 설계
• Agent 워크플로우 상태 전달: 이전 서브에이전트 결과를 다음 단계로 전달

실전 예시 — Claude Code의 CLAUDE.md

Claude Code를 써보셨다면 이미 컨텍스트 엔지니어링을 경험한 것입니다. CLAUDE.md가 바로 컨텍스트 엔지니어링의 대표 사례입니다.

# CLAUDE.md — 컨텍스트 엔지니어링 실제 사례

## 프로젝트 개요
- 학사행정 시스템 (Spring Boot + MariaDB)
- 배포 환경: Docker Compose

## 코딩 규칙
- 변수명은 camelCase 사용
- 모든 서비스 클래스에 @Transactional 적용

## 현재 작업 중인 모듈
- 수강신청 API (EnrollmentController.java)

## 절대 금지
- 프로덕션 DB에 직접 쿼리 실행 금지
- System.out.println 사용 금지 (로거 사용)

이 파일 하나로 모델은 매번 설명 없이도 프로젝트의 전체 맥락을 파악하고 작업합니다. 이것이 컨텍스트 엔지니어링의 핵심입니다.

4. 핵심 비교 분석

5. 포함 관계 — 대립이 아니다

두 개념을 경쟁 관계로 보는 시각이 있지만, 실제로는 포함 관계입니다.

좋은 컨텍스트 엔지니어는 반드시 프롬프트 엔지니어링 능력도 갖추어야 합니다. 시스템 프롬프트를 잘 작성하는 것 자체가 프롬프트 엔지니어링이기 때문입니다.

6. 언제 무엇을 써야 하나?

🟣 프롬프트 엔지니어링이 적합한 경우

• 단발성 질문/답변 (챗봇 Q&A)
• 텍스트 분류, 요약, 번역 등 단순 작업
• 프로토타이핑 단계에서 빠른 실험
• 소규모 자동화 스크립트
• 블로그 초안 생성, 이메일 작성 등 1회성 요청

🟢 컨텍스트 엔지니어링이 적합한 경우

• 멀티턴 대화 시스템 (고객 상담 AI)
• 에이전트 기반 시스템 (Claude Code, MCP 워크플로우)
• RAG 시스템 — 사내 문서 검색 + 답변
• 코드 생성 도우미 — 프로젝트 전체 구조 인식 필요
• 장기적인 프로젝트 협업 AI
• Google Calendar·Gmail·Drive 같은 MCP 연동 시스템

들어가며

Claude Code를 쓰다 보면 어느 순간 AI의 응답이 이상해지는 경험을 하게 됩니다.

"분명히 이 파일 수정하지 말라고 했는데 왜 또 건드리지?" "이 작업이랑 관계없는 내용을 왜 계속 언급하는 거야?"

이런 현상의 원인 대부분은 누적된 컨텍스트입니다. Claude Code는 대화 히스토리 전체를 참고해서 응답을 생성하는데, 작업이 길어질수록 불필요한 정보가 쌓여 판단을 흐리게 만들죠.

이럴 때 쓰는 명령어가 바로 /clear입니다.

이 글에서는 /clear의 개념, 동작 방식, 그리고 실전에서 언제 어떻게 써야 하는지를 정리합니다.

/clear란 무엇인가?

/clear는 현재 Claude Code 세션의 대화 히스토리(컨텍스트)를 완전히 초기화하는 명령어입니다.

> /clear

입력 즉시 실행되며, 확인 프롬프트 없이 바로 히스토리가 삭제됩니다.

핵심 특징

• ✅ 대화 히스토리만 삭제 (파일·코드에는 영향 없음)
• ✅ CLAUDE.md에 저장된 장기 메모리는 유지
• ✅ 별도 옵션이나 인자 없이 단독으로 사용
• ❌ 되돌리기 불가 (삭제된 히스토리 복원 없음)

언제 사용해야 할까?

1. 완전히 다른 작업으로 전환할 때

기능 A 구현을 마치고 기능 B를 시작하는 상황이라면, 이전 대화 내용은 오히려 방해가 될 수 있습니다. 새 작업 시작 전 /clear로 깨끗한 상태를 만들어 주세요.

# 기능 A 작업 완료 후
> /clear

# 새 작업 시작
> 로그인 API 엔드포인트 만들어줘

2. 컨텍스트가 오염됐을 때

잘못된 전제로 대화가 진행되거나, Claude가 이미 수정된 사항을 계속 이전 상태로 인식할 때 유효합니다.

3. 토큰 비용·응답 품질 관리

컨텍스트가 길어질수록 API 비용이 증가하고, 응답 속도도 느려집니다. 일정 분량을 넘기면 /clear 후 재시작하는 것이 효율적입니다.

4. 민감한 정보 제거

API 키, 비밀번호, 개인정보 등이 대화 중에 노출됐다면 즉시 /clear로 세션에서 제거하세요.

실제 동작 방식

Claude Code의 컨텍스트 구조는 다음과 같습니다.

┌──────────────────────────────────────┐
│         Claude Code 세션             │
│                                      │
│  ┌────────────────────────────────┐  │
│  │    대화 히스토리 (context)      │  │  ← /clear 로 삭제되는 영역
│  │  - 이전 질문/답변               │  │
│  │  - 파일 내용 스냅샷             │  │
│  │  - 작업 지시사항               │  │
│  └────────────────────────────────┘  │
│                                      │
│  ┌────────────────────────────────┐  │
│  │    CLAUDE.md (장기 메모리)      │  │  ← /clear 로 삭제되지 않음
│  │  - 프로젝트 컨벤션             │  │
│  │  - 자주 쓰는 명령어            │  │
│  │  - 팀 규칙                     │  │
│  └────────────────────────────────┘  │
│                                      │
│  실제 파일 시스템 (변경 없음)          │
└──────────────────────────────────────┘

/clear 실행 후에도 파일 시스템은 그대로 유지됩니다. Claude가 이전에 생성하거나 수정한 파일은 디스크에 그대로 남아 있습니다.

관련 개념: CLAUDE.md와 컨텍스트 관리

/clear를 잘 활용하려면 CLAUDE.md를 함께 써야 합니다.

CLAUDE.md는 프로젝트 루트에 두는 마크다운 파일로, Claude Code가 세션 시작 시 자동으로 읽어들이는 장기 메모리 역할을 합니다.

# CLAUDE.md 예시

## 프로젝트 개요
- Spring Boot 3.x + React 기반 웹 애플리케이션
- DB: MariaDB 10.6

## 코드 컨벤션
- 패키지명: com.example.project
- 서비스 레이어에서만 트랜잭션 처리

## 주의사항
- /src/legacy 폴더는 절대 수정하지 말 것
- 테스트 코드 항상 작성

/clear로 대화 히스토리를 지워도, CLAUDE.md에 적힌 내용은 다음 질문부터 다시 반영됩니다.

💡 실전 팁: 작업하다가 중요한 결정 사항이나 컨벤션이 생기면 CLAUDE.md에 기록해두고 /clear하세요. 이렇게 하면 히스토리는 깔끔하게 유지하면서 중요한 맥락은 보존할 수 있습니다.

자주 묻는 질문

Q. /clear 전에 작업한 파일이 사라지나요? 아니요. 대화 히스토리만 삭제됩니다. 파일은 그대로입니다.

Q. 실수로 /clear 했어요. 되돌릴 수 있나요? 불가능합니다. 다만 /clear 전에 작업한 파일은 디스크에 남아있고, Git을 사용 중이라면 커밋 히스토리로 코드는 복원 가능합니다.

Q. 얼마나 자주 써야 하나요? 정해진 규칙은 없지만, 큰 작업 단위가 끝날 때마다 또는 대화가 30~40턴 이상 길어졌을 때 사용하는 것을 권장합니다.

Q. /clear와 Claude Code 재시작의 차이는? /clear는 세션을 유지하면서 히스토리만 지웁니다. 재시작은 프로세스 자체를 종료하므로 더 완전한 초기화가 필요할 때 사용합니다.

마무리

/clear는 단순해 보이지만, Claude Code를 효율적으로 사용하는 핵심 습관 중 하나입니다.

핵심 요약:

• 대화 히스토리(컨텍스트)를 즉시 초기화하는 명령어
• 파일·CLAUDE.md에는 영향 없음
• 새 작업 전환, 컨텍스트 오염, 비용 관리 시 사용
• CLAUDE.md와 함께 써야 효과적

AI와 협업하는 방식도 결국 도구를 제대로 이해하고 사용하는 것에서 차이가 납니다. /clear 하나지만, 알고 쓰는 것과 모르고 쓰는 것은 다릅니다.

Claude Code를 쓰다 보면 어느 순간 세션 성능이 느려지거나, 갑자기 대화가 압축되는 경험을 하게 됩니다. 그 원인은 대부분 컨텍스트 윈도우 고갈입니다. /context 명령어 하나로 이 문제를 사전에 진단하고 최적화할 수 있습니다.

1. /context 명령어란?

Claude Code 세션에서 /context를 입력하면 현재 컨텍스트 윈도우의 토큰 사용 현황을 항목별로 분해해서 보여줍니다.

Claude Code v1.0.86에서 도입된 이 명령어는 단순한 숫자 확인을 넘어, 어디서 토큰이 낭비되고 있는지 찾아내는 진단 도구입니다.

/context

한 줄 입력만으로 아래처럼 전체 컨텍스트 구성을 확인할 수 있습니다.

2. 출력 결과 항목별 설명

실제 출력 예시는 다음과 같습니다.

Context Usage  claude-sonnet-4-5-20251101
51k/200k tokens (26%)

System prompt:      2.6k tokens  (1.3%)
System tools:      17.6k tokens  (8.8%)
MCP tools:          0.9k tokens  (0.5%)
Custom agents:      0.9k tokens  (0.5%)
Memory files:       0.3k tokens  (0.2%)
Skills:             1.0k tokens  (0.5%)
Messages:           9.6k tokens  (4.8%)
──────────────────────────────────────────
Free space:        168k  (84.0%)
Autocompact buffer: 33k tokens (16.5%)

각 항목이 무엇을 의미하는지 살펴보겠습니다.

System prompt / System tools

Claude Code 자체가 동작하기 위해 필수적으로 로드하는 항목입니다. 변경이 불가능한 고정 비용이라고 생각하면 됩니다. System prompt와 System tools를 합치면 대략 18~20k 토큰을 차지합니다.

MCP tools

연결된 MCP 서버의 도구 정의가 로드되는 항목입니다. 여기서 주의할 점이 있습니다.

MCP 서버는 실제로 사용하지 않아도, 연결만 되어 있으면 매 요청마다 토큰을 소비합니다.

예를 들어 Gmail MCP 서버만 해도 7개 이상의 도구 정의를 가지고 있어 꽤 많은 토큰을 차지합니다. 코딩 세션 중에 Gmail이 필요하지 않다면, 연결을 끊는 것만으로 컨텍스트를 절약할 수 있습니다.

Memory files

CLAUDE.md를 포함한 메모리 파일의 내용이 여기에 표시됩니다. CLAUDE.md는 매 메시지마다 컨텍스트에 포함되므로, 파일이 비대해지면 세션 전체에 걸쳐 부담이 됩니다.

Messages

지금까지 나눈 대화 히스토리의 누적량입니다. 세션이 길어질수록 이 숫자가 올라갑니다. /context를 주기적으로 확인하며 이 항목이 60~70%를 넘기 전에 /compact를 실행하는 것이 좋습니다.

Free space

앞으로 사용 가능한 잔여 공간입니다. 이 수치가 줄어들수록 Claude의 응답 품질이 저하될 수 있습니다.

3. Autocompact Buffer란?

출력 맨 아래에 표시되는 Autocompact buffer: 33k tokens는 Claude Code가 자동 압축 작업을 위해 예약해둔 공간입니다.

현재(2026년 기준) 기본값은 약 33k 토큰(전체의 16.5%)이며, 200K 컨텍스트 윈도우 기준으로 사용량이 약 **83.5%(~167K 토큰)**에 도달하면 자동으로 대화 압축(Auto-compaction)이 트리거됩니다.

[컨텍스트 윈도우 200K]
├── 사용 가능 공간: ~167K (83.5%)
└── Autocompact buffer: ~33K (16.5%) ← 자동 압축용 예약 공간

이 buffer는 하드코딩된 값으로, CLAUDE_CODE_MAX_OUTPUT_TOKENS 같은 환경변수로는 변경되지 않습니다.

💡 팁: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 환경변수로 자동 압축 트리거 임계값(%)을 조정할 수는 있습니다.

# 90%까지 사용 후 압축 (기본 83.5%보다 늦게)
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=90

# 70%에서 일찍 압축 (여유 공간 더 확보)
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70

4. 실전 최적화 액션

/context 결과를 보고 취할 수 있는 액션을 정리했습니다.

✅ MCP 서버 정리

/mcp

현재 연결된 MCP 서버 목록을 확인한 후, 이번 세션에서 쓰지 않는 서버는 비활성화합니다. 특히 Google Drive, Gmail처럼 도구 수가 많은 서버는 idle 상태에서도 상당한 토큰을 점유합니다.

✅ CLAUDE.md 다이어트

Memory files가 5k 토큰 이상이라면 CLAUDE.md 내용을 점검해보세요. 특정 작업에만 필요한 지시사항은 CLAUDE.md 대신 Skills로 분리하세요. Skills는 필요할 때만 로드되지만, CLAUDE.md는 항상 로드됩니다.

✅ 선제적 /compact 실행

자동 압축이 트리거되기를 기다리지 말고, Messages 항목이 커지기 시작하면 직접 실행하세요. 보존할 내용을 지정하면 더 정확한 요약이 됩니다.

/compact 데이터베이스 마이그레이션 관련 내용 위주로 보존해줘

✅ 서브에이전트 활용

파일 탐색, 웹 검색 등 결과가 방대한 작업은 메인 컨텍스트에서 직접 처리하지 말고 서브에이전트에게 위임하세요. 서브에이전트는 독립된 컨텍스트 윈도우를 사용하므로, 메인 세션의 컨텍스트를 깨끗하게 유지할 수 있습니다.

5. 관련 컨텍스트 명령어 비교

명령어 역할 사용 시점

세 명령어를 함께 활용하는 것이 효과적입니다.

# 컨텍스트 확인 → 압축 또는 초기화 결정
/context   → Messages 높음 → /compact
/context   → 전체 사용량 높음, 새 작업 → /clear

6. 마무리

/context는 Claude Code를 잘 쓰기 위한 필수 습관 중 하나입니다.

• 세션을 시작할 때 한 번 확인해서 MCP 오버헤드를 파악하고
• 세션 중간에 주기적으로 확인해서 Messages가 커지는 타이밍을 포착하고
• 압축/초기화 전에 확인해서 어떤 결정을 내릴지 판단하는 용도로 활용해보세요.

긴 코딩 세션일수록, 컨텍스트를 의식적으로 관리하는 것과 그렇지 않은 것의 차이는 크게 벌어집니다.

참고 자료

• Claude Code 공식 문서
• Claude Code CLI Reference

1. 들어가며

Claude Code를 처음 쓰면 이런 상황이 반드시 온다.

"매번 세션 시작할 때마다 프로젝트 구조, 기술 스택, 팀 컨벤션을 다시 설명해야 하나?"

사람으로 치면, 입사할 때마다 온보딩을 새로 받는 것과 같다. 이 문제를 단 한 줄의 명령어로 해결할 수 있다.

바로 /init이다.

이 글은 Claude Code를 실무에 도입했거나 도입을 검토 중인 개발자를 위해, /init의 개념부터 동작 원리, 실전 예시, 커스터마이징까지 한 번에 정리한다.

2. CLAUDE.md란 무엇인가?

/init을 이해하려면 먼저 CLAUDE.md를 알아야 한다.

CLAUDE.md = Claude Code를 위한 프로젝트 온보딩 문서

Claude Code는 세션을 시작할 때 프로젝트 루트의 CLAUDE.md를 자동으로 읽는다. 이 파일이 Claude의 "프로젝트 기억"이 된다.

CLAUDE.md가 없으면 Claude는 매 세션마다 컨벤션을 처음부터 추론해야 한다. 잘 만들어진 CLAUDE.md가 있으면, 이미 프로젝트를 숙지한 상태로 시작한다.

3. /init이란?

/init initializes Claude Code for the current project.
Think of it as: "Claude, understand this repository and set yourself up."
It bootstraps project awareness.

한 마디로, /init은 Claude Code가 현재 프로젝트를 스스로 이해하고 설정하도록 만드는 명령어다.

기술적으로는 Claude Code 인터랙티브 모드의 슬래시 커맨드로, 프로젝트 전체를 자동으로 스캔해서 CLAUDE.md 파일을 생성해준다. 직접 작성하지 않아도 된다.

4. 내부 동작 원리

/init을 실행하면 Claude Code는 다음 단계로 동작한다.

Step 1 — 레포지토리 구조 스캔

디렉토리 트리를 순회하면서 프로젝트 유형을 파악한다. Next.js인지, Spring Boot인지, Python 패키지인지, 모노레포 구조인지.

Step 2 — 설정 파일 분석

주요 설정 파일들을 읽어서 기술 스택과 빌드 정보를 추출한다.

파일 추출 정보

Step 3 — 아키텍처 파악

소스 디렉토리 구조, 핵심 모듈, 엔트리 포인트를 식별한다.

Step 4 — 코딩 스탠다드 감지

ESLint, Prettier, lint-staged, .editorconfig 등의 설정에서 코드 스타일 컨벤션을 추출한다.

Step 5 — 기본 메모리 초기화 & 툴 컨텍스트 준비

CLAUDE.md 생성과 함께 Claude의 도구 사용 컨텍스트도 초기화된다.

Step 6 — CLAUDE.md 생성 (또는 업데이트)

수집한 정보를 구조화된 마크다운으로 정리해 프로젝트 루트에 저장한다.

⚠️ 이미 CLAUDE.md가 존재하면 덮어쓰지 않고 현재 코드베이스를 기준으로 업데이트한다.

5. 실행 방법

방법 1: 인터랙티브 슬래시 커맨드 (가장 일반적)

Claude Code 세션 안에서 입력:

/init

⚠️ claude /init처럼 CLI에서 직접 실행하는 건 불가능하다. 반드시 인터랙티브 세션 안에서 사용해야 한다.

방법 2: CLI 플래그로 시작 시 실행

# 초기화 훅 실행 후 인터랙티브 모드 시작
claude --init

# 초기화만 하고 세션 없이 바로 종료 (CI/CD 활용)
claude --init-only

--init-only는 CI/CD 파이프라인에서 CLAUDE.md만 자동 생성하고 세션을 열지 않을 때 유용하다.

6. 생성되는 CLAUDE.md 구조와 실전 예시

기본 구조

# CLAUDE.md

## Project Overview
프로젝트 개요, 기술 스택, 핵심 기능 설명

## Commands
빌드, 테스트, 린트, 배포 명령어

## Architecture
디렉토리 구조, 핵심 모듈, 데이터 흐름

## Code Style
코딩 컨벤션, 포매터 설정, 네이밍 규칙

## Development Workflow
개발 프로세스, 브랜치 전략, CI/CD

예시 1: Next.js 프로젝트

# CLAUDE.md

## Project Overview
Next.js 15 + TypeScript + Tailwind CSS 기반 웹 애플리케이션 (App Router 사용)

## Commands

| 명령어 | 용도 |
|--------|------|
| `npm run dev` | 개발 서버 시작 |
| `npm run build` | 프로덕션 빌드 |
| `npm run lint` | ESLint 검사 |
| `npm run test` | Jest 테스트 실행 |

## Architecture
- `src/app/` — App Router 페이지 및 레이아웃
- `src/components/` — 재사용 가능한 UI 컴포넌트
- `src/lib/` — 유틸리티 함수 및 공통 로직

## Code Style
- TypeScript strict mode 활성화
- Prettier: 2칸 들여쓰기, 단따옴표
- ESLint: Next.js recommended 규칙 적용

예시 2: 모노레포 (Lerna + Nx)

# CLAUDE.md

## Project Overview
Lerna + Nx + npm workspaces 기반 프론트엔드 모노레포

## Commands

| 명령어 | 용도 |
|--------|------|
| `npm run build` | 전체 패키지 빌드 |
| `npm run test` | 전체 테스트 |
| `npm run lint` | 빌드 → 린트 → 테스트 파이프라인 |

## Monorepo Rules
- 의존성 설치: `npm i <pkg> -w <서브패키지>`
- 스크립트 실행: `npm run <script> -w <서브패키지>`
- 서브패키지 디렉토리에서 직접 install/run 금지

## Packages
- `packages/app` — 메인 웹 앱 (Next.js)
- `packages/ui` — 공유 UI 컴포넌트 라이브러리
- `packages/utils` — 공통 유틸리티 함수

예시 3: Python FastAPI 프로젝트

# CLAUDE.md

## Project Overview
FastAPI + SQLAlchemy + PostgreSQL 기반 REST API

## Commands

| 명령어 | 용도 |
|--------|------|
| `uvicorn app.main:app --reload` | 개발 서버 시작 |
| `pytest` | 테스트 실행 |
| `alembic upgrade head` | DB 마이그레이션 적용 |

## Architecture
- `app/main.py` — 앱 엔트리 포인트
- `app/routers/` — API 라우트 핸들러
- `app/models/` — SQLAlchemy 모델
- `app/schemas/` — Pydantic 스키마
- `alembic/` — DB 마이그레이션

## Code Style
- Black 포매터 (줄 길이 88)
- isort로 import 정렬
- 모든 함수에 타입 힌트 필수

7. CLAUDE.md 계층 구조 활용

Claude Code는 여러 위치의 CLAUDE.md를 동시에 읽고 병합한다. 더 구체적인 파일이 우선순위를 가진다.

~/.claude/CLAUDE.md          ← 개인 설정 (모든 프로젝트 공통)
    ↓
./CLAUDE.md                  ← 프로젝트 루트 (팀 공유, git 커밋)
    ↓
./frontend/CLAUDE.md         ← 서브디렉토리 (모노레포 모듈별)
./backend/CLAUDE.md

개인 설정 활용 예시 (~/.claude/CLAUDE.md)

## Personal Preferences
- 한국어로 응답해줘
- 코드 변경 전 계획을 먼저 설명해줘
- 커밋 메시지는 Conventional Commits 형식 사용
- 테스트 코드 항상 같이 작성해줘

8. /init 이후 — 직접 커스터마이징

자동 생성 파일은 출발점이다. Claude가 코드 분석만으로는 알 수 없는 것들을 직접 추가해야 한다.

추가하면 효과적인 항목들

## Rules (절대 지켜야 할 규칙)
- NEVER delete migration files
- NEVER modify .env files directly
- Always run tests before suggesting a commit
- 외부 API 호출 시 반드시 timeout 설정

## Architecture Decisions (결정 이유)
- App Router 사용 (Pages Router 아님) — SEO 최적화 때문
- Zustand 선택 (Redux 아님) — 번들 사이즈 최소화
- MariaDB — 레거시 시스템과의 호환성

## Known Issues (알려진 이슈)
- Windows에서는 `./gradlew.bat` 사용
- 로컬 개발 시 .env.local 필요 (팀 채널 공유)

## What Claude Should NOT Do
- console.log 대신 alert() 사용 금지
- CSS 모듈 대신 인라인 스타일 사용 금지
- 마이그레이션 파일 자동 생성 금지 (수동 검토 필요)

9. /init vs 수동 작성 비교

항목 /init 자동 생성 수동 작성

결론: /init으로 초안을 만들고, 코드 분석이 잡아내지 못하는 팀 규칙·아키텍처 결정·알려진 이슈를 직접 추가하는 것이 가장 효율적인 방식이다.

10. 언제 /init을 써야 하는가?

상황 활용 방법

11. 중요한 오해 — /init이 하지 않는 것

/init을 처음 접하면 혼동하기 쉬운 부분이 있다.

"초기화"라는 단어 때문에 환경 설정까지 해줄 것 같지만, 절대 아니다.

/init은 다음을 절대 하지 않는다:

• ❌ 의존성 설치 (npm install, pip install)
• ❌ Docker 실행
• ❌ 빌드 실행
• ❌ 배포

/init이 준비하는 것은 인프라가 아니라 컨텍스트다.

Claude가 이 프로젝트를 이해하기 위한 "두뇌 세팅"을 하는 것이지, 실제 환경을 구축하는 것이 아니다.

12. 신버전 대화형 /init (2026)

2026년부터 실험적으로 도입된 새로운 /init은 동작 방식이 완전히 달라졌다.

기존 방식 vs 새로운 방식

기존 /init 새 /init

활성화 방법

CLAUDE_CODE_NEW_INIT=1 claude

새 방식에서 Claude는 AskUserQuestion 도구로 다음을 물어본다:

• 자주 반복하는 작업이 뭔가요? (Skills로 자동화)
• 어떤 실수를 Hooks로 방지하고 싶으신가요?
• 팀의 워크플로우 패턴이 어떻게 되나요?

기존 방식이 "코드를 보고 추론"했다면, 새 방식은 "먼저 물어보고 의도대로 설정"하는 방식이다.

13. 마무리

/init을 한 줄로 요약하면 이렇다.

"Claude, 이 프로젝트를 이해하고 스스로를 세팅해줘."

코드 스캔 → 설정 분석 → 컨벤션 감지 → CLAUDE.md 생성까지, 수동으로 30분 이상 걸리던 작업을 수십 초 안에 처리한다.

핵심 요약:

• /init = 프로젝트 스캔 → CLAUDE.md 자동 생성
• /init은 컨텍스트를 준비하는 것이지, 의존성 설치나 빌드는 하지 않는다
• 자동 생성 후 팀 규칙, 아키텍처 결정, 금지 사항을 직접 추가해야 완성
• git에 커밋해서 팀 전체가 동일한 Claude 경험 공유
• CLAUDE_CODE_NEW_INIT=1으로 2026 대화형 버전 활성화 가능

새 프로젝트를 시작하거나 낯선 코드를 파악해야 할 때, 가장 먼저 해야 할 것은 /init 실행이다.

Claude Code란? — AI가 코드를 직접 짜주는 에이전틱 코딩 도구 완벽 정리

요약: Claude Code는 단순한 코드 자동완성이 아닙니다. 코드베이스 전체를 이해하고, 파일을 직접 수정하고, 테스트까지 돌려주는 에이전틱(agentic) 코딩 시스템입니다.

1. Claude Code란 무엇인가?

Claude Code는 Anthropic이 만든 에이전틱(Agentic) 코딩 시스템입니다.

"에이전틱"이라는 단어가 낯설 수 있는데, 쉽게 말하면 AI가 스스로 판단하고 행동하는 방식을 뜻합니다. 단순히 코드를 제안하는 것을 넘어서, AI가 직접 파일을 열고, 수정하고, 테스트를 돌리고, 실패하면 다시 고치는 일련의 과정을 자율적으로 수행합니다.

개발자는 "이런 기능 만들어줘"라고 목표만 설명하면, Claude Code가 프로젝트 전체를 분석해서 필요한 파일들을 찾아 작업합니다. 결과가 나오면 개발자가 검토하는 방식이죠.

2. 기존 코딩 도구와 무엇이 다른가?

많은 분들이 GitHub Copilot이나 ChatGPT로 코딩 도움을 받아본 경험이 있을 겁니다. Claude Code는 근본적으로 다른 레이어에서 동작합니다.

구분 기존 AI 코딩 도구 Claude Code

한마디로, 기존 도구가 조수(assistant) 라면 Claude Code는 주니어 개발자에 가깝습니다. 설명만 해주면 혼자서 찾아보고 작업합니다.

3. 사용 환경 — 어디서 쓸 수 있나?

Claude Code는 네 가지 환경에서 사용할 수 있습니다.

🖥️ 터미널 (CLI)

가장 강력한 형태입니다. 프로젝트 디렉토리에서 claude를 입력하면 대화 형식으로 작업을 지시할 수 있습니다.

npm install -g @anthropic-ai/claude-code
cd my-project
claude

🧩 VS Code 확장 프로그램

확장 프로그램을 설치하면 에디터 안에서 바로 사용 가능합니다. 인라인 diff 보기, @-파일 멘션, 플랜 검토 기능을 지원합니다. Cursor에서도 동일하게 사용 가능합니다.

💻 데스크탑 앱

Claude 데스크탑 앱의 Code 탭을 통해 사용합니다. 여러 세션을 나란히 실행하거나, diff를 시각적으로 비교하고, 반복 작업을 예약할 수 있습니다. (유료 구독 필요)

🌐 웹 브라우저

claude.ai/code에서 바로 접속하면 됩니다. 로컬에 설치할 필요 없이 브라우저에서 사용하며, 로컬에 없는 저장소에도 작업할 수 있습니다.

4. 핵심 기능 살펴보기

📂 코드베이스 전체 파악

프로젝트를 시작하면 Claude Code는 디렉토리를 탐색하면서 모듈 간 의존 관계를 파악합니다. 새 팀원이 프로젝트에 합류했을 때 수일 걸리던 온보딩을 몇 분 안에 끝낼 수 있습니다.

✏️ 다중 파일 수정

"인증 미들웨어를 JWT 기반으로 바꿔줘"라고 하면, 관련된 모든 파일을 찾아서 일관되게 수정합니다. 대규모 리팩토링 작업에서 특히 위력을 발휘합니다.

🔁 테스트 자동 수정

테스트가 실패하면 오류 내용을 읽고 코드를 고친 뒤 다시 테스트를 돌립니다. 모든 테스트가 통과할 때까지 이 과정을 반복합니다.

🛠️ CLI 도구 자동 실행

git, Kubernetes, Docker 등 CLI 명령어를 자연어로 설명하면 적절한 명령어를 찾아 실행합니다.

"현재 변경사항 스테이징하고 커밋 메시지 작성해서 푸시해줘"
→ git add . && git commit -m "..." && git push 자동 실행

🔗 CI/CD 모니터링

GitHub, GitLab의 CI 파이프라인을 모니터링하다가 빌드가 실패하면 자동으로 수정 커밋을 올릴 수 있습니다.

5. 설치 및 시작 방법

설치 (Node.js 필요)

# npm으로 설치
npm install -g @anthropic-ai/claude-code

# 또는 Homebrew (macOS)
brew install claude-code

# 버전 확인
claude --version

첫 실행

cd your-project
claude

처음 실행 시 로그인을 요청합니다. 브라우저 OAuth 방식과 API 키 방식 두 가지가 있습니다.

# CI/서버 환경에서는 API 키로 인증
export ANTHROPIC_API_KEY="your-api-key"

참고: Claude Pro 이상 구독이 있으면 추가 API 비용 없이 사용 가능합니다.

6. CLAUDE.md — AI에게 프로젝트를 설명하는 파일

프로젝트 루트에 CLAUDE.md 파일을 만들어두면, Claude Code가 세션을 시작할 때 자동으로 읽습니다. AI에게 프로젝트의 컨벤션, 아키텍처, 주의사항을 미리 알려주는 역할입니다.

# 프로젝트 개요
Spring Boot 3.x + React 18 기반 대학 포털 시스템

## 코딩 컨벤션
- Java: Google Style Guide 준수
- React: 함수형 컴포넌트 + Hooks 사용
- 커밋 메시지: [타입] 내용 형식 (feat, fix, docs, refactor)

## 주의사항
- MariaDB 10.6 사용 (MySQL 8.0과 일부 문법 차이 있음)
- 레거시 API와 하위 호환성 유지 필수
- 배포 전 반드시 스테이징 환경 테스트

## 절대 수정 금지 파일
- /legacy/vb6-adapter/* (레거시 연동 모듈)

⚠️ CLAUDE.md는 매 요청마다 삽입되므로 200줄 이내로 간결하게 유지하는 것이 좋습니다.

7. 안전성과 권한 제어

AI가 파일을 마음대로 수정한다고 하면 불안하실 수 있습니다. Claude Code는 이 부분을 꼼꼼하게 설계했습니다.

• 기본값은 신중(Cautious): 파일 수정이나 명령 실행 전 반드시 허가를 구합니다.
• 권한 수준 조절 가능: 모든 액션을 직접 승인하는 방식부터, 내장 분류기가 안전/위험을 자동 판별하는 방식까지 설정 가능합니다.
• 기존 환경 사용: 별도 백엔드 환경이 아닌, 개발자의 로컬 환경과 도구를 그대로 활용합니다.
• 코드 결정권은 사람에게: 어떤 코드를 배포할지 최종 결정은 항상 개발자가 합니다.

8. 2026년 최신 업데이트

2026년 들어 Claude Code는 매우 빠른 속도로 업데이트되고 있습니다.

🔑 주요 변경사항

Opus 4.6 — 100만 토큰 컨텍스트 창 정식 출시 약 75만 단어에 달하는 코드와 컨텍스트를 한 번에 처리할 수 있습니다. 대형 코드베이스 전체를 세션 하나에서 다룰 수 있게 된 셈입니다.

NO_FLICKER 렌더링 엔진 터미널 깜빡임 현상이 해결되어 장시간 작업 시 사용성이 크게 개선되었습니다.

보안 강화 PID 네임스페이스 격리, 자격증명 스크러빙, PowerShell 권한 강화, 명령 주입 취약점 수정이 이루어졌습니다.

팀 협업 기능 /powerup 대화형 튜토리얼과 /team-onboarding 가이드가 추가되어 팀 단위 도입이 쉬워졌습니다.

9. 누구에게 유용한가?

Claude Code는 개발자만을 위한 도구가 아닙니다.

대상 활용 방법

특히 레거시 시스템을 유지보수하면서 신규 개발도 병행해야 하는 상황에서 효율이 크게 올라갑니다.

10. 마무리

Claude Code를 한마디로 정리하면 이렇습니다.

"목표를 설명하면, AI가 코드베이스를 파악하고 직접 구현한다."

기존 AI 코딩 도구가 제안의 영역에 있었다면, Claude Code는 실행의 영역으로 넘어왔습니다. 아직 AI가 모든 판단을 대신할 수는 없지만, 반복적인 구현 작업의 상당 부분을 위임할 수 있다는 점은 분명합니다.

실제 업무에 도입하려면 CLAUDE.md를 잘 작성하고, 권한 설정을 꼼꼼히 확인한 후 조금씩 범위를 넓혀가는 접근을 추천합니다.

참고 자료

• Claude Code 공식 문서
• Claude Code GitHub 릴리스 노트
• claude.ai/code

안녕하세요! 오늘은 AI를 단순한 도구가 아니라, 나를 위해 일하는 '최고의 직원'으로 만드는 비결을 공유하려고 합니다.

최근 유투브 채널 '뉴즈'에서 소개된 김다솔 작가님의 'PRO-MPT' 공식은 프롬프트 작성이 막막했던 분들에게 명확한 가이드라인을 제시해 줍니다. 질문 하나로 100명의 몫을 해낼 수 있는 이 마법 같은 공식을 바로 확인해 보세요!

1. 프롬프트적 사고: AI는 내 '직원'이다

프롬프트적 사고의 핵심은 AI를 검색 엔진이 아닌 '능력 있는 직원'으로 대하는 것입니다. 단순히 단어를 던지는 게 아니라, 구체적인 업무 지시(디렉팅)를 내리고 결과물에 대해 끊임없이 피드백을 주고받는 '티키타카' 과정이 필요합니다.

2. 핵심 중의 핵심, 'PRO' 법칙

이 세 가지만 지켜도 답변의 퀄리티가 180도 달라집니다.

3. 디테일의 완성, 'MPT' 법칙

PRO에 아래 세 가지를 더하면 훨씬 정교한 결과물을 얻을 수 있습니다.

• M (Mode): 출력 형식을 지정합니다. (예: 표, 리스트, PPT 슬라이드 구성 등)
• P (Point of View): 타겟 관점을 설정합니다. (예: 초등학교 2학년 눈높이, 투자자 관점 등)
• T (Tone): 문체와 톤을 결정합니다. (예: 전문적인 명사형 어조, 따뜻한 공감형 어조 등)

4. 실전 사례: "부업 추천" 질문하기

❌ 일반적인 질문: "요즘 할 만한 부업 추천해 줘."

결과: 배달, 블로그 등 누구나 아는 뻔한 답변만 나옵니다.

✅ PRO-MPT를 적용한 질문:

(P) 너는 20년 경력의 수익 창출 전문 컨설턴트야.
(R) 내가 보낸 이력서 PDF를 바탕으로 내 마케팅 경력을 분석해 줘.
(O) 퇴근 후 하루 2시간 투자로 월 100만 원 추가 소득을 낼 수 있는 직장인 맞춤형 플랜을 짜줘.
(M/T) 3개월 치 액션 플랜을 표 형식으로 정리해 주고, 전문가답고 신뢰감 있는 어조로 써줘.

마치며: 인간은 '디렉터'가 되어야 합니다

AI가 업무의 80%를 처리하는 시대에 인간의 가치는 '좋은 질문을 던지고 결과물을 판단하는 20%'에서 나옵니다.

영역의 한계를 허물어주는 AI라는 무기를 장착하고, 여러분도 이제 상위 1%의 디렉터로 거듭나시길 바랍니다!

📌 참고 영상: 뉴즈 - 김다솔 작가님 인터뷰 보기