몇 개를 만들려 했는지, 몇 개가 만들어졌는지. 이 두 숫자를 같이 찍게 했더니 실패가 드러났습니다.
작업이 끝났다는 판단은 대개 느낌으로 합니다. 에러가 없었고 화면이 넘어갔으니 됐다고 봅니다. 그런데 여러 건을 한 번에 처리하는 작업일수록 이 판단이 자주 틀립니다. 열여덟 건을 처리했다고 생각했는데 실제로는 한 건도 반영되지 않은 경우가 있었습니다. 스크립트는 실패 건수를 세고 있었지만 그 숫자를 끝에서 쓰지 않았습니다. 그래서 완료 판정을 숫자 두 개의 비교로 바꿨습니다. 기대 개수와 실제 개수입니다. 두 숫자가 다르면 그 작업은 실패로 끝냅니다. 판정을 문장에서 숫자로 옮기면 사람이 해석할 여지가 사라집니다. 그리고 해석할 여지가 없어야 놓치지 않습니다.
완료를 문장으로 쓰면 매번 다르게 읽힌다
처리했습니다, 반영했습니다, 적용했습니다. 이런 말은 실제로 확인한 범위를 담지 못합니다. 한 건만 보고 쓴 문장인지 전부 보고 쓴 문장인지 구분되지 않습니다.
숫자는 다릅니다. 스무 건 중 스무 건이라고 쓰면 무엇을 확인했는지 분명합니다. 스무 건 중 열여덟 건이라고 쓰면 남은 두 건을 찾아야 한다는 사실이 같이 드러납니다.
그래서 여러 건을 다루는 모든 작업은 끝에 같은 형태의 줄을 출력하게 했습니다. 성공한 수와 전체 수를 슬래시로 붙여 한 줄로 찍습니다.
그리고 성공 수가 전체 수보다 작으면 프로그램을 실패로 끝냅니다. 이것이 빠지면 숫자를 찍어도 소용이 없습니다.
| 보고 방식 | 읽는 사람이 알 수 있는 것 |
|---|---|
| 반영했습니다 | 확인 범위를 알 수 없습니다 |
| 오류 없이 끝났습니다 | 신고된 문제가 없다는 것만 알 수 있습니다 |
| 20건 중 20건 | 전부 확인했다는 것을 알 수 있습니다 |
| 20건 중 18건 | 남은 2건을 찾아야 한다는 것을 알 수 있습니다 |
실패를 세기만 하는 스크립트가 실패를 숨긴다
흔한 형태가 있습니다. 반복문 안에서 실패할 때마다 화면에 실패 표시를 찍고, 변수 하나에 실패 수를 더합니다. 그리고 반복문이 끝나면 그냥 종료합니다.
이 구조에서는 실패가 모두 화면에 남아 있어도 프로그램은 정상 종료합니다. 사람이 화면을 끝까지 읽지 않으면 실패는 없던 일이 됩니다.
고치는 데는 두 줄이면 됩니다. 마지막에 성공 수와 전체 수를 찍고, 두 수가 다르면 종료 코드를 1로 바꿉니다.
이 두 줄이 들어간 뒤로는 자동으로 이어지는 다음 단계도 같이 멈춥니다. 실패가 조용히 다음 단계로 흘러가지 않게 됩니다.
화면에 보이는 개수는 전체 개수가 아니다
한 서비스의 관리 화면에서 예약된 항목이 비어 있다고 판단한 적이 있습니다. 목록을 열어 눈으로 봤고 아무것도 없었습니다.
실제로는 비어 있지 않았습니다. 그 목록이 기본으로 최근 몇 개만 보여 주는 화면이었고, 나머지는 아래에 접혀 있었습니다. 화면에 보이는 것을 전부로 착각한 것입니다.
그 뒤로는 목록을 눈으로 세지 않습니다. 목록의 전체 개수를 표시하는 값을 읽거나, 항목을 끝까지 펼친 뒤 세어서 숫자로 남깁니다.
화면은 요약해서 보여 주는 것이 일이고, 확인은 요약되지 않은 값으로 해야 합니다.
필터가 비면 성공이 아니라 모름이다
출력이 길면 필요한 줄만 걸러 봅니다. 그런데 걸러진 결과가 비어 있을 때 두 가지 경우가 겹칩니다. 정말 문제가 없거나, 필터가 틀렸거나입니다.
이 둘을 구분하지 않고 빈 결과를 문제 없음으로 읽으면 실패가 그대로 통과합니다.
그래서 순서를 뒤집었습니다. 필터를 만들기 전에 원문 한 건을 통째로 열어 실제 문구를 확인하고, 그 문구에 맞춰 필터를 씁니다.
이미 만든 필터가 계속 비어 있으면 필터를 손보기 전에 원문 전체를 파일로 저장해 한 번 봅니다. 대개 예상과 다른 문구가 나옵니다.
| 상황 | 잘못된 해석 | 실제 의미 |
|---|---|---|
| 필터 결과가 비어 있음 | 문제 없음 | 필터가 맞는지 모름 |
| 종료 코드 0 | 작업 성공 | 신고된 오류 없음 |
| 목록 화면이 비어 있음 | 항목 없음 | 화면이 접었을 수 있음 |
확인은 설정할 때 쓴 방법으로
값을 넣을 때와 다른 방법으로 확인하면 결과를 믿을 수 없습니다. 다른 위치를 읽거나, 다른 조건으로 찾게 되기 때문입니다.
실제로 값을 제대로 넣었는데 확인 코드가 다른 자리를 봐서 빈 칸으로 오판한 적이 있습니다. 반대로 값이 안 들어갔는데 확인 코드가 다른 자리에 남아 있던 옛 값을 읽어 통과시킨 적도 있습니다.
그래서 확인 코드는 설정 코드에서 경로를 그대로 복사해 씁니다. 새로 쓰지 않습니다.
겉으로 보이는 화면 대신 관리 화면에서 확인하는 것도 같은 이유입니다. 값이 저장된 자리와 화면에 그려지는 자리는 다를 수 있습니다.
완료 보고에 남기는 세 줄
정리하면 작업 하나가 끝날 때 남기는 것은 세 줄입니다.
기대 개수와 실제 개수, 실제로 본 완료 문구, 그리고 확인하지 못한 항목입니다.
세 번째 줄이 특히 중요합니다. 확인하지 못한 것을 적어 두지 않으면 다음 사람이 그것을 확인된 것으로 취급합니다.
이 세 줄은 형식이 아니라 절차입니다. 채워 넣으려면 실제로 세어 보고, 실제로 읽어 보고, 무엇을 못 봤는지 인정해야 합니다.
자주 묻는 질문
Q. 개수를 세라는 게 구체적으로 무슨 뜻인가요?
A. 만들려던 항목 수와 실제로 만들어진 항목 수를 같은 자리에서 출력하는 것입니다. 두 수가 다르면 프로그램을 실패로 끝내 다음 단계가 이어지지 않게 합니다.
Q. 목록 화면으로 확인하면 왜 안 되나요?
A. 목록 화면은 대개 일부만 보여 줍니다. 비어 있다고 판단했던 목록이 실제로는 접혀 있던 적이 있습니다. 전체 개수를 나타내는 값을 읽거나 끝까지 펼친 뒤 세야 합니다.
Q. 확인 코드를 따로 잘 만들면 되지 않나요?
A. 새로 만들면 설정할 때와 다른 경로를 보게 됩니다. 없는 문제를 만들거나 있는 문제를 놓칩니다. 설정 코드의 경로를 그대로 복사해 읽는 편이 안전합니다.
확인 자료
- AI 개발루틴 현장 부록 v1.3 — 2026-09-05~06 운영에서 나온 실패 19건 분류 (2026-09-06 정리)
- 본 블로그 운영 중 2026-09-09에 직접 겪은 사례 기록
이 글은 직접 겪은 작업 기록을 정리한 것입니다. 확인하지 못한 항목은 본문에 쓰지 않았습니다. 대표 이미지는 이해를 돕기 위한 참고용 이미지입니다.