Notion AI로 개발 문서 초안 10분 만에 만드는 법: 빈 페이지 앞에서 멍하던 개발자의 현실적인 활용기

지난 주말에 오랜만에 제주도 애월 바다 앞에 앉아 있었거든요. 커피 한 잔 들고 파도 소리 듣고 있으니 참 좋더라고요. 그런데 사람 마음이 참 이상합니다. 쉬러 갔는데도 갑자기 월요일 일이 떠올라요. “아… 출근하면 그 시스템 아키텍처 정의서랑 API 명세서 초안, 누가 쓰지?” 이런 생각이 스윽 올라오더군요.

솔직히 개발자 중에 코딩보다 문서 쓰는 걸 더 좋아하는 사람이 얼마나 될까요. 물론 문서화를 정말 잘하고 즐기는 분들도 계시지만, 적어도 저는 아닙니다. 코드는 어떻게든 붙잡고 늘어지겠는데, 그걸 기획자, QA, 운영팀, 심지어 나중의 나까지 이해할 수 있게 정리하는 일은 이상하게 기운이 쭉 빠져요. 40대가 된 지금도 새하얀 Notion 페이지를 마주하면 살짝 숨이 턱 막힙니다. 뭐랄까, 빈 화면이 사람을 무안하게 만든달까요.

그러다 몇 달 전부터 Notion AI를 개발 문서 초안 작성에 본격적으로 써보기 시작했습니다. 미리 말하면, 이거 생각보다 꽤 괜찮습니다. 아니, 제 업무 습관을 조금 바꿔놨어요. 이제는 빈 페이지에서 처음부터 문장을 짜내는 일이 확 줄었습니다. 오늘은 제가 실무에서 개발 문서 초안, API 명세서, RFC 문서를 만들 때 Notion AI를 어떻게 쓰는지, 그리고 쓰면서 겪었던 삽질과 나름의 요령을 편하게 풀어볼게요.

개발 문서가 코드랑 따로 놀면 결국 아무도 안 읽더라

제가 예전엔 문서를 Notion에만 따로 예쁘게 정리해두는 편이었어요. 처음엔 그럴싸합니다. 제목도 깔끔하고, 표도 있고, 담당자도 적혀 있고요. 그런데 시간이 지나면 문제가 생깁니다. 코드가 바뀌었는데 문서는 그대로예요. 배포 방식이 바뀌었는데 아키텍처 설명은 옛날 그림을 보고 있습니다. 그러다 누군가 묻죠. “이 문서 최신 맞아요?” 그 순간 문서의 생명은 거의 끝난 겁니다.

그래서 요즘은 프로젝트를 시작할 때부터 코드 저장소 안에 docs 폴더를 같이 둡니다. Notion은 협업과 공유용으로 쓰고, 실제 원본에 가까운 뼈대는 레포지토리에 남겨두는 식이에요. 이게 조금 번거로워 보여도, 나중에 변경 이력을 따라가기가 훨씬 편합니다.

my-awesome-service/
├── docs/
│   ├── rfc/
│   │   ├── RFC-001-auth-migration.md
│   │   └── RFC-002-payment-gateway.md
│   ├── api/
│   │   └── v1-user-api.md
│   └── templates/
│       └── rfc-template.md
├── src/
│   ├── main/
│   └── test/
└── README.md

여기서 핵심은 docs/templates/rfc-template.md입니다. 저는 이 파일 안에 우리 팀이 자주 쓰는 문서 구조를 미리 넣어둡니다. 배경, 문제 정의, 대안, 선택한 방식, 트레이드오프, 롤백 전략, 영향 범위 같은 항목들이죠. 그런 다음 이 템플릿을 Notion 페이지에 붙여넣고, Notion AI에게 “이 구조 안에서 내가 던지는 메모를 문서답게 정리해줘”라고 시킵니다.

제가 실제로 꽤 자주 쓰는 프롬프트는 아래처럼 생겼습니다. 회사마다 톤은 조금씩 다르겠지만, 저는 이 정도로 구체적으로 줬을 때 결과물이 가장 덜 흔들리더라고요.

# RFC Draft Prompt Template

당신은 시니어 소프트웨어 엔지니어이자 기술 작가(Technical Writer)입니다.
아래의 [핵심 요구사항]과 [날것의 개발 메모]를 바탕으로,
정의된 RFC 템플릿 형식에 맞추어 명확한 기술 문서 초안을 작성해 주세요.

## 규칙:
1. 전문적이지만 너무 딱딱하지 않은 문체를 사용합니다.
2. 모호한 단어(예: 잘, 빠르게, 안정적으로) 대신 구체적인 기술 표현을 사용합니다.
3. 아키텍처상의 트레이드오프를 반드시 드러냅니다.
4. 확인이 필요한 수치나 일정은 임의로 만들지 말고 [확인 필요]로 표시합니다.
5. 기획, QA, 운영팀도 이해할 수 있도록 어려운 용어는 짧게 풀어 설명합니다.

[핵심 요구사항]:
Target System: Legacy MySQL to PostgreSQL Migration
Downtime Limit: Max 5 minutes
Rollback Plan: Required

[날것의 개발 메모]:
기존 마이그레이션 도구 쓰면 락 걸려서 서비스 터질 가능성 있음.
CDC 툴인 Debezium 써서 실시간 싱크 맞추고 막판에 스위칭하는 방향이 좋아 보임.
Kafka도 필요해서 인프라 비용은 조금 올라감.
대신 다운타임을 5분 안쪽으로 줄일 가능성이 높음.
운영팀이 장애 대응 시 볼 수 있는 체크리스트도 필요함.

여기서 저는 “임의로 만들지 말고 [확인 필요]로 표시해달라”는 문장을 꼭 넣습니다. 이거 은근히 중요해요. AI는 친절한 척하면서 없는 숫자도 만들어냅니다. 문서가 그럴듯해질수록 더 위험하죠. 특히 장애율, 응답 시간, 비용, 일정 같은 건 사람이 직접 확인해야 합니다. Notion AI가 초안을 잘 뽑아줘도, 책임은 결국 우리한테 남거든요.

회의 중 끄적인 메모도 꽤 그럴듯한 문서가 된다

사실 우리가 글을 못 쓰는 게 아닙니다. 머릿속에는 이미 설계가 있어요. 다만 그걸 “문서답게” 꺼내는 과정이 귀찮고 피곤한 거죠. 저도 회의 중에는 메모를 아주 날것으로 씁니다. 문장도 아니고 단어 덩어리에 가까워요.

로그인 개편
기존 세션 방식 유지하면 모바일 앱 쪽에서 계속 꼬임
JWT로 가되 refresh token 저장 정책 필요
Redis에 세션 상태 일부 들고 가면 강제 로그아웃 처리 쉬움
단점: Redis 장애 시 인증 영향 있음
QA는 기존 로그인 유지 케이스 많이 봐야 함
운영툴에서 사용자 토큰 강제 만료 기능 필요

이 정도 메모를 Notion 페이지에 붙여넣고, 해당 블록을 드래그한 뒤 Notion AI를 호출합니다. 보통 저는 이렇게 말해요.

“위 메모를 바탕으로 3년 차 백엔드 개발자와 QA 담당자가 함께 이해할 수 있는 로그인 개편 영향도 분석서 초안을 작성해줘. 표에는 변경 항목, 영향 범위, 리스크, 대응 방안을 넣어줘.”

그러면 꽤 쓸 만한 초안이 나옵니다. 물론 한 번에 완성본이 나오진 않아요. 그래도 빈 페이지에 제목 하나 못 쓰고 20분 날리는 것보다는 훨씬 낫습니다. 초안이 생기면 사람은 이상하게 고칠 힘이 생기거든요. 아무것도 없을 때는 막막한데, 엉성한 문장이라도 있으면 “아, 이건 아닌데” 하면서 손이 움직입니다.

예전에 바이브코딩으로 개발할 때 참고하면 좋은 AI 도구 총정리 글에서도 비슷한 이야기를 한 적이 있는데요. 요즘 AI 도구는 하나만 잘 쓰는 것보다, 각 도구가 잘하는 일을 나눠서 쓰는 게 훨씬 효율적입니다. Notion AI는 특히 “이미 쓰고 있는 문서 안에서 바로 이어서 작업한다”는 점이 좋아요. 복사하고 붙여넣고 다시 포맷 맞추는 작은 귀찮음이 사라지니까, 생각보다 체감이 큽니다.

Notion AI, ChatGPT, Claude는 비슷해 보여도 쓰임새가 다르다

주변 개발자들이 자주 묻습니다. “그냥 ChatGPT나 Claude에 넣고 문서 써달라고 하면 되는 거 아니야?” 맞습니다. 그렇게 해도 됩니다. 저도 많이 그렇게 했고요. 그런데 실제 업무 흐름 안에 넣어보면 세 도구의 느낌이 꽤 다릅니다.

제가 체감한 차이를 조금 현실적으로 정리해보면 이렇습니다.

비교 항목	Notion AI	ChatGPT	Claude
업무 흐름	문서 작성 중 바로 호출할 수 있어서 흐름이 덜 끊김	브라우저 탭을 오가야 해서 살짝 번거로움	긴 글 작업엔 좋지만 별도 작업 공간이 필요함
컨텍스트 유지	현재 페이지 맥락을 잘 따라오는 편	대화 안에서는 괜찮지만 문서 전체 구조와는 분리됨	긴 컨텍스트 처리에 강해서 장문 분석에 유리함
문장 느낌	정돈된 회사 문서 느낌이 잘 남	가끔 번역투나 교과서 같은 표현이 섞임	문장이 자연스럽고 긴 글을 다듬는 데 강함
제가 주로 쓰는 용도	API 명세서, RFC, 회의록, 사내 공유 문서	아이디어 정리, 코드 예시, 빠른 질의응답	블로그 글, 긴 설명문, 외부 공개용 콘텐츠

솔직히 감성적인 글이나 외부에 공개할 콘텐츠를 쓸 때는 Claude가 더 마음에 들 때가 많습니다. 문장이 부드럽고, 흐름을 잡는 능력이 좋아요. 이 부분은 제가 예전에 쓴 Claude 글쓰기 AI로 블로그 수익화하는 방법 글에서도 꽤 자세히 다뤘습니다.

다만 회사 안에서 빠르게 공유해야 하는 개발 문서는 조금 다릅니다. 저는 이때 Notion AI 쪽에 손이 더 자주 갑니다. 이미 팀 문서가 Notion에 있고, 회의록도 Notion에 있고, API 정책도 Notion에 있다면 굳이 다른 도구로 나갔다가 다시 돌아올 필요가 없거든요. 별거 아닌 것 같지만, 이 작은 이동 비용이 쌓이면 하루 끝에 꽤 피곤합니다.

Notion AI로 API 명세서 초안 만들 때 제가 쓰는 방식

API 문서는 특히 초안 만들기가 귀찮습니다. 엔드포인트, 요청 파라미터, 응답 예시, 에러 코드, 인증 방식, 권한 조건까지 넣다 보면 문서가 금방 길어지거든요. 그래서 저는 처음부터 완벽하게 쓰려고 하지 않습니다. 일단 코드나 개발 메모에서 핵심만 뽑아 Notion AI에게 던집니다.

예를 들어 사용자 프로필 조회 API를 만든다고 하면, 먼저 이렇게 거칠게 적습니다.

사용자 프로필 조회 API
GET /api/v1/users/{userId}/profile
인증 필요: Bearer Token
본인 또는 admin 권한만 조회 가능
응답: userId, nickname, email, profileImageUrl, createdAt
email은 본인 조회일 때만 내려줌. admin은 마스킹된 email
에러:
401 토큰 없음
403 권한 없음
404 사용자 없음

그다음 Notion AI에게 이렇게 요청합니다.

위 내용을 바탕으로 API 명세서 초안을 작성해줘.

다음 형식을 반드시 포함해줘.
개요
인증 및 권한
Request
Path Parameter
Response Body
Error Response
보안상 주의할 점
QA 체크리스트

응답 예시는 JSON 코드 블록 형태로 작성하되,
확실하지 않은 필드는 임의로 추가하지 말아줘.

이 방식의 장점은 단순합니다. 제가 머릿속에서 이미 알고 있는 내용을 대충 던져도, Notion AI가 문서의 틀을 잡아줍니다. 그러면 저는 그 위에 빠진 정책을 채워 넣고, 틀린 부분을 고치고, 보안 조건을 한 번 더 확인하면 됩니다. 문서 작성자가 아니라 검토자가 되는 느낌이에요. 이 차이가 은근히 큽니다.

바이브 코딩만 위험한 게 아니라 바이브 라이팅도 꽤 위험하다

요즘 바이브 코딩이라는 말 많이 쓰잖아요. AI한테 분위기만 던지고 코드를 쭉 받는 방식이요. 잘 쓰면 정말 편하지만, 대충 믿고 붙이면 나중에 어디서 터질지 모릅니다. 문서도 비슷합니다. 저는 이걸 혼자 바이브 라이팅이라고 부릅니다.

Notion AI에게 “알아서 개발 문서 써줘”라고만 하면, 겉보기엔 멀쩡한 문서가 나옵니다. 제목도 있고, 표도 있고, 문장도 그럴듯해요. 그런데 자세히 보면 핵심이 빠져 있습니다. 장애 시나리오가 없다든지, 롤백 전략이 빈약하다든지, 제일 중요한 성능 지표가 그냥 좋은 말로 뭉개져 있다든지요. 이런 문서는 차라리 없는 게 나을 때도 있습니다. 읽는 사람에게 잘못된 안정감을 주니까요.

제가 Notion AI로 개발 문서를 만들 때 지키는 기준은 아래와 같습니다.

동사와 수치를 같이 던집니다. “성능 개선 문서 써줘”보다는 “Redis 캐싱 레이어를 추가해서 상품 상세 조회의 평균 응답 시간을 200ms에서 35ms로 낮춘 내용을 영향도 중심으로 정리해줘”가 훨씬 낫습니다.

AI에게 역할을 줍니다. “당신은 백엔드 리드 개발자입니다”, “당신은 운영 안정성을 중요하게 보는 SRE입니다”처럼 관점을 지정하면 문서의 밀도가 달라집니다.

모르는 값은 비워두게 합니다. 비용, 트래픽, 일정, 장애율 같은 숫자는 AI가 만들면 안 됩니다. 저는 꼭 “[확인 필요]로 표시해줘”라고 씁니다.

리스크와 트레이드오프를 강제로 쓰게 합니다. 좋은 점만 있는 기술 선택은 거의 없습니다. 비용이 늘거나, 운영 복잡도가 올라가거나, 학습 비용이 생깁니다. 이걸 문서에 남겨야 나중에 덜 억울합니다.

초안과 최종본을 분리합니다. Notion AI가 만든 문서는 초안일 뿐입니다. 저는 꼭 직접 읽고, 틀린 표현을 지우고, 우리 팀의 실제 운영 방식에 맞게 고칩니다.

재미있는 건, 이 기준을 몇 번 반복하면 Notion AI에게 주는 프롬프트도 점점 짧아진다는 겁니다. 처음에는 길게 설명해야 했는데, 나중에는 “우리 RFC 템플릿 기준으로, 리스크와 롤백 전략을 빼먹지 말고 정리해줘” 정도만 말해도 꽤 괜찮게 나옵니다. 물론 Notion 워크스페이스 안에 기존 문서들이 잘 쌓여 있다는 전제가 있긴 합니다.

제가 실제 업무에서 체감한 장점과 아쉬운 점

도구 이야기를 할 때 좋은 점만 말하면 좀 얄밉잖아요. Notion AI도 만능은 아닙니다. 쓰면서 좋았던 점도 분명하고, 아쉬운 점도 꽤 있습니다.

구분	제가 느낀 점	대응 방법
좋았던 점	빈 페이지 공포가 줄어듭니다. 초안 작성 시간이 확실히 짧아져요.	회의 직후 날것의 메모를 바로 Notion에 넣고 초안화합니다.
좋았던 점	표, 체크리스트, 문서 구조를 빠르게 잡아줍니다.	팀 템플릿을 고정해두고 같은 형식으로 반복 생성합니다.
아쉬운 점	가끔 너무 무난한 문장으로 핵심 리스크를 흐립니다.	“가장 위험한 실패 시나리오 3개를 별도 항목으로 써줘”라고 추가 요청합니다.
아쉬운 점	수치나 정책을 그럴듯하게 추정하려는 경향이 있습니다.	확실하지 않은 내용은 반드시 [확인 필요]로 남기게 합니다.

개인적으로는 Notion AI를 “문서를 대신 써주는 사람”이라기보다 “초안 만드는 후배” 정도로 생각하면 마음이 편합니다. 일을 정말 빠르게 해오긴 하는데, 아직 우리 서비스의 사정이나 조직의 히스토리는 잘 모릅니다. 그러니 방향을 잡아주고, 결과물을 봐주고, 위험한 표현은 바로잡아줘야 합니다.

Notion AI 문서 작성이 특히 잘 맞는 사람들

제가 몇 달 써보니, Notion AI가 특히 잘 맞는 사람들이 있습니다. 무조건 모두에게 필요한 도구라고 말하고 싶진 않아요. 도구는 결국 자기 일의 모양과 맞아야 오래 쓰게 되니까요.

개발 설계는 머릿속에 있는데 문서 첫 문장을 쓰는 데 시간이 오래 걸리는 개발자

회의록, 주간 보고, 장애 회고를 매번 손으로 정리하느라 지치는 직장인

기획, 디자인, QA, 운영팀과 공유할 기술 문서를 자주 쓰는 백엔드 또는 플랫폼 개발자

기술 블로그를 쓰고 싶은데 초안 단계에서 자꾸 멈추는 사람

팀 문서의 형식이 제각각이라 읽는 사람마다 피로해지는 조직

특히 협업 부서에서 “내용은 알겠는데 말이 너무 어려워요”라는 피드백을 자주 듣는 분들께는 한 번 써보라고 권하고 싶습니다. Notion AI에게 “기획자와 QA도 이해할 수 있게 풀어 써줘”라고만 해도 문서 톤이 꽤 달라집니다. 물론 기술적으로 틀리지 않았는지는 개발자가 다시 봐야 하고요. 이건 양보하면 안 됩니다.

저는 요즘 문서 초안을 직접 처음부터 쓰지 않습니다. 대신 메모를 잘 남기려고 합니다. 회의 중 나온 결정, 찝찝한 리스크, 나중에 꼭 확인해야 할 수치, 누가 반대했는지까지 대충이라도 적어둡니다. 그걸 Notion AI에게 넘기면 초안은 금방 나와요. 그러면 저는 개발자답게 판단하고 고칩니다. 사실 이 정도만 해도 퇴근 시간이 꽤 달라집니다.

Notion AI는 멋진 문장을 만들어주는 도구라기보다, 머릿속에 흩어진 생각을 문서라는 그릇에 담아주는 도구에 가깝습니다. 빈 화면 앞에서 괜히 커피만 마시고 있는 시간이 길다면, 한 번쯤 써볼 만합니다. 개발 문서 때문에 매번 마음이 무거운 분들, 팀 문서 품질을 조금이라도 끌어올리고 싶은 분들, 그리고 퇴근 후엔 일 생각 말고 산책이든 맥주 한 잔이든 자기 시간을 갖고 싶은 분들에게 꽤 현실적인 선택지가 될 거예요.

👨‍💻

작성자: 20년 경력 IT 전문 아키텍트

실무 개발과 아키텍처 설계를 거쳐 현재는 AI 바이브 코딩과 개발 자동화를 연구하고 있습니다. 직접 삽질하며 깨달은 실전 꿀팁과 에러 극복 사례만 투명하게 공유합니다.

🔍 관련 정보 더 보기

Iros

이 블로그 검색

Featured Post

Task Master AI로 작업분해 해봤더니, 20년 차 개발자도 놓치던 게 보이더라