---
name: notion-write
description: 노션 MCP로 페이지·문서를 만들 때 가독성 좋은 구조로 작성하도록 안내하는 스타일 가이드. 사용자가 "노션에 정리해줘", "노션에 작성/문서화해줘", "노션 페이지 만들어줘", "이 내용 노션에 올려줘", "노션에 보고서/가이드/위키 만들어줘" 같은 표현을 쓰거나, notion-create-pages·notion-update-page로 새 페이지 본문을 작성하려 할 때 반드시 이 스킬을 참고한다. 콜아웃·토글·컬럼·표·목차·구분선·색 강조 같은 노션 네이티브 블록을 "언제 어디에" 쓸지 규칙으로 정해, AI가 만든 페이지가 텍스트 벽이 되지 않게 한다. (녹취→회의록 DB 같은 특화 워크플로우는 각 전용 스킬을 따르되, 본문 가독성은 이 규칙을 함께 적용한다.)
allowed-tools: Read
argument-hint: (선택) 문서 유형 — 회의록/가이드/위키/보고서. 생략 시 내용에서 판단
---

# notion-write — 노션 페이지 가독성 스타일 가이드

노션 MCP(`notion-create-pages` / `notion-update-page`)로 페이지 본문을 만들 때, **읽는 사람이 스캔으로 요지를 잡을 수 있는 구조**로 쓰게 하는 규칙이다.

## 왜 필요한가 (전제)

사람은 문서를 **읽지 않고 스캔**한다. 스캔 사용자는 페이지 앞 1/4만 훑고, 시선은 좌측 세로 라인(F-패턴)을 따른다. 그래서 "긴 문단이 소제목·강조·구획 없이 이어지는 텍스트 벽"은 정보가 다 있어도 **안 읽힌다**. AI가 만든 노션 페이지가 "형편없다"는 건 내용이 부족해서가 아니라, 이 스캔 구조를 안 만들어서다.

노션 MCP는 기본 마크다운만 쓰는 게 아니라 **콜아웃·토글·컬럼·색·표·목차 같은 네이티브 블록을 전부 생성할 수 있다**(문법은 `references/block-cheatsheet.md`). 이 스킬의 본질은 "**언제 어떤 블록을 쓸지**"를 못박아, 매번 재설계 없이 일관되게 스캔 가능한 페이지를 뽑는 것이다.

> **문법 스펙은 MCP가 직접 제공한다.** 페이지를 쓰기 전 MCP 리소스 `notion://docs/enhanced-markdown-spec`을 (resource-reading 인터페이스로) 읽어 정확한 Notion-flavored Markdown 문법을 확인한다. 이 스킬은 그 위에 얹는 **판단 규칙**이다.

---

## 언제 적용하나

- **적용**: 노션에 새 페이지/문서 본문을 작성할 때 — 보고서·가이드·매뉴얼·위키·회의록·기획·정리 노트 등.
- **특화 스킬과의 관계**: 회의록 생성처럼 전용 워크플로우 스킬이 따로 있으면 그 절차를 우선하되, **본문 블록 구성은 이 규칙을 함께 적용**한다.
- **범위**: 새 페이지 생성이 중심이다. 기존 페이지를 통째로 재구조화(`replace_content`)하는 건 자식 페이지 삭제 위험이 있어 이 스킬의 기본 범위가 아니다 — 요청 시 사용자에게 위험을 알리고 확인받는다.

---

## 페이지 작성 워크플로우

순서대로 세운다: **진입부(식별·맥락·내비) → 본문 골격 → 블록 선택 → 강조 규율 → 생성 후 검증.**

### 1) 진입부 — 본문 시작 전에 "무엇/누구·언제/어디로"를 해결

읽는 사람이 첫 화면에서 이 문서가 뭔지 알아야 한다. 위에서부터:

1. **페이지 아이콘(이모지)** 을 설정한다(`icon` 파라미터). 사이드바·검색에서 문서를 식별하는 시각 앵커.
2. 제목 바로 아래 **요약 콜아웃** 하나. 이 문서가 무엇인지 / 핵심 결론 / (해당 시) 담당·날짜를 1~3줄로. 결론을 먼저 놓는다(역피라미드).
   - 문서형(가이드·위키): `<callout icon="📋" color="gray_bg">` 로 "이 문서란 / 왜"
   - 경고·주의가 핵심이면: `color="red_bg"`(경고) / `yellow_bg`(주의·팁)
3. 헤딩이 5개 이상인 긴 문서면 요약 아래 **`<table_of_contents/>`**. 헤딩 위계만 잘 잡으면 내비게이션이 공짜로 생긴다.

```
<callout icon="📋" color="gray_bg">
	**이 문서**: 파일 업로드 재시도 정책 정리. **결론**: 지수 백오프 3회 + 실패 시 로컬 큐 적재.
</callout>
<table_of_contents/>
```

### 2) 본문 골격 — 청킹과 얕은 위계

- **헤딩은 H1~H3만**, 건너뛰지 않고 논리적으로 중첩한다(H2→H4 점프 금지). 노션은 H3까지만 온전히 렌더된다. 가능하면 헤딩 위계를 실제 구조(단계 번호·폴더 깊이)에 맞춰 위계가 곧 지도가 되게 한다.
- **섹션마다 `---` 구분선**으로 덩어리를 분리한다. 헤딩만으로 부족한 시각 구획을 준다.
- **청킹**: 긴 설명은 소제목 + 짧은 문단으로 쪼갠다. 한 문단이 6~7줄을 넘어가면 나눌 곳을 찾는다.

### 3) 블록 선택 — "튀어야 할 것 / 접을 것 / 나란히 둘 것"

상황에 맞는 블록을 고른다. 상세 표는 아래 [블록 선택 치트시트](#블록-선택-치트시트).

- **튀어야 하는 정보**(요약·경고·팁·정의) → **콜아웃**. 색은 의미에 고정: 회색=정의/요약, 노랑=팁·주의, 빨강=경고.
- **낮은 강조**(도입 문장·인용구·여담) → **인용 `>`**. 경고를 인용으로, 여담을 콜아웃으로 쓰면 위계가 뒤집힌다.
- **길거나 선택적인 심화**(레거시·FAQ·구현 상세·긴 목록) → **토글**로 접어 개요를 지킨다. (사내에서 가장 재사용 가치 높다고 평가된 패턴.)
- **병렬 비교**(항목×속성) → **네이티브 표** `<table header-row="true">`. 표를 이미지로 넣지 않는다(아래 금지 참조).
- **좁은 콘텐츠 나란히**(목차·링크 그룹·짧은 카드) → **컬럼**. 긴 본문은 컬럼에 넣지 않는다(모바일에서 세로로 풀림).
- **병렬 항목** → 불릿, **실행 항목** → 체크박스(담당자 표기). **흐름·인과·서사** → 문단(불릿으로 쪼개지 말 것).

### 4) 강조 규율 — 희소해야 강조가 산다

- 볼드·색 강조는 문서 전체의 **10~15% 이내**, 한 곳당 몇 단어만. 전부 강조하면 아무것도 강조되지 않는다.
- 색은 **2~3개**를 의미에 고정해 반복(정보/경고/팁). 무지개색·의미 없는 색칠 금지.
- 이모지·아이콘은 한 결로 통일한다. 산발적 이모지는 위계를 무너뜨린다.

### 5) 생성 후 검증

- 생성 직후 `notion-fetch`로 다시 읽어 **콜아웃·토글·컬럼·표가 의도대로 렌더됐는지** 확인한다. 들여쓰기(탭)가 틀리면 토글/콜아웃의 자식이 밖으로 새거나 빈 블록이 된다.
- `update_content`(부분 치환)는 `old_str`이 안 맞으면 **조용히 skip하고 전체 호출은 성공으로 반환**한다(에러 없음). 여러 edit을 배치했으면 재-fetch로 각 반영을 검증하고, 누락분만 유니크한 부분 문자열로 재적용한다. `notion-fetch`는 공백을 정규화하니 화면 문자열을 그대로 `old_str`로 쓰지 말 것.

---

## 블록 선택 치트시트

| 상황 | 블록 | 색/주의 |
|---|---|---|
| 문서 요약·결론 (진입 앵커) | `<callout>` (상단) | 회색 `gray_bg` = 정의/요약 |
| 경고·하지 말 것 | `<callout icon="⚠️">` | 빨강 `red_bg` |
| 팁·부가 주의 | `<callout icon="💡">` | 노랑 `yellow_bg` |
| 인용구·도입·여담 (낮은 강조) | 인용 `> ` | — (콜아웃보다 가벼움) |
| 레거시·FAQ·긴 절차·선택적 심화 | 토글 `<details>` / `## …{toggle="true"}` | 자식은 반드시 탭 들여쓰기 |
| 항목 × 속성 비교 | 표 `<table header-row="true">` | 셀은 rich text만. **이미지 표 금지** |
| 목차·링크 그룹·짧은 카드 나란히 | 컬럼 `<columns>` | 긴 본문·순서 의존 콘텐츠 금지(모바일) |
| 긴 문서 내비게이션 | `<table_of_contents/>` | 헤딩 위계가 곧 목차 |
| 섹션 경계 | 구분선 `---` | — |
| 병렬 항목 / 실행 항목 | 불릿 `-` / 체크박스 `- [ ]` | 서사는 문단으로 |
| 다이어그램 | ` ```mermaid ` 코드블록 | 라벨에 특수문자면 `"..."`로 감싸기 |

문서 유형별(회의록·가이드·위키·보고서) 전체 레이아웃 레시피와 before/after 예시는 **`references/layouts.md`**를 읽고 따른다.

---

## 금지 (안티패턴) — 특히 AI가 저지르는 것

실무에서 흔히 관찰되는 실패를 포함한다. 이것만 피해도 "형편없음"의 대부분이 사라진다.

- **❌ 문서 전체를 하나의 코드펜스(` ``` `)로 감싸기** — 마크다운을 통째로 붙여넣으면 콜아웃·헤딩·목차 앵커가 전부 죽고 회색 코드 덩어리 하나로 보인다. 본문은 **네이티브 블록으로 쓴다**. 코드펜스는 실제 코드·터미널·설정 조각에만.
- **❌ 표를 스크린샷 이미지로 삽입** — 검색·복사 불가, 다크모드·폭 대응 안 됨, 서명 URL 만료 위험. 반드시 네이티브 `<table>`.
- **❌ 미완 플레이스홀더 노출** — 빈 블록 다수, "보류…", "좀 더 고려" 같은 초안 흔적을 그대로 두지 않는다.
- **❌ 텍스트 벽** — 소제목·구분선 없이 긴 문단이 이어짐 → 헤딩 + `---` + 상단 요약 콜아웃으로 청킹.
- **❌ 불릿 수프** — 서사·이유·모든 것을 불릿으로 나열 → 병렬만 불릿, 흐름은 문단·표로.
- **❌ 강조 도배 / 강조 실종** — 볼드·색 도배(무엇도 안 튐)나 전체 회색(밋밋) 둘 다 실패 → 10~15%로 제한.
- **❌ 진입 앵커 없음** — 요약 없이 본문으로 바로 시작 → 상단 요약 콜아웃 + (긴 문서) 목차.
- **❌ 헤딩 인플레·건너뜀** — H1 남발/H2→H4 점프/4단계 이상 중첩 → H1~H3 얕게.
- **❌ 콜아웃·토글·컬럼 남용** — 모든 문단을 콜아웃으로, 짧은 것까지 토글로, 긴 본문을 컬럼에 → 콜아웃은 진짜 standout에만, 토글은 길거나 선택적인 것에만, 컬럼은 좁은 콘텐츠에만.
- **❌ `<empty-block/>` 남용** — 노션은 블록 간격을 알아서 준다. 빈 줄로 간격을 벌리려 하지 않는다.

---

## 참고 파일

- `references/block-cheatsheet.md` — Notion-flavored Markdown 블록별 문법 요약 + 각 블록의 가독성 용도. (완전한 문법은 MCP 리소스 `notion://docs/enhanced-markdown-spec`.)
- `references/layouts.md` — 문서 유형별(회의록·가이드/매뉴얼·위키 홈·보고서) 레이아웃 레시피와 before/after 예시.