문서화와 지식 공유

🔄 이전 레슨 복습: 이전 레슨에서 AI로 코드 리뷰와 리팩토링을 배웠어요. 이제 AI로 효율적인 문서화를 하는 법을 다뤄요.

아무도 안 쓰는 문서

개발팀에 물어보세요: “문서가 최신인가요?” 웃는 모습을 보게 될 거예요.

문서화는 소프트웨어 개발의 브로콜리예요 — 좋다는 건 다 아는데, 먹고 싶지 않아요. 코드 배포하고, 기능 출시하고, 문서는… 다음 스프린트 백로그에 넣어요. 그 다음 스프린트로 넘어가요. 결국 “안 함"이 돼요.

AI가 이 방정식을 근본적으로 바꿔요. 문서를 재미있게 만들어서가 아니라, 거의 노력 없이 만들 수 있게 해서요. 오후 내내 걸리던 게 15분이면 돼요.

개발 문서 다섯 가지 유형

코드에서 API 문서 생성

AI 문서가 진짜 빛나는 곳이에요:

이 엔드포인트에 대한 API 문서를 생성해줘.
포함: 설명, 파라미터, 요청/응답 예시, 에러 코드,
인증 요구사항.

프레임워크: Express.js + TypeScript
인증: Bearer 토큰 (JWT)

[엔드포인트 코드 붙여넣기]
[요청/응답 타입 붙여넣기]

AI가 10초 만에 구조화된 문서를 생성해요. 수동 작성은 엔드포인트당 15-20분이 걸려요. 30개 엔드포인트의 API라면, 하루를 절약하는 거예요.

레거시 코드 설명

문서 없는 코드베이스를 물려받았나요? AI의 빛나는 순간이에요.

이 코드가 뭘 하는지 쉬운 말로 설명해줘.
그다음 문서 주석을 작성해줘. 대상 독자는
우리 팀에 합류하는 중급 개발자예요.

[복잡한 레거시 함수 붙여넣기]

AI가 뭘 하는지뿐만 아니라 왜 코드가 이상하게 보이는지도 설명해줘요. “47번째 줄의 중첩 루프는 의도적 — 단일 원장 항목이 여러 계정 코드에 매핑되는 분할 거래를 처리해요.” 이런 설명이 코드가 뭘 하는지보다 더 가치 있는 경우가 많아요.

✅ 확인 질문: 이 AI 생성 문서 주석에서 의심스러운 점은 뭘까요?

def get_users(status="active", limit=100):
    """
    Raises:
        DatabaseError: DB 연결 실패 시
    """

이 함수가 실제로 DatabaseError를 발생시키나요? 아니면 AI가 DB 함수니까 그럴 거라고 추측한 건가요? 문서화된 동작이 실제 코드 동작과 일치하는지 항상 검증하세요.

README 생성

이 프로젝트의 구조를 기반으로 README.md를 생성해줘.

디렉토리 트리:
[tree 명령 출력 붙여넣기]

package.json:
[의존성 파일 붙여넣기]

메인 설정 파일:
[설정 붙여넣기]

포함: 프로젝트 설명, 선수 조건, 설정 방법,
로컬 실행, 테스트 실행, 배포, 프로젝트 구조 개요.

AI가 실제 프로젝트 파일에서 올바른 설정 명령, 의존성, 설정을 추출해서 새 팀원이 실제로 따라할 수 있는 README를 만들어요.

아키텍처 문서

이건 협업이 필요해요. AI는 코드만으로 아키텍처를 알 수 없어요:

시스템 아키텍처를 문서화하는 걸 도와줘.
내가 고수준 설계를 설명하면 구조화된 문서를 만들어줘.

시스템: 이커머스 주문 처리
컴포넌트:
- API Gateway (Express.js) - 인증, rate limiting
- Order Service (Python) - 비즈니스 로직, 검증
- Payment Service (Go) - Stripe 연동
- PostgreSQL - 주문, 사용자
- Redis - 세션 캐시
- RabbitMQ - 서비스 간 비동기 통신

포함: 시스템 개요, 컴포넌트 책임, 통신 패턴,
일반적인 주문의 데이터 흐름, 장애 모드와 대처.

AI가 구조와 글을 만들어요. 인간만 아는 맥락 — 왜 그런 결정을 했는지, 어떤 트레이드오프를 고려했는지, 미래 계획이 뭔지 — 을 추가하고 정확성을 검증하세요.

살아있는 문서: 문서 최신 유지

문서의 가장 어려운 부분은 만드는 게 아니라 최신 상태를 유지하는 거예요:

PR 문서 체크:

이 PR diff가 있어요. API 문서에 반영해야 할
동작 변경이 있나요?
[diff 붙여넣기]
[영향받는 엔드포인트의 현재 문서 붙여넣기]

체인지로그 생성:

이 커밋들에서 체인지로그 항목을 생성해줘.
사용자 관점에서 작성 — 내부 구현이 아닌
사용자에게 뭐가 바뀌었는지.
[git log 출력 붙여넣기]

핵심 정리

• AI가 문서를 거의 노력 없이 만들어요 — 오후 내내가 아니라 15분이면 돼요
• 정확한 API 문서를 위해 실제 코드를 제공하세요, 코드 설명이 아니라
• AI 생성 문서를 실제 동작과 대조 검증하세요 — AI가 때로 이상적인 동작을 문서화해요
• 온보딩과 지식 이전에 AI로 레거시 코드를 설명하세요
• PR 워크플로에 문서를 포함시켜서 최신 상태를 유지하세요

다음 레슨: 아키텍처 결정과 시스템 설계 — “마이크로서비스 vs 모놀리스?” “어떤 DB가 맞아?” AI와 함께 트레이드오프를 추론하는 법을 배워요.