---
name: ecc-rules
description: Universal coding standards, security rules, and development workflow principles. Auto-activates on any coding task. Covers immutability, file organization, error handling, input validation, security checklist, git workflow, testing requirements, Python/FastAPI patterns, web design quality, and API design conventions. Adapted from ECC (Everything Claude Code).
---

# ECC Rules — Universal Development Standards

These rules apply to ALL coding tasks. They are non-negotiable standards.

## Coding Style

### Immutability (CRITICAL)

ALWAYS create new objects, NEVER mutate existing ones. Return new copies with changes applied.

### File Organization

MANY SMALL FILES > FEW LARGE FILES:
- 200-400 lines typical, 800 max
- Organize by feature/domain, not by type
- High cohesion, low coupling

### Error Handling

- Handle errors explicitly at every level
- User-friendly messages in UI code
- Detailed context in server logs
- Never silently swallow errors

### Input Validation

- Validate all user input at system boundaries
- Use schema-based validation (Pydantic for Python)
- Fail fast with clear messages
- Never trust external data

### Code Quality Checklist

- Functions < 50 lines
- Files < 800 lines
- No deep nesting (> 4 levels)
- No hardcoded values (use constants or config)
- No mutation

## Security Rules

### Before ANY Deployment

- [ ] No hardcoded secrets (API keys, passwords, tokens)
- [ ] All user inputs validated
- [ ] SQL injection prevention (parameterized queries)
- [ ] XSS prevention (sanitized HTML)
- [ ] Authentication/authorization verified
- [ ] Rate limiting on all endpoints
- [ ] Error messages don't leak sensitive data
- [ ] HTTPS enforced
- [ ] CORS properly configured

### Secret Management

- NEVER hardcode secrets in source code
- ALWAYS use environment variables
- Validate required secrets exist at startup
- Rotate any exposed secrets immediately

## Development Workflow

### Research & Reuse FIRST (mandatory)

Before writing ANY new code:
1. Search for existing implementations (GitHub, package registries)
2. Check library docs for the right approach
3. Prefer battle-tested libraries over hand-rolled solutions
4. Look for open-source projects solving 80%+ of the problem

### Plan Before Execute

1. Understand requirements fully
2. Break into phases
3. Identify dependencies and risks
4. Then implement

### Testing Requirements

- Minimum 80% coverage target
- Write tests first when possible (TDD)
- Unit tests for individual functions
- Integration tests for API endpoints
- Verify after each significant change

## Python-Specific Rules

### Standards

- PEP 8 conventions
- Type annotations on ALL function signatures
- Use `ruff` for linting, `black` for formatting

### Immutable Data

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class Config:
    name: str
    value: str
```

### FastAPI Patterns

- Put app construction in `create_app()`
- Keep routers thin; business logic in services
- Use `async def` for I/O endpoints
- Separate request/response schemas
- Use `Depends()` for DB sessions and auth
- Never expose passwords/tokens in response models
- Rate-limit auth and write-heavy endpoints

## Web Design Quality

### Anti-Template Policy

Do NOT ship generic template-looking UI. Every frontend must demonstrate:
- Clear hierarchy through scale contrast
- Intentional spacing rhythm
- Depth through overlap, shadows, or motion
- Typography with character
- Hover/focus/active states that feel designed

### Banned Patterns

- Default card grids with no hierarchy
- Stock hero with gradient blob
- Unmodified library defaults as "finished"
- Safe gray-on-white with one accent color
- Dashboard-by-numbers layouts

## Git Workflow

### Commit Format

`<type>: <description>`

Types: feat, fix, refactor, docs, test, chore, perf, ci

### Before Committing

- All tests pass
- No security vulnerabilities
- Code reviewed
- No console.log or debug statements

## API Design Conventions

### URL Structure

- Resources are nouns, plural, lowercase, kebab-case
- Query params for filtering/sorting/pagination
- Sub-resources for relationships
- Verbs only for non-CRUD actions

### Response Format

Consistent envelope: success indicator, data payload, error message, pagination metadata.

### Status Codes

- 200 OK (GET, PUT, PATCH with body)
- 201 Created (POST, include Location header)
- 204 No Content (DELETE)
- 400 Bad Request (validation failure)
- 401 Unauthorized (no/invalid auth)
- 403 Forbidden (auth valid but insufficient)
- 404 Not Found
- 429 Too Many Requests (rate limited)
- 500 Internal Server Error