AI로 기술 문서를 빠르게 만들 수는 있어도, 정확한 문서가 저절로 나오지는 않습니다

문서는 코드보다 틀려도 늦게 발견돼요 🤔

코드가 틀리면 테스트나 에러 메시지가 비교적 빨리 알려주는 편입니다. 반면 기술 문서가 틀리면 독자가 한참 따라 한 뒤에야 문제가 드러나요. 설정 이름이 바뀌었거나, 예제가 오래됐거나, 전제 조건이 빠진 글은 겉보기에는 친절해도 실제로는 독자의 시간을 빼앗습니다.

AI로 글을 만들 때 이 문제가 더 커질 수 있어요. 모델은 자연스러운 문장을 잘 만들지만, 그 문장이 현재 제품의 공식 동작과 맞는지, 독자가 그대로 따라 했을 때 성공하는지는 별개의 문제거든요. 그래서 “AI가 썼으니 검수만 하면 된다”는 흐름은 품질 관리가 아니라 맞춤법 검사에 가까워질 수 있습니다.

Google Cloud가 공개한 개발자 문서 제작 사례는 다른 방향을 보여줍니다. 이 팀은 AI를 글을 빨리 쓰는 도구로만 쓰지 않고, 공식 API 정의를 근거로 프롬프트를 만들고, 별도 평가자가 결과를 루브릭으로 점수화하고, 마지막에는 실제 환경에서 문서 절차를 실행해 확인하는 흐름을 설명합니다. MAX5가 콘텐츠 파이프라인에 근거 패킷과 점수 루프를 넣은 이유도 같은 문제의식에서 출발해요.

초안의 출발점은 ‘모델’이 아니라 원문이어야 해요 📚

문서·콘텐츠 자동화에서 가장 먼저 정해야 할 것은 “무슨 프롬프트를 쓸까?”가 아닙니다. 어떤 자료를 사실의 기준으로 삼을까?예요.

자료 종류	맡길 수 있는 역할	혼동하면 생기는 문제
공식 문서·릴리스 노트·원 연구	기능, 조건, 정책, 수치의 사실 근거	2차 보도의 해석을 제품 사실로 씀
직접 실행 결과	현재 환경에서의 재현 증거	한 번의 성공을 일반 기능으로 과장
사용자 질문·검색어	독자가 풀고 싶은 문제의 신호	검색량을 사실성이나 가치로 오해
AI 초안	설명 구조, 비교 후보, 빠진 질문 탐색	자연스러운 문장을 검증된 사실로 오해

Google Cloud 사례에서 코드 샘플 생성은 공개 API 정의를 출발점으로 삼습니다. 모델이 자유롭게 API를 상상하도록 두지 않고, 메서드·파라미터·문서를 함께 제공해 프롬프트의 사실 범위를 좁히는 방식이에요. 블로그도 마찬가지입니다. 원문 URL, 확인한 사실, 아직 모르는 것, 독자에게 줄 각도를 먼저 적으면 AI 초안은 훨씬 덜 그럴듯하게 틀립니다.

평가자는 작성자와 다른 질문을 해야 해요 🧪

글을 쓴 모델이나 사람이 곧바로 “좋은 글입니다”라고 평가하면, 빠진 전제를 놓치기 쉽습니다. 작성자는 문장이 매끄러운지에 집중하고, 평가는 독자가 실제로 믿고 실행할 수 있는지를 봐야 하거든요.

MAX5의 편집 루브릭도 이 역할을 나눕니다.

1. 독자 문제: 제목과 요약만 읽고도 누가 어떤 결정을 할 수 있는가?
2. 근거: 핵심 기능·수치·정책마다 공식 원문이나 직접 확인 경로가 있는가?
3. 고유성: 원문을 번역한 것이 아니라 비교·조건·반론·실험 중 하나를 더했는가?
4. 실행성: 독자가 다음 행동을 할 단계·체크리스트·프롬프트가 있는가?
5. 안전 경계: 맞지 않는 상황, 권한·비용·저작권·불확실성을 적었는가?

이 다섯 질문은 글을 길게 만들기 위한 장치가 아닙니다. 예를 들어 공식 링크 하나만 붙이고 “써보세요”로 끝난 도구 리뷰는 근거와 실행성이 모두 약할 수 있어요. 반대로 짧은 글이라도 특정 독자의 조건, 정확한 시작 방법, 하지 말아야 할 일을 명확히 알려주면 충분히 가치 있을 수 있습니다.

마지막 확인은 ‘읽어보기’가 아니라 ‘해보기’예요 ✅

Google Cloud는 문서 절차를 실제 환경에서 실행하는 자동 검증도 설명합니다. 이 원칙을 블로그에 그대로 복제할 필요는 없지만, 실행 가능한 글이라면 독자가 하기 전에 작성자가 가장 작은 형태로 확인해야 합니다.

예를 들어 AI 코딩 튜토리얼이라면 다음처럼 확인할 수 있어요.

1. 빈 샘플 프로젝트에서 첫 단계를 실행한다.
2. 기대한 파일·응답·화면이 실제로 나오는지 기록한다.
3. 실패하면 필요한 환경 변수·권한·버전을 문서에 추가한다.
4. 두 번째 단계로 넘어가기 전에 첫 단계의 확인 명령을 글에 남긴다.

도구 리뷰라면 무료 플랜/샘플 데이터에서 확인 가능한 기능만 쓰고, 실제로 결제하거나 운영 데이터를 연결하지 않은 부분은 “확인하지 못함”으로 남기는 편이 낫습니다. 사례 분석이라면 벤더가 말한 숫자와 MAX5가 해석한 원인을 표로 분리하면, 독자는 무엇이 사실이고 무엇이 의견인지 빠르게 구분할 수 있어요.

콘텐츠 자동화의 최소 품질 루프 🔁

혼자 운영하는 블로그에서도 거대한 평가 시스템은 필요 없습니다. 한 편을 발행하기 전 45분 정도로 아래 루프를 돌릴 수 있어요.

순서	하는 일	통과 질문
1. 후보화	원문·검색 신호·독자 질문을 한 카드에 적기	왜 지금 이 글을 써야 하나?
2. 근거 수집	공식 원문과 직접 확인 가능 자료 찾기	핵심 사실을 어디서 검증할 수 있나?
3. 초안	한 가지 논리 패턴으로 글 쓰기	배경·근거·적용·한계가 섞이지 않았나?
4. 루브릭 평가	가장 약한 두 항목 표시하기	독자가 실행·중단할 조건을 아나?
5. 수정·dry-run	파서와 링크·카테고리 확인	실제 발행 형태로 읽히나?

여기서 중요한 규칙이 하나 있습니다. 점수가 낮다고 문장을 덧붙이는 게 아니라, 가장 약한 두 항목만 보강해야 해요. 근거가 약하면 공식 원문을 찾고, 실행성이 약하면 단계와 검증을 추가하고, 한계가 없으면 맞지 않는 조건을 씁니다. 분량은 그 결과로 늘어날 수 있지만, 목표가 되면 다시 요약문을 부풀리는 습관으로 돌아가기 쉽습니다.

작성자와 검수자의 질문을 분리하세요 👀

같은 사람이 초안을 쓰고 바로 “문제없음”이라고 확인하면, 머릿속에 이미 있는 맥락 때문에 빈칸을 놓치기 쉽습니다. 팀이 없어도 역할을 시간으로 분리할 수 있어요. 초안을 쓴 직후에는 문장과 구조만 다듬고, 잠시 뒤 검수할 때는 아래 질문만 다시 봅니다.

검수 질문	찾는 결함	수정 방향
이 문장은 어디서 확인했나?	출처 없는 기능·수치·정책	공식 원문 추가 또는 표현을 가설로 낮춤
이 글만 읽고 다음 행동을 할 수 있나?	배경만 길고 실행 단위가 없음	단계·체크리스트·예상 결과 추가
다른 조건에서는 결론이 달라지나?	모든 독자에게 같은 답을 주는 일반화	대상·환경·권한·비용 조건 분리
원문을 읽지 않아도 되고, 원문을 대체하지도 않나?	요약 반복 또는 인용 과다	MAX5 해석·비교·재현 결과 추가
발행 뒤 틀렸다고 밝혀지면 무엇을 고칠 수 있나?	변경 이력·원문·작성 과정 부재	출처·검증일·업데이트 기준 명시

이 과정은 사람 검수를 완전히 없애기 위한 자동화가 아닙니다. 사람이 꼭 봐야 하는 질문을 짧은 표로 고정해, 피곤한 날에도 같은 기준을 적용하려는 장치예요.

발행 후에야 시작되는 두 번째 루프 📈

발행 전 점수는 독자 반응을 예측하지 못합니다. 그래서 글을 올린 뒤에는 28일 동안 최소한 세 가지를 다시 봐야 해요. 검색에서 어떤 질문으로 들어왔는지, 어느 섹션에서 독자가 다음 행동을 했는지, 댓글·문의·정정 요청에서 어떤 설명이 부족했는지입니다.

이 데이터가 쌓이면 다음 글의 루브릭을 바꿀 수 있습니다. 예를 들어 도구 리뷰는 비교표가 있는 글에서 더 오래 읽힌다면 ‘선택 조건’의 배점을 올리고, 튜토리얼은 특정 단계에서 이탈한다면 준비물·실패 복구 섹션을 강화하는 식이죠. 처음부터 완벽한 점수표를 믿는 대신, 발행 전 품질과 발행 후 반응을 연결하는 것이 자가개선의 목적입니다.

자동화가 대신할 수 없는 판단 ⚠️

AI 평가가 높은 점수를 줘도 사람이 확인해야 하는 일이 있습니다. 의료·금융·법률·개인정보처럼 잘못된 문장이 직접 피해로 이어질 수 있는 주제, 제3자 영상·유료 자료처럼 권리 확인이 필요한 자료, 아직 공개되지 않은 제품 정보가 그렇습니다.

또 하나는 “이 글이 우리 독자에게 필요한가”라는 질문이에요. 검색에서 많이 보이는 주제라도 MAX5의 AI 도구·바이브코딩 독자와 연결되지 않으면 쓰지 않는 편이 낫습니다. Google Search도 사람에게 도움이 되는 독창적 내용과 명확한 출처를 강조하며, 여러 주제에 자동 생성 글을 대량으로 늘려 검색 유입만 노리는 방식을 경고합니다.

잡돌쌤의 한마디 💬

AI 콘텐츠 자동화에서 가장 값비싼 일은 문장을 만드는 일이 아닙니다. “이 사실을 믿어도 되는가”, “이 독자가 지금 이 행동을 해도 되는가”를 확인하는 일이에요. 그래서 초안 생성보다 먼저 근거를 모으고, 작성자와 다른 질문을 하는 평가 단계를 두고, 가능한 부분은 실제로 실행해보는 흐름이 필요합니다.

처음부터 완벽한 자동 평가기를 만들 필요는 없습니다. 다음 글 한 편에서 공식 원문 두 개를 찾고, 독자가 할 행동 하나와 멈출 조건 하나를 추가해보세요. 그 작은 루프가 쌓이면 콘텐츠는 AI가 많이 쓴 글이 아니라, AI를 써서 더 신중하게 만든 글이 됩니다.