{
  "name": "Documentation Rules",
  "description": "효과적인 코드 및 프로젝트 문서화를 위한 규칙",
  "rules": {
    "codeDocumentation": {
      "comments": {
        "inline": {
          "purpose": "복잡한 로직 설명, 의도가 명확하지 않은 코드 설명",
          "style": "// 한 줄 주석은 간결하게",
          "avoidRedundancy": "코드 자체가 명확한 경우 불필요한 주석 지양"
        },
        "block": {
          "purpose": "여러 줄 설명이 필요한 복잡한 알고리즘, 로직",
          "style": "/* 여러 줄 주석은 명확한 형식으로 */",
          "structure": [
            "주석의 맥락 설명",
            "핵심 내용 설명",
            "필요시 예제 또는 주의사항 추가"
          ]
        },
        "todo": {
          "format": "// TODO: 설명 - 담당자(선택) - 날짜(선택)",
          "usage": "향후 개선, 수정, 추가가 필요한 코드 표시",
          "tracking": "TODO 주석은 이슈 트래킹 시스템과 연동 권장"
        }
      },
      "jsDoc": {
        "function": {
          "required": true,
          "template": [
            "/**",
            " * 함수에 대한 간략한 설명",
            " * @param {타입} 파라미터명 - 파라미터 설명",
            " * @returns {타입} 반환값 설명",
            " * @throws {예외타입} 발생 가능한 예외 설명",
            " * @example",
            " * // 사용 예시 코드",
            " */"
          ]
        },
        "class": {
          "required": true,
          "template": [
            "/**",
            " * 클래스에 대한 간략한 설명",
            " * @class",
            " * @implements {인터페이스} (해당시)",
            " * @extends {부모클래스} (해당시)",
            " * @example",
            " * // 사용 예시 코드",
            " */"
          ]
        },
        "interface": {
          "required": true,
          "template": [
            "/**",
            " * 인터페이스에 대한 간략한 설명",
            " * @interface",
            " * @property {타입} 속성명 - 속성 설명",
            " */"
          ]
        },
        "module": {
          "required": true,
          "template": [
            "/**",
            " * @module 모듈명",
            " * @description 모듈에 대한 간략한 설명",
            " * @author 작성자 (선택)",
            " */"
          ]
        }
      },
      "types": {
        "typescript": {
          "required": true,
          "interfaces": "명시적 인터페이스 정의 및 문서화",
          "genericTypes": "제네릭 타입의 명확한 문서화",
          "enums": "열거형 각 멤버의 용도 설명"
        }
      }
    },
    "projectDocumentation": {
      "readme": {
        "required": true,
        "sections": [
          "프로젝트 이름 및 간략한 설명",
          "설치 방법",
          "사용 방법 및 예제",
          "API 참조 또는 링크",
          "기여 방법",
          "라이선스 정보"
        ],
        "template": [
          "# 프로젝트 이름",
          "",
          "## 개요",
          "프로젝트에 대한 간략한 설명과 주요 기능",
          "",
          "## 시작하기",
          "### 필요 조건",
          "필요한 소프트웨어 및 종속성 목록",
          "",
          "### 설치",
          "설치 단계 설명",
          "",
          "## 사용 방법",
          "기본 사용법 예제",
          "",
          "## 주요 기능",
          "주요 기능 및 사용 사례 설명",
          "",
          "## API 참조",
          "API 문서 링크 또는 간략한 설명",
          "",
          "## 기여 방법",
          "기여 가이드라인",
          "",
          "## 라이선스",
          "라이선스 정보"
        ]
      },
      "contributing": {
        "required": true,
        "sections": [
          "기여 과정 개요",
          "개발 환경 설정",
          "코드 스타일 가이드",
          "테스트 방법",
          "PR 및 이슈 제출 지침"
        ]
      },
      "changeLog": {
        "required": true,
        "format": "시맨틱 버전 기반 변경 내역 기록",
        "template": [
          "# 변경 내역",
          "",
          "## [버전] - 날짜",
          "",
          "### 추가",
          "- 새로운 기능",
          "",
          "### 변경",
          "- 기존 기능 변경",
          "",
          "### 수정",
          "- 버그 수정",
          "",
          "### 제거",
          "- 제거된 기능"
        ]
      },
      "architecture": {
        "required": true,
        "sections": [
          "전체 시스템 구조",
          "주요 컴포넌트 및 모듈",
          "데이터 흐름",
          "외부 시스템 통합",
          "주요 설계 결정 및 이유"
        ],
        "visualizations": "아키텍처 다이어그램, 시퀀스 다이어그램 등 시각적 자료 포함"
      }
    },
    "apiDocumentation": {
      "restApi": {
        "required": true,
        "format": "OpenAPI/Swagger 형식 권장",
        "perEndpoint": {
          "template": [
            "## 엔드포인트: `[HTTP 메서드] /경로`",
            "",
            "### 설명",
            "API 엔드포인트에 대한 설명",
            "",
            "### 요청",
            "#### 헤더",
            "필요한 헤더 정보",
            "",
            "#### 파라미터",
            "- `paramName` (타입): 설명",
            "",
            "#### 요청 본문",
            "```json",
            "요청 본문 예시",
            "```",
            "",
            "### 응답",
            "#### 성공 응답 (상태 코드)",
            "```json",
            "응답 본문 예시",
            "```",
            "",
            "#### 오류 응답 (상태 코드)",
            "```json",
            "오류 응답 예시",
            "```",
            "",
            "### 예제",
            "요청 및 응답 예제"
          ]
        },
        "tools": ["Swagger UI", "ReDoc", "Postman 컬렉션"]
      },
      "graphqlApi": {
        "required": true,
        "format": "GraphQL 스키마 문서화",
        "sections": [
          "타입 정의",
          "쿼리 및 뮤테이션",
          "인자 설명",
          "사용 예제"
        ],
        "tools": ["GraphQL Playground", "Apollo Studio", "GraphiQL"]
      },
      "eventApi": {
        "required": true,
        "perEvent": {
          "template": [
            "## 이벤트: `이벤트명`",
            "",
            "### 설명",
            "이벤트에 대한 설명",
            "",
            "### 페이로드",
            "```json",
            "이벤트 페이로드 예시",
            "```",
            "",
            "### 소비자",
            "이 이벤트를 소비하는 서비스 목록",
            "",
            "### 발생 조건",
            "이벤트가 발생하는 조건 설명"
          ]
        }
      }
    },
    "userDocumentation": {
      "userGuide": {
        "required": true,
        "sections": [
          "소개 및 개요",
          "시작하기",
          "기본 기능 사용법",
          "고급 기능 사용법",
          "문제 해결",
          "용어 설명"
        ],
        "format": "단계별 지침, 스크린샷 포함"
      },
      "faq": {
        "required": true,
        "organization": "주제별 그룹화",
        "updates": "자주 받는 질문 지속적 업데이트"
      },
      "tutorials": {
        "required": false,
        "format": "특정 작업을 위한 단계별 가이드",
        "multimedia": "가능한 경우 비디오 또는 애니메이션 제공"
      }
    },
    "documentationMaintenance": {
      "reviews": {
        "frequency": "정기적인 문서 검토 (분기 또는 주요 릴리스 마다)",
        "checklist": [
          "정확성 확인",
          "최신성 확인",
          "완전성 확인",
          "가독성 및 명확성 확인",
          "예제 작동 확인"
        ]
      },
      "versioning": {
        "approach": "문서 버전 관리 (소프트웨어 버전과 연동)",
        "changelog": "문서 변경 사항 기록",
        "archiving": "이전 버전 문서 보관"
      },
      "feedback": {
        "mechanism": "사용자 피드백 수집 채널 마련",
        "incorporation": "피드백 기반 문서 개선 프로세스"
      }
    },
    "documentationTools": {
      "codeDocumentation": {
        "recommended": ["JSDoc", "TypeDoc", "Doxygen"],
        "configuration": "프로젝트에 맞는 문서 생성 도구 설정"
      },
      "apiDocumentation": {
        "recommended": ["Swagger/OpenAPI", "Slate", "Docusaurus"],
        "automation": "API 변경 시 문서 자동 업데이트 구성"
      },
      "generalDocumentation": {
        "recommended": ["Markdown", "Docusaurus", "VuePress", "MkDocs"],
        "hosting": "문서 호스팅 전략 (GitHub Pages, Netlify 등)"
      },
      "diagramming": {
        "recommended": ["PlantUML", "Mermaid.js", "Draw.io"],
        "versionControl": "다이어그램 소스 코드 버전 관리"
      }
    }
  }
}