Claude Code로 레거시 API 문서화 자동화하기

문제 상황

회사의 레거시 결제 API 서버는 2022년에 작성된 이후 문서 업데이트가 제대로 이루어지지 않았다. Swagger 문서와 실제 엔드포인트가 달라서 프론트엔드 팀에서 불만이 많았고, 새로 합류한 개발자들이 코드를 이해하는 데 시간이 오래 걸렸다.

수동으로 문서를 작성하자니 150개가 넘는 엔드포인트를 일일이 확인해야 했다. 이때 Claude Code의 코드베이스 분석 능력을 활용하기로 했다.

접근 방법

Claude Code에게 프로젝트 전체를 컨텍스트로 제공하고, Express 라우터 파일들을 순차적으로 분석하도록 했다. 단순히 문서만 생성하는 게 아니라, 실제 요청/응답 타입을 TypeScript 인터페이스에서 추출하고 검증 로직까지 확인하도록 프롬프트를 구성했다.

// Claude Code에게 제공한 작업 예시
// routes/payment.ts 분석 → OpenAPI 스펙 생성
// - 경로, 메서드 추출
// - Joi/Zod 스키마에서 요청 바디 타입 파싱
// - 응답 타입 추론 (명시적 타입이 없으면 실제 return 분석)

구현

MCP(Model Context Protocol)를 활용해 Git 히스토리도 함께 분석했다. 최근 수정된 엔드포인트를 우선 처리하고, deprecated된 API는 별도로 마킹했다.

결과물은 OpenAPI 3.1 스펙으로 출력했고, 이를 Redoc으로 렌더링해 팀 내부 문서 사이트에 배포했다. 전체 작업에 약 4시간이 걸렸는데, 수동으로 했다면 최소 일주일은 필요했을 것이다.

배운 점

Claude Code는 단순 코드 생성을 넘어 대규모 코드베이스 분석과 문서화에 강점이 있었다. 다만 100% 정확하진 않아서, 생성된 문서를 실제 Postman 컬렉션과 대조 검증하는 스크립트를 별도로 작성했다.

앞으로는 CI/CD에 문서 검증 단계를 추가해, 코드 변경 시 자동으로 문서가 업데이트되는지 체크하려고 한다.