AI가 문법에 맞는 Markdown을 만들었다고 해서 공개할 가치가 있는 글이 된 것은 아니다. 이 저장소에는 생성 단계, 메타데이터 검사, CI 빌드가 각각 있지만 세 단계가 확인하는 대상은 서로 다르다. 이 글은 실제 구현을 기준으로 자동화할 수 있는 검사와 사람이 맡아야 하는 판단을 분리한다.
현재 파이프라인의 세 단계
| 단계 | 실제 파일 | 검사 범위 | 통과가 보장하지 않는 것 |
|---|---|---|---|
| 생성 직후 검사 | scripts/auto_post.py | YAML 파싱, 필수 필드, 1,000자 하한, 중복 키워드, 일부 과장어, AI 재평가 | 사실성, 독창성, 공식 출처 |
| 저장소 콘텐츠 검사 | scripts/analyzePosts.cjs | description·tags 누락, 설명 길이 경고, 깨진 로컬 이미지 | 외부 링크 유효성, 이미지 권리, 본문 품질 |
| CI | .github/workflows/ci.yaml | 타입·형식·테스트·Quartz 빌드 | 독자에게 유용한지, 수치가 맞는지 |
세 단계가 모두 통과해도 “빌드 가능한 글”일 뿐이다. 공개 가능한 글이 되려면 주장과 근거를 사람이 대조해야 한다.
저장소에서 확인한 생성 검사
scripts/auto_post.py는 다음 흐름을 가진다.
모델 호출
→ frontmatter와 본문 분리
→ title, tags, description 검사
→ 본문 1,000자 하한 검사
→ 운영자용 과장 표현 검사
→ 같은 모델 계열의 2차 평가
→ 최대 4회 재시도
→ Markdown 저장
좋은 점은 실패한 응답을 그대로 저장하지 않고, AUTO_POST_DRAFT의 기본값을 true로 둔 것이다. 그러나 길이 하한과 AI 점수는 품질의 대리 지표다. 1,000자의 반복문도 길이 검사를 통과할 수 있고, 모델이 자신과 비슷한 오류를 놓칠 수도 있다.
메타데이터 검사를 직접 실행하는 방법
저장소 루트에서 다음 명령을 실행한다.
node scripts/analyzePosts.cjs
검사기는 content 바로 아래의 Markdown 파일을 읽어 다음 문제를 출력한다.
- frontmatter가 없는 파일
- description 또는 tags가 없는 파일
- 지나치게 짧거나 긴 description
- 존재하지 않는 로컬 이미지 경로
- reviewed: true 표시 개수
실패 코드를 반환하는 강제 게이트가 아니라 리포트 출력 도구라는 점도 중요하다. 즉 이 명령의 경고를 CI에서 차단 조건으로 쓰려면 스크립트가 이슈 발견 시 0이 아닌 종료 코드를 내도록 별도로 수정해야 한다.
공개 전 검수 체크를 코드로 표현하기
최소 기준은 “필수 필드가 있다”가 아니라 “근거가 추적 가능하다”까지 올라가야 한다. 예를 들어 별도 검사기를 만들 때는 다음과 같은 결과 구조가 유용하다.
{
"file": "content/example.md",
"checks": {
"frontmatter": "pass",
"official_sources": "needs_review",
"claims_with_numbers": "needs_review",
"local_evidence": "pass",
"limitations_section": "pass",
"human_approval": "missing"
},
"publishable": false
}
숫자가 들어간 문장을 정규식으로 찾는 것까지는 자동화할 수 있다. 그 숫자를 뒷받침하는 링크가 원자료인지, 비교 조건이 동일한지는 사람이 확인해야 한다.
주제별 공개 기준
| 콘텐츠 유형 | 최소 증거 | 공개 보류 조건 |
|---|---|---|
| 저장소 구축기 | 실제 파일 경로, 재현 명령, 실행 결과 | 파일과 설명이 다름 |
| 코드 튜토리얼 | 실행 가능한 최소 예제, 버전, 오류 처리 | 실행하지 않은 결과를 성공 사례처럼 표현 |
| 제품·서비스 비교 | 같은 날짜와 조건의 공식 문서 | 가격·한도가 최신인지 확인 불가 |
| 성능 글 | 측정 환경, 전후 값, 원본 로그 | “몇 배 빨라짐”만 있고 측정 없음 |
| 건강·금융·법률·세금 | 공식 기관 원문과 전문가 검토 | 일반 AI 초안만 존재 |
Google도 생성형 AI 사용 자체보다 사용자를 돕지 않는 대량 생성과 가치 없는 페이지를 문제로 본다. 기준은 Google Search의 생성형 AI 콘텐츠 안내와 스팸 정책 원문에서 확인할 수 있다.
CI에서 재현하는 순서
이 저장소의 .github/workflows/ci.yaml과 같은 순서로 로컬에서 확인하려면 Node.js 22 이상을 사용한다.
npm ci
npm run check
npm test
npx quartz build --bundleInfo
현재 package.json의 check는 타입 검사와 Prettier 검사를 묶는다. test는 Quartz와 scripts 아래의 테스트 파일을 실행한다. 마지막 빌드는 초안 제거, 링크 변환, 페이지 생성까지 포함하므로 frontmatter가 깨진 글을 찾는 최종 기술 게이트다.
GitHub Actions 워크플로 구문은 실행 조건과 실패 처리의 기준을 설명한다.
사람이 마지막에 확인할 질문
- 이 글에 저장소에서 직접 확인한 사실이 하나 이상 있는가?
- 수치와 날짜마다 원자료 또는 재현 명령이 있는가?
- 비교 대상의 조건과 버전이 같은가?
- 실패 조건과 적용되지 않는 경우를 한계에 썼는가?
- 제목이 본문보다 더 큰 결과를 약속하지 않는가?
- 공개할 필요가 없는 태그·아카이브·중복 글을 만들지 않는가?
한계
- analyzePosts.cjs는 외부 URL에 요청하지 않으므로 링크가 살아 있는지 확인하지 않는다.
- 현재 중복 검사는 키워드 겹침 중심이어서 같은 의도의 문장을 완전히 찾지 못한다.
- AI 재검수는 독립적인 사람 검토가 아니다.
- 본문 길이와 H2 개수에는 보편적인 품질 기준값이 없다.
- 빌드 성공은 성능, 접근성, 사실성 통과를 의미하지 않는다.
- 실제 공개 승인은 저장소에 구조화된 필드로 기록되지 않으므로, reviewed: true만으로 사람 검수를 추정하면 안 된다.
자동화는 반복 가능한 오류를 빠르게 찾는 데 쓰고, 공개 결정은 증거를 확인한 사람이 내려야 한다. 이 역할 분리가 파이프라인의 핵심이다.