방법론을 들고 첫 도구를 만들었다 — Slack to Notion 제작기

왜 만들었는가

비개발자 동료에게서 이런 이야기를 들었습니다.

“Slack 스레드에 댓글이 200개 넘게 쌓였는데, 복사해서 AI에 넣으면 중간이 잘리거나 엉뚱하게 정리해줘요.”

실제로 그렇습니다. Slack 스레드는 대화가 길어질수록 맥락이 뒤섞입니다. 그걸 통째로 복사해서 AI에게 넘기면, 토큰 제한에 걸리거나 맥락을 잘못 해석합니다.

이 문제를 듣고 생각했습니다. 직전까지 만들어온 이슈 사이클과 설계 원칙이 있으니, 실제 불편사항에 적용해볼 수 있겠다. 적응기에서 정립한 방법론의 첫 번째 실전 투입이었습니다.

무엇을 만들었는가

claude-slack-to-notion — Slack 채널의 대화를 수집하고, AI가 분석해서, Notion 페이지로 정리하는 도구입니다.

Claude Code 플러그인 형태로 동작합니다. 설치하면 자연어로 바로 사용할 수 있습니다.

“#backend 채널의 최근 50개 메시지를 Notion에 정리해줘” “이 스레드 내용을 주제별로 분류해서 Notion 페이지로 만들어줘”

데이터 흐름은 단순합니다.

graph LR
    A["Slack API"] -->|메시지 수집| B["MCP 도구"]
    B -->|포맷팅| C["Claude Code"]
    C -->|분석 결과| D["Notion API"]
    D --> E["팀 협업"]

핵심은 역할 분리입니다. 도구는 수집과 포맷팅만 하고, 분석은 AI에게 맡기고, 어떤 방향으로 정리할지는 사용자가 결정합니다.

어떻게 만들었는가

이전 포스팅에서 만든 이슈 사이클을 그대로 적용했습니다.

/github-issue → /spec → /implement → /commit → /github-pr

모든 변경이 이 흐름을 따랐습니다. 초기 구조 설계, Slack 수집 모듈, 분석 모듈, Notion 연동, MCP 서버 통합, 리팩토링까지 — 각 단계가 하나의 이슈-명세-구현-PR로 완결되는 단위였습니다.

방법론을 실제로 돌려보니 보이는 것들이 있었습니다.

명세를 먼저 쓰니까 구현이 빨랐습니다. 어디까지 만들지가 명확하니, AI에게 정확한 지시를 줄 수 있었습니다. “Slack API에서 메시지를 가져오는 함수를 만들어줘”가 아니라, “이 명세대로 SlackClient 클래스를 구현해줘”가 되었습니다.

이슈 단위로 나누니까 되돌리기가 쉬웠습니다. E2E 테스트에서 Notion Database 방식이 한글 프로퍼티와 호환되지 않는 문제를 발견했습니다. DB 방식을 버리고 직접 페이지 생성으로 전환했는데, 이슈 단위로 분리되어 있었기 때문에 영향 범위가 명확했습니다.

설계에서 고민한 것들

토큰 설계

Slack 토큰은 Bot(xoxb-)과 사용자(xoxp-) 두 방식이 있습니다. “Bot을 채널에 넣으면 다른 사람들이 알아차린다”는 현실과 “한 명이 설정하고 팀이 공유하는 게 편하다”는 현실이 공존했습니다. 둘 다 지원하되 Bot을 우선하기로 했습니다. 권장 방식이 기본값이어야 하고, 사용자 토큰은 Bot을 쓸 수 없을 때의 대안으로 남겼습니다.

이후 비개발자 피드백을 거치며 이 판단은 뒤집혔습니다. Bot 토큰은 채널 초대와 권한 설정이 추가로 필요해 비개발자에게는 사용자 토큰이 더 간단했습니다. 현재는 사용자 토큰을 권장하고, Bot 토큰은 팀 공유용 옵션입니다.

비개발자를 위한 가이드

이 도구의 사용자는 개발자가 아닙니다. 기획자, 사업 담당자, 팀원 누구나 쓸 수 있어야 합니다.

README를 작성한 뒤 처음부터 직접 따라가며 검증했습니다. 그 과정에서 발견한 것들:

• Notion UI가 한글화되어 있어 영문 가이드가 무의미
• /invite @봇이름이 App에는 동작하지 않음
• “notion” 단어가 Integration 이름에 사용 금지
• Notion 페이지 URL에서 32자 ID를 추출하라는 안내가 비개발자에겐 불친절

URL을 그대로 붙여넣으면 Page ID가 자동 추출되도록 코드를 수정하고, 가이드의 모든 UI 용어를 실제 화면 기준으로 교정했습니다.

개발자에겐 당연한 것이 비개발자에겐 허들입니다. 이 검증이 시작점이었고, 실제로 비개발자에게 건네본 이야기는 다음 편에서 다룹니다.

만들고 나서 든 생각

적응기에서 만든 방법론이 실제로 동작하는 걸 확인했습니다. 이슈 사이클이 강제하는 흐름 — 명세 먼저, 이슈 단위로 완결, 추적 가능한 변경 — 이 구조 덕분에 방향을 잃지 않고 만들 수 있었습니다.

동시에 부족한 점도 보였습니다. 비개발자 관점의 검증이 부족했고, 실제 현장에서 쓰이려면 아직 다듬어야 할 것이 많습니다.

만들었으니 다음은 검증 차례입니다. 비개발자에게 건네기 전에 직접 테스트부터 시작했고, 그 과정에서 설계가 바뀌었습니다.

---

이 글은 Claude의 도움을 받아 작성했습니다.