Doc Creator (KIPO 문서 자동 생성 도구)

출발점

풀스택 프로젝트의 클라이언트와 서버 소스를 함께 분석해 KIPO 표준 산출물 8종을 만들어야 했다. 한 번의 프롬프트에 전체 소스를 넣으면 입력 한계를 넘거나 뒤쪽 지시가 누락됐다. 여러 문서를 순서대로 만들 때는 같은 API·컴포넌트가 문서마다 다른 이름으로 기록됐고, 한 단계가 실패하면 처음부터 다시 실행해야 했다. 생성된 Mermaid 코드의 문법 오류도 PDF·PPTX 변환을 막았다.

맡은 일

1인 개발자로서 요구사항 분석부터 문서별 입력 선별, LLM 프롬프트, 중간 JSON 저장, 결과 병합, HTML/PDF/PPTX 렌더링까지 파이프라인을 설계·구현했다. 핵심 목표는 문서 간에는 같은 기준을 쓰고, 각 문서의 실행과 복구는 독립시키는 것이었다.

요구사항을 먼저 고정하고 문서별로 분석

요구사항 명세서를 requirements_parser.txt로 분석해 output/usecase.json을 만들었다. 이 파일의 UC001 같은 ID를 아키텍처(DE11), 클래스(DE21), 컴포넌트(DE23), DB(DE33), 매뉴얼(TO13-2) 등 문서가 공통으로 참조하도록 했다. 문서마다 필요한 코드가 달라 전체 소스를 반복 주입하지 않고, .gitignore를 반영한 문서별 파일리스트로 입력 범위를 좁혔다.

큰 입력은 Map-Reduce로 처리

코드를 최대 250,000자 단위로 나눠 주입했다. 특히 DE21은 첫 청크에서 시스템 개요와 전체 다이어그램을 만들고, 후속 청크는 classes-only로 신규 클래스만 수집했다. 각 응답의 chunk_meta(Part i/n)로 범위를 확인한 뒤 reduce_prompt.txt에서 설명을 합성하고, 중복 클래스·노드·엣지와 Mermaid classDef 선언을 정리했다.

렌더링 전에 오류를 걸러내고 결과를 분리 저장

문서별 결과를 output/json/에 독립 저장해 실패한 문서만 재생성할 수 있게 했다. 렌더링 전에는 JSON 필수 구조와 Mermaid의 제네릭 표기, 예약어, 특수문자 같은 오류 패턴을 검사·정규화했다. 통과한 데이터를 Jinja2 HTML, Playwright(Chromium) PDF, python-pptx PPTX로 일괄 출력했다.

전체 소스를 거대 컨텍스트 모델에 반복 투입하는 방식은 문서마다 불필요한 코드까지 비용을 지불해야 했다. 에이전트끼리 대화 내용을 직접 이어받는 방식은 앞선 오탐이 뒤 문서로 전파될 수 있었다. 요구사항 JSON과 문서별 체크포인트를 경계로 둔 이유다.

결과

• ▶클라이언트·서버가 분리된 실제 프로젝트에서 8종 JSON을 생성하고 HTML/PDF/PPTX까지 수동 코드 수정 없이 배치 출력했다.
• ▶해당 사례에서 수작업으로 45일 걸리던 문서 작성 흐름을 약 1215분의 배치 실행으로 전환했다. 실제 프로젝트의 문서 생성 작업을 기준으로 측정했다.
• ▶검증 배치에서는 Mermaid 문법 오류로 인한 PDF·PPTX 변환 실패가 0건이었다. 문서별 JSON 체크포인트 덕분에 실패한 문서만 다시 실행할 수 있었고, 개별 재실행 시간은 약 1~2분이었다.
• ▶유스케이스 ID를 여러 산출물에서 공통 식별자로 사용해 요구사항부터 설계서와 매뉴얼까지의 연결 관계를 추적할 수 있게 했다.

배운 점

컨텍스트 한계를 더 큰 모델로만 해결하려 하기보다, 기준 데이터를 먼저 고정하고 에이전트의 책임과 입력 범위를 좁히는 편이 재시도·비용·정합성 관리에 유리했다. LLM의 출력은 렌더러에 바로 넘기지 않고 구조와 구문을 확인해야 한다. 위 수치는 해당 프로젝트의 검증 범위에서 얻은 결과다.

1. 대규모 코드 분석에서 문서 간 명칭이 달라진 문제

상황: 클라이언트와 서버 코드를 한 세션에 누적하자 컨텍스트 한계로 뒤쪽 지시가 빠졌고, 앞선 문서의 추정이 다음 문서에 전파됐다. 같은 유스케이스의 컴포넌트와 API가 산출물마다 다른 이름으로 적힐 위험이 있었다.

해결: 요구사항을 먼저 usecase.json으로 고정하고 문서별 파일리스트를 따로 만들었다. DE21은 첫 청크에 개요를 맡기고 이후 청크에서는 신규 클래스만 수집했다. Reduce 단계에서 각 청크의 설명과 다이어그램을 통합했다.

결과: 문서마다 전체 코드를 다시 읽지 않고도 공통 UC ID를 기준으로 내용을 연결할 수 있었다. 청크별 중간 JSON이 남아 분석 누락이나 중복이 생긴 지점을 확인할 수 있었다.

2. Mermaid 문법 오류가 PDF·PPTX 생성까지 막은 문제

상황: LLM이 만든 다이어그램에 제네릭 꺾쇠괄호, 예약어 충돌, 특수문자, 중복 classDef 등이 섞여 렌더링 단계에서 실패했다. 프롬프트만 수정해서는 같은 유형의 오류가 다시 발생했다.

해결: JSON 구조와 필수 필드를 먼저 확인하고, Mermaid 코드를 규칙에 따라 정규화한 뒤 렌더러에 전달했다. 분할된 다이어그램은 Reduce에서 스타일 선언을 모으고 중복 노드와 엣지를 합쳤다.

결과: 실제 프로젝트의 회귀 검증에서 다이어그램 문법으로 인한 PDF·PPTX 변환 실패가 발생하지 않았다.

3. 한 문서의 실패가 전체 재실행으로 번진 문제

상황: 8종 문서를 연속 생성할 때 후반부 문서나 변환 단계에서 실패하면 앞서 끝난 분석까지 다시 호출해야 했다.

해결: 에이전트별 결과를 독립 JSON 체크포인트로 저장하고, JSON 생성과 다중 포맷 렌더링을 별도 단계로 나눴다. 오류가 난 문서의 JSON만 재생성하거나 기존 JSON에서 렌더링을 다시 시작하도록 실행 경계를 분리했다.

결과: 해당 사례에서 전체 파이프라인 재실행 없이 실패한 문서만 약 1~2분 내 재실행할 수 있었다.