Coding Best Practices

---
name: coding-best-practices
description: General coding principles for writing clean, maintainable code. Triggers on any development work, code reviews, refactoring, or when adding dependencies. For frontend/React code, also apply web-ui-best-practices and react-best-practices.
---

# Coding Best Practices

## Related Skills

- **Frontend code**: Also apply `web-ui-best-practices`
- **React code**: Also apply `react-best-practices`

## Core Principles

### Fix Root Causes

- Fix from first principles; find the source instead of applying bandaids
- If a fix feels like a workaround, it probably is—dig deeper

### Simplicity

- Write idiomatic, simple, maintainable code
- Prefer the most straightforward solution to the problem
- Prefer small helpers or state-driven flow to keep cyclomatic complexity low

### Clean Up Ruthlessly

- Leave each repo better than you found it
- Delete unused code immediately—don't let junk linger
- If a function no longer needs a parameter, remove it and update callers
- If a helper is dead, delete it

### No Breadcrumbs

- When deleting or moving code, do not leave comments in the old location
- No `// moved to X`, no `// relocated`—just remove it
- Describe changes in your response, not in the code

## Code Organization

### File Length

- Use judgment based on complexity rather than strict line limits
- Files are too long when they become difficult to navigate or understand
- If a file has multiple distinct concerns, split it
- Aim for files that can be read and understood in a single sitting

### Component Files

- One primary React component per file
- Small helper components (variants, icon sets, button sizes) can coexist if they're tightly coupled
- Group related components into folder structures (e.g., `components/` for primary, `components/Button/` with sub-components)

### Separation Principles

- Separate concerns when they can be used independently or tested in isolation
- Types/interfaces that are shared across multiple files → `types/` or `@types`
- Utility functions used in multiple places → `utils/` organized by domain
- Custom hooks used by multiple components → `hooks/`
- Constants and config → `config/` or `constants/`
- Keep things together that change together

### Directory Structure

- Organize by feature/domain, not by file type (e.g., `auth/` not `components/auth/`, `hooks/auth/`)
- Flatten directories when possible—avoid deep nesting
- Use index files for clean imports (`export * from './AuthButton'`)

## Dependencies

Before adding a new dependency:
- Quick health check: recent releases/commits?
- Reasonable adoption/community?
- Actively maintained?
- Does it solve a problem we can't easily solve ourselves?

## When Unsure

1. Read more code, documents, or files
2. If still stuck, ask with short options
3. If there are conflicts or ambiguity, call them out and take the safer path

## Context Awareness

- If project or repo-specific guidance conflicts with these rules, follow project guidance first
- Assume other agents or the user might land commits mid-run; refresh context before summarizing or editing
- If changes look unrecognized and continuing is problematic, stop and ask