포커스

에이전트에게 '맥락'을 어떻게 전달하느냐를 둘러싼 이야기들입니다.

컨텍스트 엔지니어링 : 에이전트에게 맥락을 설계하는 일

요즘 '컨텍스트 엔지니어링'이라는 말이 자주 보입니다.

에이전트에게 코드를 짜달라고 하는 건 누구나 하는데, 에이전트가 일할 수 있는 구조를 설계하는 건 다른 차원의 일이라는 거죠.

업계에서 이걸 체계화하려는 시도도 나오고 있습니다.

정의(CLAUDE.md) → 실행(Skill) → 학습(Memory) → 연결(MCP)처럼 레이어를 나눠서, 에이전트가 일하는 경기장을 구조화하자는 흐름이구요.

저도 비슷한 구조를 직접 만들어 쓰고 있는데, 실제로 해보면 여기에 훅(Hook)이나 규칙 파일 분류 같은 세부 요소들이 더해져야 합니다.

레이어를 깔끔하게 4개로 나누는 것보다, 현장에서는 좀 더 구체적이고 세밀한 구조가 필요한 것 같아요.

“하네스가 무슨 소용이냐, 모델이 알아서 잘하는데”라는 반론도 있죠. 하지만 디테일이 중요한 분야에서는 하네스가 모호성을 잡아내고 논리적 모순을 걸러주는 역할을 합니다.

모델이 좋아지면 불필요해지는 하네스도 있지만, 아무리 모델이 발전해도 팀의 선호나 워크플로우를 담은 하네스의 가치는 줄어들지 않을 것 같습니다.

코드를 생성하는 AI를 쓰는 것과, AI가 일할 수 있는 구조를 설계하는 것. 이 둘의 차이가 점점 벌어지고 있다는 느낌입니다.

누군가가 Claude Code로 Playwright E2E 테스트(브라우저에서 실제 사용자처럼 클릭하고 확인하는 자동화 테스트)를 작성했거든요. 결과는 모든 테스트 PASS. 그런데 QA 환경에서 직접 확인해보니 앱이 망가져 있었습니다.

무슨 일이었냐면, 테스트가 앱의 버그를 수정하는 대신 브라우저 안에서 JavaScript를 몰래 주입해서 결함을 숨기고 PASS를 보고한 거죠. 테스트가 통과했는데 앱은 고장나있는, 아주 위험한 상태입니다.

원인은 명확합니다. 에이전트에게 "테스트를 통과시켜"라는 목표만 줬지, "앱 코드를 건드리지 마"라는 수단의 경계를 안 줬던 거예요.

결국 CLAUDE.md에 "테스트가 통과하면서 실제 기능은 망가져 있는 상황은, 테스트가 없는 것보다 나쁘다"는 규칙을 명시적으로 추가해야 했다고 합니다.

앞서 이야기한 컨텍스트 엔지니어링이 왜 필요한지를, 역설적으로 가장 잘 보여주는 사례가 아닐까 싶습니다.

에이전트는 목표를 달성하는 데는 놀라울 정도로 창의적이거든요. 문제는 그 창의성이 우리가 원하는 방향이 아닐 수도 있다는 것이죠.