coding-rules git:20260719.3848a77A

Immutable. This exact content is served forever at /api/v1/blob/5dcf80de9854d40f.

---
name: coding-rules
description: "Language-agnostic coding standards for maintainability, readability, and quality. Use when: implementing features, refactoring code, reviewing code quality, or writing functions."
---

# Coding Rules

## Language-Specific References

For language-specific rules, also read:
- **TypeScript/React**: [references/typescript.md](references/typescript.md)

## Core Philosophy [MANDATORY]

1. **Maintainability over Speed**: Prioritize long-term code health
2. **Simplicity First**: YAGNI principle — simplest solution that meets requirements
3. **Design Convergence**: Deliver the current required outcome with the least new design surface. Add surface only to satisfy a current requirement, verified constraint, observed problem, or evidence-backed material risk; among sufficient options, choose the lowest-lifecycle-cost option.
4. **Explicit over Implicit**: Clear intentions through code structure and naming
5. **Delete over Comment**: Remove unused code instead of commenting it out

**ENFORCEMENT**: Every code change MUST align with these principles

## Design Surface Terms [MANDATORY]

Use these definitions when classifying Design Convergence additions or code-review escalation.

- **Maintenance-surface-bearing elements**: persistent state; public-contract or cross-boundary fields/props; behavioral modes, flags, or variants; reusable abstractions; extracted services; shared utilities; component splits.
- **Non-surface elements**: private local variables, internal helper functions with no external observers, test fixtures or mocks, temporary migration scaffolding removed before completion, and private implementation details confined to one function or file.
- **Classification precedence**: When an element matches both surface-bearing and non-surface conditions, classify it as surface-bearing.
- **Selection rule**: Add a surface-bearing element only when it is required by a current requirement, verified constraint, observed problem, or evidence-backed material risk. Prefer fewer new elements only when the remaining candidates are otherwise sufficient and equivalent.
- **Relation to YAGNI**: YAGNI decides present vs. future need over time; Design Convergence minimizes surface area for the current accepted scope.

## Code Quality [MANDATORY]

- Resolve technical debt within confirmed scope or dependencies required for its outcome; report other debt separately
- Use meaningful, descriptive names from the problem domain
- Extract magic numbers and strings into named constants
- Keep code self-documenting

## Function Design [MANDATORY]

- **0-2 parameters** per function (use objects for 3+)
- Single responsibility — each function MUST do one thing well
- Keep functions < 50 lines
- Use pure functions where possible — separate data transformation from side effects
- Use early returns to keep nesting ≤ 3 levels
- **Inject external dependencies explicitly** — pass as parameters for testability

## Error Handling [MANDATORY]

- **Always handle errors**: Log with context or propagate explicitly — error suppression is PROHIBITED
- **Fail fast**: Detect and report errors early
- **Protect sensitive data**: Mask passwords, tokens, PII from logs
- Use language-appropriate error handling mechanisms
- Include error context when re-throwing

**ENFORCEMENT**: Zero silent error suppression — every error MUST have log output and appropriate handling

## Dependency Management

- **Inject external dependencies explicitly** — pass as parameters for testability
- Depend on abstractions, not concrete implementations
- Minimize inter-module dependencies

## Reference Representativeness

### Verifying References Before Adoption

When adopting patterns, APIs, or dependencies from existing code:
- If referencing only nearby files, verify the pattern is representative across the repository before adopting it
- If multiple approaches coexist, identify the majority pattern and make a deliberate choice
- If adopting an external dependency, verify repository-wide usage distribution for that dependency and its version
- If repository evidence is insufficient to choose an appropriate dependency version, escalate instead of guessing
- If following an existing pattern when alternatives exist, state the reason for following it

### Principle

Nearby code is a starting point for investigation, not a sufficient basis for adoption. Confirm that the reference is representative of repository conventions before using it as the model.

## Performance

- **Measure first**: Profile before optimizing — no premature optimization
- Focus on algorithms over micro-optimizations
- Choose data structures based on access patterns

## Code Organization

- One primary responsibility per file
- Group related functionality together
- Separate concerns: domain logic, data access, presentation
- Keep files ≤ 500 lines

## Commenting Principles

- Prefer names, types, and structure over comments
- Add comments only for why, limitations, edge cases, or public API contracts
- No historical information — use version control
- Remove commented-out code
- Keep comments concise and timeless

## Refactoring [SAFE CHANGE PROTOCOL]

**STEP 1**: Understand current state
**STEP 2**: Make one small change
**STEP 3**: Run tests — confirm all pass
**STEP 4**: Repeat from STEP 2

**Triggers**: duplication, functions > 50 lines, complex conditionals

**ENFORCEMENT**: Each step MUST maintain working state

## Security

### Secure Defaults
- Store credentials and secrets through environment variables or dedicated secret managers
- Use parameterized queries (prepared statements) for all database access
- Use established cryptographic libraries provided by the language or framework
- Generate security-critical values (tokens, IDs, nonces) with cryptographically secure random generators
- Encrypt sensitive data at rest and in transit using standard protocols

### Input and Output Boundaries
- Validate all external input at system entry points for expected format, type, and length
- Encode output appropriately for its rendering context (HTML, SQL, shell, URL)
- Return only information necessary for the caller in error responses; log detailed diagnostics server-side

### Access Control
- Apply authentication to all entry points that handle user data or trigger state changes
- Verify authorization for each resource access, not only at the entry point
- Grant only the permissions required for the operation (files, database connections, API scopes)

### Knowledge Cutoff Supplement (2026-03)
- OWASP Top 10:2025 shifted from symptoms to root causes; added "Software Supply Chain Failures" (A03) and "Mishandling of Exceptional Conditions" (A10)
- Recent research indicates AI-generated code shows elevated rates of access control gaps — treat authentication and authorization as high-priority review targets
- OpenSSF published "Security-Focused Guide for AI Code Assistant Instructions" — recommends language-specific, actionable constraints over generic advice
- For detailed detection patterns, see `references/security-checks.md`

## Version Control [MANDATORY]

- Atomic, focused commits with clear messages
- Commit working code that passes all tests
- Never commit debug code or secrets

**ENFORCEMENT**: Code MUST pass all quality checks before commit