AI와 글쟁이의 동행: 코드 주면 API 레퍼런스 써드려요 (새 탭에서 열림)
기술 문서 부족 문제를 해결하기 위해 엔지니어링 관점에서 접근한 이 글은, 생성형 AI를 활용해 사내 기술 컨텍스트와 스타일 가이드가 반영된 API 레퍼런스를 자동 생성하는 프로젝트 과정을 소개합니다. 일반적인 코딩 어시스턴트의 한계를 극복하기 위해 프롬프트 워크플로를 최적화하고, 특정 IDE에 종속되지 않도록 MCP(Model Context Protocol)를 도입하여 범용성을 확보했습니다. 최종적으로 AI가 생성한 결과물은 높은 품질을 보였으나, 기술 문서의 특성상 정확성을 담보하기 위한 인간의 검토 단계가 필수적임을 강조하며 결론을 맺습니다. ## 기존 AI 도구의 한계와 도큐먼트 엔지니어링의 목표 * 기술 문서는 항상 부족하며, 개발자 교육만으로는 시간과 관심의 부재라는 근본적인 원인을 해결하기 어렵다는 판단하에 자동화 프로세스를 구축했습니다. * GitHub Copilot과 같은 기존 도구는 코드 파악 능력은 뛰어나지만, 사내 전용 기술 용어나 특수한 스타일 가이드, 프로젝트별 컨텍스트를 반영하지 못하는 단점이 있습니다. * '사내 정보를 참고해 스타일 가이드에 맞는 API 주석을 작성하고, 이를 한곳에서 배포하기'를 목표로 테크니컬 라이터의 노하우를 자동화 공정에 이식했습니다. ## 프롬프트 최적화와 단계별 워크플로 구성 * 초기에는 방대한 지시 사항이 담긴 긴 프롬프트를 사용했으나, LLM이 복잡한 지시를 놓치는 문제가 발생하여 실행 단계를 세분화했습니다. * 처리 속도와 정확도 사이의 타협점을 찾기 위해 '프로그래밍 언어 인식', 'API 파악 및 예제 작성', '설명 및 파라미터/응답 값 작성'의 3단계 워크플로로 압축했습니다. * LINE의 고유 식별자인 'MID'를 단순한 약어(Member ID 등)로 오해하지 않고 사내 정의에 맞게 설명하도록 컨텍스트를 주입하여 일반 AI 도구와 차별화된 품질을 구현했습니다. ## 범용성 확보를 위한 MCP(Model Context Protocol) 도입 * 초기 프로토타입은 VS Code 익스텐션으로 제작했으나, IntelliJ 등 다양한 IDE를 사용하는 개발자들의 요구를 수용하기 위해 MCP 기반으로 전환했습니다. * MCP 서버는 클라이언트와의 통신에만 집중하므로, UI 구현에 드는 비용을 줄이고 언어 판별이나 코드 블록 선택 같은 부가 기능을 MCP 호스트(IDE 등)에 위임할 수 있습니다. * 사용자가 AI와 대화하며 파라미터를 입력하는 방식은 현대적인 AI 사용 경험에 부합하며, 특정 도구에 종속되지 않는 범용적인 문서화 솔루션을 제공합니다. ## AI 문서화의 성과와 실질적인 한계 * 자체 평가 결과, 생성된 주석의 88%가 기준을 만족했으며 78%의 사례에서 GitHub Copilot보다 우수한 품질의 설명을 생성하는 성과를 거두었습니다. * 그러나 AI는 확률 기반으로 작동하므로 100%의 정확성을 보장하지 못하며, 단 한 줄의 오류가 문서 전체의 신뢰도를 떨어뜨리는 API 레퍼런스의 특성상 위험 요소가 존재합니다. * 따라서 AI를 '완벽하지 않은 동반자'로 정의하고, AI가 초안을 대량으로 빠르게 생산하되 마지막 단계에서는 반드시 담당 개발자가 내용을 검토하는 '사람 중심의 검증' 프로세스를 권장합니다.