---
name: conventions
description: How code is written in this project — naming, structure, patterns, and style. Load when writing new code or reviewing existing code.
triggers:
  - "convention"
  - "pattern"
  - "naming"
  - "style"
  - "how should I"
  - "what's the right way"
edges:
  - target: context/architecture.md
    condition: when a convention depends on understanding the system structure
last_updated: [YYYY-MM-DD]
---

# Conventions

## Naming
<!-- How things are named in this codebase.
     Cover: files, functions, variables, classes, database tables/columns — whichever are non-obvious.
     Only include conventions that are actually enforced, not aspirational.
     Minimum 3 items. If you cannot find 3, write "[TO DETERMINE]" — do not pad with generic advice.
     IMPORTANT: Write imperative rules ("Use...", "Never..."), not suggestions ("Consider...", "You might...").
     Claude receives this with a disclaimer saying "may or may not be relevant" — vague language gets ignored.
     Length: 3-7 items.
     Example:
     - Files: Use kebab-case (`user-profile.ts`, not `UserProfile.ts`).
     - Functions: Use camelCase, verb-first (`getUserById`, not `userById`).
     - Database columns: Use snake_case (`created_at`, not `createdAt`). -->

## Structure
<!-- How code is organised within files and across the codebase.
     Cover the things the agent is most likely to get wrong.
     Minimum 3 items. If you cannot find 3, write "[TO DETERMINE]" — do not pad with generic advice.
     Write as commands, not descriptions: "Put X in Y" not "X is usually in Y".
     Length: 3-7 items.
     Example:
     - Put business logic in services/, never in route handlers.
     - Export a single class per service file.
     - Place tests next to the file they test (`user.service.ts` → `user.service.test.ts`). -->

## Patterns
<!-- Recurring code patterns to follow consistently.
     Include concrete before/after examples for the most important ones.
     Minimum 2 patterns. If you cannot find 2, write "[TO DETERMINE]".
     Start each pattern with an imperative verb: "Use...", "Return...", "Never...".
     Length: 2-5 patterns with examples.
     Example:
     Return Result objects for error handling — never throw from the service layer:
     ```
     // Correct
     return { success: true, data: user }
     return { success: false, error: 'User not found' }

     // Wrong — never do this
     throw new Error('User not found')
     ``` -->

## AI Response Efficiency
<!-- These conventions reduce token cost. Output tokens cost 5x more than input. -->
- Respond concisely. Lead with the answer or action, not the reasoning.
- No trailing summaries repeating what was just done.
- Only add code comments where the logic is non-obvious.
- Prefer editing existing files over creating new ones.
- When reading context via MCP, use `cai_search` or `mode: summary` before loading full files.

## Verify Checklist
<!-- A short checklist the agent runs against any code it writes in this project.
     These are the things most likely to go wrong based on this specific codebase.
     The agent should explicitly check each item before presenting output.
     Minimum 4 items. If you cannot find 4, write "[TO DETERMINE]".
     Length: 4-8 items.
     Example:
     Before presenting any code:
     - [ ] Business logic is not in route handlers
     - [ ] All database access goes through the repository layer
     - [ ] Error handling uses the Result type, not exceptions
     - [ ] New files follow the naming convention above -->