5강. 컨텍스트 엔지니어링의 전환
0. 학습 목표
→ 3강에서 요청마다 반복해 넣어야 했던 파일명과 조건을, CLAUDE.md 파일 하나로 줄이는 법을 익힙니다.
0.1 이번 글에서 다룰 내용
이번 글은 실습 중심 강의입니다.
3강에서 기존 파일을 고칠 때는 대상 파일·바꿀 지점·원하는 동작·유지할 것 네 가지를 요청문에 담아야 한다고 배웠습니다. 그런데 이걸 요청마다 매번 반복하려니 번거로웠습니다.
"또 inventory.py에서, 또 함수 구조는 유지하고…"를 매번 쓰는 셈이니까요.
이번 강의는 그 반복을 CLAUDE.md 파일 하나로 덜어내는 법을 다룹니다.
이것은 Claude.ai에서 배운 컨텍스트 엔지니어링의 Claude Code 버전입니다.
Claude.ai가 대화에 참고 자료를 넣는 것이었다면,
Claude Code에서는 프로젝트 폴더 자체가 컨텍스트가 되고, 그 폴더의 규칙을 적어두는 문서가 CLAUDE.md입니다.
0.2 이번 강의 실습 내용
이번 강의에서 직접 해보는 것은 다음과 같습니다.
/init으로 CLAUDE.md 초안 만들기- Claude Code에 요청해 초안에 규칙 두 가지를 덧붙이고
cat CLAUDE.md로 확인하기 - 파일명 없이 짧게 요청해, 규칙이 자동 반영되고 CLAUDE.md 자체는 그대로인지 확인하기
| 구분 | 내용 |
| 재사용할 것 | Claude.ai의 컨텍스트 엔지니어링, 3강의 요청문 네 가지 요소 |
| 새로 익힐 것 | /init으로 CLAUDE.md 초안 만들기, 규칙을 덧붙여 짧은 요청에 자동 반영시키기 |
1. 3강에서 반복했던 것
→ 요청마다 파일명과 조건을 반복해야 했던 번거로움을 되짚고, Claude.ai의 해법과 연결합니다.
3강에서 구체적인 요청을 만들 때, 우리는 "inventory.py 파일에서 재고 수량이 5개 미만이면… 기존 함수 구조는 그대로 유지해줘"처럼 대상 파일과 조건을 요청문에 직접 담았습니다.
결과는 정확했지만, 요청을 넣을 때마다 같은 파일명과 같은 조건을 반복해서 쓰는 것이 번거로웠습니다.
만약 이 프로젝트에 "출력할 때는 항상 로그를 남긴다" 같은 규칙이 더 있었다면, 그것마저 매번 붙여야 했을 것입니다.
Claude.ai에서 이 반복 문제를 어떻게 풀었는지 떠올려봅니다.
자주 쓰는 요소를 Instructions에 등록해두면 매번 설명하지 않아도 됐습니다.
Claude Code에도 같은 발상의 해법이 있습니다.
프로젝트에 한 번 적어두면, 이후 요청마다 자동으로 참고되는 문서를 두는 것입니다.
2. 컨텍스트가 프로젝트 폴더 자체가 되다
→ Claude.ai의 컨텍스트 개념이 Claude Code에서 어떻게 확장되는지 비교합니다.
Claude.ai에서 컨텍스트 엔지니어링은 "이번 대화에서 무엇을 참고 자료로 넣을지"를 다루는 일이었습니다.
Claude Code에서는 대화가 아니라 프로젝트 폴더 전체가 컨텍스트의 기본 단위입니다.
그리고 그 폴더의 배경과 규칙을 적어두는 문서가 CLAUDE.md입니다.
| 구분 | Claude.ai | Claude Code |
| 컨텍스트 | 대화창 안의 첨부 파일이나 이전 대화 | 프로젝트 폴더 안의 모든 파일 |
| 반복 설명 해결 | Instructions | CLAUDE.md |
| 적용 범위 | 계정 전체 | 해당 프로젝트 폴더 안 |
Instructions와 CLAUDE.md는 "반복 설명을 줄인다"는 목적은 같지만 적용 범위가 다릅니다.
하나는 계정 전체에 늘 적용되고, 다른 하나는 특정 프로젝트에서만 적용됩니다.
3. CLAUDE.md 만들고 규칙 덧붙이기
→ /init으로 초안을 만든 뒤 규칙을 덧붙이고, 그 내용을 화면에 띄워 기준으로 삼습니다.
3.1 /init으로 초안 만들기
CLAUDE.md는 프로젝트 폴더 맨 위에 두는 파일로, 직접 손으로 작성할 수도 있지만 Claude Code에는 초안을 자동으로 만들어주는 전용 명령 /init이 있습니다. 3강에서 쓰던 폴더에서 Claude Code를 실행한 뒤 /init을 입력하면, 폴더 구조를 스캔해 CLAUDE.md 초안을 만들어줍니다.
cd ~/inventory-project
claude
/init
여기서 두 가지를 미리 알아두면 당황하지 않습니다.
첫째, /init이 만드는 초안은 대개 영어로, 프로젝트 구조 설명 위주로 채워집니다.
우리가 원하는 코딩 규칙까지 알아서 넣어주지는 않습니다. 영어로 나와도 정상이니 그대로 두면 됩니다.
둘째, 그래서 이 초안은 완성본이 아니라 출발점입니다.
다음 단계에서 우리가 필요한 규칙을 덧붙여야 비로소 이번 실습에 쓸 CLAUDE.md가 됩니다.
3.2 규칙 덧붙이고 내용 확정하기
초안에 이번 실습에서 확인할 규칙 두 가지를 덧붙입니다. 파일을 직접 편집기로 열지 않고, 지금까지 해온 것처럼 Claude Code에 자연어로 요청하면 됩니다. 규칙은 한국어로 덧붙여도 문제없습니다.
CLAUDE.md에 아래 두 규칙을 코딩 규칙 항목으로 추가해줘.
- 주요 파일은 inventory.py이다.
- 함수 이름은 동사로 시작한다. (예: add_item, remove_item)
승인 후, 지금 CLAUDE.md에 어떤 규칙이 적혀 있는지 화면에 띄워 눈으로 확인해둡니다.
이 내용이 곧 뒤에서 결과를 대조할 기준이 됩니다.
cat CLAUDE.md
/init이 만든 영문 프로젝트 설명 아래에, 방금 덧붙인 두 규칙이 다음과 같이 들어가 있으면 됩니다.
## 코딩 규칙 (직접 추가)
- 주요 파일은 inventory.py이다.
- 함수 이름은 동사로 시작한다. (예: add_item, remove_item)💡 팁: /init이 만든 초안에는 필요 없는 설명이 섞여 있을 수 있습니다. 지금은 지우지 않고 규칙만 덧붙여도 실습에는 충분합니다. CLAUDE.md의 자동 인식 규칙과 세부 문법은 버전에 따라 달라질 수 있으니, 정확한 동작이 궁금하면 공식 문서(code.claude.com)에서 최신 내용을 확인하세요.
4. 실습 — 짧은 요청으로 규칙이 반영되는지 대조하기
→ 파일명을 밝히지 않고 짧게 요청해, 3강 방식과 결과를 비교합니다.
이제 규칙이 눈앞에 있으니, 파일명을 밝히지 않고 짧게 요청해 이 규칙이 실제로 지켜지는지 대조합니다.
재고 삭제 기능 추가해줘.
여기서 헷갈리지 말아야 할 것이 하나 있습니다. 이 요청으로 바뀌는 파일은 CLAUDE.md가 아니라 inventory.py입니다. CLAUDE.md는 수정되는 대상이 아니라, Claude Code가 작업 전에 자동으로 읽는 참고 문서입니다.
3.2에서 확인한 그 내용 그대로 읽히기만 하고, 한 글자도 바뀌지 않습니다.
(3.2에서 규칙을 덧붙일 때만 CLAUDE.md가 바뀌었고, 지금 이 요청은 CLAUDE.md를 읽기만 합니다.)
같은 작업을 3강 방식과 나란히 놓으면 무엇이 달라졌는지 분명해집니다.
| 구분 | 3강 (CLAUDE.md 없을 때) | 5강 (CLAUDE.md 있을 때) |
| 요청문 | 대상 파일·기준·유지 조건을 매번 담은 긴 문장 | "재고 삭제 기능 추가해줘" (짧음) |
| 대상 파일 | 요청문에 직접 명시 | CLAUDE.md의 "주요 파일은 inventory.py"를 읽고 스스로 찾아감 |
| 규칙 적용 | 매번 요청문에 담아야 함 | "함수 이름은 동사로 시작" 규칙이 자동 적용 → delete_item()처럼 생성 |
▶ 지금 해보세요
- 위의 짧은 요청을 입력하고, 승인 화면에서 어느 파일이 바뀌는지 확인합니다. (inventory.py여야 정상입니다.)
- 승인 후
cat inventory.py로 새로 생긴 함수 이름을 봅니다. 요청하지 않았는데도 동사로 시작하는지 확인합니다. cat CLAUDE.md를 다시 실행해, 3.2에서 본 내용과 한 글자도 다르지 않은지 대조합니다. 읽히기만 했고 수정되지 않았음을 눈으로 확인합니다.
✔ 확인 기준: 짧은 요청 하나로 (1) 대상 파일을 스스로 찾아가고 (2) CLAUDE.md의 규칙대로 함수가 만들어지며 (3) CLAUDE.md 자체는 그대로라는 세 가지를 대조로 확인하면 완료입니다.
→ 다음 강의 (6강): Claude Code가 파일을 직접 고치다 보면 되돌리고 싶을 때가 생깁니다. v1/v2 백업 폴더 방식으로 "되돌리기" 감각을 익힙니다.