컨텍스트 엔지니어링 실전 가이드 — 코딩 에이전트로 대규모 코드베이스를 다루는 3단계 워크플로

핵심 메시지

• AI 코딩 도구는 프로토타입에는 잘 맞지만 복잡한 레거시 코드베이스에서는 재작업을 늘려 오히려 속도를 떨어뜨린다는 조사 결과가 출발점이다.
• LLM은 사실상 순수 함수이므로, 출력 품질을 좌우하는 것은 컨텍스트 창에 무엇을 넣느냐뿐이다. 최악은 잘못된 정보, 그다음이 누락, 그다음이 잡음이다.
• 자동 압축 기능에 맡기는 대신 진행 상황 파일을 직접 작성하게 해 다음 세션의 에이전트를 인수인계하는 '의도적 압축'이 핵심 기법이다.
• 서브에이전트의 본질은 역할 분담이 아니라 컨텍스트 통제다. 코드 탐색처럼 읽기 부담이 큰 작업을 떼어내 결과만 돌려받는 방식이 실용적이다.
• 조사·계획·구현 세 단계를 나누고 컨텍스트 사용률을 40% 아래로 유지하면, 사람은 2천 줄 코드 대신 200줄 계획서를 읽고 팀의 이해를 맞출 수 있다.

쉽게 이해하기

YC 행사에서 발표한 덱스터 호시는 휴먼레이어 창업자로, 코딩 에이전트를 실무에 밀어 넣으면서 겪은 변화를 이야기했다. 계기는 강제된 것이었다. 함께 일하던 개발자가 이틀에 한 번씩 2만 줄짜리 Go 코드 PR을 올렸는데, 경쟁 조건과 종료 순서가 얽힌 복잡한 시스템 코드였고 도저히 리뷰할 수 없었다. 팀이 같은 그림을 공유할 방법은 명세 우선 개발밖에 없었다.

그는 업계의 낙관과 현실 사이의 간극을 먼저 짚는다. 10만 명 규모 개발자 데이터를 분석한 연구에서 AI 코딩은 상당한 재작업을 유발했고, 특히 오래된 코드베이스의 복잡한 작업에서는 도움이 되지 않는 정도를 넘어 생산성을 떨어뜨릴 수 있었다. 여러 창업자의 경험도 비슷했다. 프로토타입에는 좋지만 큰 저장소와 복잡한 시스템에서는 무너진다는 것이다. 컨텍스트 엔지니어링은 모델이 더 좋아지기를 기다리는 대신 지금의 모델에서 최대치를 뽑아내려는 시도다.

가장 흔한 사용 방식은 에이전트와 주고받으며 계속 고쳐 말하다가 컨텍스트가 바닥나는 것이다. 한 단계 나은 방법은 궤도를 벗어났다 싶으면 미련 없이 새 세션을 시작하는 것이고, 호시가 권하는 방식은 여기서 한 걸음 더 나간다. 방향이 맞더라도 컨텍스트가 차오르면 지금까지의 맥락을 진행 상황 파일로 정리해 두고, 그 파일로 다음 에이전트를 온보딩시킨다.

왜 컨텍스트에 집착하는지에 대한 그의 답은 단순하다. 모델을 직접 학습시키거나 온도를 조절하는 것 말고, 출력 품질을 바꾸는 유일한 수단이 입력이기 때문이다. 코딩 에이전트는 다음에 어떤 도구를 부를지, 어떤 수정을 할지를 계속 판단하는데 그 판단의 재료가 컨텍스트 창이다. 파일 탐색과 흐름 파악, 큰 JSON을 뱉는 도구 호출이 이 공간을 잠식한다.

그가 매일 쓰는 방식은 '잦은 의도적 압축'이다. 조사 단계에서는 시스템이 어떻게 동작하고 문제가 어디에 있는지를 파일명과 줄 번호까지 적어 정리하게 한다. 계획 단계에서는 바꿀 파일과 코드 조각, 각 단계의 검증 방법을 명시하게 한다. 구현 단계에서는 계획을 갱신해 가며 컨텍스트 사용률을 40% 아래로 유지한다. 계획이 좋으면 구현 중에 에이전트에게 소리칠 일이 없고, 소리치게 된다면 그것은 계획이 나빴다는 신호다.

실제 적용 사례로 그는 30만 줄 규모 러스트 코드베이스의 수정을 한 번에 통과시킨 일을 들었다. PR 품질이 충분해 상대 회사 CTO가 실험인 줄 모르고 병합했다는 것이다. 또 다른 날에는 7시간 동안 3만 5천 줄 규모의 작업을 진행해 프로그래밍 언어에 WASM 지원을 추가했고, 상대 추정으로 1~2주 분량이었다고 전했다.

주요 인사이트

• 핵심 통찰은 오류의 증폭 비율에 있다. 나쁜 코드 한 줄은 한 줄이지만, 계획의 나쁜 한 대목은 나쁜 코드 수백 줄이 되고, 시스템 이해가 어긋난 조사 한 줄은 수천 줄이 된다. 시간을 쓸 지점이 어디인지가 여기서 정해진다.
• 코드 리뷰의 본질을 결함 탐지가 아니라 '정신적 정렬'로 재정의한 점이 이 워크플로를 지탱한다. 팀이 시스템의 변화를 함께 이해하는 것이 목적이라면, 그 매개가 반드시 코드일 필요는 없다.
• 서브에이전트를 역할극으로 쓰는 흔한 접근과 달리, 여기서는 컨텍스트 통제 장치로 쓴다. 다만 부모 에이전트가 자식에게 어떤 형식으로 결과를 돌려달라고 지시할지가 새로운 난제로 남는다.
• 명세 우선으로의 전환은 기술보다 심리의 문제였다. 호시는 8주에 걸쳐 코드를 한 줄씩 읽지 않는 데 적응했다고 밝혔고, 테스트는 여전히 전부 읽는다는 단서를 달았다.
• 그는 코딩 에이전트 자체는 결국 상품화될 것으로 보고, 진짜 어려운 부분은 팀의 협업 방식과 워크플로를 바꾸는 일이라고 전망했다.

자주 묻는 질문

관련 AI 소식