Module @clipboard-health/ai-rules

@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.

Install
Usage
Available Rules
Contributing Rules
Migration from v1
Local development commands

Install

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

Usage

Quick Start

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.

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

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"
  }
}

Run:

npm install  # Runs postinstall automatically

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
`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`	Updating Clipboard AI rules or modifying generated .rules, AGENTS.md, CLAUDE.md, or OVERLAY.md files
`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, or reviewing pull requests
`common/libraryAuthoring`	Authoring shared library code: @clipboard-health/* packages or shared library modules within services (e.g., src/lib)
`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: naming, structure, testing
`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/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:

Edit or create the rule file under rules/<category>/ with a frontmatter description (the "When to Read" text).
Run npx tsx scripts/populateReadme.ts to regenerate the tables above (a test fails if they drift).
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/.

Update the package:

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

Run install to trigger sync:
```
npm install
```

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.