Coding Agent Context Engineering: Make Agents Read Before They Edit

개요

코딩 에이전트의 실패는 코드 작성 능력 부족이 아닌, 성급한 편집에서 비롯됩니다. 이러한 실패를 방지하기 위해 에이전트가 편집 전에 증거를 수집하도록 하는 사전 편집 컨텍스트 엔지니어링 워크플로우가 중요합니다.

주요 내용

* 코딩 에이전트의 성급한 편집 문제: 코딩 에이전트는 종종 코드베이스에 대한 충분한 이해 없이 파일을 열고, 잘못된 부분을 수정하며, 협소한 테스트만 실행하여 문제를 야기합니다. 이는 코드의 근본적인 아키텍처, 데이터 마이그레이션, 부작용 등을 놓치는 결과를 초래합니다.
* 컨텍스트 엔지니어링의 필요성: 단순히 프롬프트를 길게 하거나 파일 몇 개를 지정하는 것만으로는 프로덕션 환경에서 에이전트의 오류를 막기 어렵습니다. 에이전트는 편집 전에 관련된 파일, 심볼, 의존성, 이전 결정, 잠재적 위험 등을 체계적으로 파악해야 합니다.
* 컨텍스트 엔지니어링의 5가지 레이어:
* 작업 컨텍스트 (Task context): 작업 내용, 사용자 스토리, 수락 기준, 목표 외 사항.
* 저장소 컨텍스트 (Repo context): 코드 구조, 파일, 심볼, 라우트, 스키마, 의존성.
* 메모리 컨텍스트 (Memory context): 이전 결정, 수정 내역, 마이그레이션 노트, 주의사항.
* 위험 컨텍스트 (Risk context): 인증, 결제, 테넌트 격리, 삭제, 개인 식별 정보(PII) 등 위험 영역.
* 검증 컨텍스트 (Verification context): 테스트, 린트, 타입 체크, 추적, 로그 등 결과 증명.
* 실행 가능한 사전 편집 루틴: 작업 재정의, 관련 파일/심볼 식별, 참조/호출자 탐색, 테스트 식별, 메모리/결정 검색, 위험/가정 명시, 편집 계획 수립, 검증 명령 제시.
* 컨텍스트 패킷 활용: 구체적인 작업 목표, 비목표, 위험 영역, 필요한 증거, 검증 사항을 명시한 컨텍스트 패킷은 에이전트에게 코드베이스 변경에 대한 명확한 지침을 제공합니다.
* 저장소 맵 구축: 저장소의 제품 영역, 위험 영역, 검증 명령 등을 포함하는 저장소 맵은 에이전트가 반복적인 탐색에 시간을 낭비하는 것을 줄이고, 인간 리뷰어가 에이전트의 작업 범위를 파악하는 데 도움을 줍니다.
* 메모리 활용 시 주의점: 메모리는 탐색을 안내하는 데 유용하지만, 현재 코드의 증거보다 우선시되어서는 안 됩니다. 메모리에는 출처, 범위, 검증 날짜 등이 명시되어 신선도와 신뢰도를 확보해야 합니다.
* 테스트 발견 우선순위: 편집 전에 현재 동작을 다루는 테스트, 수정 후 실패해야 할 테스트, 새로운 동작을 증명할 테스트를 식별해야 합니다.
* 위험 등급별 에이전트 편집: 문서 수정과 같은 낮은 위험 작업은 간소화된 절차를, 인증, 결제, AI 도구 변경과 같은 높은 위험 작업은 인간 검토와 상세한 분석을 요구해야 합니다.
* 검증 영수증 요구: 에이전트의 최종 결과물은 "완료"가 아닌, 사용된 증거, 실행된 검증, 잔존 위험 등을 명시한 검증 영수증이어야 합니다.
* 가벼운 컨텍스트 게이트 구현: .agent/context-gate.md 파일과 같은 체크리스트를 통해 에이전트가 편집 전에 필요한 절차를 수행하도록 강제할 수 있습니다.
* 흔한 실수: 저장소 전체를 컨텍스트에 덤프하는 것, 신선하지 않은 메모리에 의존하는 것, 편집 후에만 테스트를 실행하는 것, 모든 파일을 동일한 위험으로 취급하는 것, 영수증 없이 요약만 수용하는 것.

시사점

컨텍스트 엔지니어링은 코딩 에이전트의 신뢰성을 높여 코드베이스의 무결성을 보장하고, 프로덕션 환경에서의 에이전트 활용을 안전하고 효과적으로 만드는 핵심 요소입니다.