Guide Maker

Guide Maker

프로젝트 기능에 대한 가시성 높은 사용자 가이드를 Notion에 생성.

사전 요구사항

• Notion remote MCP 연결 (이 플러그인 설치 시 자동 등록됨)
• 최초 사용 시 Claude Code에서 OAuth 로그인 1회만 하면 됨 (별도 환경변수 불필요)
• 가이드를 작성할 부모 페이지가 본인 Notion workspace에 존재하고, 해당 integration이 그 페이지에 connection으로 추가되어 있어야 함

워크플로우

0. 부모 페이지 확보 (동적)

대화 시작 시 부모 페이지 ID를 다음 순서로 확보:

1. 사용자가 메시지에 부모 페이지 URL/ID를 직접 제공했으면 → 그것 사용
2. 아니면 Notion MCP의 search 도구로 사용자가 말한 부모 페이지명을 검색해서 후보 제시
3. 그래도 모호하면 사용자에게 명시적으로 묻기:

   "가이드를 어느 Notion 페이지 아래에 만들까요? 페이지 URL이나 이름을 알려주세요."

❌ 금지: 페이지 ID를 하드코딩하거나 임의로 가정하기 ✅ 필수: 매 호출마다 사용자 컨텍스트에서 부모 페이지를 동적으로 결정

확보한 page_id는 이번 대화 turn에서만 변수로 보관, 스킬 내부 어디에도 영구 저장하지 않음.

Notion 페이지 URL에서 ID 추출:

https://www.notion.so/Workspace-abc123def456...
                                ^^^^^^^^^^^^^^^
                                마지막 32자 = page_id (하이픈 추가하여 사용)

1. 기능 분석

해당 기능의 코드 분석 → 주요 버튼, 폼, 테이블, 상태값 파악

2. 콘텐츠 구조 설계

문서 구조에 맞춰 전체 블록 배열 설계 (페이지 위치, Part별 Step, 테이블, FAQ 등)

3. 한 번에 생성 (🚨 필수!)

Notion remote MCP는 표준 Notion API를 그대로 노출합니다. 일반적으로 다음 두 도구를 사용:

• notion-create-pages (또는 API-post-page): 새 페이지 생성
• notion-update-page / notion-patch-block-children (또는 API-patch-block-children): 페이지에 자식 블록 추가

정확한 도구명은 MCP 클라이언트가 노출하는 이름을 따릅니다. /mcp 슬래시 메뉴에서 사용 가능한 도구명을 확인하세요.

전체 가이드는 단 한 번의 페이지 생성 + 한 번의 블록 추가로 완성:

1. create-page 호출
   - parent: { page_id: <step 0에서 확보한 부모 페이지 ID> }
   - properties.title: "📑 [기능명]"
   → 응답에서 새 페이지 id 획득

2. patch-block-children 호출
   - block_id: 위에서 받은 새 페이지 id
   - children: [전체 블록 배열 — Part 헤더, Step, divider, 테이블, FAQ 토글 모두 포함]

3. 사용자에게 URL 반환:
   https://www.notion.so/<page_id에서 하이픈 제거>

❌ 금지: Step별/Part별로 나눠서 여러 번 API 호출 ✅ 필수: 전체 블록을 하나의 배열로 → 단 1회 API 호출

4. 완료

URL 전달: https://www.notion.so/[page_id_without_hyphens]

문서 구조 (필수)

## 페이지 위치
**[상위 메뉴]** → **[기능명]**
[이미지]
---

## [기능] 방법

### Step 1. [작업 제목]
[설명]
[이미지]
1. **'버튼명'**을 클릭합니다.
2. [동작]
💡 Tip: [정보]
---

### Step 2. ...

## [테이블명] 컬럼 설명
| 컬럼명 | 설명 |
|--------|------|
| ... | ... |
---

## [상태] 안내
| 상태 | 색상 | 설명 |
|------|------|------|
| ✅ 완료 | 🟢 초록 | ... |
| ⏳ 대기 | 🟡 노랑 | ... |
| ❌ 실패 | 🔴 빨강 | ... |
---

## 자주 묻는 질문
> Q: [질문]?
A: [답변]

가시성 원칙

레퍼런스

• Notion 블록 JSON: references/notion-blocks.md
• 가시성 패턴 예시: references/visual-patterns.md

체크리스트

필수

• 페이지 위치 (→ 화살표 + 이미지)
• 모든 Step에 이미지 블록
• 버튼/메뉴: '작은따옴표'와 굵게
• 각 Step 끝에 divider
• FAQ 섹션 (최소 3개 토글)

가시성

• 컬럼 설명 테이블
• 상태값 테이블 (이모지+색상)
• 입력 형식: 인라인 코드
• 콜아웃 활용 (💡⚠️⚡)