Documentation

Standards

Coding conventions for Catalyst projects.

Philosophy

Catalyst prioritises clarity over cleverness. Code should be simple, explicit, and easy for both humans and AI to read and modify.

Core Rules

  • Keep code simple — no over-abstraction
  • No premature optimisation
  • No defensive fallbacks without clear need
  • Prefer explicit over clever
  • Comments explain WHY, not what

Quality Expectations by Stage

Code quality requirements change as a project progresses through stages.

POC
  • • Working code that demonstrates concept
  • • Basic error handling on happy path
  • • No tests required (but recommended)
  • • Mock data acceptable
  • • Comments for complex logic only
MVP
  • • Core happy-path tested
  • • Proper error handling
  • • Real data integration
  • • Basic TypeScript strictness
  • • Code review before merge
MMP
  • • Comprehensive test coverage
  • • Edge case handling
  • • Performance optimised
  • • Security reviewed
  • • Documentation complete
PROD
  • • Full test suite passing
  • • Monitoring instrumented
  • • Logging for debugging
  • • No known security issues
  • • Operational runbook

AI-Friendly Code Principles

Code that's easy for AI to understand and modify correctly.

Simple is better

Prefer straightforward solutions. AI struggles with clever abstractions.

Explicit is better

Avoid implicit behavior. Name things clearly. Make types explicit.

Minimal abstraction

Only abstract when there's clear repetition. Don't preemptively abstract.

Consistent patterns

Use the same patterns throughout. Inconsistency confuses AI.

Good file structure

One concept per file. Clear naming. Logical folder organisation.

File Headers

Every new file should include a header comment:

/**
 * CATALYST - {File Purpose}
 *
 * Brief description of what this file does.
 */

UI Component Headers

UI components in components/ui/ include source and customisation tracking:

/**
 * CATALYST - Button Component
 *
 * @source shadcn/ui v3.6.2 + @base-ui/react v1.0.0
 * @customised No — stock component
 */

When customising, update the header to document changes:

/**
 * @customised Yes
 *   - Added size="xl" variant
 *   - Changed default border radius
 */

PR/Review Expectations

POC Stage

  • • Lightweight review
  • • Focus on "does it work?"
  • • No blocking on style issues

MVP+ Stages

  • • Full code review required
  • • Check for security issues
  • • Verify test coverage
  • • Enforce coding standards

Configuration

  • Never hardcode configurable values — use lib/config.ts
  • Never hardcode navigation — use lib/navigation.ts
  • Check AGENTS.md for AI-specific conventions

What NOT to Do

  • Don't over-abstract or over-engineer
  • Don't add defensive fallbacks without clear need
  • Don't invent scope beyond provided documents
  • Don't duplicate config values
  • Don't hardcode URLs — add to config.links

Reference

See AGENTS.md in the repo root for the complete AI agent reference.