코드베이스에서 API 문서 생성하기

API 문서는 항상 잘못되어 있다

패턴을 알고 있죠. 누군가 백엔드가 출시될 때 API 문서를 작성합니다. 세 번의 스프린트 후, 두 개의 엔드포인트가 변경되었고, 새로운 쿼리 매개변수가 생겼으며, /tags의 응답 형태에 아무도 문서화하지 않은 추가 중첩 객체가 있습니다. 위키 페이지는 여전히 v1이라고 적혀 있습니다. Postman 컬렉션은 10월의 것입니다. 프론트엔드 팀은 API가 실제로 반환하는 내용을 파악하기 위해 당신의 컨트롤러를 역공학하고 있습니다.

이건 도구 문제도 아니고, 신선도 문제입니다. 수작업으로 작성된 문서는 코드가 변경되는 순간 쇠퇴합니다. 그리고 어떤 팀도 라우트 핸들러를 수정하거나 인터페이스에 필드를 추가할 때마다 문서를 업데이트할 만큼의 규율을 가지고 있지 않습니다. 결과적으로, 당신의 프론트엔드 개발자들은 백엔드 코드를 직접 읽고, Slack에서 질문을 하거나 — 더 나쁜 경우 — 잘못된 가정에 기반한 통합을 배포하고 있습니다.

개발자가 NestJS 백엔드를 몇 분 만에 문서화한 방법

한 개발자는 NestJS 백엔드에서 라벨과 카테고리가 모바일 앱으로 어떻게 흐르는지 이해할 필요가 있었습니다. 그들은 에이전트에게 물었습니다: “우리가 라벨과 카테고리를 프론트엔드로 어떻게 보내는지 — 어떤 컨트롤러, 어떤 라우트, 어떤 인터페이스인지 알려줘.” 에이전트는 백엔드 리포지토리를 복제하고, TrendAgents 컨트롤러를 찾아 ITag 인터페이스 정의를 읽고, 엔드포인트, 매개변수, 응답 유형 및 데이터 흐름을 포함한 완전한 API 계약을 생성했습니다.

수동 코드 읽기 없이. 파일을 grep할 필요 없이. 에이전트는 컨트롤러에서 인터페이스, 응답 형태로 가는 실제 코드 경로를 추적하고 모든 단계를 문서화했습니다. 개발자는 라우트, HTTP 메서드, 예상 매개변수 및 응답 본체를 정의하는 TypeScript 인터페이스를 보여주는 구조화된 계약을 받았습니다. 모두 프로덕션에서 실행 중인 소스 코드에 기반한 것입니다.

문서에서 GitHub 이슈로 한 번의 대화로

같은 개발자가 이렇게 말했습니다: “프론트엔드에서 새로운 로직을 구현할 수 있도록 /tags 라우트에 대한 API 계약을 준비해줘.” 에이전트는 구조화된 API 계약 문서를 생성했고, 개발자는 이를 모바일 팀을 위한 GitHub 이슈에 직접 첨부했습니다. 프론트엔드 개발자들은 백엔드 코드를 읽을 필요가 없었습니다.

이게 API 문서를 유용하게 만드는 워크플로우입니다. 계약은 실제로 구현 팀이 작업하는 이슈 트래커에 들어갑니다. 그들이 절대 확인하지 않을 위키 페이지가 아닙니다. 스크롤되는 Slack 메시지가 아닙니다. 정확한 엔드포인트, 매개변수 및 응답 유형이 포함된 GitHub 이슈 — 구현할 준비가 되어 있습니다. LikeClaw의 GitHub 통합은 이를 단일 대화로 만듭니다: 문서 생성, 이슈 생성, 팀 할당.

특정 파일에서 엔드포인트 문서화

다른 개발자는 개인 리포지토리에서 특정 파일 — TrendAgents.controller.ts 및 model/ITag.ts — 를 가져와 에이전트에게 엔드포인트 동작을 문서화해달라고 요청했습니다. 에이전트는 TypeScript 코드를 읽고, 컨트롤러 메서드에서 서비스 계층을 거쳐 인터페이스 정의까지의 데이터 흐름을 추적하고, 실제 구현과 일치하는 문서를 생성했습니다.

이 접근 방식은 어떤 파일이 중요한지 이미 알고 있을 때 효과적입니다. 에이전트를 특정 컨트롤러 및 모델 파일에 지정하면 타겟 문서를 생성합니다. 하나의 엔드포인트 그룹에 대한 문서만 필요하다면 전체 리포를 복제할 필요가 없습니다. 에이전트는 제공된 코드를 읽고 발견한 내용을 문서화합니다 — 데코레이터, 라우트 매개변수, 미들웨어, 반환 유형 및 오류 처리 패턴.

문서화를 위한 샌드박스 리포 접근이 중요한 이유

AI 에이전트에게 개인 리포지토리에 대한 접근 권한을 부여할 때, 그 코드가 실행되는 위치가 중요합니다. 에이전트는 당신의 리포를 복제하고, 소스 파일을 읽고, 타입과 종속성을 해결하기 위해 빌드 도구를 실행할 수 있습니다. 만약 이 작업이 로컬 머신에서 원시 시스템 접근으로 이루어진다면, 당신은 에이전트가 하는 모든 일에 전체 개발 환경을 노출하게 됩니다.

Snyk의 연구에 따르면 오픈 소스 AI 도구 레지스트리에서 341개 이상의 악성 패키지가 발견되었습니다. LikeClaw는 모든 문서화 작업을 E2B 샌드박스 컨테이너에서 실행합니다. 당신의 리포는 샌드박스 내부에 복제됩니다. 에이전트는 샌드박스 내의 코드를 읽습니다. 작업이 완료되면 샌드박스는 파괴됩니다. 당신의 로컬 머신, SSH 키, 다른 리포지토리 — 그 어떤 것도 노출되지 않습니다.

당신의 자격 증명은 암호화되어 샌드박스 세션에 국한됩니다. 작업 간의 수평 이동 없음. 완료 후 지속성 없음.

단일 엔드포인트 문서를 넘어서

진짜 힘은 전체 백엔드 또는 여러 서비스에 걸쳐 API를 문서화해야 할 때 나타납니다. 베타 사용자들로부터의 일반적인 패턴:

• 전체 API 목록: “이 Express 앱의 모든 엔드포인트를 메서드, 경로 및 핸들러 함수와 함께 나열해줘.” 에이전트는 라우트 트리를 탐색하고 완전한 목록을 생성합니다.
• 서비스 간 계약: 에이전트를 API 게이트웨이와 두 개의 하위 서비스에 지정합니다. 요청이 각 레이어를 통해 흐르는 방식을 추적하고 모든 경계에서 계약을 문서화합니다.
• 마이그레이션 문서화: “v1과 v2 엔드포인트를 비교하고 변경된 내용을 문서화해줘.” 에이전트는 두 버전을 읽고 diff 스타일의 마이그레이션 가이드를 생성합니다.
• 스키마 추출: “API 응답에 사용된 모든 TypeScript 인터페이스를 추출하고 스키마 문서를 생성해줘.” 에이전트는 라우트 핸들러에서 참조된 모든 인터페이스를 수집하고 하나의 구조화된 파일로 출력합니다.

이것은 LikeClaw의 코드베이스 분석 기능과 자연스럽게 결합됩니다. 먼저 아키텍처를 분석하여 시스템을 이해한 후, 중요한 엔드포인트에 대한 타겟 API 문서를 생성합니다. 두 작업 모두 동일한 안전한 샌드박스에서 실행되며, 결과는 참조를 위해 작업 공간에 지속됩니다.

이 문서가 필요한 사람

Slack에서 “이 엔드포인트는 무엇을 반환하나요?“라는 질문에 지친 백엔드 개발자들. API 계약을 프론트엔드 또는 모바일 팀에 전달해야 하지만 회의를 잡기 싫은 팀 리더들. 다른 팀을 위해 내부 API를 문서화하는 플랫폼 엔지니어들. 회사 위키에서 API 문서를 검색하다가 8개월 전에 업데이트된 페이지를 찾았던 모든 사람들.

설정 필요 없음. 예측 가능한 가격. 실제 코드에서 생성된 문서, 기억에서가 아닙니다.