AI Docs Generation.

AI 문서 생성은 코드, 타입, OpenAPI, PR diff를 입력으로 README, API 설명, 주석, 변경 노트의 초안을 만드는 작업입니다. 문서를 "대신 써 주는 도구"라기보다 초안 속도를 올리고, 사람이 정확성을 고정하는 흐름입니다.

📄 잘 맞는 산출물

• 함수·컴포넌트 JSDoc / TSDoc: props, 반환, 부작용.
• README 섹션: 설치, 스크립트, 폴더 구조, 환경 변수.
• API·엔드포인트 설명: 요청/응답 예시, 에러 코드.
• 변경 노트: PR 단위 "무엇이 왜 바뀌었는지".
• 다이어그램 초안: 시퀀스·폴더 관계를 텍스트로 먼저 받고 그림으로 옮깁니다.

프론트엔드에서는 Storybook 설명, 디자인 토큰 표, 라우트 목록처럼 코드에 이미 있는 진실을 문장으로 옮길 때 효과가 큽니다.

🔄 추천 워크플로

1. 단일 진실 원천을 고릅니다: 타입 정의, OpenAPI, 실제 핸들러.
2. 범위를 고정합니다: "이 파일의 export만", "이 PR diff만".
3. 초안 생성: 모델·에이전트에 톤(비인칭 합니다체 등)과 금지 사항(추측 금지)을 넣습니다.
4. 기계 검증: 예제 코드 컴파일, 링크 존재, 스크립트 실행.
5. 사람 교정: 버전, 브라우저 지원, 보안 주장처럼 틀린 비용이 큰 문장만 집중 수정합니다.

문서가 코드보다 먼저 나가면 금방 썩습니다. 생성 직후 코드 경로를 출처로 남기거나, CI에서 "문서의 예제가 깨지면 실패"하게 두는 편이 안전합니다.

⚠️ 흔한 실패

• 존재하지 않는 API를 문서화: 환각. 시그니처를 코드에서 읽어 오게 합니다.
• 마케팅 문장: "완벽한", "차세대"처럼 검증 불가 표현이 섞입니다. 톤 규칙을 프롬프트에 넣습니다.
• 비밀 유출: .env 예시 mid에 실제 키를 넣습니다. 플레이스홀더만 허용합니다.
• 중복 문서: 같은 내용을 README와 Notion과 블로그에 복사하면 금방 어긋납니다. 생성 위치를 하나로 정합니다.

💡 같이 알아둘 것

• 좋은 문서 프롬프트는 "자세히 써 줘"보다 독자, 형식, 출처 파일, 쓰지 말 것을 적는 쪽입니다.
• 이 사이트의 Frontend Docs처럼 카테고리·로드맵 연결이 있으면, 생성 후에도 docsTree 연결은 사람이 확인합니다.

🔗 참고 자료

• TSDoc — TypeScript 문서 주석 표준입니다.
• Diátaxis — 튜토리얼, how-to, 설명, 참조를 나누는 문서 프레임워크입니다.
• OpenAPI Specification — API를 기계가 읽을 수 있는 형태로 두는 명세입니다.