Claude Code로 작업하다 보면 결과물만 남기기 아까운 순간이 많습니다.
코드를 고치다 내린 판단, 콘텐츠 초안을 만들며 정리한 논리, 사업으로 이어질 만한 아이디어, 시행착오 끝에 알게 된 것. 그 자리에서는 분명 중요한데, 대화창에만 두면 며칠 뒤 찾지 못합니다.
이런 기록을 로컬 마크다운으로 남길 수도 있고, Obsidian 같은 도구도 훌륭합니다. 다만 밖에서 꺼내 보거나 링크로 공유하거나 남과 함께 관리하려는 순간 번거로워집니다. 노션은 앱과 웹, 공유와 협업을 전제로 만들어진 공간이라 이 지점에서 유리합니다.
작업은 Claude Code에서, 정리와 축적은 노션에서. 이 글의 주제입니다.
사람이 결과물을 복사해서 노션에 옮기는 방법이 아닙니다. Claude Code가 직접 노션을 읽고 쓰면서, 작업 중 나온 기록을 정해진 위치와 형식으로 쌓게 만드는 방법입니다. "노션 MCP 연결법" 이야기도 아닙니다. 연결은 출발점이고, 나머지가 진짜입니다.
MCP를 연결하면 Claude Code가 내 노션에 들어올 수 있습니다. 어느 페이지까지 열어줄지도 내가 정합니다. 그런데 연결만 해두면 기록할 때마다 어느 페이지에 넣고 어떤 제목을 붙이고 어떤 형식으로 정리할지 다시 설명해야 하고, 결과물 모양은 매번 다릅니다. 기록이 들어갈 위치와 형식, 지켜야 할 규칙이 어디에도 적혀 있지 않기 때문입니다.
그래서 이 칼럼은 3단계로 진행합니다.
- 연결 : 노션 MCP 연결
- 스킬 : 작업별 절차 파일 작성 (복붙용 실물 2개 포함)
- 환경 : 어느 프로젝트에서든 부를 수 있게 설치
노션에 먼저 만들 것
시작하기 전에 노션에 상위 페이지 하나를 만듭니다. 이름은 AI Workspace로 하겠습니다. 작업 노트와 주간 리뷰가 모두 이 아래로 들어갑니다.
처음에는 하위 페이지 두 개면 충분합니다.
AI Workspace
├── 작업 노트 ← 작업 중 나온 판단·해결 과정·시행착오
└── 주간 리뷰 ← 작업 노트와 커밋을 모아 한 주를 돌아보는 곳
여기서 완벽한 지식 관리 시스템을 설계하려 들지 마세요. 페이지를 늘리는 건 나중에 언제든 됩니다. 지금 필요한 건 기록이 들어갈 자리가 정해져 있는 상태입니다. 그 자리에 어떤 형식으로 쓸지는 2단계에서 스킬 파일이 맡습니다.
1단계. 연결: 노션 MCP
MCP(Model Context Protocol)는 AI가 외부 도구를 직접 쓸 수 있게 해주는 연결 규격입니다. 연결하면 터미널의 Claude Code가 방금 만든 AI Workspace 페이지를 읽고, 만들고, 고칩니다.
토큰 발급(5분) → AI에게 열어줄 페이지 정하기(2분) → Claude Code에 등록(1분) → 연결 확인(1분). 화면 단위 상세 가이드는 별도 문서로 정리해뒀으니 그대로 따라 하면 됩니다.
이제 "이 작업 내용 노션에 정리해줘" 한마디로 노션에 실제 페이지가 생깁니다. Claude Code가 내 노션을 읽고 쓸 수 있게 됐습니다.
연결만으로는 부족한 이유
연결만 해둔 상태에서는 이런 일이 벌어집니다.
- 시킬 때마다 "어느 페이지 아래에, 어떤 포맷으로, 제목은 어떤 규칙으로"를 처음부터 다시 설명합니다
- 같은 일을 시켜도 결과물 모양이 매번 다릅니다
- 지난번에 잘 나온 결과를 재현하려면 그때 뭐라고 시켰는지 기억해내야 합니다
대화창을 닫으면 그 대화에서 정한 것들도 함께 사라집니다. 다음 대화의 Claude Code는 내 기록 방식을 모르는 상태에서 다시 시작합니다. 연결은 그대로 남아 있어도 기록 방식은 매번 새로 설명해야 합니다.
이 반복을 없애는 방법은 설명을 파일로 남기는 것입니다. 말로 시키던 내용을 문서로 만들어두면 AI는 매번 그 문서를 읽고 일합니다. 설명은 한 번만 하면 되고, 결과물은 항상 같은 기준으로 나옵니다.
이렇게 파일로 남긴 작업 지침을 Claude Code에서는 스킬(skill) 이라고 부릅니다.