읽을 문서가 너무 많아서, 두 실행을 나란히 놓고 봤다

2026.11.12 게시

Agent가 쓴 문서, 읽다가 지쳤다 — AI Agent들이 쏟아내는 문서 더미 앞에서 망연자실한 개발자

요즘 개발이 예전만큼 재미있지 않았다.

처음에는 내가 코드를 직접 안 써서 그런 줄 알았다. 코드를 보면서 개발하던 때가 더 재미있었다는 이야기를 Agent와 하다가, 원인이 다른 데 있다는 걸 알았다.

코드를 못 써서가 아니었다. Agent가 만들어내는 문서를 너무 많이 읽어야 해서였다.

목차
  1. 이해가 만들어지던 과정이 빠졌다
  2. 검증 기준이 틀렸으면 누가 찾나
  3. 전부 이해할 수는 없다
  4. 다이어그램 다섯 개를 그려 봤다
  5. 시뮬레이터를 만들었다가 걷어냈다
  6. 한 사례로 해 봤다
  7. 화면보다 단어가 문제였다
  8. 대체로 맞았는데 한 줄에서 틀렸다
  9. 스킬에 남긴 것
  10. 아직 확인하지 못한 것
  11. 다시 따라가는 느낌

이해가 만들어지던 과정이 빠졌다

예전에는 코드를 읽으면서 함수 호출과 데이터 흐름, 예외 처리를 따라갔다. 그러는 동안 시스템이 머릿속에 그려졌다. 개발하는 것과 이해하는 것이 같은 시간에 일어났다.

지금은 Agent가 구현을 끝내고 결과 문서를 준다. 나는 중간 과정 없이 완성된 결론을 이해해야 한다.

예전 지금
코드를 따라가며 이해가 생김 구현이 끝난 뒤 결과를 전달받음
개발과 이해가 같이 진행 개발과 이해가 분리
흐름을 직접 추적 결과 문서와 검증 보고서를 검토

Agent가 코드를 만드는 속도를 내가 이해하는 속도가 따라가지 못한다. 이걸 이해 부채라고 부르는 글들이 있다.

문서 품질이나 요약 방식의 문제로 볼 수도 있었다. HTML로 보기 좋게 만들어 보기도 했다. 그런데 화면이 예뻐져도 글자가 많으면 달라지는 게 없었다. 이해가 만들어지던 과정이 통째로 없어진 것이 문제였다.

검증 기준이 틀렸으면 누가 찾나

「Agent에게 어디까지 맡길까를 묻다가」에서 하던 고민과 이어진다.

개발자가 갈 수 있는 방향은 둘로 보였다. 도메인과 코드 흐름을 충분히 이해하고 직접 판단하는 쪽, 아니면 Agent가 안정적으로 개발하도록 환경과 검증을 설계하는 쪽이다. 꼭 하나만 고를 필요는 없다.

다만 둘째 쪽으로만 가면 남는 질문이 있다.

내가 충분히 이해하지 못하는 시스템을, 검증 체계만으로 믿을 수 있나.

Agent가 구현하고 다른 Agent가 검증해도, 검증 기준 자체가 틀렸다면 그걸 발견할 사람이 없다. 17편에서 적었듯 검사를 돌리고 통과했는데도 요구를 증명하지 못한 경우를 이미 겪었다.

전부 이해할 수는 없다

그렇다고 모든 구현을 깊게 이해하겠다는 것도 현실적이지 않다. 모델도 기술도 너무 빨리 바뀐다.

그래서 이해의 깊이를 고정하지 않고 고르기로 했다.

깊이 대상 내가 하는 일
깊은 이해 핵심 비즈니스 규칙, 데이터 정합성, 보안 직접 따라가고 판단
구조만 이해 아키텍처, 모듈 경계, API 계약 관계와 영향을 파악
검증에 맡김 반복 구현, 위험이 낮고 되돌릴 수 있는 곳 검증 결과를 확인

여기에는 역설이 하나 있다. 무엇을 이해하지 않아도 되는지 판단하려면, 최소한 전체 구조와 위험은 알아야 한다.

다이어그램 다섯 개를 그려 봤다

그럼 덜 읽고 이해하는 방법이 있을까. 사람이 복잡한 걸 머리에 다 담지 못해서 그림을 그리기 시작했다는 데서 출발했다.

개인 Android 앱의 채팅 전송 과정을 골랐다. 메시지를 보내면 여러 컨텍스트를 조립해 모델 응답을 받고 결과를 저장하는 흐름이다. 이걸 다섯 가지로 그리게 했다. 분기형 흐름도, 시퀀스 다이어그램, 스윔레인, 상태 전이도, 컨텍스트 의존성 지도.

각각 쓸모는 있었다. 그런데 보고 나서 든 생각은 이거였다.

“다 전통적인 방식이네.”

기존 다이어그램에 디자인을 입힌 것이었다. 여전히 완성된 설명을 받아 읽는 일이었다.

내가 코드를 읽으며 이해할 때는 설명의 순서를 따르지 않았다. 궁금한 순서대로 따라갔다. 이 값이 왜 이렇지, 여기서 실패하면 어떻게 되지, 하면서. 필요한 건 더 좋은 그림보다 내가 궁금한 순서대로 넘겨 볼 수 있는 것이었다.

시뮬레이터를 만들었다가 걷어냈다

그다음에 나온 아이디어는 다섯 가지였다. 3D 시스템 지도, 실행 흐름 재생, 살아 있는 데이터 흐름, 변경 영향도 지도, 시나리오 시뮬레이터. 그중 실행 흐름 재생과 시뮬레이터를 합치는 쪽이 가장 그럴듯해 보였다. 조건을 바꾸면 분기가 어떻게 달라지는지 직접 볼 수 있으니까.

그렇게 만든 것이 앞 버전인 Decision Explorer다. 선택지와 조건을 눌러 보면 조건별 결과가 바뀌는 화면으로, 영향을 이해한 뒤 결정하게 돕는 스킬이었다. 결정 계약, 선택 상태 저장, Python 검증기를 붙였고 계약 검사 53개와 브라우저 회귀 검사 18개를 통과시켜 두었다.

장치는 잘 돌았다. 그런데 동봉한 예시는 실제 로그가 없는 가상 사례였고, 검사가 통과한다는 것이 화면에 나온 결과가 사실이라는 뜻은 아니었다. 내가 더 잘 이해하게 됐다는 증거도 아니었다.

조건을 마음대로 바꿔 볼 수 있는 화면은, 실제로 실행해서 확인한 결과와 Agent가 코드를 읽고 추정한 결과를 같은 모양으로 보여 주게 된다. 내가 원한 건 믿을 수 있는 이해였는데, 그럴듯한 추정을 사실처럼 보게 되면 반대로 간다.

그래서 걷어냈다. 계약, 상태 저장, 검증기를 전부 뺐고 커밋 하나에서 1,431줄이 지워졌다. 이름도 Behavior Explorer로 바꿨다.

새 버전에는 이렇게 적었다. 실제로 캡처한 두 실행만 나란히 놓는다. 자동 재생, 임의 입력, 자유 시뮬레이션은 넣지 않는다.

목표도 바뀌었다. 앞 버전의 끝은 결정이었다. 지금은 필요한 동작을 이해했거나, 남은 범위와 검증 기준을 정해 맡겼으면 끝이다. 결정을 꼭 내려야 하는 건 아니다.

한 사례로 해 봤다

개인 앱의 재시도 로직으로 해 봤다. 질문은 이거였다.

“재시도는 넣었다는데, 어떤 실패에서 실제로 다시 시도하는 거야?”

재시도 한도는 둘 다 3회로 두고, retryable만 바꿔 결정 함수를 실제로 호출한 기록 두 개를 만들었다.

  재시도 함 재시도 안 함
바꾼 입력 retryable=true retryable=false
시도 0의 결정 decisionRetry=true decisionRetry=false
이후 기록 시도 1·2·3 없음

화면은 한 번에 사건 하나만 보여 준다. 이전·다음으로 넘기고, 같은 위치에서 두 실행을 바꿔 볼 수 있다. 첫 차이로 바로 가는 버튼이 있고, 원본 기록과 코드 위치를 펼쳐 볼 수 있다.

재시도 비교 화면을 브라우저에서 조작하는 모습

재시도 비교 화면. 캡처한 기록을 넘겨 보는 페이지이고, 앱을 다시 실행하는 것은 아니다.

같은 기록을 표로도 만들어, 화면과 표로 각각 질문에 답해 봤다. 나는 화면 쪽이 더 이해하기 쉬웠다.

그런데 정작 배운 건 다른 데 있었다.

화면보다 단어가 문제였다

이해를 가장 막은 건 배치보다 이름이었다.

처음에는 두 실행을 “기준 실행 / 대조 실행”이라고 불렀다. 실험하는 쪽에서는 자연스러운 이름인데, 보는 쪽에서는 어느 게 뭔지 계속 다시 확인해야 했다. “다시 보내면 될 수도 있는 실패”처럼 풀어 쓴 이름은 너무 길었다.

“재시도 함 / 재시도 안 함”으로 바꾸니 통했다. 결과가 어떻게 다른지를 개발자가 소리 내어 말할 만한 가장 짧은 말로 부르는 것이다.

하나 더 있었다. 나는 화면을 보고 재시도 한도가 3으로 올라갔다고 믿었다. 실제로는 양쪽 다 3이었다. 달라진 값은 강조돼 있었지만, 강조되지 않은 값이 같다는 말은 어디에도 없었다. 그래서 “재시도 한도는 둘 다 3회입니다”를 문장으로 적게 했다. 같다는 것도 말해 줘야 안다.

대체로 맞았는데 한 줄에서 틀렸다

질문에는 대체로 맞게 답했다. 그런데 이해한 내용을 한 줄로 다시 말해 보니 틀린 믿음이 하나 나왔다.

“이해했다”는 느낌과 실제로 이해한 것 사이에는 차이가 있었다. 「이해하지 못하는 결정을 승인한다는 것」에서 걱정하던 것과 같은 종류다.

다만 이걸 퀴즈로 만들지는 않았다. 스킬은 탐색이 끝나면 “원하면 이해한 내용을 한 줄로 말해 주세요”라고 권하기만 한다. 요구하지 않고, 그것 때문에 작업을 늦추지도 않는다. 틀린 부분만 고쳐 준다.

스킬에 남긴 것

남긴 건 많지 않다.

끼어드는 때를 좁혔다. 동작을 이해해 달라는 요청이 있을 때, 그리고 질문·완료 보고·병합 직전에 결과를 바꾸는 경계가 있을 때만 움직인다. 일반 디버깅, 단순 수정, 이미 승인한 작업에는 아무것도 붙이지 않는다. 볼 게 없으면 “탐색할 사항 없음” 같은 말도 하지 않는다.

시작점은 하나다. 보통 0~1개, 서로 독립적인 중요한 경계가 있을 때만 3개까지 제안한다. 읽을 것을 줄이려고 만든 스킬이 읽을 것을 늘리면 안 된다.

근거 종류를 붙인다.

표시 의미
실행 확인 명시한 입력과 환경에서 실제로 기록한 값
코드 추정 코드에서 추론했지만 실행하지 않은 경로나 인과
가상 예시 가능성을 설명하려고 만든 사례
미확인 현재 근거로 판단할 수 없음

재시도 사례에서도 이 구분이 필요했다. 실제로 실행한 건 결정 함수뿐이었다. 시도 번호를 하나씩 올린 건 테스트 코드였고, 워커가 정말 다시 실행되는지, 네트워크 실패나 대기 시간이 어떤지는 확인하지 않았다. 화면에는 그 값들에 “코드 추정”이 붙어 있다. 테스트가 통과했다는 것과 실행 기록이 있다는 것은 다르다.

짧은 건 대화로 답한다. 화면은 같은 값과 사건을 여러 번 비교해야 할 때만 만든다.

아직 확인하지 못한 것

해 본 건 나 혼자, 사례 하나다. 분기가 짧고 차이가 분명해서 화면에 유리한 사례이기도 했다. 평가 사례 10개는 적어 두었지만 아직 돌려 보지 않았다. 실제 함수 출력을 캡처하려고 임시 테스트 파일과 JDK 설정이 필요했는데, 그 비용도 따져 봐야 한다.

그래서 버릴 기준을 미리 적어 두었다. 이렇게 유리한 사례에서도 화면이 표보다 되돌아가서 찾고 비교하는 일을 줄이지 못하면, 화면을 이 스킬의 중심에서 뺀다. 더 빨랐다는 것만으로는 남기지 않는다.

다시 따라가는 느낌

처음 질문으로 돌아간다. 개발이 재미없어진 건 문서를 너무 많이 읽어야 해서였다.

화면을 직접 눌러 봤을 때는 IDE에서 함수를 따라 들어가며 분석하던 때와 느낌이 비슷했다. 완성된 설명을 받아 읽지 않고, 궁금한 곳을 내가 골라서 따라갔다.

스킬을 쓰지 않더라도 가져갈 만한 건 세 가지다.

  • 두 경우를 비교할 때는 결과가 어떻게 다른지를 가장 짧은 말로 부른다.
  • 같은 값은 같다고 말해 준다. 강조하지 않았다고 해서 같다는 뜻으로 읽히지는 않는다.
  • 이해했다고 느껴도 한 줄로 다시 말해 본다.

스킬은 여기에 있다. Claude Code와 Codex에서 쓸 수 있고, 저장소 이름은 앞 버전의 것을 그대로 두었다.