collection-writing-standards

name	collection-writing-standards
description	컬렉션 글(content/collection/**/index.md, **/*.md)을 작성할 때 따르는 이론 중심 글쓰기 표준. 전문가 수준의 이론적 설명을 문단으로 먼저 서술하고 코드/표/다이어그램은 보충 자료로만 쓰도록 한다. 컬렉션 글 작성·보강, 기술 시리즈 글 작성 시 사용한다.

컬렉션 글 작성 표준: 이론 중심 + 예제 보충식

content/collection/**/*.md를 작성·보강할 때, 전문가 수준의 이론적 설명을 유지하고 예제는 개념 보충에만 쓰도록 하는 기준이다.

함께 적용

• rules-that-must-be-followed: frontmatter, 링크 검증, Mermaid
• educational-content-writing: 교육 콘텐츠 구조·깊이·안티패딩·내용 완결성(§7 석학/SME 기준) (이 스킬은 이를 보완)
• blog-post-writing: SEO, 태그, 내부 링크

---

1. 핵심 원칙 3가지

1.1 이론 우선 (Theory-First)

본문의 주요 설명은 문단으로 이론·원칙·개념을 먼저 서술하고, 코드/표/다이어그램은 그 뒤에 보충한다.

(이론/원칙을 2-3문단으로 설명)
   ↓
(그 원칙을 보여주는 예제 1-2개)
   ↓
(예제에서 주의점·트레이드오프 1-2문장)

피할 것: 코드만 연속 배치, 예제를 먼저 제시한 뒤 설명(역순), 개념 문단 없이 예제 주석에만 의존.

1.2 예제는 보충 (Examples as Reinforcement)

목적	형태	분량
개념 설명	문단 (필수)	150-300어
개념 보충	코드 / 표 / 다이어그램 (부가)	코드 ≤50줄, 표 ≤5행
비교/차이	병렬 예제 또는 표 (필수)	각 2-10줄
실전 적용	완성된 코드 또는 사례 (선택)	20-100줄 또는 상세 설명

• 본문에서 "개념 A는 ~이다"를 문단으로 설명한 뒤 코드를 붙인다.
• 코드 블록 앞에 "다음 예제는 위 개념을 보여준다" 정도의 전개 1-2문장을 추가한다.
• 코드 뒤에 "이 코드의 주의점은 ~" 정도의 해석을 추가한다.
• 코드만 2개 이상 연달아 나열하지 않는다. 사이에 설명 문단을 끼워 넣는다.

1.3 정확성과 출처 (Accuracy & Attribution)

AI 생성 내용의 환각·오류를 방지하기 위해 다음을 검증한다.

1. 역사/인물: 연도, 저자명, 원저 제목을 정확히 기록한다. 불확실하면 "여러 문헌에서 언급된 바"로 완화한다.
2. 기술 사실: 크기(sizeof), 버전별 동작, 성능 수치는 추측하지 않는다. 불명확하면 "구현 정의" 또는 "플랫폼에 따라 다름"으로 표기한다.
3. 외부 링크: 본문에 포함하기 전 모든 URL의 접근 가능 여부를 확인한다 (404/5xx 제거).
4. 인용 블록: 직접 인용문은 blockquote + 출처(저자, 연도, 책/논문 제목, URL)를 필수로 한다.

✓ > "..." — Donald Knuth, 『The Art of Computer Programming』(1968)
✓ 이 알고리즘의 시간 복잡도는 O(n log n)이다 (실제 구현과 플랫폼에 따라 상수배 차이 발생).
✗ (추측으로 단정) 이 구조체는 정확히 24바이트다.
✗ (검증 없는 주장) 이 알고리즘은 항상 가장 빠르다.

교육/시리즈형 콘텐츠에서 "정량적"·"측정"을 표방하는 경우의 추가 요구사항(실측치·벤치마크 스켈레톤 등)은 educational-content-writing §4.4를 따른다.

---

2. 본문 구조

2.1 문단 비율

본문 + 코드 + 다이어그램의 총합 중 문단이 최소 40% 이상을 차지하도록 한다. 문단은 설명·원칙·비판적 시각·트레이드오프를 담고, 코드/표/다이어그램은 예시·구체화·시각화를 담는다.

예: 총 1000줄 글이라면 문단 400줄 이상(이론 설명), 코드 300줄(예제 2-3개, 각 100줄 미만), 표/다이어그램 100줄(3-4개), 나머지는 heading/공백.

2.2 섹션별 가이드

섹션	목표	구성	예제 분량
도입	읽어야 하는 이유 전달	문제 상황 + 해결할 개념 소개 (1-2문단)	불필요
핵심 개념	개념·원칙을 정확히 이해	용어 정의(첫 등장 시 굵게) → 원칙 설명(2-4문단) → 구조/체계(문단/표) → (선택) 작은 예제	≤20줄 코드 또는 표 1개
비교/트레이드오프	선택지 간 차이 이해	각 방식 개념 설명(문단) → 비교 표(필수) → 병렬 예제(각 10-20줄) 또는 다이어그램(필수) → 언제 어느 것을 쓸지(문단)	비교용 코드 2-3개 또는 표 1개
실전 적용	실제 적용 방법 제시	상황 설정(문단) → 단계별 구현(설명+코드) → 주의점/최적화 팁(문단)	완성 코드 1-2개 (30-100줄)
마무리	핵심 요약 + 다음 단계	핵심 요약 표 또는 3-5줄 문단 → 평가 기준(체크리스트 3-6항) → (선택) 다음 글 링크	불필요

2.3 예제 배치 패턴

**작은 예제(≤20줄)**는 개념 직후에 배치하고 설명 2-3문장을 붙인다.

**복제(Copy)** 방식은 각 객체가 독립적으로 자신의 데이터를 가진다.

[설명 문단 2-3문장]

```cpp
class Counter {
    int count = 0;
    void increment() { count++; }
};
Counter a, b;  // 각각 독립적인 count

공유(Shared) 방식은 여러 객체가 같은 데이터를 가리킨다.

[설명 문단 2-3문장]

**큰 예제(>50줄)**는 "실전 적용" 섹션으로 분리하고 단계별로 설명한다(각 단계 앞에 설명 문단 → 코드).

---

## 3. 용어·역사·정량 분석

- **용어**: 첫 등장 시 **영문(한글)** 또는 **한글(영문)**을 병기한 뒤 이후 한글로만 표기한다 (예: **Tree(트리)**는 ... 이후 "트리"). 새 개념은 기존 개념과의 관계("X는 Y의 특수한 경우이다")를 명시한다.
- **역사/배경**: 주제가 요구하면 "탄생 배경" 또는 "진화 과정" 절을 추가하고, 저자·연도·원문(책/논문)·당시 문제 상황을 포함한다.
- **정량 분석**: "정량적", "측정", "벤치마크", "성능 분석"을 표방하면 실제 수치(플랫폼·컴파일러·플래그 명시) 또는 실행 가능한 벤치 코드를 최소 1개 포함한다. 사실·정확성 검증의 상세 기준은 [`educational-content-writing`](../educational-content-writing/SKILL.md) §4.4를 따른다.

---

## 4. 안티패턴 (금지 사항)

**본문**

1. 코드만 연속 배치 — 2개 이상 코드 블록이 설명 없이 이어지지 않게, 사이에 문단을 추가한다.
2. 답 없는 리스트 — "생각해볼 질문 10가지"처럼 항목만 나열하지 않는다. 각 항목에 1-2줄 설명을 붙인다.
3. 중복 요약 — "핵심 요약", "최종 정리", "이 섹션 마무리"처럼 같은 내용을 반복하지 않는다. 마무리는 한 형식(표 또는 체크리스트 또는 문단)만 둔다.
4. 작성자용 메타 — "게시 전 자가 점검", "편집자 주" 등은 본문에서 삭제한다.
5. 존재하지 않는 자료 참조 — 링크는 항상 존재·접근 확인 후 포함한다.

**예제**

1. 미정의 타입 사용 — `T`, `vec`, `pred` 같은 타입을 정의 없이 쓰지 않는다. 의사코드는 `text` 언어로 명시한다.
2. 주석만 의존 — `/* 처리 로직 */` 같은 블록으로 핵심을 대체하지 않는다.
3. 컴파일 불가능 — 실제 코드 예제는 `#include`, 타입 정의, `main()` 등을 갖춰 컴파일 가능해야 한다.
4. 출처 없는 수치 — "수 배 빠르다", "거의 항상" 같은 양적 주장에는 수치 또는 출처를 명시한다.

---

## 5. 컬렉션별 추가 고려사항

| 컬렉션 | 추가 규칙 |
|--------|---------|
| **Algorithm** | [`algorithm-post-writing`](../algorithm-post-writing/SKILL.md) 참고. 시간/공간 복잡도를 표로 정리. |
| **Design Patterns** | 패턴의 탄생 배경(저자, 연도) + 장단점 표 필수. 안티패턴과의 비교 포함. |
| **Optimization** | 성능 주장은 반드시 벤치 또는 실행 가능한 코드 포함. 플랫폼/플래그 명시. |
| **Vocabulary** | [`vocabulary-post-writing`](../vocabulary-post-writing/SKILL.md) 참고. 단어 정의 + 콜로케이션 + 유의어 비교 표 필수. |
| **Bash/CMD** | [`shell-command-post-writing`](../shell-command-post-writing/SKILL.md) 참고. |
| **Movies** | [`movie-review-writing`](../movie-review-writing/SKILL.md) 우선 적용. |

---

## 6. 컬렉션 개정·확장 절차

기존 컬렉션(00장/개요, 여러 챕터로 구성된 시리즈)을 개정하거나 새 챕터를 추가할 때 지키는 절차다. 컬렉션 하나에 챕터가 여러 개면, 한 챕터의 변경이 다른 챕터의 전제를 깨뜨리기 쉽다 — 이 절은 그 위험을 구조적으로 줄인다.

### 6.1 형제 게시물 교차 참조 감사

00장/개요를 개편하거나, 챕터를 추가·재배치하거나, 어떤 챕터의 슬러그·범위·"마지막 장" 여부가 바뀌면, **같은 컬렉션의 모든 형제 게시물**을 감사 대상으로 삼는다.

- **점검 항목**: (a) 그 챕터를 가리키는 내부 링크가 실제 슬러그와 여전히 일치하는가, (b) "이전/다음 장에서는" 같은 내비게이션 서술이 바뀐 순서·범위를 반영하는가, (c) "이 장이 마지막"이라고 명시한 서술이 새 챕터 추가 후에도 여전히 사실인가.
- **기계적 검증을 권장한다**: 컬렉션 폴더 전체에서 내부 링크(`/post/<section-slug>/<page-slug>/` 패턴)를 추출하고, 각 대상 파일의 실제 `slug:` 프론트매터 값과 대조한다. 파일을 하나씩 눈으로 읽고 "괜찮아 보인다"고 넘어가는 것보다, grep/스크립트로 전수 대조하는 쪽이 훨씬 신뢰도가 높다 — 조용히 깨진 참조는 읽는 것만으로는 잘 드러나지 않는다.

### 6.2 대규모 개정의 다단계 검토 캐스케이드

여러 챕터를 새로 쓰거나 커리큘럼을 개편하는 등 규모가 큰 작업에는, 하나의 리뷰로 뭉뚱그리지 않고 **서로 다른 렌즈**로 순차 검토한다.

1. **기술적 정확성**: 코드가 실제로 컴파일 가능한지, 인용한 사실·수치·연도가 정확한지.
2. **내용 완결성·안티패딩**: 교육 콘텐츠라면 [`educational-content-writing`](../educational-content-writing/SKILL.md) §7의 완결성 축과 대조.
3. **챕터 간 서술 흐름**: 용어가 챕터마다 통일됐는지, 같은 개념을 중복 설명하지 않는지, 여러 챕터를 이어서 읽었을 때만 드러나는 이음매(용어 표기가 챕터마다 다르다, 앞 챕터가 뒷 챕터를 반영 못한 채 남아 있다 등)가 있는지.
4. **신선한 시각의 발행 편집자 검토**: 오탈자, 본문 내 모순, 미완성 흔적, 각 챕터 도입부의 첫인상.

각 렌즈는 이전 라운드의 결과를 모르는 새 서브에이전트로 수행해 확증 편향을 피한다. 작업 규모에 맞게 렌즈 수를 조절한다 — 오탈자 수정처럼 작은 변경에 4단계를 전부 돌리는 것은 과도하다.

### 6.3 실빌드 게이트

여러 파일에 걸친 개정 뒤에는, 로컬에 정적 사이트 생성기(Hugo 등)가 있다면 최소 1회 실제 빌드(예: `hugo --buildDrafts --gc`, 더 빠르게 확인하려면 `--renderToMemory`)를 돌려 렌더링 에러가 없는지 확인한다. lint 스크립트는 frontmatter 필드는 검사해도 Mermaid 문법·템플릿·렌더링 문제까지는 못 잡는다. `post-quality-loop`의 Build gate와 같은 개념이지만, 그 스킬을 쓰지 않는 수작업 개정에도 똑같이 적용한다.

---

## 7. 품질 체크리스트 (게시 전)

**컬렉션 개정·확장 (해당 시)**
- [ ] 챕터 추가·재배치·슬러그 변경이 있었다면 §6.1의 형제 게시물 교차 참조 감사를 마쳤는가?
- [ ] 규모가 큰 개정이었다면 §6.2의 다단계 검토와 §6.3의 실빌드 게이트를 거쳤는가?

**본문 구성**
- [ ] 주요 개념이 **문단**(리스트 아님)으로 설명되어 있는가?
- [ ] 각 섹션의 이론:예제 비율이 약 60:40 이상인가? (문단 40% 이상)
- [ ] 코드 블록이 2개 이상 연달아 나타나는 부분에 설명 문단이 있는가?
- [ ] 문단만 읽어도 핵심이 이해되는가?

**정확성 및 출처**
- [ ] 역사/인물/연도가 정확한가? (불확실한 부분은 "~라고 알려져 있다"로 완화)
- [ ] 기술 사실(크기, 동작, 성능 수치)에 불확실한 부분은 "구현 정의"/"플랫폼에 따라"로 표기했는가?
- [ ] 본문의 모든 외부 링크가 접근 가능한가? (404/5xx 없음)
- [ ] 인용 블록에 출처(저자, 연도, 제목)가 있고, 원문과 대조해 정확한가? ([`rules-that-must-be-followed`](../rules-that-must-be-followed/SKILL.md) §7)

**깊이 및 전문가 수준**
- [ ] 새 개념이 기존 개념과의 관계를 명시하는가?
- [ ] "정량적"·"측정"을 표방하는 부분에 실제 수치 또는 벤치 코드가 있는가?
- [ ] 코드 예제가 컴파일 가능하거나, 명시적으로 의사코드(`text`)인가?

**안티패딩**
- [ ] 닫는 절(요약·체크리스트·네비)이 한 형식만인가?
- [ ] 답 없는 번호 리스트가 없는가?
- [ ] 작성자용 메타("게시 전 자가 점검" 등)가 없는가?
- [ ] 존재하지 않는 파일/자료 참조가 없는가?