general

General development guidelines prioritizing readability over performance, with rules for meaningful comments. Use when writing any code in this project.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026

When & Why to Use This Skill

This Claude skill implements a 'readability-first' development philosophy, ensuring that all generated code is clean, maintainable, and professionally documented. By prioritizing human understanding over performance micro-optimizations and enforcing meaningful, intent-based commenting, it significantly reduces technical debt and improves long-term project scalability.

Use Cases

  • Codebase Standardization: Enforce a consistent coding style across the entire project, ensuring that all AI-generated code integrates seamlessly with professional standards.
  • Intent-Based Documentation: Apply the 'Why, not What' commenting rule to eliminate redundant code descriptions and focus on documenting complex business logic and non-obvious decisions.
  • Legacy Code Refactoring: Use these guidelines to rewrite or clean up existing code, transforming obscure logic into readable and maintainable modules that are easier to audit.
  • AI-Assisted Development: Guide AI agents to produce production-ready code that prioritizes correctness and maintainability, making it ideal for collaborative team environments.
namegeneral
descriptionGeneral development guidelines prioritizing readability over performance, with rules for meaningful comments. Use when writing any code in this project.

General Development Guidelines

Apply these general guidelines to all code.

Priorities

Focus 80% on readability and 20% on performance.

In order of importance:

  1. Correctness and functionality
  2. Readability & Maintainability
  3. Performance

Comments

Add comments only when they explain WHY, not WHAT. The code itself should be readable enough to show WHAT it does.

DO NOT comment obvious operations

// Bad
// increment counter
counter++;

DO comment

  • Business logic reasoning
  • Non-obvious decisions
  • Workarounds or edge cases
  • Complex algorithms (brief summary of approach)

Example of a good comment

// Using ceil() here because partial units must be charged as full units per billing policy
const billableUnits = Math.ceil(usage / unitSize);