서버 코드 자동 생성 툴 — Sherpa는 왜 완전 자동화를 선택하지 않았을까

핵심 내용

• Sherpa는 연동사 API 문서를 바탕으로 서버 코드와 마크다운을 자동 생성하는 도구
• 완전 자동화보다 검증 가능성과 재실행 가능성을 중시해 HTML을 기준 진리로 삼고, 변환 파이프라인을 분리
• 검증 뷰어로 사람의 역할을 검수자에서 자동화 판단자로 전환

구조와 흐름

• 문서 원본을 HTML로 재현해 기준 데이터 확보
• HTML 분류, API 단위 마크다운 생성, 위치 정보 인덱스 생성으로 단계 분리
• 검증된 마크다운을 입력으로 API Client 코드 생성

선택 이유

• 마크다운 생성 단계의 누락과 옵션 설명 누락 문제 누적
• PDF를 바로 마크다운으로 바꾸는 방식은 누락 지점 추적과 원본 대비 검증이 어려움
• LLM 컨텍스트 한계와 장애 추적 가능성을 고려한 설계

주의할 점

• 특정 표현 방식 의존 시 작은 UI 변경에도 파이프라인 붕괴 가능성
• 원본과 결과를 비교할 기준이 없으면 운영 자동화 적용 어려움
• 자동 생성 결과의 신뢰성 확보를 위한 구조적 검증 필요