菜单
컬렉션 글(content/collection/**/index.md, **/*.md)을 작성할 때 따르는 이론 중심 글쓰기 표준. 전문가 수준의 이론적 설명을 문단으로 먼저 서술하고 코드/표/다이어그램은 보충 자료로만 쓰도록 한다. 컬렉션 글 작성·보강, 기술 시리즈 글 작성 시 사용한다.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
게시물 품질을 루브릭 점수로 채점하고, 임계값을 넘을 때까지(또는 최대 반복까지) 채점→수정→재채점을 반복하는 품질 개선 루프. blog-agent-pipeline의 순환 버전으로, quality-critic 서브에이전트(채점자)와 분리되어 동작하며 점수판(scoreboard)에 상태를 기록한다. draft 해제는 사람만 한다. 신규 초안 게이트·기존 게시글 재점검·야간 자율 실행에 사용한다.
AI 보조 시리즈형 교육 글(컬렉션)의 본문 구성·깊이·slug·00 챕터·내용 완결성(석학/SME 기준: 오개념·개념 연결·1차 출처·과목별 필수 요소)·품질 체크리스트를 표준화한다. design-patterns, cleanarchitecture, optimization 시리즈, C++ 성능 트랙, 장문 기술 튜토리얼, 커리큘럼형 블로그 포스트를 작성·보강할 때 사용한다. blog-post-writing 스킬 및 rules-that-must-be-followed와 함께 적용한다.
42jerrykim.github.io Hugo 블로그의 모든 글쓰기·편집 작업에 적용되는 전역 필수 규칙. frontmatter(draft, tags, description, title), 날짜 확인, 본문 링크 검증, 독자용 본문 원칙, Mermaid 다이어그램 문법, 알고리즘 코드 주석 규칙, 직접 인용 검증을 포함한다. 글 작성·수정, 새 포스트 생성, 컬렉션 글 작업 시 항상 적용한다.
Hugo 블로그 글을 끝까지 작성하는 멀티스테이지 파이프라인. Research(자료·링크 검증) → Draft(blog-post-writing 준수) → QA(메타·Mermaid·링크) → PublishPrep(draft 해제 전 최종 확인) 순으로 한 세션에서 순차 실행한다. **한 세션에서 전체 사이클을 자동 진행**할 때 사용한다. 단계별 작성 규칙 자체가 필요하면 `blog-post-writing`을 참고한다.
Hugo 블로그 포스트 작성을 위한 종합 가이드. 컬렉션/일반 포스트의 frontmatter 생성, 본문 구조 템플릿, SEO 최적화, 이미지/에셋 관리, 태그 선정(data/tags.yaml), 링크 검증, Mermaid 다이어그램, 한국어/영어 이중 언어 콘텐츠를 포함한다. 블로그 글 작성, 새 컬렉션 생성, 기술 블로그 포스트 작성 시 사용한다. Research→Draft→QA→PublishPrep 전체 파이프라인을 한 번에 진행하려면 `blog-agent-pipeline`을 참고한다.
content/post/ 하위 AI 도구·서비스 활용 글(Claude Code, ChatGPT, Cursor, AI 에이전트·플러그인·워크플로 가이드) 작성 가이드. 아키텍처/기능 설명·적용 시나리오·판단 기준·장단점 구조와 태그·체크리스트를 표준화한다. content/post/ 하위 AI 도구·서비스 소개·활용 가이드 글 작성 시 사용한다.
| name | collection-writing-standards |
| description | 컬렉션 글(content/collection/**/index.md, **/*.md)을 작성할 때 따르는 이론 중심 글쓰기 표준. 전문가 수준의 이론적 설명을 문단으로 먼저 서술하고 코드/표/다이어그램은 보충 자료로만 쓰도록 한다. 컬렉션 글 작성·보강, 기술 시리즈 글 작성 시 사용한다. |
content/collection/**/*.md를 작성·보강할 때, 전문가 수준의 이론적 설명을 유지하고 예제는 개념 보충에만 쓰도록 하는 기준이다.
함께 적용
rules-that-must-be-followed: frontmatter, 링크 검증, Mermaideducational-content-writing: 교육 콘텐츠 구조·깊이·안티패딩·내용 완결성(§7 석학/SME 기준) (이 스킬은 이를 보완)blog-post-writing: SEO, 태그, 내부 링크본문의 주요 설명은 문단으로 이론·원칙·개념을 먼저 서술하고, 코드/표/다이어그램은 그 뒤에 보충한다.
(이론/원칙을 2-3문단으로 설명)
↓
(그 원칙을 보여주는 예제 1-2개)
↓
(예제에서 주의점·트레이드오프 1-2문장)
피할 것: 코드만 연속 배치, 예제를 먼저 제시한 뒤 설명(역순), 개념 문단 없이 예제 주석에만 의존.
| 목적 | 형태 | 분량 |
|---|---|---|
| 개념 설명 | 문단 (필수) | 150-300어 |
| 개념 보충 | 코드 / 표 / 다이어그램 (부가) | 코드 ≤50줄, 표 ≤5행 |
| 비교/차이 | 병렬 예제 또는 표 (필수) | 각 2-10줄 |
| 실전 적용 | 완성된 코드 또는 사례 (선택) | 20-100줄 또는 상세 설명 |
AI 생성 내용의 환각·오류를 방지하기 위해 다음을 검증한다.
sizeof), 버전별 동작, 성능 수치는 추측하지 않는다. 불명확하면 "구현 정의" 또는 "플랫폼에 따라 다름"으로 표기한다.✓ > "..." — Donald Knuth, 『The Art of Computer Programming』(1968)
✓ 이 알고리즘의 시간 복잡도는 O(n log n)이다 (실제 구현과 플랫폼에 따라 상수배 차이 발생).
✗ (추측으로 단정) 이 구조체는 정확히 24바이트다.
✗ (검증 없는 주장) 이 알고리즘은 항상 가장 빠르다.
교육/시리즈형 콘텐츠에서 "정량적"·"측정"을 표방하는 경우의 추가 요구사항(실측치·벤치마크 스켈레톤 등)은
educational-content-writing§4.4를 따른다.
본문 + 코드 + 다이어그램의 총합 중 문단이 최소 40% 이상을 차지하도록 한다. 문단은 설명·원칙·비판적 시각·트레이드오프를 담고, 코드/표/다이어그램은 예시·구체화·시각화를 담는다.
예: 총 1000줄 글이라면 문단 400줄 이상(이론 설명), 코드 300줄(예제 2-3개, 각 100줄 미만), 표/다이어그램 100줄(3-4개), 나머지는 heading/공백.
| 섹션 | 목표 | 구성 | 예제 분량 |
|---|---|---|---|
| 도입 | 읽어야 하는 이유 전달 | 문제 상황 + 해결할 개념 소개 (1-2문단) | 불필요 |
| 핵심 개념 | 개념·원칙을 정확히 이해 | 용어 정의(첫 등장 시 굵게) → 원칙 설명(2-4문단) → 구조/체계(문단/표) → (선택) 작은 예제 | ≤20줄 코드 또는 표 1개 |
| 비교/트레이드오프 | 선택지 간 차이 이해 | 각 방식 개념 설명(문단) → 비교 표(필수) → 병렬 예제(각 10-20줄) 또는 다이어그램(필수) → 언제 어느 것을 쓸지(문단) | 비교용 코드 2-3개 또는 표 1개 |
| 실전 적용 | 실제 적용 방법 제시 | 상황 설정(문단) → 단계별 구현(설명+코드) → 주의점/최적화 팁(문단) | 완성 코드 1-2개 (30-100줄) |
| 마무리 | 핵심 요약 + 다음 단계 | 핵심 요약 표 또는 3-5줄 문단 → 평가 기준(체크리스트 3-6항) → (선택) 다음 글 링크 | 불필요 |
**작은 예제(≤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`)인가?
**안티패딩**
- [ ] 닫는 절(요약·체크리스트·네비)이 한 형식만인가?
- [ ] 답 없는 번호 리스트가 없는가?
- [ ] 작성자용 메타("게시 전 자가 점검" 등)가 없는가?
- [ ] 존재하지 않는 파일/자료 참조가 없는가?