Build & Operate

Authoring 플레이북

AI 초안 생성과 사람이 직접 편집하는 흐름을 하나의 운영 루프로 묶을 때 필요한 mode 전환, 저장 전략, 검수 기준을 정리합니다.

reopt designUpdated Jun 26, 2026

1. 운영형 authoring 루프

Step 1

Prompt 준비

사용자 의도, 대상 독자, 문서 톤, 필수 섹션을 정리하고 필요하면 currentSpec을 함께 넣습니다.

Step 2

AI 스트리밍 생성

buildAIMessages와 useEditorStream으로 NDJSON 패치를 적용하면서 초안을 만듭니다.

Step 3

리뷰 및 직접 편집

stream 모드에서 초안을 확인한 뒤 edit 모드로 전환해 세부 문장을 수정합니다.

Step 4

검수 및 보강

블록 누락, 링크, 표, callout, custom block 적용 여부를 점검하고 필요하면 추가 generation을 수행합니다.

Step 5

저장 및 배포

원본 spec을 저장하고, publish 단계에서 markdown 또는 다른 출력 포맷으로 변환합니다.

2. mode 전환 기준

단계	권장 mode	판단 기준
초안 생성	`stream`	AI가 패치를 연속 적용하는 동안 사용자는 구조가 쌓이는 흐름만 확인하면 됩니다.
인간 검수/수정	`edit`	세부 문장, heading 구조, custom block props를 직접 다루는 단계입니다.
부분 재생성	`stream`	currentSpec을 포함한 수정 요청을 보내고, 기존 구조를 유지한 채 필요한 구간만 다시 생성합니다.

3. end-to-end 파이프라인 예제

실제 서비스에서는 prompt 준비, API 호출, SSE 변환, NDJSON 적용, 저장까지를 하나의 action으로 묶는 편이 좋습니다. 아래 예제는 그 최소 형태입니다.

tsx

import {
  buildAIMessages,
  defaultCatalog,
  extractSSEText,
  transformToNDJSON,
  useEditorStream,
} from "@reopt-ai/opt-editor";

async function generateDraft(prompt: string) {
  const messages = buildAIMessages({
    prompt,
    catalog: defaultCatalog,
    currentSpec: JSON.stringify(store.getSpec()),
  });

  const response = await fetch("/api/editor/generate", {
    method: "POST",
    body: JSON.stringify({ messages }),
  });

  await start(
    transformToNDJSON(
      extractSSEText(response.body!.pipeThrough(new TextDecoderStream())),
    ),
  );

  await saveDraft({
    spec: store.getSpec(),
    markdown: specToMarkdown(store.getSpec()),
  });
}

4. 저장 전략

저장 대상	왜 필요한가
Editor spec	가장 완전한 원본이며 block 구조와 편집 상태를 보존합니다.
Markdown export	검색, diff, 외부 공유, AI 재입력 컨텍스트에 유리합니다.
Prompt / generation log	왜 이런 초안이 생성됐는지 추적하고 재시도 정책을 조정할 수 있습니다.
Published snapshot	배포된 결과물을 고정해 회귀 검수와 rollback 기준으로 씁니다.

세부 스트리밍 계약은 스트리밍 문서와 AI 연동 가이드에 위임하고, 이 페이지는 운영 루프 기준만 담당하는 편이 좋습니다.

5. 검수 체크리스트

- stream 중단 후 resume이 같은 패치 시퀀스를 기준으로 이어쓰기 되는지 확인합니다.

- 사용자 편집 이후 재생성 시 currentSpec 기반 부분 수정 프롬프트를 사용합니다.

- 커스텀 블록이 있으면 prompt, schema, render 결과가 모두 일치하는지 검증합니다.

- 저장 시 spec과 markdown export를 동시에 보관해 publish 경로를 단순화합니다.

- 검수 단계에서 링크, 표, callout, heading depth 같은 구조 규칙을 자동 점검합니다.