5장: AI 기반 문서화 자동화

문서화 자동화의 목표:
 
  1. 코드와 문서의 동기화 유지
  2. API 변경 시 문서 자동 갱신
  3. PR별 변경 로그 자동 생성
  4. README의 사용법 예시 최신 상태 유지
  5. 새 함수/클래스의 JSDoc/docstring 자동 생성

interface DocImpact {
  // 영향 받는 문서 파일
  affectedDocs: AffectedDoc[]
  // 새로 생성해야 할 문서
  newDocs: NewDocSpec[]
  // 인라인 문서가 필요한 코드
  missingInlineDocs: InlineDocSpec[]
}
 
interface AffectedDoc {
  filePath: string
  docType: "api" | "readme" | "changelog" | "guide"
  // 문서에서 갱신이 필요한 섹션
  affectedSections: string[]
  // 영향을 준 코드 변경
  sourceChanges: FileChange[]
}
 
interface InlineDocSpec {
  filePath: string
  functionName: string
  lineNumber: number
  // 기존 문서 존재 여부
  hasExistingDoc: boolean
}
 
async function analyzeDocImpact(
  changes: FileChange[]
): Promise<DocImpact> {
  const impact: DocImpact = {
    affectedDocs: [],
    newDocs: [],
    missingInlineDocs: [],
  }
 
  for (const change of changes) {
    // API 엔드포인트 변경 감지
    if (isApiFile(change.filename)) {
      const apiChanges = extractApiChanges(change)
      if (apiChanges.length > 0) {
        impact.affectedDocs.push({
          filePath: findApiDocPath(change.filename),
          docType: "api",
          affectedSections: apiChanges.map(
            a => a.endpoint
          ),
          sourceChanges: [change],
        })
      }
    }
 
    // 공개 인터페이스 변경 감지
    if (isPublicModule(change.filename)) {
      const exportChanges = extractExportChanges(change)
      if (exportChanges.length > 0) {
        impact.affectedDocs.push({
          filePath: "README.md",
          docType: "readme",
          affectedSections: ["Usage", "API Reference"],
          sourceChanges: [change],
        })
      }
    }
 
    // 인라인 문서 누락 감지
    const undocumentedFunctions = findUndocumentedFunctions(
      change
    )
    for (const func of undocumentedFunctions) {
      impact.missingInlineDocs.push({
        filePath: change.filename,
        functionName: func.name,
        lineNumber: func.line,
        hasExistingDoc: false,
      })
    }
  }
 
  // CHANGELOG는 항상 갱신 대상
  impact.affectedDocs.push({
    filePath: "CHANGELOG.md",
    docType: "changelog",
    affectedSections: ["Unreleased"],
    sourceChanges: changes,
  })
 
  return impact
}

interface ApiChange {
  type: "added" | "modified" | "removed"
  method: string          // GET, POST, PUT, DELETE
  endpoint: string        // /api/users/:id
  changes: {
    parameters?: ParameterChange[]
    requestBody?: BodyChange
    response?: ResponseChange
  }
}
 
async function updateApiDocs(
  apiChanges: ApiChange[],
  existingSpec: string
): Promise<string> {
  const prompt = `다음 API 변경 사항을 반영하여 OpenAPI 스펙을 갱신해 주세요.
 
## 현재 OpenAPI 스펙
\`\`\`yaml
` + existingSpec + `
\`\`\`
 
## API 변경 사항
`
    + apiChanges.map(change => {
        return "- [" + change.type.toUpperCase() + "] "
          + change.method + " " + change.endpoint
          + ": " + JSON.stringify(change.changes)
      }).join("\n")
    + `
 
## 규칙
1. 기존 스펙의 형식과 스타일을 유지합니다.
2. 변경된 부분만 수정합니다.
3. description은 한글로 작성합니다.
4. 응답 스키마에 예시를 포함합니다.
 
갱신된 전체 OpenAPI 스펙을 YAML 형식으로 응답하세요.
`
 
  const updatedSpec = await callLLM(prompt)
  return extractYamlBlock(updatedSpec)
}

// 타입 정의에서 문서를 생성하는 예시
 
// 입력: 타입 정의
interface CreateUserRequest {
  /** 사용자 이메일 (고유) */
  email: string
  /** 사용자 이름 (2-50자) */
  name: string
  /** 비밀번호 (최소 8자, 영문+숫자+특수문자) */
  password: string
  /** 프로필 이미지 URL (선택) */
  avatarUrl?: string
}
 
interface CreateUserResponse {
  /** 생성된 사용자 ID */
  id: string
  /** 사용자 이메일 */
  email: string
  /** 사용자 이름 */
  name: string
  /** 계정 생성 시각 (ISO 8601) */
  createdAt: string
}
 
// LLM에게 타입 정의를 전달하면 다음과 같은 문서를 생성합니다:
 
/*
생성 결과 예시:
 
## POST /api/users
 
사용자를 생성합니다.
 
### Request Body
 
| 필드 | 타입 | 필수 | 설명 |
|------|------|------|------|
| email | string | O | 사용자 이메일 (고유) |
| name | string | O | 사용자 이름 (2-50자) |
| password | string | O | 비밀번호 (최소 8자) |
| avatarUrl | string | X | 프로필 이미지 URL |
 
### Response (201 Created)
 
| 필드 | 타입 | 설명 |
|------|------|------|
| id | string | 생성된 사용자 ID |
| email | string | 사용자 이메일 |
| name | string | 사용자 이름 |
| createdAt | string | 계정 생성 시각 (ISO 8601) |
*/

async function generateJSDoc(
  functionCode: string,
  context: string
): Promise<string> {
  const prompt = `다음 함수에 대한 JSDoc 주석을 생성해 주세요.
 
## 함수 코드
\`\`\`typescript
` + functionCode + `
\`\`\`
 
## 주변 맥락
\`\`\`typescript
` + context + `
\`\`\`
 
## JSDoc 작성 규칙
1. 함수의 목적을 한 문장으로 요약합니다.
2. 각 매개변수의 의미와 제약 조건을 설명합니다.
3. 반환값의 의미를 설명합니다.
4. throws 절이 있으면 에러 조건을 문서화합니다.
5. 비자명한 동작이 있으면 주의사항을 추가합니다.
6. 한글로 작성합니다.
 
JSDoc 주석만 응답하세요 (함수 코드는 제외).
`
 
  return await callLLM(prompt)
}

/**
 * 주어진 조건에 맞는 사용자 목록을 페이지네이션하여 조회합니다.
 *
 * @param filter - 검색 조건
 * @param filter.role - 사용자 역할 필터 (선택)
 * @param filter.status - 계정 상태 필터 (선택)
 * @param filter.createdAfter - 이 시점 이후 생성된 사용자만 조회
 * @param pagination - 페이지네이션 옵션
 * @param pagination.page - 페이지 번호 (1부터 시작)
 * @param pagination.pageSize - 페이지당 항목 수 (기본값: 20, 최대: 100)
 * @returns 페이지네이션된 사용자 목록과 전체 개수
 * @throws {ValidationError} 유효하지 않은 페이지 번호나 페이지 크기
 * @throws {DatabaseError} 데이터베이스 연결 실패
 */
async function findUsers(
  filter: UserFilter,
  pagination: PaginationOptions
): Promise<PaginatedResult<User>> {
  // ...
}

interface ChangelogEntry {
  version: string
  date: string
  categories: {
    features: ChangeItem[]
    fixes: ChangeItem[]
    breaking: ChangeItem[]
    performance: ChangeItem[]
    docs: ChangeItem[]
    refactor: ChangeItem[]
  }
}
 
interface ChangeItem {
  description: string
  scope?: string
  commit: string
  pr?: number
}
 
function categorizeCommits(
  commits: CommitInfo[]
): ChangelogEntry["categories"] {
  const categories = {
    features: [] as ChangeItem[],
    fixes: [] as ChangeItem[],
    breaking: [] as ChangeItem[],
    performance: [] as ChangeItem[],
    docs: [] as ChangeItem[],
    refactor: [] as ChangeItem[],
  }
 
  for (const commit of commits) {
    const parsed = parseConventionalCommit(commit.message)
    if (!parsed) continue
 
    const item: ChangeItem = {
      description: parsed.description,
      scope: parsed.scope,
      commit: commit.sha.slice(0, 7),
      pr: extractPRNumber(commit.message),
    }
 
    if (parsed.breaking) {
      categories.breaking.push(item)
    }
 
    switch (parsed.type) {
      case "feat":
        categories.features.push(item)
        break
      case "fix":
        categories.fixes.push(item)
        break
      case "perf":
        categories.performance.push(item)
        break
      case "docs":
        categories.docs.push(item)
        break
      case "refactor":
        categories.refactor.push(item)
        break
    }
  }
 
  return categories
}

async function generateAIChangelog(
  commits: CommitInfo[],
  diffs: FileDiff[]
): Promise<string> {
  const prompt = `다음 커밋 목록과 코드 변경 내용을 분석하여,
사용자 관점의 CHANGELOG를 작성해 주세요.
 
## 커밋 목록
` + commits.map(c => "- " + c.sha.slice(0, 7) + " " + c.message).join("\n") + `
 
## 주요 코드 변경
` + diffs.map(d => {
    return "### " + d.filename + "\n"
      + "```diff\n" + d.patch + "\n```"
  }).join("\n\n") + `
 
## CHANGELOG 작성 규칙
1. 사용자가 체감하는 변경만 포함합니다.
2. 내부 리팩터링은 제외합니다.
3. 각 항목은 "했습니다" 형식의 완결된 문장으로 작성합니다.
4. Breaking Change가 있으면 마이그레이션 방법을 안내합니다.
5. 새 기능은 간단한 사용 예시를 포함합니다.
 
Markdown 형식으로 응답하세요.
`
 
  return await callLLM(prompt)
}

interface ReadmeSection {
  title: string
  startLine: number
  endLine: number
  content: string
}
 
function parseReadmeSections(readme: string): ReadmeSection[] {
  const lines = readme.split("\n")
  const sections: ReadmeSection[] = []
  let currentSection: ReadmeSection | null = null
 
  for (let i = 0; i < lines.length; i++) {
    const headingMatch = lines[i].match(/^(#{1,3})\s+(.+)/)
    if (headingMatch) {
      if (currentSection) {
        currentSection.endLine = i - 1
        currentSection.content = lines
          .slice(currentSection.startLine, i)
          .join("\n")
        sections.push(currentSection)
      }
      currentSection = {
        title: headingMatch[2],
        startLine: i,
        endLine: lines.length - 1,
        content: "",
      }
    }
  }
 
  if (currentSection) {
    currentSection.content = lines
      .slice(currentSection.startLine)
      .join("\n")
    sections.push(currentSection)
  }
 
  return sections
}
 
async function updateReadmeSection(
  sectionTitle: string,
  currentContent: string,
  codeChanges: FileChange[]
): Promise<string> {
  const prompt = `README의 "` + sectionTitle + `" 섹션을 코드 변경에 맞게 갱신해 주세요.
 
## 현재 섹션 내용
` + currentContent + `
 
## 관련 코드 변경
` + codeChanges.map(c => {
    return "### " + c.filename + "\n```diff\n" + c.patch + "\n```"
  }).join("\n\n") + `
 
## 규칙
1. 기존 문서의 스타일과 톤을 유지합니다.
2. 변경된 부분만 수정합니다.
3. 코드 예시가 있으면 최신 API에 맞게 갱신합니다.
4. 새로운 기능이 추가되었으면 해당 내용을 추가합니다.
5. 제거된 기능이 있으면 해당 내용을 삭제합니다.
 
갱신된 섹션 내용만 응답하세요.
`
 
  return await callLLM(prompt)
}

name: AI Documentation Update
 
on:
  pull_request:
    types: [closed]
    branches: [main]
 
permissions:
  contents: write
  pull-requests: write
 
jobs:
  update-docs:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
 
      - run: npm install
 
      - name: Analyze changes and update docs
        env:
          ANTHROPIC_API_KEY: $ANTHROPIC_KEY_VALUE
          GITHUB_TOKEN: $GITHUB_TOKEN_VALUE
        run: node scripts/update-docs.js
 
      - name: Create docs update PR
        env:
          GITHUB_TOKEN: $GITHUB_TOKEN_VALUE
        run: |
          git config user.name "AI Docs Bot"
          git config user.email "ai-docs-bot@example.com"
          BRANCH="docs/auto-update-$(date +%Y%m%d%H%M%S)"
          git checkout -b $BRANCH
          git add -A
          if git diff --staged --quiet; then
            echo "No documentation changes needed"
            exit 0
          fi
          git commit -m "docs: AI-generated documentation update"
          git push origin $BRANCH
          gh pr create \
            --title "docs: auto-update documentation" \
            --body "This PR was automatically generated to update documentation based on recent code changes." \
            --base main \
            --head $BRANCH

interface ConsistencyIssue {
  docFile: string
  section: string
  issue: string
  severity: "error" | "warning"
}
 
async function checkDocConsistency(
  sourceFiles: string[],
  docFiles: string[]
): Promise<ConsistencyIssue[]> {
  const issues: ConsistencyIssue[] = []
 
  // 1. API 문서에 없는 엔드포인트 찾기
  const codeEndpoints = extractEndpointsFromCode(sourceFiles)
  const docEndpoints = extractEndpointsFromDocs(docFiles)
 
  for (const endpoint of codeEndpoints) {
    if (!docEndpoints.has(endpoint)) {
      issues.push({
        docFile: "docs/api.md",
        section: "API Reference",
        issue: endpoint + " 엔드포인트가 문서에 없습니다",
        severity: "error",
      })
    }
  }
 
  // 2. 문서에는 있지만 코드에서 제거된 엔드포인트
  for (const endpoint of docEndpoints) {
    if (!codeEndpoints.has(endpoint)) {
      issues.push({
        docFile: "docs/api.md",
        section: "API Reference",
        issue: endpoint + " 엔드포인트가 코드에서 제거되었습니다",
        severity: "error",
      })
    }
  }
 
  // 3. 코드 예시 실행 가능성 검증
  const codeExamples = extractCodeExamples(docFiles)
  for (const example of codeExamples) {
    const isValid = await validateCodeExample(example)
    if (!isValid) {
      issues.push({
        docFile: example.sourceFile,
        section: example.section,
        issue: "코드 예시가 현재 API와 맞지 않습니다",
        severity: "warning",
      })
    }
  }
 
  return issues
}