name: documentation-git description: Enforces API documentation using language-standard comments for public interfaces and generates Conventional Commits style messages when asked, clearly summarizing changes. Use when creating or modifying public classes/functions or when the user requests commit messages.

Documentation & Git

Instructions

When creating or modifying:

• Public classes, interfaces, or types
• Public or externally used functions/methods
• API surfaces consumed by other modules/services

you must:

1. Add or update standard documentation comments (JSDoc, XML docs, Dart doc comments, etc.).
2. Clearly document parameters, return values, and any important side effects or invariants.

When the user asks to write a git commit message, you must:

1. Use the Conventional Commits format.
2. Provide a concise but clear summary of the change.

1. Documentation Rules

When to Document

Always add or update documentation comments for:

• Public classes/components
• Public methods/functions
• Public interfaces/DTOs/config objects
• Utility functions that are reused across modules

Internal/private helpers can have lighter comments, but still document non-obvious behavior or important constraints.

How to Document

Use the idiomatic comment style of the language:

• JavaScript/TypeScript: JSDoc
• C#: XML documentation comments
• Dart: /// doc comments
• Java/Kotlin: /** ... */ style doc comments
• Python: docstrings

Each documented API should include, where applicable:

• High-level description: What this class/function represents or does.
• Parameters: Name, type (if not obvious), and meaning.
• Return value: Type (if needed) and what it represents.
• Errors/Exceptions: When and what can be thrown/returned on error.
• Side effects: External I/O, mutations, resource acquisition.

Example structure (language-agnostic):

Summary:
- What this does.

Parameters:
- param1: what it represents, constraints, units.
- param2: optional/required, allowed values.

Returns:
- What is returned and how callers should use it.

Prefer clarity and conciseness over verbosity.

2. Git Commit Message Rules (Conventional Commits)

When asked to write or suggest a commit message, always follow Conventional Commits:

Format

<type>[optional scope]: <short summary>

[optional body]

[optional footer(s)]

Common Types

• feat: 새로운 기능 추가
• fix: 버그 수정
• docs: 문서 관련 변경 (README, 주석 대규모 업데이트 등)
• refactor: 기능 변화 없이 내부 구조 개선
• perf: 성능 개선
• test: 테스트 코드 추가/수정
• chore: 빌드, 설정, 기타 잡다한 작업
• style: 포맷팅, 세미콜론, 린트 수정 등

Required Behavior

When generating a commit message:

1. Choose the most appropriate type based on the main purpose of the change.
2. Write a short, imperative summary in the subject line:
   • 영어 사용을 기본으로 하고, 필요한 경우 한글 설명은 body에 추가 가능.
3. Optionally include a body with:
   • More detailed explanation or rationale
   • Breaking change notes
   • Links to issues/tickets

Examples:

feat(auth): add JWT-based login endpoint

fix(user-profile): handle missing avatar url

docs(api): document pagination parameters on /users endpoint

refactor(core): extract validation logic into shared module

If the user provides a diff or description, base the message on:

• What changed (at a high level).
• Why it changed (motivation, bug, requirement).
• Scope (module, feature, component).

When to Apply This Skill

Use these documentation & git rules when:

• The user:
  • Requests code for new public APIs, classes, or methods.
  • Asks to “문서화해줘”, “주석 달아줘”, or similar.
  • Asks for help writing a git commit message.
• You:
  • Introduce or significantly change externally used functions/classes.
  • Produce code that will be part of a reusable library or shared module.

In these scenarios, never:

• Omit documentation for public APIs.
• Return a commit message that does not follow Conventional Commits.
• Use vague commit summaries that don’t describe the main change.

Summary Checklist

Before finalizing:

• All new or changed public classes/functions have clear, standard documentation comments.
• Parameters, return values, and important side effects are described.
• Any requested commit message follows Conventional Commits.
• The commit summary clearly conveys the primary change and scope.