API 레퍼런스를 자동 생성할 때 어려운 부분은 코드 설명 자체보다 용어·형식·검증 기준을 일관되게 유지하는 일입니다. 이 글에서는 사내 스타일 가이드와 용어 정보를 활용해 주석을 생성하고, 검토 후 문서로 배포하는 프로토타입을 정리합니다.
코드에서 확인할 수 없는 제약이나 동작을 만들어내지 않고, 생성 결과를 검토 가능한 초안으로 제공하는 것이 핵심입니다.
1. 생성형 AI로 API 레퍼런스 만들기: 왜 또 다른 도구가 필요한가?
최근 많은 기업들이 업무에 생성형 AI를 적극적으로 도입하고 있으며, 저희 역시 주요 개발 단계에서 AI를 활용하는 프로젝트에 참여하게 되었습니다. 그중 저희 팀이 맡은 과제는 바로 '문서화'였습니다.
수많은 문서 유형 중, 우리는 개발 단계에서 가장 필요하고, 소스 코드를 기반으로 생성할 수 있으며, 개발자와 사용자 모두에게 직접적인 영향을 미치는 API 레퍼런스 문서를 첫 번째 타겟으로 삼았습니다.
"잠깐만요, GitHub Copilot 같은 코딩 어시스턴트가 이미 코드 설명은 잘해주고 있잖아요?" 라는 의문이 드실 수 있습니다. 맞습니다. 하지만 기존 코딩 어시스턴트만으로는 해결하기 어려운 몇 가지 중요한 문제들이 있었습니다.
- 사내 스타일 가이드 미준수: 기업마다 고유의 기술 문서 스타일과 톤앤매너가 있지만, 별도 지침과 예시를 제공하지 않으면 기대한 형식을 얻기 어렵습니다.
- 사내 기술 및 컨텍스트 부재: 사내에서만 통용되는 용어, 기술 스택, 비즈니스 로직에 대한 이해가 없어 엉뚱한 설명을 만들어냅니다.
- 일관성 부족: 동일한 코드에 대해서도 질문할 때마다 다른 스타일과 내용의 설명을 생성합니다.
- 파편화된 문서 형식 및 배포 위치: 프로젝트마다 API 문서의 형식(예: Swagger, Javadoc, 자체 마크다운)과 배포 위치가 달라, 개발자들이 참고하고 관리하기 어렵다는 내부 의견도 있었습니다.
따라서 저희 프로젝트의 목표는 명확해졌습니다.
"사내 정보를 생성 입력에 제공하여, 사내 스타일에 맞는 API 주석을 자동으로 작성하고, 이를 표준화된 레퍼런스 문서로 만들어 한곳에서 통합 배포하자!"
2. 최적의 결과물을 위한 프롬프트와 워크플로 설계
저희 팀은 이미 기술 문서 검토, 다국어화, 스타일 일관성 검증 등에 AI를 활용하며 프롬프트 엔지니어링 경험을 쌓아왔습니다. 사내 스타일 가이드에 맞춰 일관된 결과물을 얻으려면 꽤 길고 상세한 프롬프트가 필요합니다. 여기에 프로그래밍 언어별 API 주석 작성법과 사내 용어 정보까지 더했더니, LLM이 몇몇 중요한 지시를 놓치기 시작했습니다. 입력 길이와 지시 간 충돌, 필요한 근거의 누락을 함께 점검할 필요가 있었습니다.
사내 머신러닝 전문가의 조언에 따라, 우리는 하나의 거대한 프롬프트를 여러 개의 작은 단계로 나누고, 각 단계별로 최적화된 프롬프트를 순차적으로 실행하는 워크플로를 설계하기로 했습니다.
처음에는 아래와 같이 세세하게 단계를 나누었습니다.
- API 전체 설명 작성
- 파라미터 설명 작성
- 응답 값(리턴) 설명 작성
- 예제 코드 작성
- 추가 정보(주의사항 등) 작성
과연, 단계를 나누니 한 번에 요청하는 것보다 훨씬 정확하고 상세한 설명을 얻을 수 있었습니다. 하지만 단계가 길어질수록 처리 시간이 오래 걸리는 단점이 있었죠. 결국, 결과물의 품질과 처리 시간 사이에서 적절한 타협점을 찾아야 했습니다.
여러 테스트를 거쳐, 결과물의 품질에 큰 영향이 없는 단계들을 통합하고, 프로그래밍 언어를 먼저 판별하여 해당 언어에 맞는 프롬프트를 선택하는 단계를 추가하여 언어에 맞는 생성·검토·배포 흐름으로 정리했습니다. 언어별 프롬프트 선택은 생성 전에 수행하고, 파라미터·반환값·예제 검증은 검토 단계의 항목으로 묶어 볼 수 있습니다.
비록 팀원 수는 적었지만, 프롬프트 엔지니어링 담당과 기능 구현 담당의 역할을 나누어 긴밀하게 협업한 덕분에, 계획된 일정에 맞춰 '테크니컬 라이터의 노하우가 담긴 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;
};사내 용어 정보를 제공하지 않은 출력 예시:
코드만으로 MID의 사내 의미를 확정할 수는 없습니다. 아래는 이를 'Member 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
*/용어를 반영했더라도 위 주석을 그대로 승인할 수는 없습니다. @param {*} 은 허용 타입을 설명하지 못하며, 보조 함수들의 반환 타입과 예외 계약도 원문 코드에서 확인되지 않습니다. if (uid)는 0이나 빈 문자열도 없는 값처럼 처리합니다. 어떤 UID가 유효한지는 실제 계약을 확인해야 합니다. 문서가 코드보다 더 강한 보장을 주장하지 않는지 검토해야 하는 이유입니다.
4. VS Code 익스텐션에서 MCP(Model Context Protocol)로의 전환
프로토타입 개발 후 사내 개발자들을 대상으로 테스트를 진행하면서 "VS Code 말고 IntelliJ에서도 쓸 수 없나요?"라는 질문을 많이 받았습니다. 문서화뿐만 아니라 다른 AI 활용 프로젝트에서도 IntelliJ 사용자들의 수요가 높다는 것을 알게 되었죠.
MCP는 Model Context Protocol의 약자이며, AI 애플리케이션과 도구·데이터 제공 서버가 통신하는 프로토콜입니다. 특정 IDE의 채팅 패널을 뜻하지 않습니다. 호스트가 사용자 상호작용과 권한을 관리하고, 호스트 안의 클라이언트가 서버에 연결합니다. 서버는 주석 생성 같은 기능을 도구로 노출할 수 있습니다. MCP 아키텍처 명세
이 구조를 사용하면 여러 MCP 호스트에서 같은 서버 기능을 활용할 수 있습니다. 다만 선택한 코드나 파일이 서버에 자동 전달되는 것은 아닙니다. 도구 입력 스키마를 정하고, 각 호스트가 어떤 컨텍스트를 제공하는지 확인해야 합니다. 인증·권한·오류 처리와 배포 확인 절차도 별도로 설계합니다.
MCP 아키텍처로 전환하면서 얻은 이점은 명확했습니다.
- 기능 집중: MCP 서버는 MCP 클라이언트(각 IDE의 채팅 패널)와만 통신하면 되므로, UI 구현에 신경 쓰지 않고 핵심 기능 개발에만 집중할 수 있었습니다. (단, 코드와 언어 정보를 전달하는 방식은 호스트와 도구 입력 계약으로 명시)
- 개발 공수 절감: VS Code 익스텐션을 만들 때 UI 구현에 들었던 상당한 품을 줄일 수 있었고, 일부 기능은 MCP 호스트로 위임할 수 있었습니다.
- 사용자 경험 통일: 사용자는 이미 익숙해진 채팅 방식의 AI 인터페이스를 통해 저희 기능을 사용할 수 있게 되었습니다.
5. 생성 품질을 검증하는 기준
초기 평가 기록에는 “전체 주석의 88%가 기준을 만족”, “API의 78%에서 비교 출력보다 우수”라는 값이 있었습니다. 하지만 이 글에는 표본 수, 모델·프롬프트 버전, 채점 기준과 사람의 교차 검증 결과가 공개되어 있지 않습니다. 따라서 이 수치를 일반적인 정확도나 제품 간 성능 순위로 해석하지 않습니다. LLM을 이용한 평가는 후보를 분류하는 데 활용하고, 실제 API 계약은 코드와 테스트로 확인해야 합니다.
| 검토 항목 | 확인할 근거 |
|---|---|
| 파라미터 타입·필수 여부 | 타입 선언, 입력 검증 코드 |
| 반환값·null 가능성 | 모든 반환 경로와 호출 계약 |
| 예외·오류 응답 | 예외 처리 코드와 실패 테스트 |
| 인증·권한·부작용 | 호출 경로와 권한 검사, DB·외부 호출 |
| 예제 코드 | 해당 버전에서 실행되는 테스트 |
| 문서 형식 | 스타일 가이드와 문서 빌드 결과 |
코드만으로 확인할 수 없는 값의 범위나 비즈니스 규칙은 “확인 필요”로 남깁니다. 생성한 주석이 컴파일된다고 설명까지 정확한 것은 아니며, 스타일 점수가 높다고 API 계약이 검증된 것도 아닙니다.
문서를 코드 변경과 함께 유지하기
자동 생성의 가치는 초안을 만드는 시간을 줄이고 검토 대상을 일정한 형식으로 제공하는 데 있습니다. 변경된 API와 문서를 같은 검토 흐름에 넣고, 예제 테스트와 문서 빌드가 통과한 결과를 배포하는 편이 유지보수에 도움이 됩니다.
사내 코드와 용어를 외부 모델에 전달하는 구성이라면 승인된 처리 범위와 보관 정책을 확인해야 합니다. 배포 도구는 문서의 공개 범위를 명시하고 검토된 결과만 반영하도록 구성합니다. 이렇게 해야 주석 생성 속도와 문서의 신뢰성을 함께 관리할 수 있습니다.
