기술 문서의 60% 이상이 작성 후 6개월이 지나면 실제 시스템과 내용이 달라진다는 건 개발팀이라면 누구나 체감하는 현실입니다. 저도 그 현실 안에서 꽤 오랫동안 헤맸습니다. 온보딩 가이드를 읽고도 "이게 맞나?" 싶어 결국 코드를 직접 뒤지던 경험, 다들 한 번쯤 있을 겁니다.
문서 구조가 먼저다 — AI 도입 전에 챙겨야 할 것
Notion AI를 팀에 도입하면 문서 관리가 자동으로 좋아질 거라고 생각하는 분들도 있는데, 저는 그 기대가 반은 맞고 반은 틀렸다고 생각합니다. AI가 제 역할을 하려면 그 아래에 깔린 데이터, 즉 문서 자체가 먼저 정비되어 있어야 합니다.
저희 팀이 처음 Notion AI의 Q&A 기능을 켰을 때, 솔직히 기대만큼의 결과가 나오지 않았습니다. 팀 위키가 부서별로 제각각 구조였고, 페이지 중에는 업데이트된 날짜조차 없는 것들이 수두룩했습니다. AI에 "이 서비스의 인증 플로우가 어떻게 돼?"라고 물었더니, 2년 전 기준의 OAuth 2.0 흐름을 자신 있게 설명해 주더군요. OAuth 2.0이란 사용자 인증 정보를 제3자 앱에 직접 노출하지 않고, 액세스 토큰을 통해 권한을 위임하는 인증 프로토콜입니다. 문제는 AI가 그 프로토콜 자체를 틀리게 설명한 게 아니라, 우리 서비스가 이미 그 방식을 바꿨는데 오래된 문서를 참조해서 틀린 답을 내놨다는 점이었습니다.
기술 문서 관리에서 '정보 아키텍처(IA)'를 먼저 잡아야 한다는 말이 있습니다. 정보 아키텍처란 콘텐츠를 어떤 체계로 분류하고, 어떤 위계로 구조화할지를 설계하는 작업입니다. 저희는 결국 문서를 AI에 연결하기 전에 페이지 계층 구조를 정리하고, 더 이상 유효하지 않은 문서에는 '아카이브(Archive)' 태그를 붙이는 규칙부터 만들었습니다. 아카이브 처리란 현재는 사용하지 않지만 참고 목적으로 보존하는 문서를 별도로 분류하는 것입니다. 그 이후에야 Q&A 기능의 정확도가 눈에 띄게 올라갔습니다.
문서 구조 정비 시 저희 팀이 기준으로 삼은 포인트는 다음과 같습니다.
- 페이지 최상단에 '최종 업데이트 날짜'와 '담당자'를 반드시 표기
- 6개월 이상 업데이트가 없는 문서는 자동으로 '검토 필요' 상태로 분류
- 더 이상 유효하지 않은 문서는 즉시 아카이브 처리하여 AI 참조 범위에서 제외
Q&A와 ADR — Notion AI를 실무에 쓴 방법
문서 구조를 어느 정도 잡고 나서, Notion AI를 실무에 쓰는 방식이 확연히 달라졌습니다. 제가 직접 써봤는데 가장 체감이 컸던 건 Q&A 기능보다 오히려 ADR 작성 자동화였습니다.
ADR이란 아키텍처 결정 기록(Architecture Decision Record)의 약자로, 특정 기술적 판단을 내린 이유와 맥락을 문서로 남기는 관행입니다. 팀이 어떤 선택을 했고 왜 그 선택을 했는지 기록해두지 않으면, 몇 달 뒤 같은 논쟁이 반복됩니다. 저희도 그 문제를 겪었습니다. 회의에서 결론을 내렸는데, 3개월 뒤에 새로 합류한 팀원이 같은 질문을 다시 꺼내는 상황이 반복됐습니다.
그래서 저희는 회의 결과로 나온 결정 사항을 Notion 페이지에 붙여넣고, Notion AI에게 "이 내용을 기술 명세 형식으로 바꿔줘"라고 요청하는 방식을 도입했습니다. AI가 초안을 잡아주면 담당자가 세부 내용을 보완하는 구조입니다. 문서 작성에 걸리던 시간이 평균적으로 절반 이하로 줄었습니다.
Q&A 기능도 익숙해지고 나면 꽤 유용합니다. "배포 절차 확인하고 싶은데"라고 입력하면, AI가 팀 위키 안의 관련 페이지들을 참조해서 요약해 줍니다. 기존에는 사람에게 직접 물어보거나 Ctrl+F로 문서를 뒤지던 것을, AI가 관련 컨텍스트를 모아서 답해주는 방식으로 바뀐 겁니다. 기술 문서 관리에서 이런 방식을 RAG(Retrieval-Augmented Generation)라고 부르기도 합니다. RAG란 AI가 외부 문서를 실시간으로 검색해서 그 내용을 기반으로 응답을 생성하는 방식으로, 단순한 언어 모델보다 최신 정보와 조직 내부 정보를 훨씬 잘 반영합니다.
물론 Q&A 기능이 완벽하지는 않습니다. 오래된 정보와 최신 정보가 혼재된 상태에서는 AI가 틀린 답을 자신 있게 내놓는 경우가 있었습니다. 이 문제는 결국 버전 관리와 아카이빙 정책으로 해결할 수밖에 없습니다. AI 도구의 신뢰도는 그 아래 데이터의 품질과 직결됩니다(출처: Atlassian Blog).
버전 관리 없이는 AI도 없다 — 실무 유지보수의 현실
Notion AI를 글 교정 도구로만 쓰던 시절과 비교하면, 지금 팀의 문서 관리 방식은 상당히 달라졌습니다. 그런데 제 경험상 이건 좀 다릅니다. AI 기능을 아무리 잘 써도, 문서 버전 관리 정책이 없으면 효과가 반감됩니다.
버전 관리(Version Control)란 문서나 코드의 변경 이력을 체계적으로 관리하여, 특정 시점의 상태로 되돌리거나 변경 내용을 추적할 수 있게 하는 체계입니다. 코드에서는 Git이 이 역할을 하지만, 문서에서는 명시적인 규칙 없이 자연스럽게 정착되기 어렵습니다. 저희 팀도 처음에는 아무도 문서를 '수정했다'는 사실을 기록하지 않았습니다.
실제로 오래된 API 문서를 Notion AI에게 주고 "현재 코드 스니펫과 비교해서 업데이트가 필요한 부분을 찾아줘"라고 요청해 봤습니다. 제가 직접 써봤는데, AI가 찾아낸 불일치 항목의 정확도는 문서가 얼마나 구조적으로 잘 쓰여 있느냐에 따라 크게 달랐습니다. 구어체로 대충 쓴 메모 형식의 문서는 AI가 엉뚱한 부분을 지적하는 경우가 잦았습니다.
또 팀에서 예상 밖으로 가장 많이 쓰인 기능은 '요약'과 '번역'이었습니다. 솔직히 이건 예상 밖이었습니다. 영어로 된 RFC나 기술 블로그를 팀 내에 공유할 때, Notion AI로 한국어 요약을 붙여두는 것만으로도 팀 전체의 컨텍스트 공유 속도가 확연히 빨라졌습니다. RFC란 Request for Comments의 약어로, 인터넷 표준이나 기술 제안을 공개적으로 논의하기 위해 작성하는 공식 문서입니다. 개발팀에서 새로운 기술 도입을 검토할 때 이 문서를 자주 참조하는데, 영어 원문을 전부 읽히는 것보다 핵심 요약을 함께 붙여두는 편이 실질적인 논의로 이어지기가 훨씬 수월했습니다.
기술 문서 관리 도구 비교 연구에 따르면, 문서화 도구의 효용은 도구 자체 기능보다 팀의 문서화 문화와 정책에 더 크게 좌우된다고 분석됩니다(출처: Dev.to).
Notion AI가 팀의 지식 관리 방식을 바꿀 수 있는 건 분명합니다. 그러나 그 효과를 제대로 누리려면 AI 기능 켜기 전에 문서 구조 정비와 버전 관리 정책을 먼저 챙기는 것이 순서입니다. AI는 정리된 지식을 더 잘 쓸 수 있게 해주는 도구이지, 정리되지 않은 혼란을 스스로 수습해 주는 마법이 아닙니다. 지금 팀 위키가 뒤죽박죽이라면, Notion AI 도입보다 문서 구조 재정비를 먼저 일정에 넣는 걸 권합니다.
참고:
- Notion, Notion AI Documentation, https://www.notion.so/help/notion-ai
- Notion, Official Blog, https://www.notion.so/blog
- Notion, Developers API Guide, https://developers.notion.com
- Atlassian, Technical Documentation Best Practices, 2024, https://www.atlassian.com/blog
- Dev.to, Notion AI for Engineering Teams, 2024, https://dev.to