컨텍스트 엔지니어링 입문 — 프롬프트 다음에 오는 AI 활용의 새 패러다임

같은 LLM에 같은 질문을 던져도 돌아오는 답변의 질이 완전히 다른 경험, 해보신 적 없나요?

저는 AI 에이전트 환경을 1년 정도 개인적으로 운영해 오면서, 정확도를 좌우하는 것은 프롬프트의 표현 방식이 아니라 그 모델이 무엇을 보고 있는가, 즉 "컨텍스트의 설계"라고 확신하게 됐어요. 프롬프트를 아무리 다듬어도 제자리걸음이던 작업이, 넘겨주는 정보의 구조를 바꾸는 순간 안정됩니다. 이 "전달 방식의 설계"가 바로 요즘 화제인 컨텍스트 엔지니어링이에요.

이 글에서는 유행어 풀이로 끝내지 않고, CLAUDE.md·인수인계 메모·지식 검색 같은 구체적인 방법과, 실제로 효과를 본 수치를 함께 공유할게요.

프롬프트 엔지니어링과의 차이를 한 장으로

먼저 두 기술의 역할 분담부터 정리할게요. 서로 대립하는 게 아니라 레이어가 다르다고 보는 쪽이 실제 체감에 가깝습니다.

프롬프트는 "한 번의 대화"를 좋게 만드는 기술이고, 컨텍스트 엔지니어링은 "매번 대화의 전제"를 설계하는 기술입니다. AI를 꾸준히 쓸수록 후자의 투자 대비 효과가 확 커져요.

컨텍스트를 구성하는 4레이어 (치트시트)

제가 실제로 운영하는 컨텍스트는 크게 4개 층으로 나뉩니다. 먼저 요약표부터 볼게요.

"전부를 매번 넘긴다"가 아니라, ①은 상시·②는 시작할 때·③은 필요할 때·④는 그때그때로 넘기는 양과 타이밍을 나누는 게 포인트예요. 아래에서 레이어별로 구현 방법과 수치를 살펴보겠습니다.

① 영속 컨텍스트: 전제를 "인수인계서"로 만든다

가장 먼저 손대야 할 것은, 매번 똑같이 반복하는 전제 설명을 파일로 빼내는 일입니다.

새 프로젝트에 AI를 도입했던 초기에 저는 기술 스택이나 디렉터리 구성, 금지 사항을 매 세션 말로 설명하느라 한 번에 5~10분을 날리고 있었어요. 그래서 프로젝트 루트에 약 200줄짜리 규칙 파일(CLAUDE.md)을 두고 "AI에게 주는 인수인계서"로 다시 썼더니, 세션 시작 때의 전제 설명이 통째로 필요 없어져 하루에 약 30분이 절약됐습니다. 덤으로 생성 코드의 일관성도 눈에 띄게 좋아졌고요.

# CLAUDE.md (영속 컨텍스트의 뼈대)

## 기술 스택
- 언어 / 프레임워크 / DB / 인프라 …

## 코딩 규약
- 네이밍·테스트 방침·에러 핸들링의 틀

## 금지 사항 (IMPORTANT)
- 프로덕션을 직접 건드리지 않는다 / 파괴적 명령은 확인을 거친다 …

요령은 신입 엔지니어에게 주는 인수인계 문서를 쓴다는 감각으로 쓰는 것. "말 안 해도 알겠지" 싶은 것까지 전부 글로 풀어내면 정확도가 올라갑니다.

[역주 — 참고] Claude Code는 프로젝트 루트뿐 아니라 서브 디렉터리에 둔 CLAUDE.md도 함께 읽는 계층 구조를 공식 지원합니다. Cursor, Zed 등 다른 AI 코딩 도구에서는 AGENTS.md 같은 대응 파일에 같은 개념이 적용됩니다.

실패담: 비대해져서 오히려 느려졌다

다만 이 파일, 그냥 두면 계속 불어납니다. 저도 한 번 500줄을 넘겨 버렸는데, 응답이 느려지고 지시의 우선순위도 흐릿해져서 규약 위반이 늘었어요. 해결책은 계층화였습니다. 루트에는 방침만 남기고 세부 사항은 서브 디렉터리 쪽 파일로 나눈 다음, 우선순위 높은 제약은 맨 앞에 IMPORTANT로 올렸습니다. 그 결과 체감 응답 속도가 1.5배로 돌아왔고 규약 준수율도 개선됐어요. 영속 컨텍스트는 "많이 쓰기"보다 "구조화해서 줄이기"가 정답입니다.

② 작업 기억: 세션의 기억을 파일로 옮겨 둔다

LLM은 대화가 끊기면 맥락을 잃습니다. 저도 예전에는 작업을 재개할 때마다 "지난번에 어디까지 했더라?"를 다시 설명하고 있었죠.

그래서 세션이 끝날 때 진행 중 작업·보류 사항·다음 액션·결정 사항을 구조화한 인수인계 메모(handoff.md)를 자동 생성하는 방식으로 바꿨습니다. 다음번에는 이 파일만 읽으면 맥락 복원이 약 5초 만에 끝나요. "기억"을 모델 안에 붙잡아 두려 하지 말고 파일 시스템으로 빼두는 것, 이게 현실적인 해법이었습니다.

# handoff.md (작업 기억 템플릿)
## 진행 중
- [ ] ○○ 구현 (남은 것: 밸리데이션)
## 보류·판단 대기
- △△ 사양, 확인 필요
## 다음 액션
1. …
## 최근 결정 사항
- □□ 방식 채택 (이유: …)

구조를 고정해 두면 복원 정확도가 안정됩니다. 포맷이 매번 들쭉날쭉하면 AI가 읽어내는 것도 흔들려요.

③ 참조 지식: 필요할 때만 꺼낸다 (전부 넘기지 않는다)

컨텍스트는 "많을수록 좋다"가 아닙니다. 오히려 불필요한 정보는 노이즈이자 비용이라는 게 실제 운영에서 얻은 교훈이에요.

400페이지가 넘는 지식이 사내 위키 곳곳에 흩어져 있던 프로젝트에서는, 필요한 정보를 찾는 데 매번 15분 이상 걸렸습니다. 이걸 전 페이지 Markdown으로 변환해 벡터 DB에 넣고, 질문할 때 관련 청크만 검색해서 넘기는 RAG 구성으로 바꿨더니 검색이 15분에서 약 10초로 줄었어요. 청크 크기는 500~1000토큰 정도가 실용적인 타협점이었습니다.

포인트는 "모든 지식을 매번 컨텍스트에 싣는다"가 아니라, 그 질문과 관련된 조각만 그때그때 꺼내는 것. 컨텍스트 윈도우는 유한하고, 채워 넣을수록 주의가 분산되며 비용도 올라갑니다. "무엇을 넘길까"의 설계가 90%라는 말, 체감상 그대로였어요.

④ 동적 컨텍스트: 출력의 "틀"을 먼저 보여준다

마지막은 작업마다 확정하는 컨텍스트입니다. 여기서 프롬프트 엔지니어링의 기법(Few-shot)이 힘을 발휘해요.

AI에게 코드 리뷰를 맡기던 시절, 사소한 스타일 지적과 중대한 버그 지적이 같은 수준으로 뒤섞여 Critical을 놓칠 뻔한 적이 있습니다. 그래서 의뢰문에 중요도(Critical / Warning / Info) 분류 기준을 Few-shot 예시 3가지 패턴으로 첨부했어요. 그러자 출력이 중요도 순으로 정리되면서 확인 시간이 절반으로 줄었습니다.

# 출력 예시 (이 틀로 답해 줘)
[Critical] SQL 인젝션 가능성: user 입력을 쿼리에 직접 연결
[Warning]  N+1 쿼리: 루프 안의 findById 재검토
[Info]     네이밍: getData → fetchUserOrders 쪽이 의도가 명확

규칙을 긴 글로 설명하기보다 기대하는 출력을 3개 보여주는 쪽이 확실하게 먹힙니다. "틀을 먼저 보여준다" — 이것도 어엿한 컨텍스트 설계예요.

또 하나의 효용: 혼자서도 "벽치기 상대"가 생긴다

컨텍스트를 갖춰 두면 리뷰어가 없는 환경에서도 AI를 시니어 역할의 벽치기 상대, 그러니까 스파링 파트너로 쓸 수 있습니다. 설계서를 AI에게 읽게 하고 "경력 20년 아키텍트로서 문제점을 지적해 줘"라고 비기능 요건 관점까지 지정해서 요청했더니, 5개의 개선 제안 중 2개는 프로덕션 운영에서 실제로 문제가 될 수 있는 중대한 설계 누락이었어요. 역할(누구로서)과 참조(무엇을 보고)라는 컨텍스트를 맞춰 주면 벽치기의 질이 한 단계 올라갑니다.

정리: 프롬프트를 다듬기 전에 환경을 설계한다

컨텍스트 엔지니어링을 한마디로 하면 **"AI에게 무엇을 보여줄지를 설계하는 기술"**입니다. 오늘부터 시작할 수 있는 순서로 정리해 볼게요.

1. ① 영속화 — 매번 설명하는 전제를 CLAUDE.md로 옮긴다 (단, 비대해지지 않게 구조화해서 줄인다)
2. ② 외부화 — 세션의 기억을 handoff.md에 기록해 둔다
3. ③ 검색화 — 지식은 전부 넘기지 말고 필요한 조각만 꺼낸다
4. ④ 틀 제시 — 기대하는 출력 형태를 Few-shot으로 먼저 보여준다

프롬프트 문구를 고민하기 전에, 먼저 모델이 놓여 있는 "정보 환경"부터 의심해 보세요. 많은 경우 개선 여지는 지시문 바깥에 있습니다.

여기까지 읽어 주셔서 감사합니다. 도움이 되셨다면 좋아요를 눌러 주시면 큰 힘이 됩니다.

Claude Code·AI 에이전트·업무 자동화 구현 팁을 꾸준히 올리고 있습니다. 팔로우하시면 새 글 소식을 받아보실 수 있습니다.

여러분은 AI에게 넘기는 "컨텍스트"에서 가장 효과를 본 방법이 무엇이었나요? 댓글로 알려 주세요.