A comprehensive collection of software development best practices applicable across various technology stacks and project types.
Write short, focused functions with a single responsibility.
Use clear, descriptive names for variables, functions, and classes.
Avoid deep nesting; prefer early returns and guard clauses.
Keep functions and methods to a reasonable length (typically under 30 lines).
Always handle errors explicitly rather than silently ignoring them.
Use wrapped errors for traceability and context.
Provide meaningful error messages that help with debugging.
Fail fast and fail loudly during development.
Organize code into logical modules and packages.
Separate concerns: keep business logic separate from infrastructure code.
Use consistent file and folder naming conventions.
Follow the principle of least surprise in API design.
Structure code into distinct layers:
Prefer composition over inheritance.
Program to interfaces, not implementations.
Use dependency injection for testability and flexibility.
Design for change: isolate business logic and minimize framework lock-in.
Apply SOLID principles where appropriate.
Write tests that are fast, isolated, and repeatable.
Use table-driven tests for testing multiple scenarios.
Mock external dependencies cleanly.
Aim for high test coverage of business-critical code.
Test interactions between components and external systems.
Use separate test configurations and databases.
Clean up test data after each test run.
Separate fast unit tests from slower integration tests.
Run fast tests frequently during development.
Include tests in CI/CD pipelines.
Validate all inputs at service boundaries.
Never trust user input; sanitize and validate everything.
Use parameterized queries to prevent SQL injection.
Use secure defaults for tokens and sessions.
Implement proper access control at every layer.
Store secrets securely; never commit them to version control.
Use HTTPS for all communications.
Implement rate limiting to prevent abuse.
Use circuit breakers for external service calls.
Profile before optimizing; avoid premature optimization.
Measure and benchmark regularly.
Focus on hot paths and frequently executed code.
Minimize memory allocations in critical paths.
Use connection pooling for database and network connections.
Implement proper resource cleanup and disposal.
Cache expensive computations and frequently accessed data.
Use appropriate cache invalidation strategies.
Consider cache consistency and freshness requirements.
Use structured logging (JSON format for production).
Include relevant context: request IDs, user IDs, timestamps.
Log at appropriate levels: DEBUG, INFO, WARN, ERROR.
Avoid logging sensitive information.
Track key metrics: latency, throughput, error rates.
Set up alerts for anomalies and threshold violations.
Use dashboards for visibility into system health.
Implement distributed tracing for microservices.
Propagate trace context across service boundaries.
Record important attributes in spans for debugging.
Document public APIs with clear descriptions.
Explain the "why" not just the "what".
Keep documentation close to the code it describes.
Update documentation when code changes.
Maintain a clear README with setup instructions.
Document architecture decisions (ADRs).
Provide contribution guidelines for team members.
Write clear, concise commit messages.
Make atomic commits that represent a single logical change.
Keep commits small and focused.
Use feature branches for new development.
Keep the main branch stable and deployable.
Review code before merging to main.
Run tests automatically on every commit.
Enforce code formatting and linting.
Include security scanning in the pipeline.
Use consistent development environments across the team.
Document setup steps and prerequisites.
Automate common development tasks.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
