context-engineering은 추상적인 프롬프트 기법이 아니라, 에이전트가 매 턴 무엇을 볼지 결정하는 코드베이스 운영 문제다. Real Python의 Python 코드베이스 가이드는 이를 Curate, Distill, Delegate, Externalize 네 가지 전략으로 정리한다.

1. Curate: 들어갈 컨텍스트를 고른다

에이전트에게 저장소 전체를 무작정 읽히면 오래된 코드, 무관한 테스트, 빌드 산출물이 신호를 흐린다. Python 프로젝트에서는 다음을 우선 고정한다.

• AGENTS.md 또는 CLAUDE.md에 패키지 매니저, 테스트 명령, 스타일 규칙을 기록
• pyproject.toml, uv.lock, requirements.txt처럼 환경을 결정하는 파일을 먼저 읽힘
• 작업 대상 모듈과 그 테스트 파일을 함께 제공
• 대형 로그와 생성 파일은 기본 컨텍스트에서 제외

2. Distill: 이미 들어온 정보를 줄인다

긴 디버깅 세션에서는 실패한 시도, 중복 로그, 오래된 가설이 계속 남는다. 이때는 대화 이력을 그대로 유지하기보다 “현재 사실”만 남겨야 한다.

현재 목표:
- failing test: tests/test_parser.py::test_nested_case
- 수정 대상: src/parser/core.py
- 이미 배제한 원인: tokenizer regex, fixture path
- 다음 검증: uv run pytest tests/test_parser.py::test_nested_case

이런 상태 요약은 긴 대화보다 더 안정적으로 다음 턴의 판단을 돕는다.

3. Delegate: 별도 컨텍스트 창으로 나눈다

코드 리뷰, 성능 분석, 문서 조사, 테스트 실패 원인 조사처럼 서로 독립적인 작업은 하나의 대화에 모두 넣지 않는다. 하위 에이전트나 별도 세션으로 분리하면 각 작업의 컨텍스트가 작고 선명해진다.

Python 코드베이스에서는 예를 들어 “의존성 업데이트 영향 조사”와 “실패 테스트 수정”을 분리하는 편이 낫다. 두 작업은 읽어야 할 파일과 판단 기준이 다르다.

4. Externalize: 나중에 읽을 수 있게 저장한다

컨텍스트 창은 영속 저장소가 아니다. 장기 작업에서는 중간 결론을 파일, 이슈, 체크리스트, 테스트 결과물로 남겨야 한다.

• 조사 결과: docs/notes/나 작업용 Markdown에 저장
• 반복 검증: 테스트 명령을 스크립트나 Makefile 타깃으로 고정
• 결정 사항: PR 설명이나 설계 노트로 외부화
• 대형 출력: 파일로 저장하고 필요한 부분만 재검색

적용 체크리스트

관련 문서

• context-engineering — 컨텍스트 창을 유한 자원으로 관리하는 방법론
• agent-harness — 컨텍스트, 도구, 샌드박스를 포함한 에이전트 하네스 설계
• prompt-compression-tips-agentic-loop-cost — 에이전틱 루프 비용을 줄이는 프롬프트 압축 패턴

참고 자료

• Context Engineering for Python Codebases — Real Python (2026-06-17)