Reference Docs — Navigation Guide

Overview

Best practices reference docs used by specialist agents. Covers Supabase/Postgres (backend-specialist) and Vitest testing (all agents writing tests).

Structure

references/
  AGENTS.md                    # This navigation guide
  {prefix}-{topic}.md          # Individual reference files (30 Postgres)
  vitest-best-practices.md     # Consolidated vitest testing guide

Usage

1. Read this file (AGENTS.md) for the full reference index
2. Read individual files for detailed documentation
3. Reference files are loaded on-demand — read only what you need

Vitest Testing

Covers: organization, AAA pattern, parameterized tests, error handling, assertions, test doubles, async testing, performance, vitest features, snapshot testing.

Supabase Postgres

Reference files are named {prefix}-{topic}.md (e.g., query-missing-indexes.md).

Available References

Query Performance (query-):

• query-missing-indexes.md
• query-composite-indexes.md
• query-covering-indexes.md
• query-index-types.md
• query-partial-indexes.md

Connection Management (conn-):

• conn-pooling.md
• conn-limits.md
• conn-idle-timeout.md
• conn-prepared-statements.md

Security & RLS (security-):

• security-rls-basics.md
• security-rls-performance.md
• security-privileges.md

Schema Design (schema-):

• schema-primary-keys.md
• schema-data-types.md
• schema-foreign-key-indexes.md
• schema-lowercase-identifiers.md
• schema-partitioning.md

Concurrency & Locking (lock-):

• lock-short-transactions.md
• lock-deadlock-prevention.md
• lock-skip-locked.md
• lock-advisory.md

Data Access Patterns (data-):

• data-n-plus-one.md
• data-pagination.md
• data-batch-inserts.md
• data-upsert.md

Monitoring & Diagnostics (monitor-):

• monitor-explain-analyze.md
• monitor-pg-stat-statements.md
• monitor-vacuum-analyze.md

Advanced Features (advanced-):

• advanced-jsonb-indexing.md
• advanced-full-text-search.md

31 reference files across 9 categories