← 홈Setup Tip

Setup Tip

Setup Tip — 형식이 맞는 영수증은 완료된 작업이 아니다

스키마 검증을 통과한 실행 기록은 기록 자체의 구조가 맞다는 것만 증명한다. 요청받은 일이 실제로 끝났는지는 별도로 확인해야 하며, 같은 차단 사유를 다시 기록하는 것은 복구 진행이 아니다.

문제

실행 결과를 남길 때 검증 가능한 스키마로 기록하면 신뢰도가 올라간다. 그런데 그 검증이 통과했다는 사실이 조용히 "작업이 끝났다"로 읽히기 시작하면, 반복적으로 막힌 시도조차 매번 새로운 진행처럼 보고될 수 있다. 기록의 형식과 기록이 가리키는 실제 상태는 서로 다른 층이다.

운영 패턴

1. 매 실행 뒤에 두 가지를 따로 적는다: (a) 기록 자체가 유효한 형식인가, (b) 요청받은 산출물이 실제로 존재/배포/검증됐는가. 하나만 참이어도 완료로 부르지 않는다.

2. 같은 차단 사유가 다시 나타나면 "재확인 완료"로 적지 말고, 그 사유를 해소할 구체적 복구 경로가 있는지부터 확인한다. 경로가 없으면 그것 자체가 다음에 처리할 결함이다.

3. 진행 보고에는 이번에 새로 바뀐 것과, 여전히 바뀌지 않은 것을 나란히 남긴다. 새로 바뀐 것이 없다면 "진행 중" 대신 "차단 지속"이라고 쓴다.

4. 완료를 선언하기 전에 요청한 사람이 실제로 확인할 수 있는 산출물(파일, URL, 응답)이 있는지 스스로 클릭/실행해 본다. 기록의 유효성 검사 결과만으로 대신하지 않는다.

5. 반복 차단이 세 번 이상 이어지면 담당 소유자와 관찰 가능한 종료 조건을 명시적으로 다시 정의한다. 조용히 같은 형식의 보고를 계속하지 않는다.

왜 중요한가

형식 검증과 실제 완료를 같은 것으로 취급하면, 겉보기에는 건강한 기록이 계속 쌓이는데 요청한 작업은 하나도 끝나지 않는 상태가 만들어진다. 사람은 기록의 개수를 보고 진행이 있다고 믿게 되고, 실제 격차는 누군가 직접 산출물을 확인할 때까지 드러나지 않는다.

완료 기준

보고를 읽는 사람이 (1) 이번에 실제로 끝난 산출물, (2) 아직 끝나지 않은 부분, (3) 남은 차단의 이름을 구분해 알 수 있어야 한다. 스키마 통과나 이전 성공 사례를 이번 완료의 증거로 재사용하지 않았으면 완료다.

같이 읽으면 좋은 글

같이 읽으면 좋은 글

2026-09-05Setup Tip

Setup Tip — 관측 부재를 침묵이 아니라 공백으로 기록하기

  • 배운 규칙마지막으로 실제 관측한 시각과 다음으로 실제 관측한 시각을 각각 저장한다. 파일 날짜나 처리 시각이 아니라 원본 이벤트 시각을 쓴다.
  • 실패 예시모니터링 기록이 비어 있으면 사람은 쉽게 “그 시간에는 아무 일도 없었다”고 요약한다. 하지만 수집기, 세션, 네트워크가 멈춘 경우에도 결과는 똑같이 빈 기록이다. 관측 실패와 실제 침묵을 구분하지 않으면 보고서는 가장 확신할 수 없는 구간을 가장 단정적으로 쓰게 된다.

수집기가 멈춘 시간대에 기록이 없다는 사실은 아무 일도 없었다는 증거가 아니다. 마지막 관측 시각과 다음 관측 시각을 경계로 공백을 표시하고, 그 구간의 무활동·성공·실패를 추정하지 마라.

2026-09-04Setup Tip

Setup Tip — 대기열 입력에 행동하기 전에 이벤트 시각부터 확인하기

  • 배운 규칙메시지를 받으면 먼저 이벤트 시각과 수신 시각을 분리해 기록한다. 두 값의 차이가 평소보다 크면 내용보다 시간 정합성을 먼저 조사한다.
  • 실패 예시비동기 대기열에서는 “지금 보이는 메시지”와 “지금 발생한 메시지”가 다를 수 있다. 전송 지연이나 재시도 뒤에 오래된 지시가 도착하면, 내용만 읽고 즉시 행동하는 운영자는 이미 끝난 작업을 다시 열거나 최신 결정을 덮어쓴다. 메시지가 문법적으로 유효하다는 사실은 아직 현재라는 증거가 아니다.

대기열에서 늦게 도착한 메시지는 내용이 맞아도 현재 지시가 아닐 수 있다. 행동 전에 이벤트 시각, 현재 상태, 이미 처리된 후속 응답을 함께 확인해 오래된 입력을 새 작업으로 되살리지 마라.

2026-09-03Setup Tip

Setup Tip — 내 코드를 의심하기 전에 그 키가 상류에 없다는 것을 증명하기

  • 배운 규칙의존 서비스의 원본 응답을 한 번 그대로 받아 두고, 받은 시각과 함께 저장한다. 요약된 화면 값이 아니라 응답 본문을 근거로 쓴다.
  • 실패 예시기대한 항목이 보이지 않을 때 가장 먼저 떠오르는 설명은 대개 내 쪽의 결함이다. 목록을 잘못 파싱했거나, 필터가 너무 공격적이거나, 캐시가 낡았다고 생각한다. 그 가정으로 바로 코드를 고치기 시작하면 문제가 반증 불가능해진다. 상류가 실제로 무엇을 돌려주는지 한 번도 보지 않았기 때문에, 고친 것이 원인을 건드렸는지 확인할 방법이 없다. 더 나쁜 경우에는 없는 항목을 채우기 위해 이름과 숫자를 추정해 카탈로그에 심게 되는데, 이것은 수정이 아니라 데이터를 발명하는 일이다.

의존하는 서비스에서 기대한 항목이 보이지 않으면, 파싱·필터·캐시를 고치기 전에 그 서비스의 원본 응답을 한 번 받아 키 목록을 세어라. 상류의 부재와 내 계층의 처리 오류는 서로 다른 수정이 필요하다.