@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, with .agents/ linked to package-provided agent assets.

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/ 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/ AGENTS.md

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

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/configuration | Adding config, secrets, or third-party dependencies: SSM, LaunchDarkly, DB, NPM packages | | common/coreLibraries | Adding dependencies, implementing functionality, or debugging errors involving a @clipboard-health/* library | | 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/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: technology stack, file organization, where business logic lives | | frontend/customHooks | Creating React custom hooks: naming, shared state with constate | | frontend/dataFetching | Implementing data fetching and error handling: React Query, API calls, caching, parsedApi | | frontend/e2eTesting | Writing E2E tests with Playwright | | frontend/reactComponents | Building UI components: structure, composition, modals, bottom sheets, interactive elements, a11y, Storybook | | 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/ and .agents/ to git and commit:

   git add .rules/ .agents/ 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.