산타클로드 노션 — 프로젝트 팔로우 · @santa

이 세션이 맡은 프로젝트를 노션으로 추적한다. 유저는 노션으로 "이 프로젝트가 뭐고, 이 세션으로 뭘 할 수 있고, 지금까지 뭐가 바뀌었나"를 본다. 읽기=맥락 파악, 쓰기=진행 보고.

인증

자격증명은 ~/.santaclaude/.env: NOTION_TOKEN(ntn_…), NOTION_PARENT_PAGE(부모 페이지 32자 id).
REST 직접 호출(정식 MCP 아님). 헤더: Authorization: Bearer <NOTION_TOKEN>, Notion-Version: 2022-06-28.
⚠️ 부모 페이지에 통합을 Connections로 연결 안 하면 토큰이 있어도 403. 제일 흔한 실패 — 안 되면 이걸 먼저 의심·안내.

📖 노션 읽기 — 프로젝트 맥락 브리핑

유저가 "노션 읽기"를 트리거하면, 이 프로젝트와 이 세션 활용법을 노션에서 찾아 유저에게 읊는다.

⚠️ 읽기가 "안 되는" 진짜 원인 (제일 먼저 이해할 것): Notion API는 이 통합(봇)에 Connections로 연결된 페이지·DB만 본다. 유저 노션이 아무리 방대해도 연결 안 된 페이지는 검색에 안 나오고 직접 GET도 404/403. 그래서 검색 결과가 부모·세션 페이지뿐이면 콘텐츠가 없는 게 아니라 통합에 안 보이는 것 — 이걸 "없음"으로 끝내면 유저는 읽기가 고장났다고 느낀다. 원인과 해결을 반드시 안내한다.

절차

1. 부모 밑부터 (즉시·확실) — GET /blocks/<NOTION_PARENT_PAGE>/children 로 부모(이 프로젝트 노션 루트) 직속 child page·DB를 받는다. 부모 밑은 권한이 상속되고 search 인덱싱과 무관하게 즉시 보인다 — 방금 만든 페이지도 여기서 잡힌다. ⚠️ /v1/search 는 인덱싱 지연이 있어 막 만든·막 연결한 페이지를 놓치므로, search 단독에 의존하지 말고 부모 children을 1순위로 본다.

2. 넓게 (search) — POST /v1/search 빈 쿼리(body { "page_size": 100 })로 부모 밖까지 통합 가시범위를 확장한다. (특정 주제를 물었으면 그 키워드로도.) 1·2를 합쳐 중복 제거.

3. 흐름은 항상 읽힌다 — 이 세션 페이지(~/.santaclaude/notion/<세션창>.id)는 통합 소유라 늘 보인다. 거기 쌓인 변경 보고(흐름)를 읽어 "이 프로젝트가 지금까지 뭘 했나"는 언제나 브리핑할 수 있다. 먼저 이걸 답한다.

4. 프로젝트 문서 브리핑 — 1·2 목록에 PRD·기획·활용법·프로젝트 맵으로 보이는 페이지가 있으면 GET /blocks/{id}/children 로 본문 읽어 요약(개요→PRD→이 세션으로 할 수 있는 일 순). 각 핵심이 어느 페이지에서 왔는지 밝힌다.

5. 유저가 URL/페이지명을 줬는데 안 잡히면 — page_id로 GET /pages/{id} 직접 시도. 404/403이면 그 페이지에 통합이 연결 안 된 것 → 아래 안내.

가시 범위가 빈약할 때 (읽을 게 부모·세션뿐) — 흔한 첫 경험. "없음"으로 끝내지 말 것

원인과 해결을 같이 준다:

"지금 이 통합에 연결된 노션 페이지가 N개뿐(부모·세션)이라 읽을 PRD·문서가 없어요. 콘텐츠가 없는 게 아니라 통합에 안 보이는 거예요."
해결 ① 읽고 싶은 노션 페이지를 열고 → 우상단 ⋯ → 연결(Connections) → 이 통합 추가. 다음 읽기부터 잡힘.
해결 ② 부모 페이지(NOTION_PARENT_PAGE) 밑에 child로 PRD·문서를 만들면 권한이 상속돼 자동으로 읽힘.
지어내지 말 것 — 안 보이는 건 안 보인다고, 대신 보이게 하는 법을 알려준다.

✍️ 노션 쓰기 — 프로젝트 변경 보고

유저가 "노션 쓰기"를 트리거하면, 이번 세션에서 진행한 변경·패치를 보고 형식으로 노션 이 세션 페이지에 남긴다. 즉흥 메모가 아니라 변경로그 틀을 지킨다.

세션 페이지 잡기

~/.santaclaude/notion/<세션창이름>.id 가 있으면 그 page_id 재사용.
없으면 부모(NOTION_PARENT_PAGE) 밑에 POST /v1/pages 로 🦌 <세션창> child_page 생성 → 받은 id를 ~/.santaclaude/notion/<세션창>.id 에 캐시(파일명은 URL 인코딩). 매번 새로 만들면 안 됨 — 캐시 필수.

보고 형식 (이 블록 구성 그대로 append)

heading_3: 📌 <YYYY-MM-DD> · <한 줄 제목>
bulleted_list_item × N: 변경·패치 요약 (한 일마다 한 줄)
paragraph(선택): 영향: … 무엇이 바뀌어 무엇에 영향
paragraph(선택): 다음: … 후속 작업

append는 PATCH /blocks/<page_id>/children 의 children 배열로. 한 번에 100블록까지, rich_text 2000자 한계(길면 슬라이스). 맨 밑에 시간순 누적된다.

절차

1. 유저가 추가로 적을 내용을 말했으면 반영. 안 했으면 이번 세션 작업 내역으로 초안을 잡아 위 형식으로 보여주고 "이대로 남길까?" 확인받는다.

2. 확인되면 세션 페이지에 append.

3. 남긴 뒤 "노션에 남겼어 — <제목>" 한 줄. 웹터미널 노션탭 흐름 타임라인에 바로 뜬다.

일석이조 — 세션 자기 기록도 함께

노션은 사람을 위한 거지만, 이 세션이 자체 메모리·일지 관습을 가졌다면(프로젝트 CLAUDE.md·AGENTS 가이드에 메모리/일지 경로가 명시돼 있으면) 같은 변경 보고를 거기에도 남긴다.

일지(daily/저널 폴더가 있으면): 오늘 날짜 일지에 같은 변경 요약을 한 단락 누적.
메모리(메모리 시스템이 있으면): 단, 메모리는 변경로그 전부가 아니라 이번에 새로 확정된 결정·합의·바뀐 사실만 선별해 저장(코드·git에서 자명한 건 제외).

한 번의 "쓰기"로 사람용(노션)과 세션용(메모리/일지)을 동시에 — 따로 또 적느라 일을 두 번 하지 않는다. 세션 관습이 없으면 노션만 남기면 된다.

규칙

토큰은 ~/.santaclaude/.env 에서만 읽는다. 코드·로그·노션 본문에 토큰 노출 금지.
모든 시각 한국(KST), 날짜 YYYY-MM-DD.
노션은 유저 것 — 부모 페이지 밖을 함부로 건드리지 말 것.