Commit Message Standards

Language: English | 繁體中文

Version: 1.0.0 Last Updated: 2025-12-24 Applicability: Claude Code Skills

Core Standard: This skill implements Commit Message Guide. For comprehensive methodology documentation, refer to the core standard.

Purpose

This skill ensures consistent, meaningful commit messages following conventional commits.

Quick Reference

Basic Format

code

<type>(<scope>): <subject>

<body>

<footer>

Commit Types

English	When to Use
`feat`	New feature
`fix`	Bug fix
`refactor`	Code refactoring (no functional change)
`docs`	Documentation only
`style`	Formatting (no code logic change)
`test`	Adding or updating tests
`perf`	Performance improvement
`build`	Build system or dependencies
`ci`	CI/CD pipeline changes
`chore`	Maintenance tasks
`revert`	Revert previous commit
`security`	Security vulnerability fix

Subject Line Rules

•Length: ≤72 characters (50 ideal)
•Tense: Imperative mood ("Add feature" not "Added feature")
•Capitalization: First letter capitalized
•No period: Don't end with a period

Detailed Guidelines

For complete standards, see:

•Conventional Commits Guide
•Language Options

AI-Optimized Format (Token-Efficient)

For AI assistants, use the YAML format files for reduced token usage:

•Base standard: ai/standards/commit-message.ai.yaml
•
Language options:
- •English: ai/options/commit-message/english.ai.yaml
- •Traditional Chinese: ai/options/commit-message/traditional-chinese.ai.yaml
- •Bilingual: ai/options/commit-message/bilingual.ai.yaml

Examples

✅ Good Examples

code

feat(auth): Add OAuth2 Google login support
fix(api): Resolve memory leak in user session cache
refactor(database): Extract query builder to separate class
docs(readme): Update installation instructions for Node 20

❌ Bad Examples

code

fixed bug                    # Too vague, no scope
feat(auth): added google login  # Past tense
Update stuff.                # Period, vague
WIP                          # Not descriptive

Body Guidelines

Use the body to explain WHY the change was made:

code

fix(api): Resolve race condition in concurrent user updates

Why this occurred:
- Two simultaneous PUT requests could overwrite each other
- No optimistic locking implemented

What this fix does:
- Add version field to User model
- Return 409 Conflict if version mismatch

Fixes #789

Breaking Changes

Always document breaking changes in footer:

code

feat(api): Change user endpoint response format

BREAKING CHANGE: User API response format changed

Migration guide:
1. Update API clients to remove .data wrapper
2. Use created_at instead of createdAt

Issue References

code

Closes #123    # Automatically closes issue
Fixes #456     # Automatically closes issue
Refs #789      # Links without closing

Language Selection Decision (YAML Compressed)

yaml

# === LANGUAGE DECISION MATRIX ===
decision_tree:
  - q: "Open source project?"
    y: "→ English (international contributors)"
    n: next
  - q: "International/distributed team?"
    y: "→ English (common language)"
    n: next
  - q: "Single-language team?"
    y: "→ Team's primary language OR English"
    n: "→ Bilingual (subject:EN, body:local)"

recommendation_matrix:
  open_source: {lang: English, reason: "international contributors"}
  international_team: {lang: English, reason: "common language"}
  local_team_EN: {lang: English, reason: "tool compatibility, career mobility"}
  local_team_ZH: {lang: "繁體中文", reason: "clarity, team preference"}
  mixed: {lang: Bilingual, reason: "best of both worlds"}

# === TOOL COMPATIBILITY ===
tool_support:
  full_unicode:
    - GitHub/GitLab/Bitbucket
    - VS Code/JetBrains
    - SourceTree/GitKraken
  potential_issues:
    - "Some CI/CD log viewers"
    - "Legacy terminal encodings"
    - "Email notifications (rare)"

# === FORMAT BY LANGUAGE ===
english:
  types: [feat, fix, refactor, docs, style, test, perf, build, ci, chore, revert, security]
  example: "feat(auth): add OAuth2 Google login support"

traditional_chinese:
  types: [功能, 修復, 重構, 文件, 樣式, 測試, 效能, 建置, CI, 雜項, 回退, 安全]
  example: "功能(認證): 新增 OAuth2 Google 登入支援"

bilingual:
  format: "type(scope): English subject\n\n中文詳細說明"
  example: |
    feat(auth): add OAuth2 Google login

    新增 Google OAuth2 登入功能
    - 實作授權流程
    - 處理 token 交換

Configuration Detection

This skill supports project-specific language configuration.

Detection Order

•Check CONTRIBUTING.md for "Commit Message Language" section
•If found, use the specified option (English / Traditional Chinese / Bilingual)
•If not found, default to English for maximum tool compatibility

First-Time Setup

If no configuration found and context is unclear:

•Ask the user: "This project hasn't configured commit message language preference. Which option would you like to use? (English / 中文 / Bilingual)"
•After user selection, suggest documenting in CONTRIBUTING.md:

markdown

## Commit Message Language

This project uses **[chosen option]** commit types.
<!-- Options: English | Traditional Chinese | Bilingual -->

Configuration Example

In project's CONTRIBUTING.md:

markdown

## Commit Message Language

This project uses **English** commit types.

### Allowed Types
feat, fix, refactor, docs, style, test, perf, build, ci, chore, revert, security

Related Standards

Version History

Version	Date	Changes
1.0.0	2025-12-24	Added: Standard sections (Purpose, Related Standards, Version History, License)

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards