"기술 문서는 늘 부족합니다. 특히 '좋은' 기술 문서는 더더욱 그렇죠."
테크니컬 라이터로서, 또 문서 엔지니어로서 항상 마주하는 현실입니다. 모든 개발 프로젝트의 문서를 소수의 전문가가 전부 책임지기에는 수가 턱없이 부족합니다. "개발자 글쓰기 교육"으로 그 간극을 메워보려는 시도도 있지만, 과연 교육만으로 이 문제가 해결될까요?
저는 조금 회의적이었습니다. 개발자가 기술 문서를 쓰지 않는 이유는 단순히 '잘 쓰는 방법을 몰라서'가 전부는 아니기 때문입니다. '시간 부족'이나 '관심 부족'과 같은 현실적인 제약은 교육만으로는 해결하기 어렵습니다. 그래서 저는 이 문제를 '개발자 교육'보다는 '엔지니어링', 즉 프로세스를 통한 강제화와 도구를 이용한 자동화로 풀어보려고 노력해 왔습니다.
생성형 AI의 등장은 글 쓰는 직무를 위협할 것이라는 예측을 낳았지만, 저와 같은 문서 엔지니어에게 AI는 경쟁자가 아닌, 기존의 한계를 극복하게 해주는 강력한 '동반자'이자 '기회'였습니다. 비유하자면, 테크니컬 라이터가 한 땀 한 땀 공들여 문서를 만들어 내던 가내수공업 방식을, 공장형 자동 생산 시스템으로 전환할 기회랄까요?
물론 공장형 생산이 항상 가내수공업보다 우월하다는 의미는 아닙니다. 짧은 시간에 대량으로 결과물을 만들어낼 수 있지만, 그 품질을 온전히 담보하기는 어렵다는 명확한 트레이드오프가 존재하죠. 저희 팀은 이러한 마음가짐으로 AI를 꾸준히 활용해 왔고, 마침내 그 아이디어를 실제 프로젝트로 시험해 볼 기회를 얻었습니다.
1. 생성형 AI로 API 레퍼런스 만들기: 왜 또 다른 도구가 필요한가?
최근 많은 기업들이 업무에 생성형 AI를 적극적으로 도입하고 있으며, 저희 역시 주요 개발 단계에서 AI를 활용하는 프로젝트에 참여하게 되었습니다. 그중 저희 팀이 맡은 과제는 바로 '문서화'였습니다.
수많은 문서 유형 중, 우리는 개발 단계에서 가장 필요하고, 소스 코드를 기반으로 생성할 수 있으며, 개발자와 사용자 모두에게 직접적인 영향을 미치는 API 레퍼런스 문서를 첫 번째 타겟으로 삼았습니다.
"잠깐만요, GitHub Copilot 같은 코딩 어시스턴트가 이미 코드 설명은 잘해주고 있잖아요?" 라는 의문이 드실 수 있습니다. 맞습니다. 하지만 기존 코딩 어시스턴트만으로는 해결하기 어려운 몇 가지 중요한 문제들이 있었습니다.
- 사내 스타일 가이드 미준수: 기업마다 고유의 기술 문서 스타일과 톤앤매너가 있지만, 범용 AI는 이를 따르지 못합니다.
- 사내 기술 및 컨텍스트 부재: 사내에서만 통용되는 용어, 기술 스택, 비즈니스 로직에 대한 이해가 없어 엉뚱한 설명을 만들어냅니다.
- 일관성 부족: 동일한 코드에 대해서도 질문할 때마다 다른 스타일과 내용의 설명을 생성합니다.
- 파편화된 문서 형식 및 배포 위치: 프로젝트마다 API 문서의 형식(예: Swagger, Javadoc, 자체 마크다운)과 배포 위치가 달라, 개발자들이 참고하고 관리하기 어렵다는 내부 의견도 있었습니다.
따라서 저희 프로젝트의 목표는 명확해졌습니다.
"사내 정보를 학습하여, 사내 스타일에 맞는 API 주석을 자동으로 작성하고, 이를 표준화된 레퍼런스 문서로 만들어 한곳에서 통합 배포하자!"
2. 최적의 결과물을 위한 프롬프트와 워크플로 설계
저희 팀은 이미 기술 문서 검토, 다국어화, 스타일 일관성 검증 등에 AI를 활용하며 프롬프트 엔지니어링 경험을 쌓아왔습니다. 사내 스타일 가이드에 맞춰 일관된 결과물을 얻으려면 꽤 길고 상세한 프롬프트가 필요합니다. 여기에 프로그래밍 언어별 API 주석 작성법과 사내 용어 정보까지 더했더니, LLM이 몇몇 중요한 지시를 놓치기 시작했습니다. (LLM도 한 번에 너무 많은 지시를 받으면 기억력이 떨어지나 봅니다.)
사내 머신러닝 전문가의 조언에 따라, 우리는 하나의 거대한 프롬프트를 여러 개의 작은 단계로 나누고, 각 단계별로 최적화된 프롬프트를 순차적으로 실행하는 워크플로를 설계하기로 했습니다.
처음에는 아래와 같이 세세하게 단계를 나누었습니다.
- API 전체 설명 작성
- 파라미터 설명 작성
- 응답 값(리턴) 설명 작성
- 예제 코드 작성
- 추가 정보(주의사항 등) 작성
과연, 단계를 나누니 한 번에 요청하는 것보다 훨씬 정확하고 상세한 설명을 얻을 수 있었습니다. 하지만 단계가 길어질수록 처리 시간이 오래 걸리는 단점이 있었죠. 결국, 결과물의 품질과 처리 시간 사이에서 적절한 타협점을 찾아야 했습니다.
여러 테스트를 거쳐, 결과물의 품질에 큰 영향이 없는 단계들을 통합하고, 프로그래밍 언어를 먼저 판별하여 해당 언어에 맞는 프롬프트를 선택하는 단계를 추가하여 최종적으로 아래와 같은 3단계 워크플로를 완성했습니다.
비록 팀원 수는 적었지만, 프롬프트 엔지니어링 담당과 기능 구현 담당의 역할을 나누어 긴밀하게 협업한 덕분에, 계획된 일정에 맞춰 '테크니컬 라이터의 노하우가 담긴 API 주석 자동 생성 및 문서 배포기' 프로토타입을 완성할 수 있었습니다.
3. 프로토타입 시연: 사내 컨텍스트를 이해하는 AI
프로토타입은 개발자에게 친숙한 UX를 제공하기 위해 VS Code Chat 익스텐션 형태로 만들었습니다. 사용법은 간단합니다.
- VS Code Chat 창에서
@doc으로 저희 익스텐션을 호출합니다. /generate명령을 실행하면, 현재 열려 있는 파일 또는 선택한 코드 블록에 대한 API 문서용 주석을 자동으로 생성해 줍니다.- 개발자는 생성된 주석의 정확성을 검토하고 수정합니다.
/publish명령을 실행하면, 주석을 기반으로 웹 문서를 생성하여 배포하고, 해당 문서의 링크를 알려줍니다.
개발자 입장에서는 소스 파일을 열고 명령어 몇 번만 입력하면, 누구나 접근 가능한 API 문서를 손쉽게 만들 수 있게 된 것입니다.
과연 사내 컨텍스트를 잘 이해할까요?
아래는 이 글을 위해 만든 예시 함수입니다. 여기서 MID는 저희 회사 내부에서 사용자 정보와 연결되는 고유 식별자로 사용되는 용어입니다.
const findInfoByMid = (mid) => {
const uid = getUidById(mid);
if (uid) {
return { name: getName(mid), detailedInfo: getDetailedInfo(mid, uid) };
}
return null;
};일반적인 코딩 어시스턴트(예: GitHub Copilot)의 결과:
범용 AI는 MID가 사내에서 어떤 의미로 쓰이는지 알지 못합니다. 따라서 코드의 맥락을 유추하여 'Member ID' 또는 심지어 'Machine ID'와 같은 일반적인 약어로 해석하여 주석을 생성합니다.
/**
* Finds and returns information for a given MID.
*
* @param {string} mid - The MID (Member ID) to look up.
* @returns {{ name: string, detailedInfo: any } | null} An object containing the name and detailed information if found, otherwise null.
*/저희가 만든 주석 생성기의 결과:
반면, 저희 주석 생성기는 사내 컨텍스트를 학습했기 때문에, MID가 단순한 약어가 아니라 사용자 정보와 연결되는 고유 식별자라는 것을 정확히 이해하고 주석을 작성합니다.
/**
* Retrieves detailed information using a given identifier.
* This function obtains a UID and returns an object with properties or null if no uid exists.
*
* Ensure that getUidById, getName, and getDetailedInfo are defined and functional. Use a valid MID.
*
* @param {*} mid - The unique identifier (MID) to retrieve the corresponding user information.
* @returns {Object|null} An object with properties `name` and `detailedInfo`, or null if no uid is found.
*
* @ai-doc
*/이렇게 '사내 컨텍_스트를 반영한' 문서를 만든다는 초기 목표를 달성할 수 있었습니다. /publish 명령을 통해 배포된 웹 문서는 아래와 같은 모습입니다.
4. VS Code 익스텐션에서 MCP(Multi-IDE Chat Panel)로의 전환
프로토타입 개발 후 사내 개발자들을 대상으로 테스트를 진행하면서 "VS Code 말고 IntelliJ에서도 쓸 수 없나요?"라는 질문을 많이 받았습니다. 문서화뿐만 아니라 다른 AI 활용 프로젝트에서도 IntelliJ 사용자들의 수요가 높다는 것을 알게 되었죠.
마침 JetBrains의 Junie나 GitHub Copilot 등 주요 AI 코딩 어시스턴트들이 특정 IDE에 종속되지 않고 범용적으로 작동할 수 있는 MCP(Multi-IDE Chat Panel)를 지원하기 시작했습니다. 저희는 특정 IDE에 의존하는 솔루션보다, MCP 서버를 구축하여 범용성을 확보하는 것이 장기적으로 더 나은 방향이라는 결론을 내렸습니다.
MCP 아키텍처로 전환하면서 얻은 이점은 명확했습니다.
- 기능 집중: MCP 서버는 MCP 클라이언트(각 IDE의 채팅 패널)와만 통신하면 되므로, UI 구현에 신경 쓰지 않고 핵심 기능 개발에만 집중할 수 있었습니다. (사용자가 어떤 코드를 선택했는지, 어떤 언어로 주석을 생성할지 등의 문제는 MCP 호스트가 처리)
- 개발 공수 절감: VS Code 익스텐션을 만들 때 UI 구현에 들었던 상당한 품을 줄일 수 있었고, 일부 기능은 MCP 호스트로 위임할 수 있었습니다.
- 사용자 경험 통일: 사용자는 이미 익숙해진 채팅 방식의 AI 인터페이스를 통해 저희 기능을 사용할 수 있게 되었습니다.
5. AI는 완벽하지 않은, 그러나 유용한 동반자
그렇다면 AI가 쓴 API 레퍼런스는 과연 얼마나 쓸 만할까요? 저희는 자체적으로 마련한 평가 기준표를 바탕으로 LLM을 통해 결과물을 평가해 보았습니다.
- 전체 주석의 88%가 평가 기준을 만족.
- API 개수 기준으로 78%가 일반 코딩 어시스턴트로 생성한 주석보다 우수.
이 정도면 충분히 써볼 만한 결과입니다. 하지만 100%가 아니라는 점이 중요합니다. 실제로 API 담당 개발자가 내용을 상세히 검토해 보니, 미묘하게 틀린 정보가 일부 포함되어 있었습니다.
이 프로젝트를 통해 AI에 대해 다시 한번 깨닫게 된 점이 있습니다.
첫째, AI는 '정확성'이 아닌 '확률'을 기반으로 작동합니다.
알고리즘이 100%의 정확도를 기본 전제로 시간과 공간 복잡도를 줄이는 것을 목표로 한다면, AI는 정답일 확률을 높이는 것을 목표로 합니다. 100줄짜리 블로그 글에서 한두 줄 틀린 내용은 애교로 넘어갈 수 있지만, 한두 줄이 전부인 API 레퍼런스에서 한 줄이 틀리면 그 문서는 쓸모가 없어집니다. 그 API를 보는 사용자에게는 100% 틀린 정보가 되니까요.
둘째, AI는 지시를 따를 줄은 알지만, 예외 상황을 스스로 판단하지는 못합니다.
예를 들어 '범위를 명시해'라는 지시에, 굳이 범위를 지정할 필요가 없는 파라미터에도 어떻게든 범위를 만들어 붙이려고 합니다. AI의 속내를 훤히 들여다볼 수 없는 이상, 언제나 100% 신뢰할 수는 없습니다.
결론적으로, 아직은 AI에게 온전히 일을 맡길 수 없습니다.
AI의 역할은 '내가 할 일을 0으로 만들어 주는 것'이 아니라, '내가 1시간 걸려 할 일을 10분 만에 끝내도록 도와주는 것'입니다.
그 10분은 AI가 생성한 결과물을 사람이 직접 검토하고 수정하는 시간일 테고요. AI는 완벽한 대체재가 아닌, 우리의 생산성을 극대화해 주는 강력한 '조수'이자 '동반자'입니다.
마무리하며: 변화에 적응하는 새로운 문서화의 시대
ChatGPT가 처음 등장했을 때, 많은 사람들이 AI가 자신의 직무를 대체할까 봐 불안해했습니다. 기술 문서 분야 역시 마찬가지였죠.
하지만 AI는 경쟁자가 아닙니다. 오히려 테크니컬 라이터는 (개발자 대신) AI가 더 나은 글을 쓰도록 가르치고 프롬프트를 설계하며 전문성의 외연을 확장할 수 있습니다. 문서 엔지니어는 (개발자 대신) AI가 대량으로 생성한 문서의 품질을 자동으로 검토하고, 반복되는 문제점을 찾아 해결하는 시스템을 만들 수 있습니다. 혹은, AI가 만든 문서를 다시 AI가 읽고 또 다른 문서를 생성하도록 하는 더 큰 그림을 그릴 수도 있을 테고요.
물론, 먼 미래에는 AI가 개발까지 모두 처리하여 기술 문서 자체가 필요 없는 세상이 올지도 모릅니다. 하지만 그때는 또 그 세상에 맞는 새로운 적응 방법이 나타나겠죠.
변화는 필연적입니다. 중요한 것은 그 변화에 어떻게 적응하느냐 하는 우리의 선택입니다. 저는 AI와 함께, 새로운 문서화의 시대를 개척하고 그 가능성을 계속해서 탐색해 나갈 예정입니다.
긴 글 읽어주셔서 감사합니다. 😊
