증상: 기술블로그 제목만 보고는 무슨 글인지 알 수 없었다
기술블로그 제목에 기술명이 빠지면 글이 아무리 정확해도 독자는 클릭할 이유를 찾지 못합니다. 2026년 9월 2일 밤, 회사 대표가 발행된 기술블로그 글 4편을 직접 읽고 이렇게 말했습니다.
아무리 기술블로그라지만 검색 키워드나 글 주제와 맥락은 너무 고려를 안 한 것 같다. 전문적이고 어려워서가 아니라 그냥 문맥적으로 이해가 어렵다. 제목만 보고 어떤 내용일지 감도 안 오고, 어떤 문제·어떤 기술 이야기인지 예상이 안 되고, 그래서 궁금하지가 않다.
4편은 모두 자동 파이프라인이 쓰고 검사를 거쳐 실린 글이었습니다. 제목 가운데 셋은 이랬습니다. 「묻는 쪽이 더 위험했다」, 「1,300개의 에러는 버그가 아니었다」, 「노출 2.6→0.9, 범인은 따로 있었다」.
세 제목에는 이야기의 긴장은 있는데 주어가 없습니다. 누가 무엇을 물었는지, 어떤 도구의 에러인지, 어디의 노출이 떨어졌는지 제목만으로는 알 길이 없습니다. 검색창에서 이 제목을 본 사람은 자기 문제와 관련이 있는지조차 판단할 수 없습니다.
이 문제는 코드 버그와 달리 에러 메시지를 내지 않습니다. 글은 정상으로 발행되고, 검사도 전부 초록불이고, 그저 조용히 읽히지 않을 뿐입니다. 그래서 사람이 읽기 전까지 어떤 자동 검사도 이 결함을 잡지 못했습니다.
처음 의심한 것: 글이 너무 전문적이어서 어려운가?
첫 번째 용의자는 난이도였습니다. 기술블로그는 전문 용어를 피하기 어렵고, 개발자가 아닌 독자에게는 문장마다 모르는 단어가 걸릴 수 있습니다. 이 가설이 맞다면 처방은 전문 용어를 줄이고 쉬운 말로 풀어 쓰는 쪽입니다.
두 번째 용의자는 첫 문단이었습니다. 우리 글쓰기 규칙에는 이미 「첫 문단은 결론 한 문장과 근거 수치 하나로 연다」는 조항이 있었습니다. 결론을 먼저 말하는 방식(BLUF, Bottom Line Up Front)입니다. 제목이 모호해도 첫 문단이 결론을 말해 주니 독자는 곧 상황을 알 거라고 여겼습니다.
두 가설 모두 그럴듯했고, 둘 다 고치기 쉬운 방향을 가리켰습니다. 첫째를 받아들이면 용어 목록을 만들어 쉬운 말로 바꾸면 되고, 둘째를 받아들이면 첫 문단 검사를 조금 더 엄하게 하면 됩니다. 그런데 지적 원문에 첫 가설을 겨냥한 문장이 이미 들어 있었습니다. 「전문적이고 어려워서가 아니라 그냥 문맥적으로 이해가 어렵다.」
읽은 사람이 직접 「어려워서가 아니다」라고 말했으니, 이 가설은 확인 없이 받아들일 수도, 확인 없이 버릴 수도 없었습니다. 난이도가 원인이라면 잘 읽히는 기술블로그일수록 제목과 본문에 전문 용어가 적어야 합니다. 이 예측을 실제 표본에 대 보기로 했습니다.
무엇으로 확인했나 — 제목 1,157편 분류와 본문 단어 세기
첫 번째 수단은 비교 표본이었습니다. 글쓰기 규칙을 만들 때 모아 둔 다른 회사 기술블로그 1,157편의 제목을 다시 분류했습니다. 기준은 하나, 제목에 기술명(예: pytest, Kubernetes) 또는 문제 명사(예: 메모리 누수, 검색 노출)가 들어 있는가였습니다.
결과는 86%였습니다. 영문 기술 토큰만 세도 71%가 제목에 기술 이름을 앞세웠습니다. 같은 기준으로 우리 4편을 세면 0편이었습니다.
두 번째 수단은 본문 단어 세기였습니다. 4편 본문에서 외부 독자가 모를 수밖에 없는 표현을 찾아 셌습니다. 판매 서비스를 가리키는 사내 약칭이 21회, 사내 검사 단계를 부르는 「게이트」가 30회 나왔습니다. 사내 작업 트랙 이름과 승인 단계 번호, 연도 없이 월과 일만 적은 날짜 표기도 섞여 있었습니다.
세 번째 수단은 기존 검사기의 항목을 한 줄씩 읽는 일이었습니다. 하루 전인 2026년 9월 1일에 SEO 검사기를 8항목으로 만들어 두었고, 만들자마자 이미 실린 글 2편이 그 제약을 어기고 있다는 사실을 잡아낸 검사기였습니다. 검사기 자체는 적힌 항목에서 제대로 일하고 있었습니다. 질문은 그 8항목 안에 이번 결함을 잡을 항목이 있느냐였습니다.
알리바이: 어려운 건 기술 용어가 아니라 사내 약칭이었다
난이도 가설은 표본 앞에서 무너졌습니다. 잘 읽히는 기술블로그일수록 제목에 전문 용어가 적어야 한다는 예측과 반대로, 1,157편의 86%는 기술명이나 문제 명사를 제목 맨 앞에 내세웠습니다. 전문 용어는 독자를 막는 벽이 아니라 좌표였습니다. pytest를 써 본 적 없는 사람도 제목에서 그 단어를 보면 테스트 도구 이야기라는 것쯤은 압니다.
막힌 곳은 다른 층에 있었습니다. 판매 서비스 사내 약칭, 사내 트랙 이름, 승인 단계 번호는 업계 누구도 쓰지 않는 말입니다. 검색해도 나오지 않고, 문맥으로 짐작할 단서도 없습니다. 대표가 말한 「문맥적으로 이해가 어렵다」는 정확히 이 층을 가리켰습니다.
그러니 첫 가설의 처방은 방향이 거꾸로였습니다. 전문 용어를 줄였다면 제목은 더 흐릿해졌을 겁니다. 줄여야 할 것은 사내 약칭이고, 오히려 늘려야 할 것이 기술명이었습니다.
첫 문단 가설도 알리바이가 있었습니다. 첫 문단 규칙이 요구한 것은 결론을 맨 앞에 두는 형태였지, 그 결론을 누가 이해할 수 있느냐가 아니었습니다. 결론 문장이 사내 약칭으로 쓰이면 첫 줄에 결론이 있어도 외부 독자에게는 결론이 아닙니다. 맥락을 아는 사람에게만 결론인 셈입니다.
세 번째 확인 수단에서도 답이 나왔습니다. SEO 검사 8항목 어디에도 「제목에 무슨 기술인지 들어 있는가」가 없었습니다. 규칙은 제목의 길이와 형태를 다뤘지만 제목이 무엇을 말하는지는 다루지 않았습니다. 검사기는 고장 나지 않았고, 이번 결함은 애초에 검사 범위 밖에 있었습니다.
진짜 원인은 무엇이었나 — 글쓰기 규칙에 독자가 없었다
세 가지 관찰을 모으면 원인은 하나로 모입니다. 우리 글쓰기 규칙은 독자를 정의한 적이 없었습니다. 규칙이 다룬 것은 제목의 길이와 형태, 첫 문단의 결론 위치뿐이었고, 둘 다 우리 사정을 이미 아는 사람을 전제로 쓰여 있었습니다.
- 재료의 어휘가 그대로 흘러나왔다 — 초안의 재료가 사내 결정 기록과 작업 지식 메모라, 거기 쓰인 약칭과 날짜 표기가 본문에 옮겨졌습니다.
- 검사 항목에 제목의 내용이 없었다 — 글쓰기 규칙은 제목 길이·형태와 첫 문단 결론만 다뤘고, SEO 검사 8항목 어디에도 제목이 어떤 기술을 말하는지 보는 항목이 없었습니다.
- 검색어를 정하는 단계가 없었다 — 파이프라인 어디에도 「독자가 검색창에 칠 말 하나를 먼저 정한다」는 단계가 없었습니다. 제목은 검색어가 아니라 이야기의 반전을 중심으로 지어졌습니다.
셋 중 어느 하나만 고쳐서는 부족합니다. 약칭을 걸러도 제목에 기술명을 넣으라는 규칙이 없으면 여전히 서사 훅만 남은 제목이 나옵니다. 제목 규칙을 넣어도 검색어를 정하는 단계가 없으면 무엇을 제목에 넣을지 기준이 없습니다.
이 사고에서 가장 불편한 사실은 모든 검사가 통과였다는 점입니다. 검사는 적힌 것만 봅니다. 목적이 「외부 독자가 읽는다」인데 그 목적을 적은 항목이 없으면, 검사를 전부 통과한 글이 목적에서는 전부 실패할 수 있습니다.
고친 방법: 독자 규칙을 맨 앞에 두고 4편을 다시 썼다
글쓰기 규칙 문서의 맨 앞에 독자 절을 새로 만들었습니다. 독자는 「우리 회사도, 우리 시스템도, 우리 용어도 모르는 사람」입니다. 중소기업 대표, 마케팅 담당자, 외주 검토자, 다른 회사 개발자가 여기에 해당합니다. 이 정의가 문서의 나머지 모든 규칙보다 앞섭니다.
- 타깃 검색어 1개를 먼저 정하고, 제목·description·첫 문단에 그대로 넣는다.
- 제목에 기술명 또는 문제 명사를 반드시 넣고, 서사 훅은 부제 자리로 보낸다.
- 첫 문단 아래에 「이 글의 배경」을 120자 이상 둔다 — 어떤 회사가, 어떤 시스템으로, 무슨 일을 하다가, 무엇이 문제였나.
- 사내 약칭은 0건. 쓰고 싶으면 풀어 쓴다.
- 연도 없는 날짜는 0건. 「9월 2일」이나 ISO 형식으로 쓴다.
- 자주 쓰는 전문 용어는 3회 이상 등장하면 배경 블록에서 한 줄로 정의한다.
이미 발행한 4편은 전부 다시 썼습니다. 제목에 기술명과 문제 명사를 앞세우고, 배경 블록을 붙이고, 본문의 사내 약칭을 모두 풀어 썼습니다. 글 주소는 바꾸지 않았습니다.
제목을 나란히 놓으면 차이가 분명합니다. 「노출 2.6→0.9, 범인은 따로 있었다」는 새 제목에서 「SEO 콘텐츠 노출이 안 붙은 원인 — 중복이 아니라 검색광고 입찰가였다」가 됐습니다. 무엇의 노출인지(SEO 콘텐츠), 무엇을 의심했는지(중복), 무엇이 원인이었는지(검색광고 입찰가)가 제목 안에 다 들어 있습니다. 다시 쓴 글은 SEO 콘텐츠 노출 원인 분석 글에서 볼 수 있습니다.
검색량은 검사 조건에 넣지 않았습니다. 참고만 합니다. 기술 롱테일 검색어는 월 검색량이 0으로 잡히는 자리가 많고, 그게 정상입니다. 검사가 보는 것은 「그 말이 제목에 들어 있는가」 하나입니다.
같은 실수를 막는 장치: 기준 하나를 작성 전과 발행 후에 모두 부른다
규칙 문서만 고치면 다음 글에서 다시 새어 나옵니다. 그래서 독자 검사 8항목을 함수 하나에 모았습니다. 초안을 쓴 직후 도는 작성 검사와, 발행된 글을 다시 훑는 SEO 검사가 둘 다 이 함수를 가져다 씁니다. 규칙을 두 곳에 따로 적으면 한쪽만 고쳐지는 날이 오기 때문입니다.
검사기가 정말로 가려내는지도 따로 확인했습니다. 일부러 만든 나쁜 예는 떨어뜨리고 좋은 예는 통과시키는지 보는 자체 시험을 붙였고, 통과했습니다. AI에게 초안을 시키는 작성 프롬프트와 글마다 만드는 작성 지시서에도 같은 규칙을 넣었습니다. 쓰는 쪽과 재는 쪽이 같은 기준을 보게 하려는 조치입니다.
한 번 실행에 발행하는 상한 5편은 그대로 뒀습니다. 검사 항목이 8개 늘었으니 통과율은 떨어질 것이고, 그건 의도한 결과입니다. 떨어진 글을 살리려고 기준을 낮추는 대신 다른 안전장치를 하나 더 두었습니다.
사흘 뒤인 2026년 9월 5일, 검사에서 떨어진 기술블로그 초안 20건을 다시 봤더니 2건이 현재 기준으로 전 항목 통과였습니다. 한 건은 첫 문장을 자르는 정규식이 「정해진 시각마다 자동으로」의 「마다」를 문장 끝으로 잘못 읽어 「11자 미달」로 떨어졌는데, 실제 첫 문장은 108자였습니다. 검사기는 계속 고쳐지지만 그 수리는 이미 버린 글에 소급되지 않습니다.
그래서 검사 기준은 그대로 두고, 검사가 버린 초안이 디스크에 남아 있으면 다음 실행이 먼저 다시 검사하는 경로를 만들었습니다. 첫 실행에서 2편을 회수해 발행했고, 공개 목록은 19편에서 21편이 됐습니다. 기준은 엄하게 두되 기준의 오판은 다음 실행이 다시 보는 구조입니다.
같이 발견한 사고 1: AI 호출 실패가 왜 로그에 안 남았나?
같은 날 이 작업을 하면서 다른 결함 두 개를 함께 발견했습니다. 둘 다 이번 사고와 같은 모양, 곧 「실패가 실패처럼 보이지 않는」 결함이었습니다.
첫째는 AI 호출 잔액 소진이었습니다. 크론 작업들은 공통 실행 스크립트를 거쳐 외부 LLM 게이트웨이(DeepSeek 계정)로 AI를 부르고 있었는데, 그 계정 잔액이 바닥났습니다. 2026년 9월 1일 07:15부터 `claude -p` 호출이 `API Error: 402 Insufficient Balance`로 전부 실패했습니다. 오류를 찍고 곧바로 끝나지 않고 매달리다가 제한시간 초과로 끝났고, 영향을 받은 크론은 27개였습니다.
하루 넘게 아무도 몰랐던 이유는 관측 수단에 있었습니다. 402 문구는 표준 출력(stdout)으로 나왔는데, 크론 로그는 표준 에러(stderr)만 남기고 있었습니다. 크론 상태 감시기는 파이썬 Traceback 문자열만 찾았습니다. 오류 문구가 떨어지는 자리와 감시기가 보는 자리가 한 번도 겹치지 않았습니다.
고친 방법은 로그를 더 꼼꼼히 뒤지는 쪽이 아니었습니다. 잔액을 직접 조회하는 감시 항목을 새로 만들었습니다. 로그는 실패가 어떤 모양으로 찍힐지 미리 알아야 잡을 수 있지만, 직접 조회는 그런 가정이 필요 없습니다. 기술블로그 작성 작업은 구독 계정 경로로 옮기고 새벽 2시 20분으로 옮겼습니다. 글은 밖에 내놓는 결과물이라 모델을 싼 쪽으로 바꾸지 않았고, 밤 시간이라 낮 작업과 사용량이 겹치지 않습니다.
이 사고에는 뒷이야기가 있습니다. 9월 3일 공통 실행 스크립트에 차단 스위치를 달아 크론 26개가 구독 경로로 우회했습니다. 그런데 공통 스크립트를 거치지 않고 옛 설정 파일을 직접 읽던 스크립트 하나(네이버 지식iN 자동 답변 파이프라인)는 그 스위치를 보지 못했습니다. 이 스크립트는 반환 코드를 확인하지 않아 402 문구를 AI의 답으로 받아들였고, 답변 후보 282건을 「건너뜀」으로 기록했습니다.
크론은 10일 동안 하루 네 번 돌며 로그에 「완료」를 찍었고, 선별 0건이 10회 연속 이어졌습니다. 발행 누적은 147에서 멈춰 있었지만 경보는 하나도 울리지 않았습니다. 표준 에러에는 모델 이름 경고만 찍혀 원인을 잘못 읽게 만들기까지 했습니다. 9월 10일 이 결함을 고치면서 차단 스위치 대신 죽은 계정을 가리키는 설정 파일 자체를 치웠습니다. 스위치는 누군가 우회하면 끝이지만, 가리킬 곳이 없으면 우회할 것도 없습니다.
같이 발견한 사고 2: crontab 파이프 한 줄이 작업 166개를 지운 이유는?
둘째는 크론 설정 전체가 1분 동안 사라진 사고였습니다. 크론 설정을 고치려고 `crontab -l | sed … | crontab -` 형태의 파이프를 썼습니다. 현재 설정을 꺼내 sed로 고친 뒤 다시 등록하는, 흔히 쓰는 한 줄입니다.
sed가 치환식 구분자로 쓴 `#`이 내용과 부딪혀 실패했습니다. 문제는 파이프라인이 거기서 멈추지 않았다는 점입니다. sed가 아무것도 내보내지 않자 `crontab -`는 빈 입력을 새 설정으로 받아들였고, 등록된 작업 166개가 0개가 됐습니다.
직전에 떠 둔 백업이 있어 1분 만에 복원했습니다. 그 뒤로 규칙을 하나 정했습니다. crontab은 파이프로 곧장 등록하지 않고, 먼저 파일에 쓰고, 내용을 검증한 뒤, `crontab <파일>`로 등록합니다. 한 단계가 조용히 실패해도 다음 단계가 빈 결과를 정상으로 받아들이지 못하게 하려는 규칙입니다.
세 사고를 나란히 놓으면 공통점이 보입니다. 읽히지 않는 글은 모든 검사를 통과했고, 402 오류는 아무도 안 보는 출력으로 나갔고, 빈 입력은 정상 입력처럼 다음 단계로 넘어갔습니다. 어느 쪽도 에러를 내지 않았습니다.
검사를 통과한 결과물이 왜 목적에서는 실패하나?
검사는 적힌 항목만 봅니다. 기술블로그 제목 사고에서 SEO 검사 8항목은 모두 제 몫을 했지만, 「외부 독자가 제목만 보고 주제를 아는가」라는 목적 자체가 어디에도 적혀 있지 않았습니다. 그래서 첫 번째로 고친 것은 검사 항목이 아니라 목적의 정의, 곧 독자가 누구인가였습니다.
처음 세운 가설은 둘 다 틀렸습니다. 난이도를 의심했다면 전문 용어를 줄여 제목을 더 흐리게 만들었을 겁니다. 첫 문단 규칙을 엄하게 했다면 사내 약칭으로 쓴 결론을 첫 줄에 더 단단히 박았을 겁니다. 두 처방 모두 원인을 건드리지 않은 채 검사 통과율만 지켰을 겁니다.
같은 원인, 곧 작성자만 아는 맥락이 문서에 그대로 흘러나오는 문제는 사내 문서에서도 반복됩니다. 사내 보고서를 두고 같은 축을 추적한 기록은 AI 문서 작성 규칙 글에 있습니다. 자동으로 글을 생산하는 파이프라인에서 비슷한 증상을 겪고 있다면 상담으로 문의하셔도 됩니다.
SGK 스튜디오 엔지니어링 기록. 이 글도 위의 독자 검사 8항목을 통과해야 발행됩니다.