@clipboard-health/ai-rules

Pre-built AI agent rules for consistent coding standards. Uses a retrieval-based approach: generates a compressed index in AGENTS.md pointing to copied .rules/ files that agents read on demand.

Table of contents

• Install
• Usage
  • Quick Start
  • Include/Exclude Rules
  • Updating Rules
• Available Rules
• Contributing Rules
• Migration from v1
• Local development commands

Install

npm install --save-dev @clipboard-health/ai-rules

Usage

Quick Start

1. If you have an existing AGENTS.md and/or CLAUDE.md file in your repository, rename it to OVERLAY.md. The sync script appends this file's contents to generated AGENTS.md so it's loaded into LLM agent contexts.

2. Choose the profile that matches your project type:

   | Profile | Includes | Use For | | -------------- | --------------------------- | -------------------------------------- | | common | common | TypeScript libraries, generic projects | | frontend | common + frontend | React apps, web apps | | backend | common + backend | NestJS services, APIs | | fullstack | common + frontend + backend | Monorepos, fullstack apps | | datamodeling | datamodeling | DBT data modeling |

3. Add it to your package.json:

   {
     "scripts": {
       "sync-ai-rules": "node ./node_modules/@clipboard-health/ai-rules/scripts/sync.js [PROFILE_NAME]",
       "postinstall": "node --run sync-ai-rules"
     }
   }

4. Run:

   npm install  # Runs postinstall automatically

5. Commit the generated files:

   git add .rules/ AGENTS.md CLAUDE.md
   git commit -m "feat: add AI coding rules"

Include/Exclude Rules

Fine-tune which rules are synced using --include and --exclude:

# Backend profile without MongoDB rules
node sync.js backend --exclude backend/mongodb

# Common profile plus one backend rule
node sync.js common --include backend/architecture

# Multiple overrides
node sync.js backend --exclude backend/mongodb backend/postgres --include frontend/testing

Unknown rule ids are skipped with a warning so a stale --include/--exclude never breaks installs.

Update your package.json script accordingly:

{
  "scripts": {
    "sync-ai-rules": "node ./node_modules/@clipboard-health/ai-rules/scripts/sync.js backend --exclude backend/mongodb"
  }
}

Updating Rules

When we release new rules or improvements:

# Update the package
npm update @clipboard-health/ai-rules

# The postinstall script automatically syncs the latest files
npm install

# Review the changes
git diff .rules/ AGENTS.md

# Commit the updates
git add .rules/ AGENTS.md CLAUDE.md
git commit -m "chore: update AI coding rules"

Rules are occasionally split so each one carries a narrower retrieval trigger. If you pin individual rule ids with --include rather than taking a whole category, check the diff for new ids after upgrading: a stale --include keeps resolving, so you lose the split-out rules without a warning.

Available Rules

Each rule's "When to Read" text comes from the description field in the rule file's YAML frontmatter — the single source of truth used for the generated AGENTS.md index and the tables below.

backend

| Rule ID | When to Read | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | backend/architecture | Structuring NestJS modules, services, repos: three-tier, microservices, ts-rest contracts | | backend/asyncMessaging | Working with queues, async messaging, or background jobs; planning their rollout or rollback; adding event-dependent behavior | | backend/infrastructure | Provisioning infrastructure: Terraform, Docker, ECS, DNS | | backend/mongodb | Working with MongoDB/Mongoose: schemas, indexes, queries, transactions, migrations | | backend/notifications | Implementing notifications via Knock: push notifications, deep links, workflow design | | backend/postgres | Working with Postgres: column types, schema changes, query patterns, Prisma TypedSQL | | backend/restApiDesign | Designing REST APIs: JSON:API, auth, validation, pagination, ts-rest contracts, DTOs | | backend/serviceTests | Writing service tests: test data, background jobs, bug handling, migrations |

common

| Rule ID | When to Read | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | common/aiRules | Editing Clipboard agent instructions: shared rules, repository overlays, or generated .rules, AGENTS.md, and CLAUDE.md files | | common/ciRunners | Writing or editing GitHub Actions workflows: choosing runs-on runners, runner OS and egress constraints | | common/configuration | Adding config, secrets, or third-party dependencies: SSM, LaunchDarkly, DB, NPM packages | | common/containerRegistry | Choosing or pulling a container image: Dockerfile FROM, Compose services, CI workflow images | | common/coreLibraries | Adding dependencies, implementing functionality, or debugging errors involving a @clipboard-health/* library | | common/dateTime | Working with dates, times, timezones, or date comparisons | | common/errorHandling | Returning or throwing errors: ServiceResult, ServiceError, ERROR_CODES, toError | | common/featureFlags | Creating or managing feature flags: naming, lifecycle, SDK usage, Zod schemas | | common/gitWorkflow | Writing commit messages, PR titles and descriptions, or reviewing pull requests | | common/groundtruth | Identifying owners or understanding architecture across Clipboard systems | | common/libraryAuthoring | Authoring shared library code: @clipboard-health/* packages or shared library modules within services (e.g., src/lib) | | common/localChecks | Running type checks, lint, or tests locally to verify a change | | common/loggingObservability | Adding logging, metrics, monitoring, or observability: levels, context, PII, Datadog | | common/rulesEngine | Writing or modifying @clipboard-health/rules-engine rule functions | | common/testing | Writing unit tests: conventions, naming, structure | | common/typeScript | Writing ANY TypeScript code |

datamodeling

| Rule ID | When to Read | | -------------------------------------- | ------------------------------------------------------------------------------ | | datamodeling/analytics | Querying analytics data: dbt-mcp, Snowflake, source columns, output formatting | | datamodeling/castingDbtStagingModels | Casting data types in dbt staging models | | datamodeling/dbtModelDevelopment | Developing dbt models or diagnosing schema and ingestion failures | | datamodeling/dbtYamlDocumentation | Writing dbt YAML documentation and schema files |

frontend

| Rule ID | When to Read | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | frontend/architecture | Frontend architecture: feature-based file organization, where business logic lives | | frontend/customHooks | Creating React custom hooks: naming, shared state with constate | | frontend/dataFetching | Implementing data fetching, API response fixtures, and error handling: React Query, MSW, Playwright, caching, parsedApi | | frontend/designSystem | Implementing UI from the design system or Figma: prefer shared components, theme lookup, optional Code Connect | | frontend/e2eTesting | Choosing and writing Playwright E2E tests for registered critical flows | | frontend/reactComponents | Building UI components: structure, composition, modals, bottom sheets, interactive elements, a11y, Storybook | | frontend/renderScope | Adding or restructuring React state, context, hook returns, wall-clock values, hidden queries/subscriptions, or list filtering | | frontend/styling | Styling components with MUI sx prop: theme tokens, spacing, no CSS/SCSS | | frontend/testing | Writing frontend tests: React Testing Library, component tests |

Contributing Rules

A rule earns its place only if a frontier model would do the wrong thing without it: Clipboard-specific decisions, library choices, naming, and hard-won gotchas. Do not add tutorials, generic best practices, or anything a linter already enforces.

To add or change a rule:

1. Edit or create the rule file under rules/<category>/ with a frontmatter description (the "When to Read" text).
2. Run npx tsx scripts/populateReadme.ts to regenerate the tables above (a test fails if they drift).
3. New categories are directories under rules/; no registration needed.

Migration from v1

v2 replaces the monolithic AGENTS.md with a retrieval-based approach. Rule files are now committed to your repo under .rules/.

1. Update the package:

   npm install --save-dev @clipboard-health/ai-rules@latest

2. Run install to trigger sync:

   npm install

3. Add .rules/ to git and commit:

   git add .rules/ AGENTS.md CLAUDE.md
   git commit -m "feat!: update ai-rules to v2 retrieval-based approach"

Local development commands

See package.json scripts for a list of commands.