원고 규약

원고지는 단일 출처다 — 빌드 도구는 여기서 읽기만 한다. 그래서 형식이 흔들리면 빌드 산출물 전체가 흔들린다. 이 문서가 그 형식을 잡는다.

디렉터리 구조

manuscript/
├── README.md           ← 사용자용 안내
├── _template.md        ← 새 글 골격
└── articles/
    └── <order>-<slug>.md

_ 로 시작하는 파일(_template.md 등)은 빌드 시 제외된다 — copy-from-manuscript.mjs 의 path.basename(rel).startsWith('_') 필터.

파일명

articles/<order>-<slug>.md

<order> — 카테고리 내 정렬 정수, 10 단위 권장 (010, 020, 030 ...)
<slug> — 영문 또는 한글 kebab-case
- 영문 예: 010-harness-intro.md
- 한글 예: 020-원고-규약.md
파일명의 <slug> 가 URL slug 가 된다 — Docusaurus가 frontmatter에 slug를 명시하도록 copy 스크립트가 자동 주입

frontmatter

각 글 상단의 YAML frontmatter:

---
title: 하네스로 만드는 테크 라이팅, 첫걸음
order: 10
status: draft
date: 2026-05-25
description: 한 줄 요약
category: harness
---

필드	필수	타입	의미
`title`	✅	string	글 제목 — 사이트 페이지 제목으로 사용
`order`	✅	int	사이드바 정렬값 (10 단위 권장)
`status`	✅	enum	`draft` / `review` / `published`
`date`	선택	YYYY-MM-DD	작성/수정 일자
`description`	선택	string	검색 결과/카드 노출 한 줄
`category`	선택	string	분류 라벨

order 규칙

한 카테고리(또는 articles/ 전체) 내에서 유일해야 한다
새 글 추가 시: 기존 최대 order + 10
두 글 사이에 끼우려면: 사이 값(예: 25)
사이드바 노출 순서를 바꿀 때 frontmatter만 수정 → 파일명도 같이 갱신 (slug 안정성 위해)

status enum 외 값 금지

다른 값(wip, archived 등)을 도입하려면 [[manuscript-architect]] 가 본 규약 갱신을 먼저 수행해야 한다. copy-from-manuscript.mjs 의 MANUSCRIPT_STATUS_FILTER 도 함께 갱신.

status — 검수 워크플로우

draft  →  review  →  published
  │         │           │
  │         │           └─ 자동 배포 대상
  │         └─ 검수 대기 (빌드에서 제외)
  └─ 골격만 (빌드에서 제외)

status	의미	비고
`draft`	골격 + 자리표시자 위주	작성 중
`review`	본문 작성 완료, 검수 대기	full-review 호출 가능
`published`	검수 통과 — 정식 발행	자동 배포

승급 조건

전이	조건
`draft → review`	frontmatter 필수 필드 모두 채워짐 / 본문이 자리표시자만은 아님 (텍스트 비율 ≥ 50%)
`review → published`	자리표시자 0건 / 템플릿 주석 제거됨 / full-review 모든 영역 ≥ B 또는 ≥ 3 / manuscript-architect lint 통과

자리표시자 (Placeholders)

[[TYPE: 의도]] 형태. 본문의 자리만 잡아두고 나중에 실제 내용으로 교체한다.

TYPE	용도	예시
`INTRO`	첫 한 줄 — 글이 답하는 질문	`[[INTRO: 카카시 하네스가 왜 필요한지 한 줄로]]`
`BULLET`	항목 한 줄	`[[BULLET: 정원지기의 역할]]`
`CONTEXT`	배경/맥락	`[[CONTEXT: 어떤 문제를 풀려는지]]`
`BODY`	본문 한 단락	`[[BODY: 정원의 세 겹 토양 설명]]`
`FIGURE`	이미지/다이어그램	`[[FIGURE: ![cover](./images/cover.png)]]`
`CODE_OR_QUOTE`	코드/명령/인용	`[[CODE_OR_QUOTE: npm install ...]]`
`KEY_TAKEAWAY`	마무리 한 줄	`[[KEY_TAKEAWAY: 정원은 도구가 아니라 태도다]]`
`REF`	외부 링크/참고	`[[REF: book-happtalk 레퍼런스]]`
`SCREENSHOT`	캡처 필요 표시	`[[SCREENSHOT: GitHub Pages 설정 화면]]`

규칙

자리표시자가 status: published 글에 잔존하면 lint 실패 — 빌드는 통과해도 사이트에서 [[...]] 가 그대로 노출되어 부끄럽다
status: review 글에는 잔존 시 경고만 — 작성자에게 채우라고 알린다
자리표시자를 새 TYPE 으로 확장하려면 본 문서에 추가하고 [[manuscript-architect]] 검수 로직도 갱신

이미지

상대 경로만 허용

✅ ![cover](./images/cover.png)
✅ ![logo](../assets/logo.png)
❌ ![bad](/absolute/path.png)            ← copy 스크립트가 그대로 둠 → 빌드 시 404
❌ ![bad](C:\Users\...\foo.png)          ← 동일

외부 이미지 (manuscript/ 바깥)

상대경로로 외부 디렉터리(예: ../assets/)를 가리키면 copy 스크립트가 docs-docusaurus/docs/_assets/<parent>/<file> 로 자동 복사 + 경로 재작성.

이미지 생성

[[FIGURE: ...]] 자리표시자를 채울 때 .claude/skills/image-gen/ 호출 권장. 생성된 이미지의 위치 컨벤션:

manuscript/articles/images/<글-slug>-<purpose>.png
또는 글마다 폴더 분리: manuscript/articles/<slug>/images/*.png

템플릿 주석

manuscript/_template.md 의 하단  블록은 작성자가 본문 채우는 동안 도움말 역할. status: published 승급 전 반드시 제거한다. lint 가 잔존 여부를 점검한다.

빌드 측 행동 요약

빌드 도구(copy-from-manuscript.mjs)가 하는 변환:

manuscript frontmatter	docs frontmatter
`title`	`title` (그대로)
`order`	`sidebar_position`
`description`	`description`
파일명의 slug	`id`, `slug` 명시 주입
`category` / `status` / `date`	주석 형태로 보존 (`# category: ...`)

{{변수}} 문법은 MDX 파서가 JS 평가하지 않도록 백틱 inline code 로 자동 escape.

디렉터리 구조​

파일명​

frontmatter​

order 규칙​

status enum 외 값 금지​

status — 검수 워크플로우​

승급 조건​

자리표시자 (Placeholders)​

규칙​

이미지​

상대 경로만 허용​

외부 이미지 (manuscript/ 바깥)​

이미지 생성​

템플릿 주석​

빌드 측 행동 요약​