---
name: til-notion
version: 1.1.0
description: |
  Notion에 TIL(Today I Learned) 문서를 작성하는 스킬.
  Notion 페이지 URL과 주제를 받아 구조화된 TIL 문서를 해당 페이지에 직접 추가한다.
  세션에서 관련 코드나 레퍼런스가 있으면 함께 첨부한다.
  트리거: "TIL 작성", "노션에 기록", "오늘 배운 것 정리", "til-notion"
allowed-tools:
  - AskUserQuestion
  - Read
  - Grep
  - mcp__claude_ai_Notion__notion-fetch
  - mcp__claude_ai_Notion__notion-update-page
---

# til-notion: Notion TIL 문서 작성

Notion MCP를 사용해 TIL 문서를 기존 페이지에 직접 추가한다.
**절대 하위 페이지를 새로 생성하지 않는다.** 항상 지정된 페이지에 내용을 append한다.

## Step 1: 입력 수집

인자에서 다음을 파악한다:

- **Notion 페이지 URL** — 문서를 작성할 Notion 페이지 링크
- **주제(topic)** — TIL로 기록할 내용

인자에서 URL과 주제를 모두 파악할 수 없으면 직접 텍스트로 요청한다:

> TIL 문서를 작성할 Notion 페이지 URL과 주제를 알려주세요.
>
> 예시:
>
> - URL: https://app.notion.com/p/workspace/page-title-383286f3bd7080599a55f5639d97dd59
> - 주제: React 19의 use() 훅 사용법

## Step 2: 페이지 ID 추출

URL에서 페이지 ID(32자리 hex)를 추출한다.

지원하는 URL 형식:

- `https://www.notion.so/Page-Title-{page_id}`
- `https://www.notion.so/{workspace}/{page_id}`
- `https://app.notion.com/p/{workspace}/{slug}-{page_id}` ← slug 뒤 32자리가 page_id
- 32자리 hex 문자열 직접 입력

**추출 규칙:** URL의 마지막 경로 세그먼트에서 `-`로 구분된 마지막 토큰이 32자리 hex이면 그것이 page_id다.

예시: `i18next-383286f3bd7080599a55f5639d97dd59` → page_id = `383286f3bd7080599a55f5639d97dd59`

## Step 3: 세션 컨텍스트 및 근본 원인 수집

현재 세션에서 주제와 관련된 내용을 깊이 있게 추적하여 수집한다:

- **동작 원리 분석**: 이 코드가 왜 작동하는지, 브라우저와 네트워크 레이어(HTTP 헤더, MIME 타입 등)에서 일어난 인과관계.
- **예외 및 제어 가드레일**: 할루시네이션 방지, 방어 코드, 또는 메모리 누수(`revokeObjectURL` 등) 및 보안(RLS, CORS 등)을 위해 채워 넣은 안전장치(Harness).
- **고부가가치 재투자(전결)**: 이 작업을 통해 리소스를 얼마나 절감했으며, 그렇게 확보한 자원을 어떤 핵심 아키텍처 개선에 집중시켰는지에 대한 기승전결 선순환 맥락.

## Step 4: TIL 문서 구조 작성 (구체화 규칙)

다음 구조로 Notion 페이지에 블록을 추가한다. Claude는 각 섹션의 질문에 스스로 답변하며 내용을 **매우 정교하고 구체적으로** 채워야 한다.

```
# {주제} — TIL ({오늘 날짜 YYYY-MM-DD})

## 1. 배경 및 문제 정의
- **Context**: 어떤 기능을 구현하거나 아키텍처를 고도화하는 과정에서 이 기술/개념을 마주했는가?
- **병목 지점**: 기존 방식이나 레거시 구조가 가진 한계점, 혹은 개발 과정에서 덜컹거렸던 에러/현상은 무엇이었는가?

---

## 2. 작동 원리 및 로우 레벨 레이어 분석
- **도구/라이브러리 명세**: 사용한 특정 기술이나 훅(Hook)의 명확한 역할은 무엇인가?
- **기저 메커니즘**: 라이브러리 차원의 단순 사용법을 넘어, 브라우저 렌더링 사이클, 컴파일러 레벨, 혹은 네트워크 레이어(HTTP 요청/응답 헤더, 상태 코드 등)에서 일어난 인과관계와 동작 원리는 무엇인가?

---

## 3. 품질 가드레일(Harness) 및 예외 처리 설계
- **예외 통제**: AI의 환각(Hallucination), 품질 파편화, 혹은 예상치 못한 사이드 이펙트를 방어하기 위해 설계한 규칙이나 하네스는 무엇인가?
- **기본기 검증**: 보안 취약점 방어(BFF, RLS, CORS 등)나 메모리 누수(Memory Leak) 방지, 렌더링 병목 최적화를 위해 코딩 규격에 어떤 안전장치를 채웠는가?

---

## 4. 코드 스니펫 및 Before & After 대조

### ❌ Before (기존 안티패턴 또는 파편화된 구조)
\`\`\`{언어}
// 변경 전 문제 코드 또는 원리가 결여된 단순 구현 코드
\`\`\`

### ✨ After (시스템화 및 가드레일이 반영된 근본 구조)
\`\`\`{언어}
// 최적화, 보안, 메모리 해제, 혹은 품질 제어 루프가 반영된 코드
\`\`\`

---

## 5. 지속 가능한 가치 및 리소스 선순환 (전결)
- **자원화 지표**: 이 시스템 정착, 혹은 코드 최적화를 통해 단발성이 아니라 복리로 지속 절감할 수 있는 리소스(시간/비용/UX)는 무엇인가?
- **인지 리소스 재투자**: 기계적이고 반복적인 작업을 자동화하거나 코드를 추상화하여 아낀 소중한 개발 리소스를, **'사람이 직접 깊게 고민해야 하는 고부가가치 작업(핵심 비즈니스 아키텍처 고도화, 기술 부채 청소)'에 어떻게 전환하여 집중시켰는지** 선순환 서사로 결론을 맺는다.

```

## Step 5: Notion 페이지에 내용 추가

`mcp__claude_ai_Notion__notion-update-page`를 `insert_content` 커맨드로 호출한다.
**`notion-create-pages`는 절대 사용하지 않는다** — 하위 페이지가 생성되기 때문이다.

```
tool: mcp__claude_ai_Notion__notion-update-page
params:
  page_id: {추출한 32자리 page_id}
  command: "insert_content"
  content: {Step 4에서 준비한 Markdown 문자열}
  position: { "type": "end" }
```

## Step 6: 완료 보고

작성 완료 후 다음을 출력한다:

```
TIL 작성 완료
- 주제: {주제}
- 날짜: {오늘 날짜}
- Notion 페이지: {원본 URL}
- 포함된 코드: {있음/없음}
```

## 주의사항

- **하위 페이지 생성 금지**: `notion-create-pages`에 `parent.page_id`를 넘기면 하위 페이지가 만들어진다. 반드시 `notion-update-page` + `insert_content`를 사용한다.
- Notion MCP 도구(`mcp__claude_ai_Notion__*`)가 없으면: "Notion MCP 서버가 설정되어 있지 않습니다. Claude Code 설정에서 Notion MCP를 추가해주세요."
- 페이지 접근 권한 오류(404)가 발생하면: "Notion 페이지 설정 → Connections에서 MCP 인테그레이션을 추가해주세요."