Claude Code Cookbook

The semantic-commit command automatically determines whether to generate commit messages in Portuguese (pt) or English (en) using a scoring algorithm. It analyzes several signals to decide the language:

1. CommitLint Configuration (+3 points): If subject-case is disabled (set to [0]) in commitlint.config.*, it strongly suggests Portuguese support.
2. Git Log Analysis (up to +2 points): It checks the last 20 commits. If a significant portion contains Portuguese linguistic markers (e.g., ção, ões, agem), points are awarded.
3. README.md Content (+1 point): It scans the first few lines of the README.md for Portuguese markers.
4. Changed Files Content (+1 point): It scans the git diff of current changes for Portuguese comments or strings.

Threshold: A score of 3 or more triggers Portuguese mode (pt). Otherwise, it defaults to English (en).

# Example of scoring logic (conceptual)
# 3 points or more = Portuguese mode
# Less than 3 = English mode

The /smart-review command uses a hierarchical logic to determine which roles to suggest. It looks at file extensions, directory structures, and content patterns (like error logs or security keywords).

Role Priority Order

When multiple roles are detected, the command prioritizes them in this order:

1. Security: Authentication, authorization, and encryption.
2. Critical Errors: System crashes or data loss.
3. Architecture: Large-scale changes and technology selection.
4. Performance: User experience and optimization.
5. Frontend/Mobile: UI/UX improvements.
6. QA: Quality assurance and testing.

When to use role-debate

The command will recommend the role-debate format instead of standard roles when:

• Three or more roles are relevant to the context.
• There is a clear trade-off required (e.g., Security vs. Performance).
• Significant architectural changes are involved.
• The context affects both mobile and web platforms.

The /smart-review command uses a priority-based logic to determine which roles to recommend based on the context detected:

Role Mapping Logic

• frontend: package.json, *.tsx, *.jsx, *.css, *.scss
• architect: Dockerfile, docker-compose.yml, *.yaml
• qa: *.test.js, *.spec.ts, test/, __tests__/
• performance: *.rs, Cargo.toml, performance/, webpack.config.js, vite.config.js
• security: auth.js, security.yml, .env, config/auth/, jwt.js, api/auth/
• mobile: mobile/, *.swift, *.kt, react-native/
• analyzer: Stack traces, error.log, crash.log, or specific issues like memory leak or SQL injection.

Priority Order

When multiple roles are applicable, the system prioritizes them in this order:

1. Security (Authentication, encryption)
2. Critical Errors (Outages, data loss)
3. Architecture (Large-scale changes)
4. Performance (UX impact)
5. Frontend/Mobile (UI/UX)
6. QA (Testing)

The /update-doc-string command applies specific formatting rules based on the programming language detected or specified:

Prohibitions

• No code changes: The command must only modify documentation, never the logic.
• No speculation: Do not guess implementation details.
• No type removal: Do not modify or remove existing type annotations.

# Python (PEP 257) Example
def calculate_total(items: List[Item]) -> float:
    """Calcular el monto total para una lista de elementos. (30-60 characters)

    Multiplica el precio y cantidad de cada elemento y devuelve
    el total con impuestos. (50-200 characters)

    Args:
        items: Lista de elementos a calcular

    Returns:
        Monto total con impuestos

    Generado por Claude 🤖
    """

Prompt quality is measured using a weighted scoring system based on category scores, penalties for critical issues, and bonuses for advanced features.

Scoring Formula: Score final = Score base + Bônus - Penalidades

• Score base: Σ(Score de cada categoria × Pontuação) / 100
• Penalties (Fatal Problems):
  • Level 1: -20 points/case
  • Level 2: -10 points/case
  • Level 3: -5 points/case
• Bonuses:
  • Automation support: +5 points
  • Learning function implementation: +5 points
  • Proven improvement cases: +5 points

Quality Thresholds:

• 95-100: World-class standard (industry recommended)
• 90-94: Excellent (production ready)
• 80-89: Good (operable with minor improvements)
• 70-79: Normal (improvement needed)
• 60-69: Requires improvement (substantial correction needed)
• 50-59: Requires substantial correction (fundamental revision needed)
• ≤ 49: Prohibited for use (complete redesign required)