AI 기반 API 레퍼런스 자동화 시스템 구축

1. 프로젝트 목표 및 동기

• 기술 문서 부족 문제 해결을 위해 생성형 AI를 활용한 문서 엔지니어링 접근 방식 도입.
• 기존 코딩 어시스턴트의 한계(사내 스타일/컨텍스트, 일관성 부족) 극복을 목표로 설정.
• 사내 스타일 가이드에 맞춰 API 주석을 작성하고, 이를 중앙 집중식으로 배포하는 시스템 구축.

2. 워크플로우 설계 및 구현

• 초기 다단계 프롬프트의 비효율성을 개선하여 3단계 워크플로우로 최적화:
  • 프로그래밍 언어 인식: 코드의 언어 식별.
  • API 파악 및 추가 정보/예제 코드 작성: 내부 컨텍스트 기반 정보 생성.
  • API 설명, 파라미터, 응답 값 설명 작성: 상세 주석 생성.
• VS Code Chat 익스텐션 기반 프로토타입 개발: @doc /generate로 주석 생성 (예: Swagger 어노테이션), @doc /publish로 웹 문서 배포.
• MCP (Multi-platform Protocol) 전환을 통해 다양한 IDE (예: IntelliJ, GitHub Copilot 익스텐션) 지원 및 범용성 확보.
• MCP 호스트가 UI/UX 및 코드 블록 선택 등을 처리, 개발팀은 핵심 기능 구현에 집중 가능.

3. AI 기반 문서화의 한계와 역할

• AI 생성 문서의 정확성 문제: 88% 만족, GitHub Copilot 대비 78% 우수하나 100% 보장 불가.
• 짧은 API 레퍼런스에서 작은 오류도 문서의 유용성을 크게 저해.
• AI는 지시를 따르지만 예외 상황을 판단하지 못하여 불필요한 정보 삽입 가능성.
• 결론적으로 AI는 생산성 향상 도구이며, 사람의 최종 검토 및 수정이 필수적.
• AI의 역할은 '일을 0으로 만드는 것'이 아닌 '1시간 걸릴 일을 10분으로 단축'하는 것.