에이전트 런타임 설계 실수 2026 — capability 경계가 무너지는 순간 5가지

Posted on by

좋은 에이전트 시스템은 보통 화려한 기능보다 지루한 경계선에서 버틴다.

입력 계약, 권한 구분, 세션 수명주기, 로그, cleanup. 이런 거 말이다.

사람이 보기에 재미없는 부분인데, 실제로는 여기서 런타임 품질이 갈린다.

Quick Answer

  • 에이전트 런타임이 망가질 때는 대개 모델이 갑자기 멍청해져서가 아니라 capability 경계가 흐려져서다.
  • 가장 흔한 실수는 read와 write를 한 칸에 넣기, 외부 write를 local write처럼 다루기, 긴 세션을 한 몸으로 끌기, cleanup 없는 상태 축적, 실패 후 복구 경로 부재다.

런타임은 똑똑함보다 경계선으로 산다.

이 글이 필요한 사람

  • Claude Code, Codex, Cursor, 자체 에이전트를 운영해본 사람
  • 프롬프트보다 운영 구조에서 더 자주 망하는 걸 느낀 사람
  • capability, permission, lifecycle 문서를 아직 대충 적고 있는 사람

지금 결론

실수 왜 위험한가
read/write 혼합 사고 범위 예측이 어려움
external write 축소평가 되돌리기 어려움
세션 비만 규칙이 흐려짐
cleanup 부재 상태 오염 누적
복구 경로 없음 실패가 장기 장애가 됨

실수 1. read와 write를 같은 capability처럼 다루는 것

많은 시스템이 여기서 이미 미끄러진다.

  • 파일 읽기
  • 파일 수정
  • 원격 발행
  • 삭제/이동

이걸 다 “도구 사용” 한 단어로 묶어버린다.

그러면 어떤 일이 생기냐.

  • 승인 정책이 흐려진다
  • 로그 해석이 어려워진다
  • 사고 시 원인 추적이 늦어진다

read는 정보 수집이고, write는 상태 변경이다. 이 둘은 애초에 다른 capability다.

실수 2. external write를 local write처럼 보는 것

이건 특히 자주 나온다.

로컬 파일 수정과 외부 발행을 같은 write로 두면 편해 보인다.

근데 실제론 다르다.

  • 로컬 수정은 되돌리기 쉽다
  • 외부 write는 이미 세상에 흔적이 남는다

워드프레스 발행, 배포, 시트 수정, 거래 API 호출은 같은 write가 아니다.

이걸 따로 안 빼면 시스템은 편해지고 운영은 불안해진다.

실수 3. 긴 세션을 하나의 뇌로 계속 끌고 가는 것

데모에선 한 세션이 다 한다.

실전은 다르다.

  • 조사
  • 수정
  • 리뷰
  • 발행

이걸 한 세션에서 오래 끌면 컨텍스트도 비만해지고 규칙도 흐려진다.

처음엔 “이 세션은 조사만”이었는데 끝날 땐 발행까지 해버리는 식이다.

긴 세션이 문제라기보다 단계 분리 없는 긴 세션이 문제다.

실수 4. cleanup 없는 상태 축적

좋은 런타임은 시작보다 종료가 중요할 때가 많다.

근데 많은 시스템은 시작만 설계하고 끝은 비워둔다.

  • temp 파일 정리 안 함
  • lock 해제 안 함
  • 세션 로그 종료 처리 안 함
  • 미완료 작업 상태가 어정쩡하게 남음

이게 쌓이면 다음 실행이 오염된다.

그리고 이건 눈에 안 띄어서 더 짜증난다. 조용히 품질을 갉아먹는다.

실수 5. 실패 후 복구 경로를 문서화하지 않는 것

에이전트 시스템은 실패한다. 이건 전제다.

문제는 실패 자체가 아니라 실패했을 때 어디로 돌아오느냐다.

최소한 아래는 있어야 한다.

  • 중단 시 상태 파일 위치
  • 재시도 가능한 단계
  • 사람이 이어받는 방법
  • cleanup 기준

이게 없으면 실패가 곧 장애가 된다.

capability 경계를 지키는 최소 표

이런 표 하나만 있어도 운영이 꽤 쉬워진다.

capability read write external side effect cleanup
search vault 있음 없음 없음 불필요
edit draft 있음 있음 없음 git/diff
publish post 있음 있음 있음 URL/시트 sync
trade order 있음 있음 매우 큼 강한 로그/승인

이 표의 좋은 점은 도구 이름보다 행동 구조가 먼저 보인다는 거다.

런타임이 무너지는 신호

아래 신호가 보이면 capability 경계를 다시 봐야 한다.

1. 왜 승인 요청이 뜨는지 설명이 안 된다

권한 모델이 불명확하단 뜻이다.

2. 같은 세션이 조사, 수정, 발행을 다 한다

lane이 무너진 거다.

3. 실패 후 temp나 lock이 자꾸 남는다

cleanup이 설계되지 않았다.

4. 로그는 있는데 복구 순서가 없다

기록은 있는데 운영 절차가 없는 상태다.

실수 TOP 5 요약

  1. read/write 혼합
  2. external write 축소평가
  3. 세션 단계 분리 실패
  4. cleanup 부재
  5. 복구 문서 부재

이 다섯 개는 사실 별거 아닌 것처럼 보이는데, 별거 아닌 것치고 시스템을 꽤 잘 부순다.

FAQ

Q. capability 문서는 얼마나 자세해야 하나

처음엔 read, write, external side effect, cleanup 네 칸만 있어도 충분히 도움이 된다.

Q. 세션을 꼭 여러 개로 나눠야 하나

무조건은 아니지만, 조사와 발행은 분리하는 게 대체로 낫다.

Q. Claude Code 사례에서 제일 배운 건 뭔가

도구를 함수가 아니라 계약 묶음처럼 보는 관점이다.

다음에 읽을 글

출처와 전제

  • 이 글은 Claude Code 소스맵 이슈에서 읽힌 capability/lifecycle 관점을 런타임 실수 패턴으로 다시 묶은 후속이다.
  • 특정 제품 내부 구현 재현이 아니라 운영 구조 학습용 정리다.