Publication Pipeline — 원고 게시 풀 파이프라인
한 송이의 꽃이 씨앗에서 게시까지 가는 길.
목적
manuscript/ 의 한 원고를 진입부터 사이트 게시까지 흐르게 한다. 각 단계마다 책임지는 전문가가 다르고, 보조 도구(image-gen 스킬 등)와 연동된다.
유형 카탈로그 (Type Catalog)
원고가 들어오는 모양은 한 가지가 아니다. 진입 형태에 따라 흐름의 앞부분이 달라지고, 검수·승급·배포 단계는 공통이다.
| 유형 | 진입 | 상태 | 비고 |
|---|---|---|---|
| Type 1 | 초안 시작형 (draft/<slug>.md) | ✅ 검증됨 (v1.0.0 사이클) | 가장 흔한 유형, 기본 경로 |
| Type 2 | 직접 작성형 (manuscript/articles/ 바로) | ⏳ 자리만 확보 | 골격 없이 본문이 머릿속에 잡혀 있을 때 |
| Type 3 | 외부 입력형 (Notion / Google Docs / 사내 위키 등) | ⏳ 자리만 확보 | 영입 → 변환 → manuscript 진입 |
| Type 4 | 이슈 기반 수정/리비전 (GitHub Issue) | ✅ 정식화 (v1.4.0) | 출판 후 편집장이 발견한 문제, 안전한 트리아지 필수 |
| Type 5 | 시리즈형 (관련 글 N편 묶음 발행) | ⏳ 자리만 확보 | 상호 참조·일관 톤·동시 승급 |
Type 1 외의 유형은 사용 사례가 누적되면 정원지기(tamer)가 본 문서에 절차를 추가한다. 새 유형이 발견될 때 가장 먼저 점검할 질문: "공통 stage(검수·승급·배포)는 그대로 쓰는가, 분기가 필요한가?"
Type 1 — 초안 시작형 (Drafted-First, ✅ 검증됨)
검증 사이클: v1.0.0 (010-문서시스템-하네스도입). 1편 게시까지 약 2시간 (사람 작성 시간 포함).
흐름
┌─────────────────────────────────────────────────────────────┐
│ Stage 0: 초안 작성 (사용자) │
│ ───────────────────────────────────── │
│ draft/<slug>.md ← 자유 형식 골격 │
│ · frontmatter 없음, 자리표시자 자유 │
│ · "이 글이 답하는 질문"과 절 헤딩만 잡아도 충분 │
│ · 길이/형식 제약 없음 — 정원지기·편집장이 다듬을 재료 │
└────────────────────┬────────────────────────────────────────┘
│
▼ "이 초안으로 원고 만들어줘"
┌─────────────────────────────────────────────────────────────┐
│ Stage 1: 초안 → 정식 원고 변환 (manuscript-architect) │
│ ───────────────────────────────────── │
│ draft/<slug>.md → manuscript/articles/<order>-<slug>.md │
│ · frontmatter 채움 (title/order/status/date/description) │
│ · _template.md 구조에 초안 내용 매핑 │
│ · 누락된 절은 자리표시자([[TYPE: 의도]])로 보충 │
│ · 외부 자료 조사·인용·통계 보강 (편집장 판단) │
│ · status: review (이미 본문이 있으므로 draft 단계 생략 가능) │
└────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Stage 2: 편집장 개입 — 보조 자산 생성 (선택, manuscript-architect) │
│ ───────────────────────────────────── │
│ 본문이 글 그림이 필요로 하면 편집장이 판단해 image-gen 스킬 호출: │
│ · 히어로 카드 1장 (1536x1024) │
│ · 절별 시각자료 N장 (1024x1024) │
│ · 산출물: manuscript/articles/images/<order>-<slug>/*.png │
│ · 메타: .prompts/<slug>.md 자동 보존 │
│ 본문에 alt 텍스트와 함께 임베드 — 그림만 보고도 글의 골격 파악 가능 │
└────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Stage 3: 내용 검수 ([[full-review]] 엔진 호출) │
│ ───────────────────────────────────── │
│ doc-reviewer : 명확성/구조/독자 친화성 │
│ style-enforcer : 문체/표기/톤 │
│ terminology-keeper : 용어/약어/정의 │
│ → 통합 리포트: 우선순위 Top 5 + 영역별 점수 │
│ → 차단 사유가 있으면 Stage 3.5 로 │
└────────────────────┬────────────────────────────────────────┘
│
▼ (차단 사유 있음 → 보강 적용)
┌─────────────────────────────────────────────────────────────┐
│ Stage 3.5: 보강 적용 + 재검수 (사용자 또는 manuscript-architect)│
│ ───────────────────────────────────── │
│ 필수 보강 적용 (예: 약어 풀어쓰기, 한 문장 분할) │
│ → 자리표시자 잔존 0건 재확인 │
│ → full-review 재실행 (선택 — 차단 사유만 좁게 재검토 가능) │
│ → 모든 점수 ≥ B 또는 ≥ 3 도달 시 Stage 4 로 │
└────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Stage 4: 형식 lint + status 승급 (manuscript-architect) │
│ ───────────────────────────────────── │
│ · frontmatter 완비 확인 │
│ · 자리표시자 0건 │
│ · 템플릿 주석 제거 │
│ · full-review 모든 영역 ≥ B + 모든 점수 ≥ 3 │
│ → status: review → published 승급 │
│ → 로그: harness/logs/manuscript-architect/*-promotion.md │
└────────────────────┬────────────────────────────────────────┘
│
▼ (사용자 결정: 커밋 + 푸시 + 태그)
┌─────────────────────────────────────────────────────────────┐
│ Stage 5: 배포 ([[docs-publisher]] 책임, CI 실행) │
│ ───────────────────────────────────── │
│ 1) git commit + push origin main (작업 백업, 배포 미발동) │
│ 2) git tag vX.Y.Z + push tag (배포 발동) │
│ 3) GitHub Actions: │
│ npm install │
│ MANUSCRIPT_STATUS_FILTER=published copy-from-... │
│ npm run build │
│ upload-pages-artifact → deploy-pages │
│ → https://blumnai-studio.github.io/tech-writing-harness/ │
│ articles/<order>-<slug>/ │
└─────────────────────────────────────────────────────────────┘
Stage별 산출물
| Stage | 산출물 | 위치 |
|---|---|---|
| 0 | 초안 파일 | draft/<slug>.md |
| 1 | 정식 원고 파일 | manuscript/articles/<order>-<slug>.md |
| 2 | 이미지 + 프롬프트 메타 | manuscript/articles/images/<order>-<slug>/*.png + .prompts/ |
| 3 | 통합 검수 리포트 | harness/logs/full-review/<timestamp>-<slug>.md |
| 3.5 | 보강 diff | 동일 원고 파일 (수정 반영) |
| 4 | lint 리포트 + status 갱신 | 원고 파일 + harness/logs/manuscript-architect/<>-promotion.md |
| 5 | 빌드 산출물 + 라이브 URL | docs-docusaurus/build/ (로컬) / GH Pages |
트리거별 진입 Stage
| 사용자 요청 | 진입 Stage |
|---|---|
| "초안 만들어 줘 / draft 작성" | Stage 0 (사용자가 손으로) |
| "이 초안으로 원고 만들어 줘" / "draft/<>.md 로 원고 짜줘" | Stage 1 |
| "히어로 카드 / 절별 이미지 생성" | Stage 2 |
| "전체 점검해" / "검수해줘" | Stage 3 |
| "권장 보강 적용" / "재검수해" | Stage 3.5 |
| "원고 lint" / "status 승급해" | Stage 4 |
| "사이트 게시" / "vX.Y.Z 태그" | Stage 5 |
종료 조건
- Stage 5 의 워크플로우가 success + 사이트에서 새 글 확인 가능
- 또는 사용자가 임의 단계에서 "여기까지" 선언
Type 2~5 — 자리만 확보
Type 2: 직접 작성형 (Drafterless)
골격이 머릿속에 잡혀 있어 draft/ 단계 없이 바로 manuscript/articles/<order>-<slug>.md 작성.
Stage 0 생략, 나머지(2~5)는 Type 1 과 동일.
Type 3: 외부 입력형 (Imported)
Notion / Google Docs / 사내 위키 / 다른 마크다운 저장소에서 영입. Stage 0 자리에 "외부 → manuscript/ 변환 단계" 가 들어간다.
- 사용 사례 발생 시 새 스킬 분리 (예:
notion-import,gdoc-import) - 변환 후에는 Type 1 의 Stage 1~5 그대로 흐른다
Type 4: 이슈 기반 수정/리비전 (Issue-Driven Revision, ✅ 정식화)
진입: 출판된 글을 본 편집장(또는 독자) 이 GitHub Issue 로 문제를 제기. 핵심 통찰: 같은 증상이 원고 문제 일 수도, 빌드/렌더링 깨짐 일 수도 있다. 트리아지가 안전 장치다.
흐름
┌─────────────────────────────────────────────────────────────┐
│ Stage R-0: 이슈 수집 (docs-publisher 또는 사용자) │
│ ───────────────────────────────────── │
│ gh issue list --label editorial │
│ · 라벨 컨벤션: editorial (진입), manuscript-fix / │
│ build-fix (트리아지 결과), rejected (반려) │
│ gh issue view <num> --json title,body,labels │
└────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Stage R-1: 트리아지 (manuscript-architect 책임) │
│ ───────────────────────────────────── │
│ 이슈 본문에서 다음을 추출: │
│ · 대상 글의 URL 또는 slug → manuscript/articles/<>.md 매핑 │
│ · 재현 가능한 증상 (인용·스크린샷) │
│ 결정 트리 ([[issue-triage]] 참조): │
│ (a) 원고 파일에 같은 증상이 보이는가 → manuscript-fix │
│ (b) 원고는 멀쩡한데 사이트만 깨졌나 → build-fix │
│ (c) 재현 불가 / 의견 차 → rejected (라벨 + 코멘트) │
│ 결정 후 라벨 토글 + 이슈에 트리아지 코멘트 │
└──────┬──────────────────────────┬───────────────────────────┘
│ │
▼ (manuscript-fix) ▼ (build-fix)
┌──────────────────────┐ ┌──────────────────────────────────┐
│ Stage R-2A: │ │ Stage R-2B: │
│ 원고 수정 │ │ 빌드/렌더링 수정 │
│ (manuscript-architect)│ │ (docs-publisher) │
│ ────────────────── │ │ ──────────────────────────────── │
│ · 대상 .md 수정 │ │ · docs-docusaurus/ 설정/스크립트 │
│ · status: published │ │ /custom CSS 수정 │
│ 유지 (롤백 아님) │ │ · 또는 copy-from-manuscript.mjs │
│ · 자리표시자 잔존 0 │ │ 로직 수정 │
│ 재확인 │ │ · manuscript/ 는 손대지 않음 │
└────────┬─────────────┘ └──────────┬───────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ Stage R-3: 안전 재검수 (manuscript-architect) │
│ ───────────────────────────────────── │
│ manuscript-fix 인 경우: │
│ · 변경된 글에 full-review 호출 (좁게 재실행 가능) │
│ · 회귀 여부 — 다른 글에 영향 없는지 grep 으로 점검 │
│ build-fix 인 경우: │
│ · 로컬에서 copy-from-manuscript + build 통과 확인 │
│ · 다른 글의 렌더링이 깨지지 않는지 회귀 점검 │
│ 안전 통과 시 Stage R-4 로 │
└────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Stage R-4: PATCH 태그 배포 (docs-publisher) │
│ ───────────────────────────────────── │
│ git commit + push origin main │
│ git tag vX.Y.(Z+1) -m "fix: <증상 요약> (#<이슈번호>)" │
│ git push origin vX.Y.(Z+1) │
│ → GitHub Actions 가 새 PATCH 로 배포 │
│ 배포 성공 후: │
│ gh issue close <num> --comment │
│ "수정 적용 — vX.Y.(Z+1) 배포 완료. 사이트 확인 요청." │
└─────────────────────────────────────────────────────────────┘
Stage별 산출물
| Stage | 산출물 | 위치 |
|---|---|---|
| R-0 | 이슈 목록/본문 | GitHub repo issues (label:editorial) |
| R-1 | 트리아지 코멘트 + 라벨 | 이슈 본체 (gh issue comment/edit) |
| R-2A | 원고 수정 diff | manuscript/articles/<>.md |
| R-2B | 빌드 설정/스크립트 수정 | docs-docusaurus/... |
| R-3 | 안전 검수 리포트 | harness/logs/full-review/ 또는 harness/logs/docs-publisher/ |
| R-4 | PATCH 태그 + 이슈 close 코멘트 | git tag + GitHub issue |
트리거별 진입 Stage
| 사용자 요청 | 진입 Stage |
|---|---|
| "이슈 확인 / editorial 이슈 점검" | R-0 |
| "이슈 #N 트리아지" | R-1 |
| "manuscript-fix 진행 (이슈 #N)" | R-2A |
| "build-fix 진행 (이슈 #N)" | R-2B |
| "리비전 재검수" | R-3 |
| "PATCH 태그 발행 #N" | R-4 |
| "이슈 #N 기반 리비전" (전체 흐름) | R-0~R-4 자동 |
안전 규칙
- manuscript-fix 와 build-fix 를 한 PATCH 에 섞지 않는다 — 회귀 발생 시 원인 식별이 어려워진다. 분리해서 두 PATCH 로 (예: v1.0.1 = build-fix, v1.0.2 = manuscript-fix)
- manuscript-fix 시에도 status: published 유지 — 롤백이 아니라 같은 글의 새 리비전
- rejected 결정도 코멘트 의무 — 왜 반려했는지 이슈에 한 줄 남기기
- 재현 불가 시 정보 요청 후 보류 — 무리한 추정 fix 금지
Type 5: 시리즈형 (Series)
관련 글 N편을 묶어 동시 발행.
- 각 글이 Type 1 흐름을 병렬로 거치되,
- Stage 3.5 에서 상호 참조 일관성 추가 점검 (예: 같은 개념의 표기 통일, 절 번호의 상호 호출)
- Stage 5 의 태그는 MINOR bump (시리즈 N편 모두 한 태그로)
종합 평가 (정원지기 시점)
엔진 1회 실행이 끝나면 [[tamer]] 가 3축 평가:
| 축 | 평가 | 기준 |
|---|---|---|
| 파이프라인 효율 | A/B/C/D | 단계 간 대기 시간, 리워크 횟수 |
| 검수 품질 | 1~5 | full-review + manuscript-architect lint 통과율 |
| 배포 안정성 | A/B/C/D | CI 빌드 성공 여부, 깨진 링크 수 |
v1.0.0 사이클 평가 (참고)
| 축 | 점수 | 메모 |
|---|---|---|
| 파이프라인 효율 | B+ | Stage 5 에서 YAML 콜론 함정 / 환경 정책 / Pages 가시성 3건 시행착오 — 다음 사이클부터는 zero |
| 검수 품질 | 5/5 | full-review 가 약어 정의 누락을 즉시 잡아냄, manuscript-architect lint 통과 |
| 배포 안정성 | B | 첫 시도 3건 실패 후 4번째 성공. 학습 사항은 [[docs-publishing]] 에 누적 |
한계
- 사람이 본문을 작성하는 Stage 0~1 에서 파이프라인이 일시중단된다 — 완전 자동화 X
- 이미지 생성은 편집장이 자리표시자/본문 신호를 보고 판단 — 자동 생성 X
- 영문/다국어 번역은 본 파이프라인 범위 밖 (향후 별도 엔진 또는 Type 3 변형으로 확장)
위임 표
| 작업 | 담당 |
|---|---|
| 초안 → 정식 원고 변환 (Stage 1) | [[manuscript-architect]] |
| 보조 이미지 생성 판단 (Stage 2) | [[manuscript-architect]] → .claude/skills/image-gen/ 호출 |
| 내용 검수 (Stage 3) | [[full-review]] 엔진 → 3인 전문가 |
| 보강 적용 (Stage 3.5) | 사용자 또는 [[manuscript-architect]] |
| 형식 lint + 승급 (Stage 4) | [[manuscript-architect]] |
| 배포 (Stage 5) | [[docs-publisher]] |
| 신규 외부 시스템 (예: Slack 공지, Notion 미러링) | [[tamer]] Mode B 제안 |
새 유형이 발견될 때
사용자가 기존 유형으로 잘 안 잡히는 진입을 들고 오면:
- [[tamer]] 가 "Type N 후보" 로 식별
- 공통 stage(2~5)와의 차이를 정리
- 본 문서의 유형 카탈로그 표에 placeholder 로 추가
- 사용 사례가 2회 누적되면 본격적인 Stage 절차 작성
새 유형을 미리 만들지 않는다. 두 번 발생해야 자리가 잡힌다.