기술 문서 자동 생성

코드 주석부터 API 문서부터 아키텍처 다이어그램까지 —— 코드 다 쓰고 문서가 나와요

문서라는 함정, 해본 사람은 알아요

문서는 항상 코드를 못 따라가

코드를 20번 바꿨는데, README는 여전히 3개월 전 버전이에요. 신입 입사해서 문서 따라 한 번 돌려보니 에러가 가득해요. 물어보면 "아, 그 문서는 더 이상 안 써"라고 해요.

아무도 문서를 쓰고 싶지 않아해요. 개발자는 "코드가 문서지"라고, 기획자는 "당신이 먼저 쓰면 봐줄게"라고 해요. 결국 아무도 안 써요. 입으로만 전해져요.

겨우 API 문서 작성했는데, 온라인에서 두 필드를 바꿨는데 동기화 까먹었어요. 프론트엔드 팀원이 옛날 문서 보면서 반나절을 낭비했어요. 나중에 따져요.

OpenClaw가 문서 처리를 다 해줄 거예요

코드를 읽고, 문서를 쓰고, 계속 동기화해요

OpenClaw가 당신의 소스 코드를 직접 읽어요 —— 함수 시그니처, 파라미터 타입, 반환값, 주석, 호출 관계, 다 분석해서 구조화된 문서를 생성해요.

"이 함수는 파라미터 하나를 받아요" 같은 허튼소리 문서가 아니에요. 각 인터페이스의 목적, 파라미터 설명, 반환 예제, 에러 코드, 다 있어요.

코드를 바꿨어? Prompt를 다시 돌려요. 문서가 자동으로 업데이트돼요. 문서와 코드 사이의 버전 지옥에서 벗어날 거예요.

문서 생성 Prompt, 바로 써요

README부터 API 문서부터 아키텍처 다이어그램까지. 3가지 Prompt로 다 해결돼요.

프로젝트 README 한 번에 생성 초보자 친화적
이 프로젝트의 완전한 코드 구조를 분석해서 전문적인 README.md를 만들어줄래.

이런 섹션들을 포함해줄래:
1. 프로젝트 소개: 이 프로젝트가 뭘 하는지 한두 줄로
2. 기능 특징: bullet points로 핵심 기능 나열
3. 빠른 시작: 설치, 설정, 실행 단계 (복사 붙여넣기하면 돼요)
4. 프로젝트 구조: 디렉토리 트리 + 각 디렉토리 간단 설명
5. 설정 설명: 환경 변수, 설정 파일 설명
6. API 간단 설명 (있으면)
7. 자주 묻는 질문

스타일: 간결하고 명확하게. 허튼소리 쓰지 말고. 코드 예제는 완전해서 돌릴 수 있어야 해요.
이 Prompt가 가장 좋아요. 한 번 돌려주면 괜찮은 README가 생겨요. 처음부터 수동으로 쓰는 것보다 10배 빨라요. 기존 프로젝트도 써먹을 수 있어요. 생성 후 조금 손수 수정하면 돼요.
API 인터페이스 문서 생성 골든 인스트럭션
프로젝트의 모든 API 라우팅/컨트롤러 파일을 읽어줘.

각 인터페이스마다 표준 API 문서를 생성해줄래 (Markdown 포맷):
1. 인터페이스 경로와 요청 방법 (GET/POST/PUT/DELETE)
2. 기능 설명: 이 인터페이스가 뭐 하는지
3. 요청 파라미터: 파라미터명, 타입, 필수 여부, 설명, 예제 값
4. 요청 본문 예제 (JSON 포맷)
5. 응답 예제: 성공 케이스와 실패 케이스
6. 에러 코드 설명
7. 인증 요구사항 (token 필요하면)

모듈별로 그룹화해서, 목차 네비게이션도 붙여줄래.
백엔드 개발은 이게 필수예요. 한 Prompt로 모든 인터페이스 문서가 생겨요. 프론트엔드 팀원이 또 "이 인터페이스 파라미터가 뭐야"라고 물어보는 일이 없을 거예요.
프로젝트 아키텍처 다이어그램 (Mermaid) 고급 기법
이 프로젝트의 완전한 코드 구조와 모듈 의존성 관계를 분석해줄래.

이런 Mermaid 다이어그램들을 생성해줄래:

1. 시스템 아키텍처 다이어그램 (flowchart):
   - 주요 모듈과 그들의 상호작용 관계 표시
   - 데이터 흐름 방향 표기
   - 프론트엔드, 백엔드, 데이터베이스, 써드파티 서비스 구분

2. 모듈 의존성 다이어그램 (flowchart):
   - 코드 모듈들의 import/의존 관계 표시
   - 핵심 모듈과 도구 모듈 표기

3. 데이터 흐름 다이어그램 (sequenceDiagram):
   - 핵심 비즈니스의 완전한 요청 체인 표시
   - 사용자 조작부터 데이터베이스거기 다 포함

각 다이어그램마다 텍스트 설명도 붙여서, 중요한 설계 결정을 설명해줄래.
아키텍처 다이어그램은 손으로 그리기가 가장 힘들어요. 이 Prompt가 생성한 Mermaid 다이어그램을 Notion, GitHub Wiki, 비행선 문서에 바로 붙여서 렌더링할 수 있어요.

문서 생성: OpenClaw vs ChatGPT

둘 다 문서를 생성할 수 있지만, 방식이 완전 달라요.

OpenClaw
  • 프로젝트 소스 코드를 직접 읽어서, 문서는 실제 코드 기반으로 생성돼요
  • 파일 간의 참조 관계를 이해해서, API 문서가 정확하고 완전해요
  • 코드가 업데이트되면 다시 생성, 문서가 자동으로 동기화돼요
  • Mermaid 아키텍처 다이어그램, 타임시퀀스 다이어그램 생성 지원해요
VS
ChatGPT
  • 코드를 수동으로 복사 붙여넣기하니까, 컨텍스트가 제한적이에요
  • 전체 프로젝트 구조를 못 봐서, 인터페이스를 놓칠 수 있어요
  • 문서가 일회용이에요. 코드 바뀌면 문서를 새로 생성해야 해요
  • 코드가 token 제한을 초과하면, 한 번에 처리 못 해요

문서 생성 팁 몇 가지

💡 API 문서 생성할 때, OpenClaw에게 Postman/Insomnia 임포트 파일도 함께 생성하라고 하세요. 프론트엔드 팀원이 바로 임포트해서 테스트할 수 있어요.
🎯 코드에 JSDoc, docstring이나 Swagger 주석이 있으면, Prompt에서 한 번 언급해줘요. AI가 이런 주석들을 기반으로 더 정확한 문서를 생성할 거예요.
README와 간단한 문서는 GPT-4o로 충분해요. 빠르고 포맷이 안정적이에요. 아키텍처 분석과 복잡한 의존성 문서는 Claude Opus 4.6으로 해요. 더 깊게 이해하거든요.
이 사례가 도움이 됐나요?