건네도 될까에서 건넸다로 — 비개발자 실전 피드백

건네보기로 했다

이전 포스팅에서 이렇게 마무리했습니다.

“건네도 될까”라는 질문에 아직 완전히 답하지 못했습니다. 실제 비개발자에게 건네보는 것은 다음 실전의 몫으로 남겨둡니다.

적응기는 거기서 끝났지만 질문은 남아 있었습니다. 직접 만들고, 직접 테스트하고, E2E까지 돌렸지만 “비개발자가 실제로 쓸 수 있는가”는 건네봐야만 알 수 있었습니다.

그래서 건넸습니다. 결과는 절반의 성공이었습니다.

코드 버그는 0건. 막힌 것은 전부 문서와 가이드였습니다.

첫 피드백 — 설정에서 또 막혔다

도구를 건네받은 비개발자가 가이드를 따라 설정을 시작했습니다. 5편에서 “설치보다 설정에서 많이 깨졌다”고 정리했는데, 실제 비개발자에게서도 설정에서 막혔습니다.

Slack API의 함정

Slack 앱 설정에서 Bot Token Scopes를 먼저 추가하고 앱을 설치한 뒤 User Token Scopes를 설정하려 했습니다. 그런데 User Token 영역이 비활성화되어 토큰 복사가 불가능했습니다.

가이드대로 했는데 동작하지 않는 상황. Slack API의 UI 버그였습니다.

해결 방법은 앱을 삭제하고 처음부터 다시 만드는 것뿐이었습니다.

개발자라면 “삭제하고 다시 해보자”고 판단할 수 있지만, 비개발자에게 “만든 걸 지우고 다시 하세요”는 불안한 안내입니다. 가이드에 이 함정을 미리 경고해야 했습니다.

Notion UI가 바뀌었다

Notion Integration 생성 URL이 바뀌어 있었습니다. 기존 my-integrations에서 profile/integrations/internal로 변경. 가이드의 URL이 엉뚱한 곳을 가리키고 있었습니다.

더 중요한 문제는 콘텐츠 권한 설정이었습니다. Integration을 만든 뒤 “콘텐츠 사용 권한” 탭에서 워크스페이스나 페이지를 연결해야 API가 동작합니다.

이 단계를 빠뜨리면 토큰은 정상인데 API가 거부합니다.

가이드 구조의 문제

설정 순서도 맞지 않았습니다. API Integration을 만드는 과정에서 Notion 페이지 연결이 필요한데, 가이드에서는 페이지 생성이 뒤에 나왔습니다.

개발자 전용 설정이 일반 사용자에게도 보이는 것도 문제였습니다. 비개발자는 setup.sh만 실행하면 되는데, 환경변수 설명이 같은 섹션에 있으니 “이것도 해야 하나?” 하고 혼란을 느꼈습니다.

피드백을 반영하다

피드백은 5가지. 전부 문서와 가이드의 문제였고, 코드 버그는 0건이었습니다.

가이드 전면 개편

토큰 발급 가이드를 다시 썼습니다. 3편에서 Bot 토큰을 기본으로 권장했지만, 비개발자에게는 채널 초대 없이 바로 쓸 수 있는 사용자 토큰이 더 간단했습니다. 권장 순서를 뒤집는 것부터 시작했습니다.

• Slack API 버그를 주의사항으로 명시
• Notion URL을 현행화
• 단계 순서 변경: 페이지 생성 → API Integration 순으로
• 개발자 설정을 별도 섹션으로 완전 분리
• 활용 팁 섹션 추가

특히 팁 섹션은 단순한 사용법이 아니라 “AI에게 분석 방향을 학습시키는 법”을 안내하는 것이었습니다. 비개발자는 AI와의 대화가 매번 리셋된다는 사실을 모릅니다. 분석 선호도를 저장하면 다음에도 같은 방식으로 정리해준다는 걸 알려줘야 했습니다.

새 기능 — 활성 사용자 확인

피드백 과정에서 “지금 누가 온라인인지도 알 수 있으면 좋겠다”는 의견이 나왔습니다. Slack 워크스페이스에서 현재 활성 상태인 사용자를 확인하는 기능을 추가했습니다.

도구 하나와 테스트 7건. 기존 토큰 권한으로 바로 동작했습니다.

다시 건넸다 — 절반의 성공

개편한 가이드로 처음부터 다시 진행해달라고 요청했습니다. 이번에는 설정부터 사용까지 막히는 구간 없이 통과했습니다.

다만 솔직히 말하면, “건네기만 하면 되는” 수준은 아니었습니다. 가이드를 전면 개편하고, 기능을 추가하고, 개발자가 옆에서 첨언한 뒤에야 완성된 결과였습니다. 비개발자 혼자 처음부터 끝까지 해낸 것이 아니라, 개발자가 피드백을 받아 고치고 다시 건넨 것입니다.

돌아보며

5편의 E2E에서 잡은 것과 실제 사용자가 잡은 것이 달랐습니다.

구분	5편 (개발자 E2E)	6편 (실제 비개발자)
코드 버그	5건	0건
문서/UX 이슈	2건	5건
해결 방식	개발자 혼자 수정	피드백 → 개편 → 재시도

개발자의 “비개발자 관점” 테스트는 결국 개발자의 상상력 안에서의 시뮬레이션이었습니다.

Slack API의 UI 버그는 상상할 수 없었습니다. Notion URL이 바뀐 것도 직접 가보기 전에는 몰랐습니다.

“이 단계는 개발자만 보면 되지 않나?”라는 판단도 비개발자가 실제로 혼란을 느끼기 전에는 확신할 수 없었습니다. 건네봐야 알 수 있는 것들이었습니다.

코드 버그가 0건이었다는 점에서는 안도했습니다. 5편까지의 테스트가 코드 품질은 잡아준 셈입니다. 이번에 드러난 것은 전부 문서와 UX의 문제였고, 그것은 실제 사용자만이 발견할 수 있는 영역이었습니다.

“비개발자도 쓸 수 있는 도구”를 만들겠다고 시작했습니다. 도구 자체는 동작합니다. 하지만 비개발자가 혼자 설정까지 마치려면 아직 개발자의 도움이 필요합니다. 완전한 셀프서비스까지는 한 걸음이 남아 있습니다.

1편에서 프로세스를 만들고, 2편에서 사고방식을 바꾸고, 3편에서 도구를 만들고, 4편에서 테스트가 설계를 바꾸고, 5편에서 사용자 관점까지 도달하고, 이번에 실제 사용자에게 건넸습니다.

적응기는 여기까지입니다.

---

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