Coding Conventions

---
name: coding-conventions
description: Analyzes a scope (a whole repo, a folder, a feature, or a single package) and produces a CLAUDE.md-style reference document that teaches Claude (or any AI coding agent) the coding standards, patterns, conventions, and rules of that scope, so future code generation aligns with the team's conventions and does not break existing patterns. Use when the user says "coding conventions", "coding standards", "write a CLAUDE.md for X", "teach claude the patterns", "generate conventions doc", "AI rules for X", "align claude with this codebase", "write rules for claude", "document the patterns", or wants a reference that future AI sessions can load to follow house style for a specific area.
argument-hint: [scope — path, package, or feature description]
---

# Coding Conventions

Analyze a user-specified scope and produce a reference document aimed at **Claude (or any AI coding agent)** that will be loaded into future sessions to keep code generation aligned with the team's conventions.

This is **not** human onboarding prose. It is an imperative rulebook: "When you do X, do it this way. Never do Y. The pattern for Z is this." Optimize for an AI reader that needs to make the right call fast without re-deriving house style from the codebase each time.

`$ARGUMENTS` may be:
- A path (e.g., `apps/ms-profile`, `libs/infrastructure`)
- A package name (e.g., `@pc-services/ms-cards`)
- A feature or domain description (e.g., "the authorization flow")
- Empty — default to the entire current repository

## Workflow

### 1. Clarify the scope

- Resolve `$ARGUMENTS` to concrete paths. If ambiguous, grep/glob and confirm.
- Default to the full repo if no scope is given.
- State the resolved scope back to the user in one sentence.
- Ask where to write the output. Sensible defaults:
  - Scope = whole repo → `./CLAUDE.md` (or a new file if `CLAUDE.md` already exists — never clobber without confirming)
  - Scope = a subfolder → `<scope>/CLAUDE.md`
  - Otherwise → ask.
- If a `CLAUDE.md` already exists at the target path, read it first and treat this as an **update**, not a rewrite. Preserve user-authored rules; add/refine the rest.

### 2. Discover existing rules

Read everything that already encodes team conventions:

- All existing `CLAUDE.md` / `AGENTS.md` / `README.md` from the repo root down through the scope
- `.cursor/rules/*`, `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md` if present
- `CONTRIBUTING.md`, `STYLE.md`, `ARCHITECTURE.md`, `docs/`
- Linter configs: `eslintrc*`, `tsconfig*.json`, `.prettierrc*`, `ruff.toml`, `pyproject.toml`, `.editorconfig`
- Commit / PR templates: `.github/PULL_REQUEST_TEMPLATE.md`, `commitlint.config.*`
- Husky / lint-staged / pre-commit hooks — these encode enforced rules
- CI config: `.github/workflows/*`, `cloudbuild-*.yaml` — what CI actually enforces
- Test config: `jest.config.*`, `vitest.config.*`, `pytest.ini`

### 3. Extract patterns from code (not just docs)

Docs lie; code is ground truth. Read real code in the scope to verify and extract:

- **Module/file structure** — how a typical feature is organized on disk
- **Naming conventions** — files, classes, functions, variables, env vars, routes, DB tables/columns
- **Boilerplate shape** — controller/service/repo templates, module registration, DI wiring
- **Error handling** — custom error classes, when to throw vs. return, how errors surface to the client
- **Validation** — DTO/schema library, where validators live, how errors are formatted
- **Auth & authorization** — guards, decorators, permission checks, how identity propagates
- **Database access** — ORM/query builder, transaction patterns, migration workflow, RLS/tenancy rules
- **Logging** — logger used, log levels, structured field conventions, PII handling
- **Configuration** — how env vars are read and typed, where secrets live
- **Testing** — framework, file naming, mocking conventions, fixture style, what must be integration vs. unit
- **Commit / PR conventions** — format, signing, what's banned (e.g. `Co-Authored-By`, `--amend`, `--no-verify`)
- **Imports** — aliasing, ordering, barrel files, banned imports
- **Formatting** — what the formatter enforces so Claude doesn't fight it

To extract a pattern, open 2–3 files that implement it and confirm they agree. If they disagree, note it as an inconsistency rather than inventing a rule.

### 4. Write the rules file

Structure the output so an AI agent can scan it fast and apply it without re-reading the codebase. Use **imperative voice** (`Do X`, `Never Y`, `Always Z`). Show **one short code example per rule** when the rule is non-obvious.

Target length: dense but not padded. A good scope-level `CLAUDE.md` is ~150–400 lines. Cut anything that isn't actionable.

---

```markdown
# CLAUDE.md — <Scope Name>

> AI coding agent reference. Load this before generating or editing code in this scope. Rules here override general defaults.

## Purpose of This Scope
1–2 sentences: what this scope is and what it is responsible for. Needed so the agent rejects out-of-scope changes.

## Tech Stack (authoritative)
- Language & version
- Framework & version
- Database / ORM
- Key libraries the agent MUST use (and the ones it MUST NOT reach for as alternatives)

## Module / File Structure
Where things go. For a new feature, the agent must create files in this shape:

\`\`\`
src/modules/<feature>/
├── <feature>.module.ts
├── <feature>.controller.ts
├── <feature>.service.ts
├── dto/
│   └── *.dto.ts
└── <feature>.service.spec.ts
\`\`\`

Include a one-line rule per directory ("DTOs live here; do not put them in the controller").

## Naming Rules
Concrete conventions, one line each. Examples:
- Files: `kebab-case.ts`
- Classes: `PascalCase`, service classes end in `Service`
- DB tables: `snake_case`, plural; columns `snake_case`, singular
- Env vars: `SCREAMING_SNAKE_CASE`, prefix with service name
- Route paths: plural nouns, kebab-case

## How to Add a New <Thing>
For each common task the agent will be asked to do, give an exact recipe.

### Adding a new endpoint
1. Create DTO in `dto/` with class-validator decorators.
2. Add method to `<feature>.service.ts` — business logic only, no HTTP concerns.
3. Add route to `<feature>.controller.ts`, wire guards, return a DTO (never an entity).
4. Add `*.spec.ts` covering success + auth failure + validation failure.
5. If the route needs a new permission, add it to `permissions.enum.ts`.

Repeat for: adding a new entity/migration, adding a new background job, adding a new integration client, adding a new env var, etc. Be specific to this scope — skip recipes that don't apply.

## Patterns

### Error handling
- Throw typed exceptions from `<path>/errors.ts`; never throw plain `Error`.
- Map to HTTP in the global filter at `<file>`. Do not catch-and-remap in controllers.
- Example:

\`\`\`ts
throw new NotFoundError('account', id);
\`\`\`

### Validation
- DTOs use `class-validator`. Every field must have a decorator, including `@IsOptional()` for optional fields.
- Transform with `class-transformer` via the global pipe. Don't parse manually.

### Database access
- All queries through the repository layer. Services must not import the ORM directly.
- Every query must scope by `account_id`. RLS is the last line of defense, not the first.
- Transactions use `<helper>`; do not start transactions manually.

### Logging
- Use `<logger>`. Always include `correlationId` and `accountId`.
- Never log secrets, tokens, full request bodies, or PII fields listed in `<file>`.

### Configuration
- Read env vars through `<ConfigService>`; never read `process.env` directly.
- Required vars are declared in `<file>`. Adding a var means updating `.env.example`, the schema, AND the Pulumi stack.

### Testing
- Unit tests: `*.spec.ts` next to source. Mock repositories; do not mock the service under test.
- Integration tests: `test/` directory, real DB via testcontainers. Must pass before merge.
- Run: `<exact command>`.

## Things the Agent Must NOT Do
A short banned list. Be specific — this is the most valuable section.
- Do not introduce a new dependency without calling it out explicitly.
- Do not add `any` — use `unknown` and narrow.
- Do not use `--no-verify`, `--amend`, or force-push.
- Do not add `Co-Authored-By` trailers.
- Do not write comments explaining *what* code does; only *why* when non-obvious.
- Do not generate migration files by hand — use `<command>`.
- Do not cross service boundaries by importing from a sibling `apps/*` package.
- … (continue with scope-specific bans)

## Commit & PR Conventions
- Commit format: `<conventional-commits or whatever the repo uses>`
- PR title / body format
- What CI enforces and will reject (lint, typecheck, tests, formatting)
- Required pre-push command: `<command>`

## Non-Obvious Constraints
Things that aren't in the code but will break production if ignored:
- Settings that must never change
- Coupled services that must be updated together
- Deploy ordering requirements
- Data/schema invariants

## Open Questions
Anything you couldn't determine from the code. Do not invent rules here; flag them for the human to fill in.
```

---

### 5. Present back to the user

After writing the file:
- Report the path written and whether it was a new file or an update.
- List the top 5–10 rules you extracted — the user should sanity-check these.
- Flag any **inconsistencies** you found in the codebase (two files doing the same thing differently) — these need a human decision before they become a rule.
- List any **open questions** you left in the doc.

## Guidelines

- **Imperative voice, not descriptive.** "Throw typed errors" > "The codebase uses typed errors".
- **Ground every rule in real code.** If you can't point to 2+ examples of a pattern in the scope, it isn't an established convention — mark it as a suggestion or leave it out.
- **Prefer bans and recipes over principles.** "Never import X from Y" and "to add an endpoint, do steps 1–5" are far more useful to an agent than "maintain separation of concerns".
- **Deduplicate against parent `CLAUDE.md` files.** If the root `CLAUDE.md` already states a rule, don't restate it — the agent will load both. Only add rules that are specific to this scope or that refine the parent.
- **Don't invent rules.** When the code is inconsistent, say so and surface the inconsistency; do not pick a winner unilaterally.
- **Don't copy prose from the human onboarding guide.** This file is rules, not explanations. If a reader needs to understand *why*, that's what `ENGINEERING_GUIDE.md` is for — link to it.
- **Short, dense, scannable.** An agent under time pressure should be able to grep this file for the rule it needs. Avoid long paragraphs, table-of-contents bloat, and restating defaults.
- **Never clobber an existing CLAUDE.md** without showing the user the diff first.