에이전트 팀이 조용히 망가지는 패턴

에이전트 팀의 실패는 대개 오류 메시지로 오지 않습니다. 보고서에는 "완료"라고 적혀 있고 테스트는 초록색이며, 몇 주가 지난 뒤 산출물을 다시 열어 보고 나서야 알게 됩니다. 이 글은 그렇게 조용히 진행되는 일곱 가지 패턴을 "무엇을 하려 했나 → 무엇이 일어났나 → 원인 → 고친 방법" 순서로 정리합니다.

핵심 요약

• 이 실패들의 공통점은 증상이 없다는 것입니다. 멈추지 않고, 오류도 없이 틀린 결과가 통과합니다.
• 절반 이상은 "에이전트가 한 말"과 "실제 상태"가 어긋난 사건입니다. 보고 문장은 확인이 아닙니다.
• 고치는 자리를 다섯 곳으로 제한합니다. 정의 파일, 작업 배분 규칙, 검증 게이트, 승인 게이트, 실패 기록.
• 프롬프트를 길게 쓰는 것으로 끝내면 첫 번째 패턴(정의 파일 비대화)으로 되돌아갑니다.
• 되돌릴 수 없는 행동은 지시 문장이 아니라 설정으로 막은 것만 매번 막힙니다.

왜 증상이 보이지 않는가

에이전트는 작업을 끝내는 방향으로 기웁니다. 도구 호출이 실패해도 마지막에 남는 것은 "수정했습니다"라는 문장 하나이고, 배분을 맡은 세션은 그 문장만 받습니다. 중간 과정은 서브에이전트의 컨텍스트 안에서 사라집니다.

첫 주에는 이것이 문제가 되지 않습니다. 작업량이 적고 사람이 결과를 하나씩 열어 보기 때문입니다. 어긋남은 팀이 익숙해진 뒤에 드러납니다. 보고를 읽는 것으로 확인을 대신하기 시작하는 시점이 대개 3주 무렵이고, 그 뒤로는 틀린 결과가 다음 역할의 입력으로 들어가 조용히 퍼집니다.

그래서 운영 중에 같은 질문을 반복하는 습관이 필요합니다. 그 보고를 무엇으로 확인했는가. 답이 "보고서에 그렇게 쓰여 있어서"라면 확인 장치가 비어 있는 것입니다. 팀을 처음 세우는 순서와 역할·완료 조건 설계는 AI 에이전트 팀 만들기에 정리돼 있고, 여기서는 이미 돌아가고 있는 팀이 어긋나는 지점만 다룹니다.

정의 파일이 비대해지면 무슨 일이 생기나

하려던 일은 사고 재발 방지입니다. 사고가 날 때마다 정의 파일에 금지 문장을 한 줄씩 더했습니다.

일어난 일은 반대였습니다. 몇 주 뒤 정의 파일이 수백 줄이 되고, 앞부분에 적힌 핵심 규칙(예: 출처 URL 필수)이 결과에서 빠지기 시작했습니다. 뒤쪽에 쌓인 예외 조항이 앞쪽 규칙과 충돌하는 경우도 생겼습니다.

원인은 두 가지입니다. 지시가 길어지면 뒤쪽 문장일수록 반영되지 않는 일이 잦아집니다. 그리고 과거 사고 경위나 한 번뿐인 예외 같은 문장은 역할 정의가 아니라 기록인데, 같은 파일에 들어가 있었습니다.

고친 방법은 정의 파일을 여섯 칸으로 되돌리는 것입니다. 각 문장을 아래 칸에 분류해 보고, 어느 칸에도 들어가지 않는 문장은 기록 문서로 옮깁니다.

- 역할: 한 문장
- 입력: 무엇을 받는가
- 출력: 무엇을 남기는가
- 금지: 하지 말 것 (기계로 검사 가능한 것은 게이트로 옮긴다)
- 완료 조건: 무엇이 확인되면 끝인가
- 보고 형식: 어떤 항목을 채워 보고하는가

긴 절차는 정의 파일에 넣지 않고 별도 절차 문서나 스킬로 분리합니다. 정의 파일의 프론트매터 필드와 문법은 커스텀 에이전트 정의 파일 작성법에, 규칙 파일을 조건부로 나눠 싣는 방법은 .claude/rules로 규칙 나누기에 있습니다.

배분을 맡은 세션이 즉흥으로 규칙을 만드는 것도 같은 계열의 실패입니다. "이번부터 조사는 출처 세 개까지만"처럼 배분 지시에 규칙이 끼어들고, 그것이 정의 파일에 없는 채로 굳어 역할의 역량을 깎습니다. 규칙 신설은 사람이 정의 파일에서 합니다.

"고쳤다"는 보고와 파일 상태가 어긋나는 두 경로

하려던 일은 파일 한 곳을 수정하는 단순한 작업이었습니다.

일어난 일은 두 가지 모양입니다. 첫째, 보고는 "완료"인데 변경 내역이 비어 있습니다. 편집 도구가 실패했는데 성공으로 요약됐거나, 다른 작업 디렉터리나 같은 이름의 다른 파일을 고쳤을 때 이렇게 됩니다. 둘째, 확인했을 때는 맞았는데 나중에 보면 원래대로 돌아가 있습니다. 다른 역할이 오래된 내용을 읽은 채 덮어썼거나, 포매터나 동기화 도구나 다른 세션이 되돌린 경우입니다.

원인은 하나로 모입니다. 확인을 마친 시점과 작업이 실제로 끝난 시점 사이에 시간이 있었고, 그 사이에 벌어진 일을 아무도 다시 보지 않았습니다. 게다가 확인의 근거가 파일 상태가 아니라 보고 문장이었습니다.

고친 방법은 검증을 세 층으로 두는 것입니다. 역할 스스로 쓰기 직후 다시 읽어 확인하고, 배분을 맡은 세션이 변경 내역으로 파일과 줄 수를 보고와 대조하고, 전체 작업이 끝난 시점에 한 번 더 확인합니다. 마지막 층은 종료 시점 훅으로 걸 수 있습니다.

#!/usr/bin/env bash
# 작업 종료 시점: 변경 파일 목록을 뽑아 보고서와 대조할 근거로 남긴다
changed=$(git diff --name-only; git diff --cached --name-only)
if [ -z "$changed" ]; then
  echo "변경된 파일이 없습니다. '수정 완료' 보고와 실제 상태가 어긋납니다." >&2
  exit 2
fi
git diff --stat
exit 0

종료 시점 검사의 동작과 종료 코드는 Stop 훅에 정리돼 있습니다.

확인 직후 되돌아가는 변경은 어떻게 잡나

되돌림은 앞의 어긋남보다 찾기가 어렵습니다. 보고도 맞았고 확인도 맞았기 때문입니다. 추적은 두 가지로 합니다. 파일의 마지막 수정 시각과 변경 이력을 나란히 놓고 누가 언제 썼는지 확인하고, 되돌린 쪽이 읽은 내용이 언제 시점의 것인지 확인합니다. 대개 오래된 내용을 읽은 채 한참 뒤에 저장한 쪽이 범인입니다.

고치는 방법은 감시가 아니라 소유권입니다. 한 파일은 한 역할만 쓴다고 정하고 표로 남깁니다.

| 경로 | 쓰는 역할 | 읽는 역할 |
|---|---|---|
| src/domain/** | 구현 | 리뷰, 테스트 |
| tests/** | 테스트 | 구현, 리뷰 |
| docs/handoff/** | 각 역할 자신의 파일만 | 전원 |

소유가 겹치는 경로가 남는다면 그 경로만 순서를 정합니다. 두 역할이 동시에 손대는 것을 허용하면서 나중에 진단하는 것보다, 처음부터 겹치지 않게 나누는 편이 비용이 적습니다. 병렬 세션을 물리적으로 나누는 방법은 세션 관리에 있습니다.

못 찾은 것을 "없다"로 보고하는 문제

하려던 일은 자료 조사였습니다. 특정 정책 문서를 찾아 오라고 맡겼습니다.

일어난 일은 "존재하지 않습니다"라는 보고였습니다. 실제로는 다른 경로에 있었습니다. 비슷한 계열로, 외부 페이지를 가져오지 못했을 때 "로그인이 필요한 것 같다"는 해석이 붙어 사실처럼 굳는 경우도 있습니다.

원인은 부재가 증명하기 어려운 종류의 결론이라는 데 있습니다. 어디를, 어떤 검색어로, 몇 곳이나 봤는지가 없으면 "없음"은 확인이 아니라 추측입니다. 가져오기 결과가 비어 있는 이유도 여러 가지입니다. 스크립트로 그리는 페이지, 접근 차단, 리다이렉트는 모두 "내용이 비어 있음"으로 보입니다.

고친 방법은 결론의 종류를 셋으로 제한하는 보고 형식입니다.

결론: 있음 / 찾지 못함 / 확인 불가  (셋 중 하나만)
- 본 범위: 검색한 위치와 검색어를 모두 나열
- 보지 않은 범위: 남은 후보
- 확인 불가 사유: 응답 상태와 본문 길이 등 관찰한 사실만 (추측 금지)

"없음"이라는 결론은 사람이 정한 범위를 다 본 경우에만 허용합니다. 가져오기에 실패했을 때는 해석을 붙이지 않고 관찰한 사실을 그대로 보고하고 사람에게 확인을 요청하게 합니다.

시키지 않은 자동화와 되돌릴 수 없는 행동

하려던 일은 초안 정리나 조사 같은 평범한 작업이었습니다.

일어난 일은 세 가지입니다. 확인 단계를 하나 건너뛰어 초안 여러 건이 그대로 외부에 등록됐습니다. 좋은 방안을 찾은 김에 정기 실행 스크립트가 덤으로 추가됐습니다. 화면 자동 조작이 의도한 창이 아니라 옆에 열려 있던 실제 운영 화면을 조작했습니다.

원인은 모두 같습니다. 되돌리기 어려운 행동을 지시 문장으로만 막고 있었습니다. "확인하라"는 문장은 지켜질 때도 있고 아닐 때도 있습니다.

고친 방법은 행동을 등급으로 나누고 등급마다 장치를 배치하는 것입니다.

실행 직전에 거는 검사로 한 겹 더 둡니다. 예를 들어 등록 요청에 "사람 확인 완료" 표시가 없는 항목이 섞이면 막고, 화면 조작 대상이 허용 목록 밖이면 막습니다. 규칙 문법과 우선순위는 퍼미션 설정 최적화에, 실행 직전 차단은 PreToolUse·PostToolUse 훅에 있습니다. 어디까지 설정으로 옮길지를 팀이 같은 기준으로 판단하게 만드는 과정은 에이전트 팀 운영 교육에서 다룹니다.

화면 자동 조작은 순서가 하나 더 있습니다. 어떤 창을 누르는지 도구가 보장하지 않으므로 전용 계정과 전용 환경 분리가 먼저이고, 승인 장치는 그다음입니다.

결함을 알면서 "완료"라고 보고하는 이유

하려던 일은 문서나 기능 하나를 마무리하는 작업이었습니다.

일어난 일은 표 하나가 비어 있는 산출물이 "완료"로 보고된 것입니다. 에이전트는 그 빈칸을 알고 있었습니다.

원인은 성실성이 아니라 "완료"의 정의가 없다는 것입니다. 정의가 없으면 "대부분 완료"가 "완료"로 요약됩니다.

고친 방법은 "완료"를 세 부분으로 정의하는 것입니다. 충족 조건(무엇이 확인되면 완료인가), 알려진 결함 목록(비어 있지 않으면 "완료"라는 말을 쓰지 않는다), 확인 방법(누가 무엇으로 봤는가). 결함이 있으면 "부분 완료 + 결함 목록"으로 보고하게 합니다. 종료 시점 검사에서 결함 목록이 비어 있지 않은데 보고서에 "완료"가 쓰였으면 되돌려 보내면 기계적으로 강제됩니다.

고치는 자리를 다섯 곳으로 제한하는 이유

실패를 겪은 뒤 대응이 "다음에는 더 자세히 지시하자"로 끝나면 아무것도 바뀌지 않습니다. 지시문은 매번 새로 쓰이고, 자세해진 지시문은 정의 파일로 옮겨져 첫 번째 패턴으로 돌아갑니다.

그래서 모든 수정은 다섯 곳 중 하나에만 넣고, 어디에 넣었는지 기록합니다.

같은 문제가 두 번 나왔는데 아직 기록에만 남아 있으면 게이트로 승격할 시점입니다. 반대로 게이트로 옮긴 항목은 정의 파일에서 지웁니다. 같은 내용이 문장과 검사 두 곳에 있으면 한쪽만 고쳐지는 일이 생깁니다.

팀 실패 대장은 어떤 서식으로 쓰나

같은 실패를 두 번 겪지 않으려면 기록이 필요합니다. 한 행에 아래 항목을 적습니다.

원인과 고친 곳을 정해진 목록에서만 고르게 하는 것이 요점입니다. 자유롭게 쓰게 하면 대부분 "프롬프트를 더 자세히 쓰기로 했다"로 수렴합니다. 그리고 "고친 곳"이 정의 파일에 문장 추가로만 끝난 행이 세 개를 넘으면 정의 파일을 줄일 시점이라는 신호로 읽습니다.

정리

• 이 실패들은 멈추지 않고 진행됩니다. 발견은 장치가 하고, 사람은 장치를 설계합니다.
• 보고 문장이 아니라 파일 상태·명령 출력·변경 내역을 확인의 근거로 씁니다.
• "없음"과 "완료"는 정의가 필요한 단어입니다. 정의 없이 쓰이면 둘 다 확인되지 않은 주장입니다.
• 되돌릴 수 없는 행동은 등급을 나눠 설정과 실행 직전 검사로 막습니다.
• 고친 곳을 기록하면 정의 파일이 언제 비대해졌는지도 같은 기록에서 보입니다.

이어서 볼 글은 퍼미션 설정 최적화, Hooks 가이드, 서브 에이전트로 작업 나누기입니다. 운영 중인 팀의 어긋남을 유형별로 재현하며 고치는 실습은 에이전트 팀 운영 교육을 참고하세요.