Notion write

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 예시.