2023년이나 2024년에 AI 코딩 에이전트를 시도했다가 포기한 대부분의 개발자들은 여전히 이 문제를 모델이 제대로 작동하게 만드는 마법 같은 문구를 찾는 "프롬프트 엔지니어링 (Prompt Engineering)"의 문제로 생각하고 있습니다. 그러한 프레임워크는 시대에 뒤처졌습니다. 에이전트들은 더 똑똑해졌고, 병목 현상의 위치가 이동했습니다. 오늘날 정확한 코드를 안정적으로 배포하는 에이전트와 자신 있게 틀린 변경 사항을 만들어내는 환각 (Hallucination) 에이전트 사이의 차이는, 질문을 얼마나 영리하게 표현했느냐가 아니라 거의 전적으로 컨텍스트 윈도우 (Context Window) 안에 무엇이 들어있는가 그리고 _언제 들어있는가_에 달려 있습니다. 이것이 바로 컨텍스트 엔지니어링 (Context Engineering)이며, 의도적으로 쌓아 올릴 수 있는 기술입니다.

이번 주에 바로 채택할 수 있는 패턴과 함께, 이것이 실제로는 어떻게 적용되는지 살펴보겠습니다.

1. 지속적인 프로젝트 지침 (Persistent project instructions)이 반복적인 프롬프팅 (Prompting)보다 낫습니다

매 세션마다 테스트 프레임워크, 커밋 컨벤션 (Commit conventions), 또는 "TypeScript에서 any를 사용하지 마세요"와 같은 내용을 다시 설명하고 있다면, 당신은 변하지 않는 사실들에 토큰 (Tokens)과 인내심을 낭비하고 있는 것입니다. Claude Code, Cursor, Windsurf와 같은 도구들은 모두 프로젝트 수준의 지침 파일(CLAUDE.md, .cursorrules, AGENTS.md)을 지원합니다. 이를 매우 빠르지만 조직에 대한 기억이 전혀 없는 신입 사원을 위한 온보딩 문서처럼 취급하세요.

실제로 그곳에 포함되어야 할 내용:

• 빌드/테스트/린트 (Build/test/lint) 명령 (설명이 아닌 정확한 문자열)
• 명확하지 않은 아키텍처 결정 사항 ("감사 요구 사항 때문에 주문 테이블에 이벤트 소싱 (Event sourcing)을 사용합니다 — CRUD로 리팩터링하지 마세요")
• 코드에서 추론할 수 없는 팀 컨벤션 (Team conventions)
• 명시적 경계: 묻지 않고는 절대 건드려서는 안 되는 것들 (마이그레이션, CI 설정, 비밀 값 (Secrets))

포함되지 말아야 할 내용: 코드를 읽어서 유도할 수 있는 것들. 파일 구조를 재진술하거나 각 함수가 무엇을 하는지 설명하는 CLAUDE.md는 누군가 리팩터링을 하는 순간 부패하며, 실제 소스 코드보다 오래된 문서를 신뢰하도록 당신을 훈련시키게 됩니다. 파일에는 문서화가 아닌 _결정 사항과 제약 조건 (Decisions and constraints)_이 포함되어야 합니다.

2. 에이전트에게 단일 세션 내에서뿐만 아니라 세션 간에도 메모리 (Memory)를 제공하세요

단일한 롱 컨텍스트 (Long-context) 대화는 지속적인 메모리 (Persistent memory)와는 다릅니다. 세션 내에서 에이전트는 전체 코드베이스를 머릿속에 담아둘 수 있습니다. 하지만 그 세션이 종료되는 순간, 특정 수정 사항이 왜 까다로웠는지, 혹은 무엇을 왜 거절했는지에 대해 어렵게 얻은 모든 컨텍스트 (Context)를 포함하여 모든 것이 사라집니다.

픽스 (Fix)는 가벼운 외부 메모리입니다. 즉, 에이전트가 관련 작업을 시작할 때 읽고, 기억할 만한 일이 발생했을 때 기록하는 주제별 범위가 지정된 작은 노트들의 디렉토리입니다. 핵심적인 원칙은 메모리에 속해야 할 것과 코드 또는 Git 히스토리에 속해야 할 것을 분리하는 것입니다. "로그인 함수는 auth.py에 있습니다"와 같은 내용은 저장하지 마세요. 그것은 grep 한 번이면 찾을 수 있습니다. 대신 "미들웨어 계층에서 속도 제한 (Rate-limiting)을 시도했으나 웹소켓 업그레이드를 망가뜨려 되돌렸습니다"와 같은 내용을 저장하세요. 이것은 정적 분석 (Static analysis)으로는 절대 복구할 수 없는 '흉터 조직 (Scar tissue)'과 같은 사실이며, 그렇지 않으면 다음 에이전트(또는 6개월 후의 당신)가 똑같은 실수를 반복하게 될 것입니다.

직접 구현한다면, 각 메모리 파일을 작고 단일 목적을 갖도록 유지하고, 에이전트가 모든 것을 읽지 않고도 무엇을 사용할 수 있는지 알 수 있도록 매번 로드하기 저렴한 짧은 인덱스 (Index) 파일을 유지하세요.

3. 서브에이전트 (Subagents)는 단순한 병렬 처리 기술이 아니라 컨텍스트 격리 도구입니다

서브에이전트의 명백한 장점은 "작업을 동시에 수행한다"는 것입니다. 하지만 과소평가된 장점은 서브에이전트가 컨텍스트를 격리 (Quarantine) 할 수 있게 해준다는 점입니다. 하나의 질문에 답하기 위해 20개의 파일을 읽어야 하는 조사 작업이, 세션이 끝날 때까지 메인 대화에 20개 파일 분량의 토큰 (Tokens)을 남겨두어서는 안 됩니다. 이는 이후의 모든 턴마다 재처리 비용을 지불해야 하는 컨텍스트이며, 실제로 구축하려는 것을 밀어내게 됩니다.

실무적인 규칙: 많은 중간 읽기 과정을 거치지만 최종 답변은 작은 탐색적 작업("X는 어디서 처리되는가", "Y의 현재 테스트 커버리지는 얼마인가", "이 API의 인증 흐름을 요약하라")은 정제된 결과를 반환하는 서브에이전트에게 맡겨야 합니다. 반복적인 편집을 위해 전체 세부 사항을 유지해야 하는 모든 작업은 메인 스레드 (Main thread)에 남겨둡니다.

이는 요청을 작성하는 방식 또한 변화시킵니다. 서브에이전트 (Subagent)는 당신과의 대화 내용을 기억하지 못합니다. 따라서 단순히 '무엇(what)'을 할지가 아니라, '왜(why)' 하는지가 필요합니다. "세션이 만료되는 지점을 찾아줘"라고 하면 얕은 수준의 grep-and-report(검색 및 보고) 결과만 얻게 됩니다. 반면, "사용자가 결제 도중 로그아웃되는 문제를 디버깅 중입니다. 세션 만료 로직이 어디에 있는지 찾아서, 장시간 실행되는 요청(long-running requests)을 고려하고 있는지 확인해 주세요"라고 요청하면 실제로 유용한 답변을 얻을 수 있습니다. 에이전트가 무엇이 관련성이 있는지 알게 되기 때문입니다.

4. 검증 (Verification) 또한 컨텍스트입니다 — 시간을 아끼려고 이를 건너뛰지 마세요

현재 에이전트 기반 코딩 (Agentic coding)에서 발생하는 가장 흔한 실패 모드는 잘못된 코드 생성 그 자체가 아닙니다. 바로 에이전트(또는 그 결과물을 검토하는 개발자)가 "코드가 컴파일된다"거나 "diff(차이점)가 그럴듯해 보인다"는 것을 "기능이 작동한다"와 동일하게 취급하는 것입니다. 이는 결코 같지 않습니다. 타입 체크 (Type checking)와 유닛 테스트 (Unit tests)는 시스템에 구축하라고 지시한 내용의 정확성을 검증할 뿐입니다. 그것이 올바른 작업이었는지, 혹은 실제 런타임 동작 (Runtime behavior)이 의도와 일치하는지에 대해서는 아무것도 말해주지 않습니다. 특히 UI가 있거나 외부 부작용 (External side effects)이 발생하는 작업의 경우 더욱 그렇습니다.

이러한 규율을 실천하는 가장 저렴한 방법은 다음과 같습니다. 에이전트(또는 팀 동료, 혹은 자기 자신)에게 작업이 완료되었다고 말하기 전에, '작동해야 하는 것'이 아니라 '실제로 실행되고 관찰된 것'이 무엇인지 기술하게 하십시오. "새 테스트를 실행했고 통과했습니다. 여기 출력 결과입니다"는 검증입니다. "이것은 엣지 케이스 (Edge case)를 올바르게 처리할 것입니다"는 자신감이라는 옷을 입은 추측일 뿐입니다. 글로 써놓으면 당연해 보이지만, 이는 AI 보조 작업을 지시하는 모든 사람에게 가장 영향력이 큰 습관입니다. 왜냐하면 LLM (Large Language Models)은 매우 유창하기 때문에, 확인하기 전까지는 자신감 넘치는 오답과 자신감 넘치는 정답이 똑같이 읽히기 때문입니다.

5. 오케스트레이션 (Orchestration)의 규모를 기술적으로 가능한 수준이 아니라, 작업의 규모에 맞추세요

서브 에이전트 (subagents)와 메모리 (memory)가 제대로 작동하기 시작하면, 모든 것을 확장하고 싶은 유혹에 빠지기 쉽습니다. 예를 들어, 단 한 줄의 CSS 수정을 위해 다섯 명의 에이전트가 검토하게 하거나, 30초면 답할 수 있는 질문에 대해 전체 리서치 파이프라인 (research pipeline)을 가동하는 식입니다. 이를 경계하십시오. 오케스트레이션 (Orchestration)에는 실제 비용이 따릅니다. 토큰 소비 (token spend), 지연 시간 (latency), 그리고 작업이 요구하는 수준보다 더 넓은 영역을 검토해야 하는 인지적 부하 (cognitive overhead)가 그것입니다. 기계 장치의 규모를 변경의 영향 범위 (blast radius)에 맞추십시오. 오타 수정에는 diff 읽기만 있으면 됩니다. 하지만 프로덕션 테이블 (production table)에 영향을 미치는 스키마 마이그레이션 (schema migration)에는 독립적인 검토, 적대적 검증 (adversarial verification), 실제(또는 현실적인) 데이터셋에 대한 실제 테스트와 같은 전체 파이프라인이 필요합니다.

근본적인 변화

이 중 그 어떤 것도 더 똑똑한 모델을 요구하지 않습니다. 대신 컨텍스트 (context) — 에이전트가 무엇을 알고 있는지, 그것을 언제 배웠는지, 그리고 무엇을 잊어도 되는지 — 를 캐싱 (caching)이나 데이터베이스 스키마 설계 (database schema design)에 적용하는 것과 동일한 엄격함을 가진 엔지니어링 영역 (engineering surface)으로 취급할 것을 요구합니다. 현재 코딩 에이전트로부터 복리 효과를 얻고 있는 팀들은 가장 뛰어난 프롬프트 (prompts)를 가진 팀들이 아닙니다. 그들은 매 세션마다 자신을 다시 설명하는 것을 멈추고, 도구에 메모리를 부여하며, 결과물을 배포하기 전에 증거를 바탕으로 주장을 확인하는 습관을 구축한 팀들입니다. 이것은 모델 업그레이드가 아니라 프로세스의 변화이며, 여러분이 이미 사용 중인 어떤 에이전트로든 오늘 바로 시작할 수 있습니다.