글쓰기 리뷰 지적 10건 중 4건은 이미 가이드에 있던 내용이었습니다

발행한 글 한 편을 외부 마케팅 도구의 브랜드 리뷰 기능으로 검토했습니다. 지적은 10건이었습니다. 심각도별로는 높음 0건, 중간 4건, 낮음 6건이었습니다. 숫자만 보면 큰 문제는 없어 보였습니다.

하지만 내용을 하나씩 읽어 보니, 4건은 이미 글쓰기 가이드에 적어 둔 규칙을 지키지 않은 것이었습니다.

제목에 검색어를 넣습니다.

세 가지 이상을 나열할 때는 목록 블록을 사용합니다.

내부링크는 2~4개를 넣습니다.

실제로 측정하지 않은 숫자는 쓰지 않습니다.

같은 주에 발행한 다른 글에서는 개발자 속어가 세 차례 그대로 사용됐습니다. 이 문제는 도구가 아니라 사람이 발견했습니다. 두 사례 모두 규칙은 이미 있었습니다. 빠진 것은 규칙을 확인하고 적용하는 과정이었습니다.

가이드에 규칙을 추가하는 것만으로는 부족했습니다

지적을 받으면 가장 먼저 떠오르는 대응은 가이드에 한 줄을 추가하는 것입니다. 작업이 간단하고, 곧바로 대응했다는 느낌도 줍니다. 하지만 이번에 지적받은 네 가지는 이미 가이드에 있었습니다. 같은 내용을 다시 적는 것만으로 문제가 해결될지는 알 수 없었습니다.

가이드를 읽었다고 해서 모든 규칙을 빠짐없이 적용하는 것도 아닙니다. 매번 사람과 에이전트의 주의력에 의존하면, 문서에 있는 규칙도 작업 중에 놓칠 수 있습니다.

대응 방법을 세 가지로 나눠 비교했습니다.

검수 기록이 없다는 점도 문제였습니다. 글을 통과시킨 이유가 남아 있지 않으면, '확인한 뒤 문제가 없다고 판단한 것'과 '확인하지 못한 것'을 구분하기 어렵습니다.

검사·검수·가이드의 역할을 나눴습니다

기계 검사를 추가하되, 모든 판단을 기계에 맡기지는 않았습니다. 확인할 내용에 따라 역할을 세 가지로 나눴습니다.

개수와 포함 여부는 검사 스크립트가 확인합니다. 글자 수, 내부링크 개수, 목록 블록 유무처럼 조건이 명확한 항목입니다.

문맥은 검수 에이전트가 확인합니다. 표의 라벨과 본문 설명이 맞는지, 처음 등장한 용어에 설명이 있는지, 근거 없는 효과를 주장하는지 살펴봅니다.

문체와 선호는 가이드에 남깁니다. 숫자나 포함 여부만으로 판정하기 어려운 표현과 톤의 기준입니다.

이렇게 나누면 가이드에만 맡겨 두었던 확인 작업을 실제 검사 과정으로 옮길 수 있습니다. 가이드는 작성 기준을 설명하고, 검사와 검수는 그 기준이 적용됐는지 확인합니다.

검사 네 가지를 추가하고, 하나만 자동 중단 조건으로 뒀습니다

출력 검사 스크립트에 네 가지 항목을 추가했습니다. 결과는 FAIL 과 WARN 으로 나눴습니다. FAIL 은 후속 작업을 중단하는 판정이고, WARN 은 추가 확인이 필요한 경고입니다.

ALT 는 이미지를 설명하는 대체 텍스트입니다. 이미지 내용을 이해하는 데 필요한 문장이므로, 파일명 대신 구체적인 설명이 들어가는지 확인했습니다.

자동 중단 조건을 하나만 둔 이유는 나머지 세 항목에 문맥 판단이 필요하기 때문입니다. 기계는 목록 블록이 없는지 정확히 셀 수 있습니다. 하지만 그 글에 목록이 필요한지는 별도로 판단해야 합니다.

제목에 태그의 단어가 들어 있는지도 확인할 수 있지만, 그것만으로 좋은 제목인지 알 수는 없습니다. 경고와 실패가 발생했을 때 어떻게 대응할지도 작업 절차에 적었습니다.

모든 경고에서 작업을 멈추면 검사에 맞추기 위해 단어를 억지로 넣거나 불필요한 목록을 만들 수 있습니다. 그래서 세 항목은 경고로 남겼습니다.

문제가 있는 글을 검사했을 때 실제로 걸리는지 확인했습니다

검사를 추가한 뒤에는 지적받았던 글의 형태를 재현한 테스트 데이터를 만들었습니다. 이런 검증용 데이터를 '픽스처'라고 합니다. 문제가 있는 픽스처에서는 FAIL 1건과 WARN 3건이 나왔습니다. 정상 픽스처는 모두 통과했습니다.

확인하려던 문제를 검사 스크립트가 실제로 구분한 것입니다. 정상 데이터가 통과하는지만 보면 검사가 작동하는지 알기 어렵습니다. 문제를 재현한 데이터도 통과한다면, 그 검사는 해당 문제를 잡지 못하고 있는 것입니다.

코드 테스트에서도 비슷한 경험이 있었습니다. 검증 코드를 지웠는데도 테스트 24건이 그대로 통과했습니다. 테스트가 통과했다는 사실과 필요한 조건을 검사했다는 사실은 별개였습니다.

ALT 가 발행 화면에 전달되는지도 확인했습니다

ALT 를 검사하더라도 그 값이 발행 과정에서 사라진다면 검사만으로는 부족합니다. 실제로 어디까지 전달되는지 배포 코드를 확인했습니다. 사용 중인 블록 에디터의 이미지 블록에는 캡션과 별도로 'name' 속성이 있었고, 렌더링 코드는 이 값을 HTML 이미지의 'alt' 속성으로 사용하고 있었습니다.

이미지 적용 스크립트가 name 에 대체 텍스트를 넣도록 수정했습니다. 이미지를 다시 적용할 때 기존 대체 텍스트가 파일명으로 덮어써지지 않도록 처리도 보완했습니다.

해당 코드에는 'alt 자리가 없어 버린다'는 오래된 주석이 있었습니다. 실제 동작과 다른 설명이었습니다. 주석을 지우는 대신, 기존 설명이 틀렸다는 정정 내용을 함께 남겼습니다. 다음에 코드를 확인할 때 같은 오해를 반복하지 않도록 하기 위해서입니다.

속어는 원문 기록부터 고쳤습니다

속어 문제는 글쓰기 단계만 확인해서는 해결되지 않았습니다. 발행된 글에 '규칙이 먹습니다'라는 표현이 세 번 등장했는데, 그 출발점은 제가 작성한 내부 기록이었습니다. 작가 에이전트는 그 표현을 그대로 옮겼습니다.

글쓰기 가이드에 '피하는 표현·통일하는 용어' 절을 추가하고, 속어를 대신할 표현을 정리했습니다. 여기에 더해 내부 기록을 작성하는 규칙에도 속어를 쓰지 않는다는 기준을 넣었습니다. 글의 근거가 되는 기록부터 표현을 다듬으려는 조치입니다.

다만 외부 도구의 지적을 모두 새 규칙으로 만들지는 않았습니다. 10건 중 나머지 6건은 우리 문체와 운영 방식에 따라 의도적으로 선택한 부분이었습니다. 다른 기준을 그대로 적용하기 전에, 실제로 놓친 문제인지 우리가 선택한 방식인지 구분했습니다.

외부 제안을 그대로 적용할지 판단했던 다른 사례도 있습니다.

같은 문제가 생기면 먼저 확인할 항목입니다

규칙이 없었던 것인지, 있었지만 적용되지 않은 것인지 확인합니다.

개수로 검사할 항목과 문맥을 읽어 판단할 항목을 나눕니다.

문제가 있는 테스트 데이터에서 새 검사가 실제로 실패하는지 확인합니다.

자동 중단 조건과 추가 검토 조건을 구분합니다.

어색한 표현이 작성 과정에서 생겼는지, 근거가 된 원문에서 옮겨졌는지 확인합니다.

검사 기능과 실제 효과는 구분해서 봅니다

지금 확인한 것은 문제가 있는 테스트 데이터에서 검사가 의도대로 작동한다는 사실입니다. 실제 작성 과정에서 오류를 얼마나 줄였는지는 아직 확인하지 못했습니다. 이후 작성한 글의 경고 기록과 검수 결과를 살펴볼 필요가 있습니다.

이미 발행된 글의 표현은 이번 작업에서 일괄 수정하지 않았습니다. 새 검사는 앞으로 작성하는 글에 적용하고, 과거 글을 정리하는 작업은 별도로 남겼습니다.

처음 정하는 규칙이라면 가이드에 적는 것부터 시작할 수 있습니다. 이번에 바꾼 것은 이미 적혀 있는데도 반복해서 놓치던 규칙의 확인 방식입니다. 개수로 확인할 수 있는 항목은 검사로 옮기고, 문맥 판단은 검수에 남겼습니다.