문서 작성 규약¶

이 학습서를 쓰고 고칠 때 지키는 규칙입니다. 새 장을 추가하거나 기존 장을 수정하기 전에 확인합니다.

이 문서가 정하는 것¶

장의 구성 순서와 각 절의 역할
예제를 재현 가능한 형태로 남기는 파일 규격
도식과 이미지의 제작 기준, 색상이 뜻하는 것
문서를 분할하는 기준과 반영 전 점검 절차

편집 원칙¶

Diffusion 원리를 ComfyUI 노드와 연결해 배우는, 실험 중심 한국어 오픈 교재.

공식 자료로 최신성과 정확성을 확인하고, 생성형 이미지의 원리와 실습을 한국어로 만들어 나갑니다.

문서의 양보다 학습자의 첫 성공, 재현, 설명, 응용을 우선합니다. 구체적으로 다음을 지킵니다.

학습 순서를 하나로 잇습니다. 앞 장이 뒤 장의 전제가 되도록 배치하고, 전제가 없는 내용을 앞에 두지 않습니다.
한 변수 실험을 넣습니다. Seed를 고정하고 값 하나만 바꿔 비교하는 절차를 실습에 포함해, 결과의 원인을 스스로 짚게 합니다.
설정값의 근거를 밝힙니다. 노드 입력의 범위와 기본값은 실제 구현을 확인해 적고, 커스텀 노드가 필요한 기능은 그 사실을 함께 표시합니다.
깊은 주제를 회피하지 않되 부담을 나눕니다. 배경 원리와 참조 정보는 접이식으로 두어 필요할 때만 펼치게 합니다.
정본을 복사하지 않습니다. 같은 내용을 두 곳에 두지 않고 링크로 연결합니다.

표준 장 템플릿¶

새 장을 만들거나 기존 장을 고칠 때 아래 순서를 씁니다. 본문 장 29개가 이 구조입니다. 섹션 인덱스, 참조표, 용어 사전은 학습 절이 없어 일부 항목이 빠집니다.

# 장 제목

> 한 문장 목표

## 이 장에서 배우는 것

- 이 장의 결론을 서술형 두세 줄로 적습니다. 같은 내용을 명사형 목록으로 겹쳐 쓰지 않습니다.

<div class="guide-meta" markdown>
**대상** 누가 읽는가 · **사전 이해** 앞서 끝냈어야 할 것 · **시간** 예상 소요

**이럴 때 읽으세요** 이 문서를 찾게 되는 상황
</div>

## 1. 첫 절

본문. 절 번호는 한 문서 안에서 통일합니다. 붙인 문서와 붙이지 않은 문서가 섞여 있어도 됩니다.
배경 원리와 참조 정보는 접이식 블록에 넣습니다.

## 완료 기준

세 가지를 모두 만족했다면 이 장을 끝냈습니다.

- 관찰 가능한 행동으로 적습니다.

## 다음 단계

- 다음 문서로 가는 링크 하나와, 그 문서가 다루는 것 한 줄

설명과 실습의 권장 비율은 입문 40:60, 중급 50:50, 심화 60:40입니다. 비율 자체보다 한 화면 이상 읽은 뒤 바로 손을 움직일 기회가 있는지가 중요합니다.

재현 가능한 예제 규격¶

워크플로우 하나를 추가할 때 다음 네 파일을 한 디렉터리에 둡니다.

examples/<topic>/<example-name>/
├── README.md       목적, 준비물, 실행 순서, 관찰 질문
├── workflow.json   ComfyUI에서 불러올 워크플로우
├── preview.webp    그 워크플로우로 만든 대표 결과 한 장
└── params.yml      모델, Seed, Steps, CFG, Sampler, 해상도, 검증일

ComfyUI의 Save Image는 워크플로우 정보를 PNG 메타데이터로 넣습니다. webp로 바꾸면 그 정보가 사라지므로, 복원용 원본은 같은 폴더의 workflow.json이 맡습니다. preview.webp는 결과를 보여 주는 용도입니다.

결과 이미지 필수 메타데이터¶

사용 모델의 정확한 이름과 다운로드 출처
모델·LoRA·입력 이미지 라이선스
Positive/Negative prompt 전문
Seed, Steps, CFG/Guidance, Sampler, Scheduler, 해상도
ComfyUI 버전 또는 검증일
커스텀 노드 이름과 버전
후처리 여부

실제 ComfyUI 결과와 장식용 AI 생성 이미지를 혼동하지 않도록 캡션에 용도를 표시합니다.

시각 자료 원칙¶

종류	언제 사용	제작 기준
UI 스크린샷	클릭 위치·에러 위치가 핵심일 때	필요한 영역만 자르고 번호/테두리 표시, 버전 기록
결과 비교	파라미터 효과를 배울 때	Seed와 나머지 값을 고정, 같은 크기로 나란히 배치
SVG 흐름도	데이터 흐름과 구조를 설명할 때	색만으로 구분하지 않고 라벨 병기, 확대해도 선명하게
개념 일러스트	첫 이해와 흥미를 도울 때	실제 결과가 아님을 캡션에 표시, 핵심 구조를 왜곡하지 않기
짧은 영상/GIF	드래그·마스킹처럼 움직임이 핵심일 때	20초 안팎, 정지 이미지 대체 설명 제공

이미지는 장식이 아니라 다음 질문 중 하나에 답해야 합니다: “어디를 누르나?”, “무엇이 연결되나?”, “값을 바꾸면 어떻게 달라지나?”, “정상과 오류가 어떻게 다른가?”

이미지 배치 클래스¶

stylesheets/extra.css에 세 가지가 있습니다. 용도가 달라 서로 바꿔 쓰지 않습니다.

클래스	쓰는 곳	폭
`.workflow-figure`	가로로 긴 전체 배선도	넓은 화면에서 본문 폭을 벗어남
`.result-compare`	값 하나만 바꾼 결과를 나란히	본문 폭, 화면이 좁아지면 한 열로 접힘
`.node-shot`	노드 한 개 클로즈업	최대 26rem

노드 한 개짜리 그림에 .workflow-figure를 쓰면 본문 폭까지 늘어나 실제 화면보다 크게 보입니다. 반대로 배선도를 .node-shot에 넣으면 연결선을 읽을 수 없습니다.

폴더 구조는 .filetree를 씁니다. 아이콘을 붙이려면 .filetree--icon을 함께 적습니다. ├── 같은 문자는 글꼴에 따라 선이 어긋나고 화면 낭독기가 기호를 읽으므로 쓰지 않습니다.

이미지 포맷과 화질¶

용도	포맷	이유
결과 비교	WebP 무손실	손실 압축이 만든 흔적을 파라미터 차이로 오해하면 실습이 성립하지 않습니다
UI 스크린샷	WebP 무손실	글자와 선의 경계가 흐려지면 어디를 누를지 읽기 어렵습니다
개념 일러스트	WebP `quality=95`	비교 대상이 아니므로 크기를 줄입니다

im.save("out.webp", format="WEBP", lossless=True, method=6)
im.save("out.webp", format="WEBP", quality=95, method=6)

method=6은 압축을 가장 세게 시도합니다. 인코딩이 느려지는 대신 화질은 그대로고 파일만 작아집니다.

같은 이미지를 1024×1024로 인코딩해 잰 값입니다. PNG 640KB, WebP 무손실 462KB, WebP quality=95 128KB였습니다. 무손실이 필요한 경우에도 PNG 대신 WebP를 씁니다.

원본은 ComfyUI가 내보낸 PNG를 그대로 두고 변환합니다. 화면 캡처를 JPEG으로 먼저 저장하면 되돌릴 수 없습니다.

워크플로우 SVG는 다음 기준을 함께 지킵니다.

연결선은 출력 포트 중심에서 시작하고 입력 포트 중심에서 끝냅니다.
ComfyUI 워크플로우 도식은 기본 UI처럼 연결 화살표를 쓰지 않고, 오른쪽 출력·왼쪽 입력 포트로 방향을 나타냅니다.
선이 다른 노드 뒤를 통과하지 않게 배치하고, 필요한 경우 ComfyUI가 지원하는 직각 연결선이나 Reroute 방식으로 우회합니다.
색만으로 구분하지 않고 노드명·포트명·데이터 타입을 함께 표시합니다.
실제 UI 노드명은 KSampler, VAE Decode, Save Image처럼 화면 표기와 맞춥니다.
python scripts/check-docs.py로 연결선과 포트의 좌표 불일치를 검사합니다.

의미 기반 강조 색상¶

색상은 장식이 아니라 문서 전체에서 같은 의미를 전달하는 데 씁니다.

의미	색상 역할	함께 표시할 정보
핵심 개념	보라	용어명·굵은 핵심어
실행·설정	파랑	단계명·입력값·코드
결과·완료	초록	결과 제목·완료 체크
주의	주황	`주의`·`경고` 라벨
오류·문제	빨강	증상·오류명·해결 제목

색만으로 의미를 구분하지 않고 제목, 라벨, 아이콘 또는 문장을 함께 둡니다.
본문 전체나 긴 문단을 색칠하지 않고 핵심어와 구조 요소에만 적용합니다.
밝은 화면과 어두운 화면 모두에서 대비를 확인합니다.
새 색상을 임의로 추가하지 않고 stylesheets/extra.css의 의미 변수를 재사용합니다.

문서 유지보수 기준¶

파일 길이¶

길이	상태	조치
~500줄	적정	유지
500–800줄	주의	실습 또는 주제 단위로 분할 검토
800줄+	분할 권장	상위 인덱스와 하위 장으로 분리

분할 원칙¶

논리적 단위와 학습 목표로 나눕니다.
파일명은 의미를 드러내고 part-01 같은 순번 의존을 피합니다.
상위 인덱스에서 새 장을 반드시 링크해 고아 문서를 만들지 않습니다.
같은 정본을 요약본에 복사해 이중 관리하지 않습니다.

반영 전 점검¶

python scripts/check-docs.py
python scripts/check-nav.py
python scripts/check-style.py
mkdocs build --strict

링크, 네비게이션, 문체·용어, 사이트 빌드가 모두 통과해야 문서 변경을 완료한 것으로 봅니다.

check-style.py는 이 문서가 정한 표현 규칙과 용어 사전 등재 여부를 검사합니다. 새 노드나 기능 이름을 문서에 넣을 때는 용어 사전에 표제어를 만들고, 스크립트의 UI_TERMS 목록에도 추가합니다.

계획과 미결 항목¶

작업 계획과 미결 항목은 저장소의 이슈로 관리합니다.

다음 단계¶

문서 지도 — 목적별로 문서 찾기
용어 사전 — 본문에서 쓰는 용어의 정의
기본 Text-to-Image 템플릿 — 예제 규격을 적용한 실물