컨텍스트 엔지니어링
“매번 설명하지 않아도 되게”
02이 차시를 마치면
- 1.CLAUDE.md 같은 규칙 파일이 프로젝트 안에서 어떤 계층 구조로 읽히는지 설명할 수 있다.
- 2.지켜지는 규칙과 무시되는 규칙의 차이를 문장 수준에서 구별할 수 있다.
- 3.자신의 프로젝트에 규칙 파일을 작성하고, 실제로 지켜지는지 테스트로 검증할 수 있다.
- 4.긴 세션에서 맥락을 잃지 않도록 체크포인트를 남기는 습관을 만들 수 있다.
03왜 필요한가
지난 차시에서 진단 리포트를 써보니, 프로젝트에서 맥락 유실 사례가 실제로 있었다는 걸 확인했다고 하자. 예를 들어 '입력 폼 에러 메시지는 항상 존댓말로 쓴다'는 규칙을 초반에 말해뒀는데, 세션을 새로 열고 다른 화면을 추가해달라고 하니 반말 에러 메시지가 섞여 나왔다. 매번 새 대화를 시작할 때마다 프로젝트 규칙, 폴더 구조, 하지 말아야 할 것들을 처음부터 다시 설명하고 있다면, 그 설명 자체가 실습 시간의 상당 부분을 차지하게 된다.
- 새 세션을 열 때마다 같은 규칙을 처음부터 다시 타이핑하느라 실습 시간이 줄어든다.
- 규칙을 어딘가에 적어두긴 했는데, AI가 그 파일을 읽는지 안 읽는지 확인할 방법이 없어 불안하다.
- 규칙을 여러 개 늘어놓다 보면 서로 충돌하거나 너무 길어져 오히려 안 지켜지는 규칙이 생긴다.
- 긴 작업 세션 도중에 대화가 길어지면 초반 규칙이 흐려지는데, 언제 새로 시작해야 할지 판단 기준이 없다.
04개념 설명
규칙 파일의 계층 — CLAUDE.md와 그 아래
Claude Code는 프로젝트 루트의 CLAUDE.md(또는 AGENTS.md)를 세션 시작 시 자동으로 읽어들인다. 이 파일이 프로젝트 전체에 적용되는 '가장 넓은 규칙'이다. 그 아래, 특정 폴더 안에 별도 규칙 파일을 두면 그 폴더에서 작업할 때만 적용되는 '좁은 규칙'을 얹을 수 있다. 예를 들어 프로젝트 전체 규칙은 '커밋 메시지는 한글로 쓴다'처럼 넓게, /api 폴더의 규칙은 '이 폴더의 함수는 반드시 에러를 try/catch로 감싼다'처럼 좁게 둘 수 있다.
계층을 나누는 이유는 규칙 파일이 길어질수록 AI가 그 안에서 지금 작업과 관련된 규칙을 골라내기 어려워지기 때문이다. 관련 없는 규칙까지 매번 다 읽게 하는 것보다, 필요한 폴더에서 필요한 규칙만 보게 하는 편이 더 잘 지켜진다.
| 위치 | 적용 범위 |
|---|---|
| 프로젝트 루트 CLAUDE.md | 전역 규칙 (넓게) |
| 하위 폴더 규칙 파일 | 그 폴더 안에서만 (좁게) |
- 프로젝트 루트 CLAUDE.md = 전역 규칙
- 하위 폴더 규칙 파일 = 그 폴더 안에서만 적용되는 규칙
- 규칙은 넓은 데서 좁은 데로 내려갈수록 구체적이어야 한다
지켜지는 규칙 vs 무시되는 규칙
같은 내용이라도 문장 방식에 따라 지켜지는 정도가 달라진다. '깔끔한 코드를 작성해줘'처럼 추상적인 규칙은 AI가 매번 다르게 해석한다. 반면 '함수 하나는 40줄을 넘기지 않는다. 넘으면 나눠서 제안한다'처럼 구체적이고 확인 가능한 규칙은 지켜졌는지 아닌지를 눈으로 바로 판단할 수 있다.
규칙이 지켜지는지는 말로 짐작하지 않고 실제로 테스트해서 확인한다. 규칙을 적어둔 뒤 그 규칙을 어길 만한 상황을 일부러 만들어 AI에게 요청해보고, 결과가 규칙을 지켰는지 확인하는 것이 유일하게 믿을 수 있는 검증 방법이다.
"깔끔한 코드를 작성해줘"
AI가 매번 다르게 해석한다
"함수는 40줄을 넘기지 않는다"
지켜졌는지 눈으로 바로 판단할 수 있다
- 추상적 규칙('깔끔하게')은 해석이 갈려 지켜지기 어렵다
- 구체적이고 확인 가능한 규칙('40줄 이내')은 위반 여부를 바로 판단할 수 있다
- 규칙은 적어두는 것으로 끝나지 않는다 — 지켜지는지 테스트해야 한다
긴 세션 관리와 체크포인트
대화가 길어질수록 컨텍스트 예산이 소진된다(01차시). 이를 막는 방법은 세션을 무한히 이어가지 않고, 의미 있는 지점마다 체크포인트를 남기는 것이다. 체크포인트란 지금까지의 작업 상태를 커밋하거나 요약 문서로 남겨, 다음 세션(또는 다른 사람)이 그 지점부터 이어갈 수 있게 하는 지점이다.
실무에서는 기능 하나가 끝날 때마다 커밋하고, 세션이 지나치게 길어졌다 싶으면(예: 체감상 응답이 느려지거나 이전 지시를 놓치기 시작하면) 지금까지의 결정 사항을 규칙 파일이나 별도 메모에 반영한 뒤 새 세션을 시작하는 방식을 쓴다. 새 세션은 텅 빈 상태가 아니라 규칙 파일을 통해 이전 세션의 핵심을 이어받는다.
- 체크포인트 = 커밋 + 요약, 다음 세션이 이어받을 수 있는 지점
- 세션이 길어져 지시를 놓치기 시작하면 요약 후 새 세션으로 넘어간다
- 규칙 파일은 세션 간 기억을 이어주는 다리 역할을 한다
좋은 규칙 파일의 형태
규칙 파일은 산문이 아니라 체크리스트에 가깝게 쓴다. 짧고 명령형인 문장을 불릿으로 나열하면 AI가 검색하고 참조하기 쉽다. 각 규칙은 가능하면 '왜 그런지'보다 '무엇을 해야 하는지·하지 말아야 하는지'를 앞세운다 — 이유는 필요할 때만 짧게 덧붙인다.
그리고 규칙 파일은 한 번 쓰고 끝나는 문서가 아니다. 규칙이 지켜지지 않는 걸 발견할 때마다 그 규칙을 더 구체적인 문장으로 고쳐 쓰는 반복 작업이 이번 차시 실습의 핵심이다.
산문 · '왜' 위주 설명
AI가 검색·참조하기 어렵다
명령형 불릿 · '무엇을' 먼저
이유는 필요할 때만 짧게 덧붙인다
- 산문 대신 명령형 불릿 목록
- '왜'보다 '무엇을' 먼저, 이유는 짧게
- 규칙은 안 지켜질 때마다 더 구체적으로 다시 쓴다
05실습 가이드
1. 진단 리포트에서 규칙 후보 뽑기
- 01차시에서 작성한 진단 리포트를 다시 열어, 맥락 유실 사례에 등장했던 규칙(또는 앞으로 지키고 싶은 규칙) 3~5개를 목록으로 뽑는다.
- 각 규칙을 최대한 구체적인 문장으로 다시 써본다(예: '예쁘게' → '버튼은 항상 모서리가 둥근 파란색 배경, 흰 글씨를 쓴다').
예상 결과 — 구체적인 문장으로 다듬어진 규칙 후보 3~5개 목록이 만들어진다.
안 될 때 — 진단 리포트에 규칙 유실 사례가 없었다면, 지금까지 작업하며 반복해서 AI에게 알려줘야 했던 것(디자인 원칙, 금지 라이브러리, 코딩 스타일 등)을 떠올려 목록으로 대신한다.
2. CLAUDE.md 작성하기
- P2-1 프롬프트로 AI에게 프로젝트 루트에 CLAUDE.md(또는 AGENTS.md) 파일 작성을 요청하며, 1단계에서 뽑은 규칙 목록을 전달한다.
- 생성된 파일을 열어 불릿 형태로 명확하게 적혔는지 확인한다.
예상 결과 — 프로젝트 루트에 규칙이 불릿 목록 형태로 정리된 CLAUDE.md 파일이 생긴다.
안 될 때 — 문장이 여전히 추상적이면('좋은 코드를 짜라') 그 문장만 콕 짚어 더 구체적으로 다시 써달라고 요청한다.
3. 폴더별 규칙 나누기 (필요한 경우)
- 프로젝트 구조를 살펴보고, 특정 폴더(예: /api, /components)에만 적용돼야 하는 규칙이 있는지 확인한다.
- 있다면 P2-2 프롬프트로 해당 폴더 안에 별도 규칙 파일을 만들도록 요청한다.
예상 결과 — 전역 규칙과 폴더별 규칙이 계층적으로 분리된 구조가 만들어진다.
안 될 때 — 프로젝트가 아직 작아서 폴더별 규칙이 필요 없다면 이 단계는 건너뛰고 전역 규칙만으로 진행해도 된다.
4. 규칙이 지켜지는지 첫 테스트
- 새 대화(세션)를 하나 연다 — 방금 만든 규칙 파일을 다시 언급하지 않는다.
- 규칙 중 하나를 어길 만한 상황을 만드는 기능 요청을 P2-3 프롬프트로 던진다.
- 결과 코드·화면이 규칙을 지켰는지 눈으로 확인한다.
예상 결과 — 규칙 파일만으로 규칙이 지켜지는지 여부(지켜짐/안 지켜짐)를 확인한다.
안 될 때 — 새 세션에서도 규칙 파일이 자동으로 안 읽히는 것 같으면, 파일명과 위치(프로젝트 루트, 정확한 파일명)가 맞는지 다시 확인한다.
5. 무시된 규칙 재작성하기
- 4단계에서 지켜지지 않은 규칙이 있다면 P2-4 프롬프트로 그 규칙만 더 구체적인 문장으로 다시 써달라고 요청한다.
- 재작성된 문장으로 규칙 파일을 갱신한다.
예상 결과 — 추상적이던 규칙이 확인 가능한 구체적 문장으로 바뀐다.
안 될 때 — 재작성해도 계속 안 지켜지면, 규칙 하나에 여러 요구가 섞여 있지 않은지 의심하고 문장을 둘로 쪼갠다.
6. 재검증 반복하기
- 4~5단계를 규칙 목록 전체에 대해 반복한다 — 새 세션을 열고, 지켜지는지 테스트하고, 안 지켜지면 다시 쓴다.
- 모든 규칙이 최소 한 번씩 통과할 때까지 반복한다.
예상 결과 — 목록에 있는 모든 규칙이 새 세션·무언급 상태에서도 지켜지는 것을 확인한다.
안 될 때 — 시간 안에 다 못 끝내면 가장 자주 위반됐던 규칙 2~3개만이라도 통과시키고 나머지는 과제로 이어간다.
7. 체크포인트 습관 만들기
- 지금까지의 규칙 파일 작업을 git commit으로 체크포인트를 남긴다.
- P2-5 프롬프트로 AI에게 '지금 세션에서 결정한 내용'을 요약받아 규칙 파일이나 별도 메모(예: SESSION-NOTES.md)에 추가한다.
예상 결과 — 규칙 세트가 커밋되고, 이번 세션의 결정 사항이 별도로 기록된다.
안 될 때 — 요약이 너무 장황하면 '규칙으로 남길 것만 3줄로 추려줘'라고 다시 요청한다.
06실전 프롬프트
07이것만은 주의
무슨 일이 생기나 — 규칙을 계속 추가하다 보면 파일이 수십 줄로 늘어나고, 오히려 뒤쪽 규칙일수록 무시되는 경향이 생긴다.
대처 — 정말 자주 어겨지는 핵심 규칙만 전역에 남기고, 나머지는 폴더별 규칙이나 스펙 문서(다음 차시)로 분산한다.
무슨 일이 생기나 — 규칙 파일을 만든 것만으로 문제가 해결됐다고 여기고 넘어가면, 실제로는 안 지켜지는 규칙을 몇 주 뒤에나 발견하게 된다.
대처 — 규칙을 추가할 때마다 그 자리에서 최소 한 번은 어길 만한 상황을 만들어 테스트한다.
무슨 일이 생기나 — API 키나 내부 URL 같은 민감한 정보를 규칙 파일에 예시로 적어뒀다가 그대로 커밋해 저장소에 남긴다.
대처 — 규칙 파일에는 '어떻게 다뤄야 하는지'만 적고 실제 값은 절대 적지 않는다. 환경변수 이름 정도만 예로 든다.
무슨 일이 생기나 — 한 세션에서 몇 시간씩 계속 요청을 이어가면 컨텍스트가 소진되어 앞서 정한 규칙과 결정이 흐려지기 시작한다.
대처 — 기능 하나가 끝날 때마다 커밋하고, 세션이 길어졌다 싶으면 결정 사항을 규칙 파일·메모에 반영한 뒤 새 세션으로 넘어간다.
08자가 점검
09과제
자신의 프로젝트에 있는 CLAUDE.md(또는 규칙 파일 세트)를 동료나 스터디원에게 공유해, 그 사람이 프로젝트를 전혀 모르는 상태에서 규칙 파일만 읽고 새 세션으로 작업을 하나 시켜보게 한다. 결과가 규칙을 지켰는지 함께 확인하고 안 지켜진 부분을 다시 구체화한다. 동료가 없다면 새 채팅 세션을 '동료' 삼아 같은 방식으로 진행해도 된다.
제출 형식 — 최종 규칙 파일(CLAUDE.md 등) 전문과, 검증 과정에서 재작성한 규칙의 전/후 문장 비교표를 제출한다.
10더 알아보기
- Claude Code 공식 문서 — 프로젝트 메모리와 CLAUDE.md — 규칙 파일이 실제로 어느 시점에 읽히는지 정확한 동작 확인용
- 01차시 진단 리포트 — 이번 차시 규칙 목록의 출발점으로 다시 참고
- CLAUDE.md
- — Claude Code가 세션 시작 시 자동으로 읽어들이는 프로젝트 규칙 파일. 프로젝트 루트에 두면 전역 규칙으로 적용된다.
- 체크포인트(Checkpoint)
- — 작업 상태를 커밋이나 요약으로 남겨, 이후 세션이나 다른 사람이 그 지점부터 이어갈 수 있게 하는 지점.
- 규칙 계층(Rule Hierarchy)
- — 전역 규칙 파일과 폴더별 규칙 파일처럼, 적용 범위가 넓은 규칙에서 좁은 규칙으로 내려가는 구조.
다음 차시 예고 — 다음 차시(스펙 기반 개발)에서는 규칙만으로는 담기 어려운 '이번 기능이 무엇을 해야 완료된 것인지'를 스펙과 완료 조건으로 미리 합의하는 법을 다룹니다.