AI 에이전트 완료 확인 기준 3단계
Claude Code에 실무(스프레드시트 업데이트, 외부 툴로의 스크립트 편집, SNS 게시 예약)를 맡기기 시작하면, 반드시 한 번은 밟게 되는 것이 “됐다고 했는데, 되어 있지 않다”입니다. 저는 2026년 7월부터 9월 사이에, 적어도 2번은 분명한 형태로 겪었습니다. 이 글은 그 기록과, 거기서 정한 “완료”의 정의입니다.
1번째: edits applied라고 돌아왔는데 아무것도 바뀌지 않음
7월 19일. 메인 Claude Code 대화(저는 “비서”라고 부르고 있습니다)가, Roblox Studio MCP(게임 개발 환경을 Claude Code에서 조작하는 MCP 서버)의 multi_edit로 서버 스크립트를 replace_all: true로 일괄 치환했습니다.
툴은 “edits applied”라고 성공을 반환했습니다. 그러나 실제 스크립트에는 반영되어 있지 않았습니다. 같은 날 2번 연속으로 일어났습니다. 발견된 계기는, 구현했어야 할 장비 효과가 작동하지 않는다는 버그를 제가 플레이 테스트에서 밟았을 때였습니다. 비서는 툴의 응답만 보고 반영된 것으로 간주한 채 다음 작업으로 진행하고 있었습니다.
툴의 버그인지 사양인지 는 알지 못합니다. 알고 있는 것은 “성공이라고 반환해도 반영되지 않는 경우가 있다”는 사실뿐이고, 운영 규칙으로는 그것만으로 충분했습니다.
고치는 방법은 다음과 같습니다.
replace_all을 그만두고, 주변 행을 포함한 문맥이 있는 개별 편집으로 바꾼다
- 편집 후에는 반드시 읽기 툴로 본문을 읽어 반영을 확인한다. 검색 툴의 행 번호는 캐시 때문에 오래될 수 있으므로, 최종 확인은 본문을 읽어서 한다
2번째: 다시 읽어 봤을 때는 맞았는데, 나중에 되돌아가 있었음
8월 17일. 비서가 Google Sheets에 기획 구성을 써 넣고 “수정했습니다”라고 보고했습니다. 쓰기 API는 성공을 반환했고, 비서는 직후에 다시 읽어 올려 올바른 내용이 들어가 있는 것도 확인했습니다. 그런데 나중에 제가 화면을 열어 보니, 옛 내용으로 돌아가 있었습니다. 원인은 특정하지 못했습니다.
1번째보다 더 까다롭습니다. 비서는 다시 읽기를 했습니다. 그래도 부족했습니다. 원인은, 한 번의 다시 읽기를 “확정됐다”의 증거로 삼았기 때문입니다. 쓰기 직후의 다시 읽기는 “그 순간에는 들어 있었다”까지만 보장합니다.
저는 “수정했습니다는, 스프레드시트 업데이트가 끝난 뒤에 말해”라고 지적했습니다. 당시에는 감정적인 말투였지만, 나중에 보니 요구사항 그 자체였습니다. 저에게 “끝났다”는 “제가 화면에서 봤을 때 들어 있다”입니다. 비서에게 “끝났다”는 “API가 성공을 반환했다”였습니다. 정의가 다르면, 둘 다 거짓말을 하지 않았는데도 거짓말을 들은 체험이 됩니다.
정한 “완료”의 정의
3가지로 정리했습니다.
- 반영을 확인한 뒤에 “했습니다”라고 말한다 . 쓰기 → 직후에 다시 읽어 대조 → 일치 확인 후 보고한다. 제가 화면에서 확인하는 시점이 더 늦다면, 그 직전에 다시 한 번 읽어 본다. “〜합니다”(예고)와 “〜했습니다”(완료)를 같은 메시지에 섞지 않는다
- 예상보다 시간이 오래 걸리면, 다음 재시도 전에 상담한다 . 같은 작업이 실패를 반복하거나, 왕복이 여러 번 필요하다고 느낀 시점에서 상황을 보고하고, 계속할지 다른 방법을 쓸지 저에게 결정하게 한다. 실패 비용이 큰 작업일수록 더 빨리
- 제시하기 전에 자문하고, 결함을 먼저 신고한다 . 숫자나 체크 항목을 처리했다는 이유만으로 제시하지 않는다. “대체품으로 처리한 부분”, “자신이 없는 부분”은 보고의 앞부분에 적는다
3번째는, 영상 합성에서 “그림자가 대체품이라는 걸 알면서도 말없이 제시했다”는 또 다른 실패에서 왔습니다. 몰랐던 결함은 어쩔 수 없습니다. 알고 있던 결함을 말하지 않는 것은, 판단 재료를 저에게서 빼앗는 행위였습니다.
바로 쓸 수 있는 확인 절차
- “했습니다”라고 쓰기 전에, 그 상태를 스스로 다시 읽어 봤는지 확인한다. 다시 읽지 않았다면 “써 넣었습니다, 반영 확인 중입니다”라고 쓴다
- 같은 에러가 2번 연속 나오면, 3번째 전에 한마디 넣는다
- 결과물을 제시하는 문장의 앞부분에 “이번에 자신 없는 점”을 1개 이상 쓴다. 쓸 수 없다면, 아직 점검이 부족한 것이다
이것을 Claude Code의 설정 파일(CLAUDE.md)과, 비서가 자기용으로 남기는 교훈 메모에 적어 둔 뒤로, 같은 유형의 사고는 발생하지 않았습니다(9월 19일 기준).
이 글은, 제가 운영에서 실제로 망가뜨린 12가지 장면을 실패 장부 형식으로 정리한 책 『Claude Code에 7부서를 맡겨서 망가진 12가지 장면과, 작동한 수정 방법』의 제3·4·13장을 바탕으로 합니다. “서문”과 제1·2·5장은 무료로 읽을 수 있습니다.
출처
- 원문: https://zenn.dev/akira_books/articles/9e2a9462b72231 (2026-09-21 · akira books)