Claude Code가 내 노션을 관리하는 환경 만들기

Claude Code로 작업하다 보면 결과물만 남기기 아까운 순간이 많습니다.

코드를 고치다 내린 판단, 콘텐츠 초안을 만들며 정리한 논리, 사업으로 이어질 만한 아이디어, 시행착오 끝에 알게 된 것. 그 자리에서는 분명 중요한데, 대화창에만 두면 며칠 뒤 찾지 못합니다.

이런 기록을 로컬 마크다운으로 남길 수도 있고, Obsidian 같은 도구도 훌륭합니다. 다만 밖에서 꺼내 보거나 링크로 공유하거나 남과 함께 관리하려는 순간 번거로워집니다. 노션은 앱과 웹, 공유와 협업을 전제로 만들어진 공간이라 이 지점에서 유리합니다.

작업은 Claude Code에서, 정리와 축적은 노션에서. 이 글의 주제입니다.

사람이 결과물을 복사해서 노션에 옮기는 방법이 아닙니다. Claude Code가 직접 노션을 읽고 쓰면서, 작업 중 나온 기록을 정해진 위치와 형식으로 쌓게 만드는 방법입니다. "노션 MCP 연결법" 이야기도 아닙니다. 연결은 출발점이고, 나머지가 진짜입니다.

MCP를 연결하면 Claude Code가 내 노션에 들어올 수 있습니다. 어느 페이지까지 열어줄지도 내가 정합니다. 그런데 연결만 해두면 기록할 때마다 어느 페이지에 넣고 어떤 제목을 붙이고 어떤 형식으로 정리할지 다시 설명해야 하고, 결과물 모양은 매번 다릅니다. 기록이 들어갈 위치와 형식, 지켜야 할 규칙이 어디에도 적혀 있지 않기 때문입니다.

그래서 이 칼럼은 3단계로 진행합니다.

1. 연결 : 노션 MCP 연결
2. 스킬 : 작업별 절차 파일 작성 (복붙용 실물 2개 포함)
3. 환경 : 어느 프로젝트에서든 부를 수 있게 설치

노션에 먼저 만들 것

시작하기 전에 노션에 상위 페이지 하나를 만듭니다. 이름은 AI Workspace로 하겠습니다. 작업 노트와 주간 리뷰가 모두 이 아래로 들어갑니다.

처음에는 하위 페이지 두 개면 충분합니다.

AI Workspace
├── 작업 노트     ← 작업 중 나온 판단·해결 과정·시행착오
└── 주간 리뷰     ← 작업 노트와 커밋을 모아 한 주를 돌아보는 곳

여기서 완벽한 지식 관리 시스템을 설계하려 들지 마세요. 페이지를 늘리는 건 나중에 언제든 됩니다. 지금 필요한 건 기록이 들어갈 자리가 정해져 있는 상태입니다. 그 자리에 어떤 형식으로 쓸지는 2단계에서 스킬 파일이 맡습니다.

1단계. 연결: 노션 MCP

MCP(Model Context Protocol)는 AI가 외부 도구를 직접 쓸 수 있게 해주는 연결 규격입니다. 연결하면 터미널의 Claude Code가 방금 만든 AI Workspace 페이지를 읽고, 만들고, 고칩니다.

토큰 발급(5분) → AI에게 열어줄 페이지 정하기(2분) → Claude Code에 등록(1분) → 연결 확인(1분). 화면 단위 상세 가이드는 별도 문서로 정리해뒀으니 그대로 따라 하면 됩니다.

→ 가이드: 노션 MCP 연결하기

이제 "이 작업 내용 노션에 정리해줘" 한마디로 노션에 실제 페이지가 생깁니다. Claude Code가 내 노션을 읽고 쓸 수 있게 됐습니다.

연결만으로는 부족한 이유

연결만 해둔 상태에서는 이런 일이 벌어집니다.

• 시킬 때마다 "어느 페이지 아래에, 어떤 포맷으로, 제목은 어떤 규칙으로"를 처음부터 다시 설명합니다
• 같은 일을 시켜도 결과물 모양이 매번 다릅니다
• 지난번에 잘 나온 결과를 재현하려면 그때 뭐라고 시켰는지 기억해내야 합니다

대화창을 닫으면 그 대화에서 정한 것들도 함께 사라집니다. 다음 대화의 Claude Code는 내 기록 방식을 모르는 상태에서 다시 시작합니다. 연결은 그대로 남아 있어도 기록 방식은 매번 새로 설명해야 합니다.

이 반복을 없애는 방법은 설명을 파일로 남기는 것입니다. 말로 시키던 내용을 문서로 만들어두면 AI는 매번 그 문서를 읽고 일합니다. 설명은 한 번만 하면 되고, 결과물은 항상 같은 기준으로 나옵니다.

이렇게 파일로 남긴 작업 지침을 Claude Code에서는 스킬(skill) 이라고 부릅니다.

2단계. 스킬: 노션 기록 스킬 만들기

스킬은 거창한 것이 아닙니다. 정해진 위치에 놓는 마크다운 파일 하나입니다.

~/.claude/
└── skills/
    └── notion-note/
        └── SKILL.md

~/.claude/는 내 계정 전체에 적용되는 위치입니다. 여기에 두면 어느 프로젝트에서 Claude Code를 열어도 같은 스킬을 부를 수 있습니다. 특정 프로젝트에서만 쓸 스킬이라면 그 프로젝트 폴더의 .claude/skills/에 두면 됩니다.

이렇게 만들어두면 Claude Code가 알아서 인식하고, "남겨줘" 한마디에 스킬에 적힌 절차대로 일합니다.

노션 쪽 준비는 앞에서 끝났습니다. 스킬에는 그 페이지를 어떻게 채울지만 적으면 됩니다. 아래 두 개를 복붙해서 페이지 이름만 내 구조에 맞게 바꾸세요.

스킬 1. notion-note : 판단과 시행착오를 작업 노트에 저장

작업 전체를 매번 요약할 필요는 없습니다. "이 판단은 나중에 다시 봐야겠다", "이 시행착오는 남겨두면 같은 실수를 줄이겠다" 싶은 것만 골라 저장하면 됩니다.

~/.claude/skills/notion-note/SKILL.md :

---
name: notion-note
description: 작업 중 나온 판단·해결 과정·시행착오를 노션 "작업 노트"에 정리해 저장. "이거 남겨줘", "노션에 정리해줘" 요청 시 사용.
---

# notion-note

사용자가 남기려는 작업 내용을 노션 "작업 노트" 페이지 하위에 저장한다.

## 읽는 것

1. 사용자가 방금 남기라고 한 내용
2. 그 내용이 나온 작업 맥락 (관련 결정·이유·시행착오·파일명)

## 절차

1. 노션에서 "작업 노트" 페이지를 찾는다.
   없으면 "AI Workspace" 하위에 먼저 만든다
2. 하위에 새 페이지를 생성한다
   - 제목: `YYYY.MM.DD - 프로젝트명 - 핵심 주제`
   - 본문 구조: 상황 / 핵심 정리 / 근거 / 다음에 볼 것
3. 생성한 페이지 링크를 보고한다

## 규칙

- 기록에 없는 일을 지어내지 않는다. 사실과 추정은 구분해서 쓴다
- 같은 이름의 페이지가 여럿이면 임의로 고르지 말고 어느 것인지 사용자에게 묻는다
- 원문 내용을 요약해 빼지 않는다. 정리는 형식만
- 남에게 공유해도 되는 문서처럼 쓴다
- 토큰·비밀번호·개인정보는 노션에 기록하지 않는다

파일을 만든 뒤 Claude Code를 새로 열고 /skills를 입력해보세요. 목록에 notion-note가 보이면 인식된 것입니다. 안 보이면 파일 위치와 이름(SKILL.md, 대문자)을 다시 확인하세요.

이제 작업 중에 "이거 노션에 남겨줘"라고 요청하면 됩니다. 어느 페이지에 어떤 제목으로 어떤 구조로 넣을지는 스킬에 적혀 있습니다.

스킬 2. notion-weekly : 기록과 커밋으로 주간 리뷰 작성

이건 제가 실제로 쓰는 방식입니다.

저는 매주 스터디를 운영하면서 한 주 작업 내역을 노션에 올립니다. 처음엔 직접 한 주를 돌아보며 썼는데, 일주일치를 되짚는 데 시간이 오래 걸리고, 분명히 했는데 빼먹는 작업이 꼭 나왔습니다.

지금은 작업 폴더에서 한 줄만 시킵니다. AI가 그 주의 노션 작업 노트와 git 커밋, 작업 중 남긴 기록을 분석해서 내가 무엇을 했고 무엇을 중요하게 여겼는지를 한 번에 정리합니다.

이 스킬을 쓰기 시작한 뒤로 한 주를 돌아보는 방식이 바뀌었습니다. 한 주를 정리하는 쪽이 내가 아니라 AI가 되고, 나는 정리된 리뷰를 읽으면서 "이번 주에 이걸 했었구나, 이걸 중요하게 여겼구나"를 확인합니다. AI가 커밋과 작업 노트를 직접 읽고 쓰기 때문에, 기억을 더듬을 때처럼 분명히 했는데 회고에서 빠지는 작업도 생기지 않습니다.