general
General development guidelines prioritizing readability over performance, with rules for meaningful comments. Use when writing any code in this project.
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.
| name | general |
|---|---|
| description | General 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:
- Correctness and functionality
- Readability & Maintainability
- 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);