Conventions

Conventions — Analyze Codebase & Build Convention Files

You analyze the codebase and create or update the .conventions/ directory. This directory is the single source of truth for project patterns — it encodes taste once, so every agent (and human) follows the same conventions.

Target Structure

.conventions/
  gold-standards/           # 20-30 line exemplary code snippets
    [pattern-name].tsx/ts   # one file per pattern (form, api-endpoint, hook, etc.)
  anti-patterns/            # what NOT to do (with code examples)
    [avoid-something].md    # one file per anti-pattern
  checks/                   # automated pass/fail rules
    naming.md               # naming conventions (regex patterns, examples)
    imports.md              # allowed/forbidden import patterns

How It Works

Step 1: Check current state

Glob(".conventions/**/*")

• If .conventions/ exists → this is an update (add missing patterns, refresh stale ones)
• If .conventions/ does not exist → this is a bootstrap (create from scratch)

Step 2: Dispatch researchers (parallel)

Spawn 3 researchers in parallel to scan the codebase:

Task(
  subagent_type="Explore",
  prompt="Analyze this project's STRUCTURE and STACK.
  Return: framework, language, package manager, DB, key libraries,
  directory structure, where API routes/pages/components live.
  Be specific — file paths and command names. Under 30 lines."
)

Task(
  subagent_type="Explore",
  prompt="Find the 5-7 BEST example files in this codebase — files that represent
  'how things are done here'. Look for:
  - A well-structured UI component
  - An API endpoint / router
  - A custom hook
  - A form component
  - A test file
  - A database query / migration
  For each: return the file path, what pattern it shows, and the FULL file content.
  Skip patterns that don't exist in this project."
)

Task(
  subagent_type="Explore",
  prompt="Analyze NAMING CONVENTIONS and IMPORT PATTERNS in this codebase.
  Check:
  - File naming: kebab-case? camelCase? PascalCase? (check src/ files)
  - Function/variable naming: camelCase? snake_case?
  - Component naming: PascalCase?
  - DB tables/columns: snake_case? camelCase?
  - API endpoints: /kebab-case? /camelCase?
  - Import patterns: what's imported from where, any barrel exports, any forbidden imports
  - Design system: what UI library, any wrapper components
  Return specific patterns with regex examples where possible. Under 40 lines."
)

Step 3: Build conventions

From researcher findings, create the files:

Gold standards — For each pattern found by the reference researcher:

• Extract the BEST 20-30 lines that demonstrate the pattern
• Strip implementation-specific details, keep the structural skeleton
• Add a 2-line comment at the top: what this file demonstrates and what to pay attention to
• File name = pattern name in kebab-case (e.g., api-endpoint.ts, form-component.tsx)

Anti-patterns — Look for:

• Inconsistencies found by researchers (some files do X, others do Y → the minority is an anti-pattern)
• Common mistakes visible in the codebase (raw HTML where design system should be used, direct DB calls where ORM should be used)
• Each anti-pattern file: short description, BAD example, GOOD example

Checks — From naming researcher:

• naming.md: file naming, function naming, component naming, DB naming — with regex patterns and examples
• imports.md: what should be imported from where, forbidden imports

Step 4: Write files

If bootstrap (no .conventions/ yet):

• Create the full directory structure
• Write all discovered gold standards, anti-patterns, and checks

If update (.conventions/ already exists):

• Read existing files first
• Add new patterns that weren't covered
• Update patterns that have drifted from what the codebase actually does
• Do NOT delete existing files — only add or update
• Report what was added/changed

Output format: the "now → after" table

The report is read by a product person, not an engineer. Any conclusion that involves a choice or a change is presented as a table framed by the outcome the user sees — not by how the system is built.

When there is a fork (something must be chosen):

Below the table, a "Why" block: one line per option (what it wins, what it costs). Then one line: "Recommend X, because …".

When there is no fork — a result delivered or a problem found: the same table with two columns, "Before" and "After" (for a problem: "Now" and "If fixed").

Rules for filling it in:

• Rows are real user situations, never system components. "Scanned a barcode and typed 73 g", not "the barcode_service handler".
• Cells say what the person will see, concretely and with numbers: "calories for 60 g instead of 73", not "incorrect calculation".
• The "Now" column is mandatory — without a baseline the options have nothing to compare against. If the thing doesn't exist yet, write "doesn't exist".
• Include at least one edge-case row: typo, empty input, error. That is usually where the options actually diverge.
• 2-4 rows, 2-3 options. More means the thinking isn't finished and the choice is being dumped on the reader.
• Name options by meaning ("trust the person" / "trust the package"), never "Option 1/2".

No fork and no change means no table: one line saying what you're doing and why. Technical detail (files, line numbers, stack traces) belongs under the conclusion as evidence, never instead of it. Write the table in the language the user is speaking.

Step 5: Report

══════════════════════════════════════════════════
CONVENTIONS {CREATED / UPDATED}
══════════════════════════════════════════════════

Gold standards:
  [created/updated] .conventions/gold-standards/api-endpoint.ts
  [created/updated] .conventions/gold-standards/form-component.tsx
  ...

Anti-patterns:
  [created] .conventions/anti-patterns/avoid-inline-styles.md
  ...

Checks:
  [created/updated] .conventions/checks/naming.md
  [created/updated] .conventions/checks/imports.md

Total: N files created, M files updated
══════════════════════════════════════════════════

Rules

• Gold standards are 20-30 lines max — short enough to include in agent prompts as few-shot examples
• Every gold standard has a 2-line header comment explaining what it demonstrates
• Anti-patterns always show BAD → GOOD comparison
• Checks use regex patterns where possible for automated verification
• Do NOT invent patterns — only document what actually exists in the codebase
• If the codebase is inconsistent (50/50 split), pick the better pattern and note the inconsistency in an anti-pattern file
• Skip categories that don't apply (no DB? skip DB gold standard)

Reference Files

• references/examples.md — Example convention files showing the expected format and quality level for gold standards, anti-patterns, and checks. Read this before generating convention files to ensure consistent quality and format.