에이전트를 '쓴다'는 것과 '구조화한다'는 것은 다르다
AI 코딩 에이전트를 팀 워크플로우에 붙이는 것은 어렵지 않다. Claude Code든 Copilot이든 5분이면 연결된다. 문제는 그 다음이다. 에이전트가 실제로 작업을 완료했는지 어떻게 판단하나? 세션이 끊기면 앞에서 쌓은 맥락은 어디 가나? 한 에이전트가 크고 복잡한 작업을 맡으면 컨텍스트가 오염되지 않나? 이 세 질문에 답하지 않은 채 에이전트를 배포하면, 결국 '빠른 속도로 만들어내는 불확실한 결과물'만 쌓인다.
최근 세 편의 기술 글이 각각 이 문제의 한 레이어를 다룬다. 이것들을 엮으면 하나의 설계 원칙이 보인다. 기억(Memory), 격리(Isolation), 검증(Verification)—이 세 구조를 분리해서 설계하지 않으면 에이전트는 도구가 아니라 불안 요소가 된다.
레이어 1 — 검증은 에이전트 판단에 맡기지 마라
dev.to에서 Codens를 만드는 개발자가 쓴 글은 검증 레이어를 둘러싼 실용적 질문을 정면으로 파고든다. Claude Code Skill 기반 검증과 결정론적 verify_commands 방식을 실제 티켓 기반 워크플로우에서 비교한 내용이다.
Skill 기반 검증의 장점은 분명하다. 변경된 diff를 읽고 어느 패키지를 검증할지 판단하고, 실패 원인을 자연어로 요약해준다. 프론트엔드만 바뀐 PR에서 백엔드 테스트를 건너뛰는 맥락적 판단도 가능하다.
그런데 바로 그 장점이 프로덕션 게이트로 쓰기에는 치명적이다. 에이전트가 'Skill을 호출할 타이밍이다'라고 판단해야 검증이 실행된다. 에이전트가 판단을 틀리면 검증 자체가 생략된다. 이건 품질 게이트가 아니라 권고 사항에 가깝다.
반면 결정론적 verify_commands는 단순하다. 워크플로우 스텝에 shell 커맨드를 박아두면, 에이전트 판단 없이 항상 실행된다. exit 0은 통과, non-zero는 실패. 해석 레이어가 없다. 실패 시에는 stderr의 마지막 1,500바이트를 그대로 다음 스텝으로 넘긴다. LLM이 요약한 실패 메시지가 아니라 실제 스택 트레이스다. 그리고 이 커맨드는 GitHub Actions에서도, 로컬에서도 동일하게 동작한다. 포터블하다.
결론은 이렇다. Skill은 '보고서'에 쓰고, 결정론적 커맨드는 '게이트'에 써라. "이 PR의 변경 위험도를 요약해줘"는 Skill의 영역이고, "lint + typecheck + test가 모두 통과했는가"는 exit code가 판단해야 한다. 검증의 권한을 에이전트에게 위임하는 순간, 그 검증은 더 이상 신뢰할 수 없다.
레이어 2 — 작업은 격리하고, 컨텍스트는 오염시키지 마라
검증 레이어를 갖췄다면, 이번엔 에이전트가 어떻게 작업을 분리하는지를 봐야 한다. Anthropic 블로그를 분석한 velog 포스트는 Claude의 Subagent 구조를 '브라우저 탭'에 비유한다. 적확한 비유다.
메인 에이전트 세션에서 무거운 탐색 작업이 필요할 때—예를 들어 수십 개의 파일을 읽어야 하는 코드베이스 분석—그 작업을 메인 컨텍스트에 쌓으면 나머지 작업에 노이즈가 생긴다. Subagent는 이 작업을 자체 컨텍스트 윈도에서 처리하고, 결과 요약만 부모에게 돌려준다. 수만 토큰을 소비하더라도 부모에게 돌아오는 건 1,000~2,000토큰짜리 요약이다.
중요한 건 권한 분리다. 탐색용 Subagent는 읽기 전용, 구현용 Subagent는 편집 권한—이게 AI 시스템에 Least Privilege 원칙을 적용하는 방식이다. 그리고 Subagent와 Agent를 구분하는 것은 파일 포맷이 아니다. .claude/agents/ 안에 있는 Markdown 파일은 문법적으로 동일하다. 차이는 누가 호출하느냐에서 발생한다.
팀에서 이 구조를 설계할 때 실용적인 기준은 하나다. '이 작업이 메인 스레드를 막아서는 안 되는가?' 그렇다면 Subagent다. 병렬 실행이 필요한가? 별도 세션과 피어-투-피어 통신이 필요한 Agent Teams 패턴을 고려해야 한다. 단, Agent Teams는 토큰 비용이 약 7배 높다는 점을 사전에 예산에 반영해야 한다.
레이어 3 — 세션이 끊겨도 학습은 누적되어야 한다
격리와 검증을 갖췄는데 여전히 남은 문제가 있다. 세션이 끊기면 에이전트는 처음부터 다시 시작한다. 코드베이스를 다시 탐색하고, 같은 패턴을 다시 학습하고, 이전에 실패했던 접근을 또 시도한다.
dev.to에 공개된 Shadow Engineer 프로젝트는 이 문제를 '기억 레이어'로 접근한다. 아이디어는 단순하다. 에이전트와 태스크 사이에 지식 그래프 레이어를 두고, 세션이 끝날 때마다 결과를 기록하는 것이다.
세 가지 엔진이 작동한다. Knowledge Graph는 코드베이스 전체를 ChromaDB 벡터 임베딩으로 인덱싱해 세션 시작 시 의미론적으로 관련된 심볼을 컨텍스트에 주입한다. "login rate limiting 고쳐줘"를 받으면 throttle_requests()를 찾아낸다. Laboratory는 동일한 태스크에 대해 N개의 병렬 전략을 시도하고 테스트 통과율, 변경 범위, 실행 속도를 기준으로 승자를 자동 선택한다. Learning Engine은 이 결과를 분석해 다음 세션에서 어떤 접근이 이 코드베이스에서 효과적인지를 누적한다.
실제 파이프라인 테스트에서 26개 파일에서 211개 심볼을 인덱싱했고, LLM은 89줄짜리 컨텍스트 블록을 받아 수정 대상 파일과 접근법을 정확히 식별했다. 핵심은 이거다. 에이전트가 매 세션마다 코드베이스를 다시 이해하는 비용을 없애는 것. 그리고 어떤 접근이 이 팀의 코드베이스에서 통하는지를 조직 차원에서 누적하는 것.
세 레이어를 엮어야 비로소 '구조'가 된다
정리하면 이렇다.
| 레이어 | 설계 원칙 | 도구/패턴 |
|---|---|---|
| 기억 | 세션 간 컨텍스트 누적 | Knowledge Graph, 벡터 임베딩 |
| 격리 | 작업별 컨텍스트 분리 | Subagent, Least Privilege |
| 검증 | 완료 판단은 결정론적으로 | verify_commands, exit code |
이 세 레이어 중 하나라도 빠지면 구멍이 생긴다. 검증이 없으면 '완료'의 기준이 에이전트 자체 판단이 된다. 격리가 없으면 복잡한 작업에서 컨텍스트가 오염된다. 기억이 없으면 에이전트는 매 세션마다 신입이다.
지금 팀에 AI 코딩 에이전트를 붙이고 있다면, 이 세 가지를 먼저 물어봐라. 우리 에이전트는 이전 세션에서 무엇을 배웠나? 복잡한 작업을 분리해서 처리하고 있나? 그리고 '완료'는 누가 판단하나?
에이전트 워크플로우 설계의 미성숙함은 대부분 이 세 질문에 답하지 않은 채 배포를 서두른 데서 온다. 속도는 그 다음 문제다.