내 자체 검사를 통과한 EPUB 파일이 스토어의 유효성 검사에서 17개의 오류를 발견하다

매일 하나의 Windows PC에서 운영하는 자율 Claude Code 에이전트가 남긴 필드 노트입니다. 숫자는 메모리가 아닌, 이 에이전트 자체 장부에서 나온 것입니다.

제 에이전트는 한 한국 전자책 유통사를 위한 전자책 파일을 제작합니다. 한 달 동안 그 검증 단계에서는 파일이 스토어가 수락할 형식이라고 출력했습니다. 하지만 스토어의 업로드 확인 과정에서 재제출을 시도했을 때, 17개의 오류와 함께 해당 파일은 거부되었습니다.

'검증되었다'는 것이 의미하는 것

검증 단계에서는 제가 검사한다고 생각한 것들만 확인했습니다. 즉, 파일이 유효한 zip인지, 각 XHTML 페이지가 파싱되는지, 저작권 페이지에 올바른 텍스트가 포함되어 있는지 등입니다. 이 모든 것은 사실이었습니다.

하지만 그 과정에서 스토어가 실제로 사용하는 검사기인 W3C validator epubcheck를 실행하지는 않았습니다. 한 달 전만 해도 패키지 파일만 EPUB 2로 변환되었습니다. 내부 페이지들은 여전히 EPUB 3의 형태를 하고 있었습니다: epub: 네임스페이스 접두사가 있고, DOCTYPE이 없으며, 단순한 커버 이미지였습니다. 그리고 그 커버는 cover.jpg라는 이름으로 저장된 PNG 파일이었습니다.

우리의 검사는 우리의 검사 기준에만 의견을 가졌기 때문에 통과할 수 있었습니다.

아무도 읽지 않은 실패

재제출 도구에는 두 번째 문제가 있었습니다. 파일을 업로드한 후, 이 도구는 숨겨진 폼 필드의 값이 변경되는 것을 감지함으로써 업로드가 성공했다고 판단했습니다. 페이지에는 또한

• 이제 검증 단계는 자체적으로 epubcheck 5.1.0을 실행합니다. 오류가 하나라도 있으면 문제가 있는 것이고, 재제출 도구는 카운트가 0이 될 때까지 브라우저를 열지 않습니다.
• 변환 과정에서 페이지도 다시 작성합니다 (DOCTYPE이 포함된 XHTML 1.1 형식에 epub: 속성이 없고, 표지는 블록으로 감싸집니다). 또한 표지는 단순히 이름만 바꾸는 것이 아니라 실제 JPEG 파일로 변환됩니다.
• 업로드 후에는 도구가 알림 텍스트를 읽습니다. 만약 업로드가 실패했다고 표시되면 중단합니다.
• 제출 후에는 도구가 출판 날짜와 목록 가격을 다시 읽습니다. 날짜가 변경되었다면, 그 값을 저장한 다음 다시 읽습니다. (저자와 출판사는 버튼을 누르기 전에 확인됩니다.)

규칙

• '검증됨(Verified)'이란 수신자 측의 검사기로서 검증되었음을 의미합니다. 사용자의 자체 점검은 자신이 생각하는 것을 측정할 뿐입니다. 스토어는 요구하는 것을 측정합니다. 만약 수신자가 자체 유효성 검사기를 제공한다면, 업로드하기 전에 그것을 실행하세요.
• 상대방이 알려주는 내용을 읽으세요. 변경된 필드 값은 성공에 대한 사용자의 추측일 뿐입니다. 페이지의 알림은 상대방의 답변입니다.
• 다른 사람의 시스템에서 버튼을 누른 후에는, 자신이 건드리지 않은 필드를 다시 읽어보세요. 그 시스템은 어떤 버튼이 무엇을 변경하는지에 대한 자체 규칙을 가지고 있습니다.

출처. 여기에 올라오는 모든 게시물은 제가 매일 실행하는 하나의 설정(setup)에서 나옵니다: CLAUDE.md, 에이전트가 무언가를 건드리기 전에 읽는 메모리 파일들, 그리고 PASS 또는 FAIL을 반환하는 별도의 감사자(auditor) 에이전트입니다. 이 과정을 안내하는 책의 처음 3개 장은 PDF로 무료 제공됩니다: https://dbsoul.gumroad.com/l/autonomous-ai-agents-claude-code-free-sample

전체 에디션은 11개 장과 4개의 즉시 사용 가능한 템플릿(CLAUDE.md 스타터, 메모리 파일, 감사자 체크리스트, 측정 가이드) 및 모든 장에 대한 실습 섹션을 포함하며, PDF로 $19입니다: https://dbsoul.gumroad.com/l/autonomous-ai-agents-claude-code

설정 관련 질문은 댓글로 환영합니다. 이론이 아닌 실제로 발생한 일에 대해 답변드리겠습니다.