Fusion Rule Author

Rule Author

Canonical workflow, templates, and references for authoring AI coding assistant rules. Supports GitHub Copilot, Cursor, and Claude Code.

Internal skill. Users interact via the fusion-rules gateway, which routes to editor-specific agents that follow the workflow defined here.

Scope

This skill provides:

• Workflow (Steps 1–7 below) — the guided authoring process
• Templates (assets/) — starter files for each editor format
• References (references/) — tech-stack examples

It does not provide agents. Agents live in fusion-rules/agents/ and reference this skill's assets and workflow.

Required inputs

Mandatory

• [ ] Repository context (working directory or repo URL)

Gathered during interview

• [ ] Tech stack (languages, frameworks, build tools)
• [ ] Code conventions (naming, formatting, patterns)
• [ ] Testing expectations (framework, coverage, style)
• [ ] Documentation preferences (comments, TSDoc/JSDoc, README standards)
• [ ] Commit and PR conventions
• [ ] Error handling patterns
• [ ] Security or compliance constraints
• [ ] File/path-specific conventions that need scoped rules

Instructions

Step 1 — Assess current state

Check the repository for existing rule files:

.github/copilot-instructions.md
.github/instructions/*.instructions.md
.cursor/rules/*.md
.cursor/rules/*.mdc
.cursor/rules/**/*.md
.cursor/rules/**/*.mdc
CLAUDE.md
.claude/CLAUDE.md
.claude/rules/*.md
.claude/rules/**/*.md

Report what exists, what is missing, and whether updates or new files are needed.

Step 2 — Scan repository

Before interviewing, scan for existing documentation and configuration that encodes conventions. Extract actionable directives from:

Documentation files:

• README.md — project overview, setup, tech stack
• CONTRIBUTING.md — code style, PR workflow, commit conventions
• AGENTS.md, CLAUDE.md — existing AI instructions
• docs/adr/**, adr/**, docs/decisions/** — Architecture Decision Records
• docs/**/*.md — developer guides, onboarding docs, style guides
• SECURITY.md — security policies
• CODE_OF_CONDUCT.md — collaboration guidelines (rarely rule-relevant)

Configuration files:

• package.json / pyproject.toml / *.csproj — tech stack, scripts, dependencies
• tsconfig.json / jsconfig.json — language settings, strictness
• biome.json / .eslintrc* / .prettierrc* / ruff.toml / .editorconfig — formatting and linting
• .github/workflows/*.yml — CI checks, required validations, test commands
• Dockerfile / docker-compose.yml — runtime environment
• Makefile / Justfile / Taskfile.yml — build and task commands

Code patterns (sample, don't exhaustively read):

• Entry points (src/index.*, src/main.*, app.*) — architecture patterns
• Test files — testing framework, naming conventions, file placement
• Directory structure — architectural boundaries, feature organization

For each source, extract: 1. Concrete conventions that can become imperative directives 2. Build/test/lint commands the AI should know 3. Architecture boundaries or patterns to follow 4. Explicit "do this / don't do that" rules

Skip:

• Implementation details that change frequently
• Content that restates language/framework defaults
• Aspirational rules not enforced by CI or team practice

Present summary of discovered conventions to the developer, organized by area, before proceeding to the interview.

Step 3 — Interview (fill gaps)

Use scan results to skip areas already well-documented. Ask focused questions only for gaps. Cover these areas one at a time:

1. Tech stack — languages, frameworks, runtime, package manager 2. Code style — naming conventions, formatting rules, import ordering 3. Architecture — project structure, key patterns (MVC, hexagonal, etc.) 4. Testing — framework, conventions, coverage expectations 5. Documentation — inline comments style, doc generation, README standards 6. Git workflow — branch naming, commit message format, PR expectations 7. Security — sensitive data handling, auth patterns, compliance rules 8. Path-specific concerns — directories or file types needing specialized guidance

For each area, present what the scan found and ask: "Is this accurate? Anything to add or correct?" Don't re-ask for information already captured.

For each convention needing deeper context, use follow-up questions in assets/creation-follow-up.md — purpose, exceptions, boundaries, voice.

Step 4 — Classify guidance

Separate the gathered conventions into buckets:

GitHub Copilot:

Cursor:

Claude Code:

Decision rule: If a convention applies to all files in the repo, it belongs in root / always-on instructions. If it applies only to specific paths or file types, create a scoped rule.

When targeting multiple editors, generate parallel files with equivalent content — do not duplicate guidance within a single editor's files.

Step 5 — Draft rule files

Generate files using templates in assets/:

GitHub Copilot:

• Root instructions: use assets/copilot-instructions-template.md
• Scoped instructions: use assets/scoped-rule-template.md with correct applyTo glob

Cursor:

• Use assets/cursor-rule-template.mdc and set frontmatter accordingly

Claude Code:

• Project instructions: use assets/claude-rule-template.md
• Scoped rules: place in .claude/rules/ with paths frontmatter

Quality rules (enforced during drafting):

• Keep instructions concise — actionable directives, not explanations
• Use imperative voice ("Use camelCase for variables", not "Variables should use camelCase")
• Avoid duplicating guidance between root and scoped files
• Validate applyTo / globs / paths glob patterns match intended files
• Warn if total root instructions exceed ~80 lines (risk of context dilution)
• Warn if scoped instruction file exceeds ~50 lines (GitHub Copilot), ~500 lines (Cursor), ~200 lines (Claude Code CLAUDE.md)
• See references/examples.md for concrete good/bad examples
• See assets/quality-checklist.md for full checklist

Step 6 — Review and refine

Present drafted files to the developer. For each file:

1. Show full content 2. Highlight quality warnings (length, broad globs, duplication) 3. Ask for approval or edits

Step 7 — Write files

After approval, write rule files to the repository. Create .github/instructions/, .cursor/rules/, and/or .claude/rules/ directories as needed.

Confirm final file list and paths before writing.

Expected output

• .github/copilot-instructions.md — root instructions file (created or updated)
• .github/instructions/*.instructions.md — zero or more scoped instruction files
• .cursor/rules/*.mdc — zero or more Cursor rule files (when Cursor is targeted)
• CLAUDE.md or .claude/CLAUDE.md — project instructions (when Claude Code is targeted)
• .claude/rules/*.md — zero or more Claude Code scoped rule files
• Summary of what was created/updated and why

Instructions vs skills vs rules — when to use which

Instructions and rules shape how the AI writes code. Skills define what it can do as structured tasks.

Safety and constraints

Never:

• Embed secrets, tokens, or credentials in rule files
• Generate rules that contradict repository security policies
• Overwrite existing files without showing the diff and getting approval
• Invent conventions — only document what the developer confirms

Always:

• Show drafts before writing any files
• Validate glob patterns against actual repository paths
• Warn on overly broad globs (e.g., **/* captures everything)
• Keep instructions concise and actionable
• Preserve existing content when updating (append or merge, never replace silently)

References

• references/examples.md — concrete examples for different tech stacks
• assets/creation-follow-up.md — per-rule follow-up questions (purpose, exceptions, boundaries, voice)
• assets/frontmatter-scenarios.md — scenario-based frontmatter guide for GitHub Copilot, Cursor, and Claude Code
• assets/copilot-instructions-template.md — starter template for root instructions
• assets/scoped-rule-template.md — starter template for scoped rules
• assets/cursor-rule-template.mdc — starter template for Cursor rules
• assets/claude-rule-template.md — starter template for Claude Code rules
• assets/quality-checklist.md — quality review checklist

Claude Code Rule — Starter Templates

Templates for Claude Code project instructions and scoped rules.

---

Project instructions (CLAUDE.md or .claude/CLAUDE.md)

No frontmatter needed. Write plain markdown. Target under 200 lines.

# Project Instructions

## Language and runtime

- 

## Code style

- 

## Architecture

- 

## Testing

- 

## Error handling

- 

## Build and run

- 

## Security

- 

You can import additional files using @path syntax:

See @README.md for project overview and @package.json for available scripts.

# Additional Instructions
- Git workflow: @docs/git-instructions.md

---

Path-scoped rule (.claude/rules/<name>.md)

---
paths:
  - "<glob-pattern>"
---

# <Rule title>

- 
- 
- 

Multiple patterns and brace expansion are supported:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
---

# <Rule title>

- 
- 
- 

---

Unconditional rule (.claude/rules/<name>.md)

Omit paths to make the rule load every session:

# <Rule title>

- 
- 
- 

Copilot Instructions — Starter Template

Use this as the starting structure for .github/copilot-instructions.md. Delete sections that do not apply. Keep directives concise and imperative.

---

# Copilot Instructions

## Language and runtime

- 

## Code style

- 

## Architecture

- 

## Testing

- 

## Error handling

- 

## Documentation

- 

## Git conventions

- 

## Security

- 

Rule creation follow-up questions

Questions to ask per rule when the scan and initial interview leave gaps. Ask only what's missing — skip anything already answered.

---

Purpose and scope

"What problem does this rule solve? What would go wrong without it?"

Ensures the rule has a reason to exist. If the developer can't explain the problem, the rule may not be needed.

"Is this a hard requirement or a preference?"

Hard requirements become imperative directives ("Use X"). Preferences become softer guidance ("Prefer X over Y when Z").

---

Specificity

"Can you give a concrete example of code that follows this rule and code that violates it?"

Turns vague conventions into testable directives. If the developer can't give an example, the rule is too abstract.

"Does this apply to new code only, or should existing code be refactored to match?"

Determines whether the rule is forward-looking or retroactive. Forward-only: "For new files, use X." Retroactive: "Use X."

---

Exceptions

"Are there cases where this rule should NOT apply?"

Common exception patterns:

• Generated code / vendor files
• Test code vs production code
• Legacy modules being phased out
• Third-party API boundaries (must match external conventions)
• Performance-critical paths with different patterns

"If there are exceptions, how should the AI recognize them?"

Options: file path (tests/, generated/), filename pattern (*.generated.ts), comment marker (// legacy), or directory convention.

---

Boundaries

"Does this rule interact with or depend on other rules?"

Catches conflicts early. Example: "Use named exports" + "Re-export everything from index.ts" — the AI needs to know both.

"Should this rule override the linter/formatter, or defer to it?"

If a tool already enforces it (ESLint, Biome, Ruff), the rule may be redundant. Best to reference the tool instead of duplicating.

---

Granularity

"Does this apply everywhere, or only to specific directories/file types?"

Determines always-on vs scoped. See assets/frontmatter-scenarios.md for frontmatter options.

"Should this be one rule or split into several?"

Split when: different parts apply to different paths, or the rule covers unrelated concerns. Keep together when: the parts are meaningless in isolation.

---

Voice and format

"How strict should the directive be?"

"Anything the AI should explicitly avoid doing, even if it seems reasonable?"

Captures anti-patterns the developer has seen the AI produce. Example: "Do not add any type assertions even if it fixes a type error."

---

Validation

"How would you verify the AI followed this rule?"

If it's testable (linter, type check, test suite), mention the command. If it's a judgment call (architecture, naming), note that.

"Is there an existing doc or ADR that backs this up?"

Claude Code can import it with @path. Copilot and Cursor need the content inlined.

---

Usage guide

Use these questions during Step 3 (Interview) for each convention discovered in the scan. Don't ask all questions for every rule — pick the ones where context is missing:

Frontmatter scenarios

Decision tree for choosing the right frontmatter. Each scenario includes what to ask when context is missing.

---

1. Does this convention apply everywhere or only to certain files?

Ask when: The scan found a convention but it's unclear whether it's universal or path-specific.

"Does this apply to all code in the repo, or only to specific directories/file types?"

If everywhere → always-on (Scenario 2) If specific paths → path-scoped (Scenario 3) If unclear → "Can you give an example of a file where this matters and one where it doesn't?"

---

2. Always-on rules

The convention applies to all files — code style, naming, error handling, commit format.

GitHub Copilot — root instructions (no frontmatter):

.github/copilot-instructions.md

Cursor — alwaysApply: true:

---
alwaysApply: true
---

Claude Code — CLAUDE.md or rule without paths:

CLAUDE.md
.claude/rules/code-style.md  # no paths = unconditional

---

3. Path-scoped rules

The convention applies only to specific directories or file types.

Ask when: The developer says "this is only for the API" but hasn't named the exact directory.

"Which directory or file pattern should trigger this rule? (e.g., src/api/**, **/*.test.ts)"

Ask when: Multiple directories might match.

"Should this cover just src/api/ or also src/middleware/ and src/validators/?"

GitHub Copilot — applyTo:

---
applyTo: "src/api/**"
---

Cursor — globs:

---
globs: "src/api/**"
alwaysApply: false
---

Claude Code — paths:

---
paths:
  - "src/api/**"
---

Multiple patterns

When one rule covers several file types or directories:

# Copilot
applyTo: "**/*.{ts,tsx}"

# Cursor
globs:
  - "**/*.ts"
  - "**/*.tsx"

# Claude Code
paths:
  - "**/*.{ts,tsx}"
  - "lib/**/*.ts"

---

4. Who should use this rule — coding agent, code review, or both?

Ask when (Copilot only): The convention might not apply to code review (e.g., "generate tests" makes sense for coding but not review).

"Should this instruction apply to both Copilot coding and code review, or just one?"

If both → omit excludeAgent If coding only:

---
applyTo: "**/*.ts"
excludeAgent: "code-review"
---

If review only:

---
applyTo: "**/*.ts"
excludeAgent: "coding-agent"
---

No equivalent in Cursor or Claude Code.

---

5. Should an AI agent use this rule automatically, or only when relevant?

Ask when (Cursor only): The rule is topical (architecture, deployment) rather than file-specific.

"Should this rule always be active, or should the agent include it only when the topic comes up?"

If always → alwaysApply: true (Scenario 2) If topic-dependent:

---
description: "Conventions for database migrations and schema changes"
alwaysApply: false
---

If rarely needed / reference-only:

"Is this something developers would explicitly ask for, or should it auto-activate?"

If explicit only → manual (no alwaysApply, no globs, no description — @-mention to activate)

---

6. Does the repo already have docs that cover this?

Ask when (Claude Code only): The scan found CONTRIBUTING.md, ADRs, or other docs that overlap with what the developer wants in rules.

"I found existing docs that cover this. Should we import them into CLAUDE.md instead of duplicating the content?"

If yes → use @path imports:

See @CONTRIBUTING.md for code style and PR conventions.
See @docs/architecture.md for system design decisions.

No equivalent in Copilot or Cursor — content must be written directly.

---

7. Does a subfolder have its own conventions?

Ask when: The repo is a monorepo or has directories with distinct tech stacks / patterns.

"Does packages/ui/ follow different conventions than the rest of the repo?"

If yes:

# Copilot — scoped instruction
applyTo: "packages/ui/**"

# Cursor — subdirectory in .cursor/rules/
.cursor/rules/ui/components.mdc

# Claude Code — subdirectory CLAUDE.md
packages/ui/CLAUDE.md

---

8. Is root instructions getting too long?

Ask when: The drafted root file exceeds ~80 lines (Copilot), ~500 lines (Cursor), or ~200 lines (Claude Code CLAUDE.md).

"The root instructions are at [X] lines. Can we move any of these conventions into scoped rules for specific directories?"

Look for conventions that only matter for certain file types and split them out.

---

Quick reference

Glob cheat sheet

Common mistakes

Quality checklist for AI coding rules

Review every rule file against this checklist before finalizing.

Root instructions (copilot-instructions.md)

• [ ] Conciseness — Under ~80 lines. Every line is an actionable directive.
• [ ] Imperative voice — Uses "Use X", "Do Y", not "You should consider X".
• [ ] No explanations — Directives only, not rationale. Copilot needs rules, not reasons.
• [ ] No secrets — No API keys, passwords, connection strings, or environment-specific values.
• [ ] No duplication — Nothing repeated in scoped instruction files.
• [ ] Covers key areas — Language, style, architecture, testing, error handling as applicable.
• [ ] Accurate — Every convention matches what the team actually follows.

Scoped instructions (.github/instructions/*.instructions.md)

• [ ] Valid frontmatter — Has applyTo field. Optionally excludeAgent to scope to a specific agent.
• [ ] Correct glob — Pattern matches intended files (verified against actual repo paths).
• [ ] Not too broad — Glob is not **/* or equivalent (use root instructions instead).
• [ ] Conciseness — Under ~50 lines per file. Split if larger.
• [ ] No overlap — Does not repeat guidance from root instructions.
• [ ] Kebab-case filename — Named <domain>.instructions.md.
• [ ] Scoped content — Every directive is specific to the matched files.

Cursor rules (.cursor/rules/*.mdc)

• [ ] Valid frontmatter — Uses correct combination of description, globs, and alwaysApply for the intended activation mode.
• [ ] Correct globs — Pattern matches intended files (verified against actual repo paths).
• [ ] Not too broad — Glob-scoped rules do not use **/* (use alwaysApply: true instead).
• [ ] Conciseness — Under ~500 lines per file. Split if larger.
• [ ] No overlap — Does not repeat guidance from always-apply rules.
• [ ] Kebab-case filename — Named <domain>.mdc.
• [ ] Scoped content — Every directive is specific to the matched files.
• [ ] Description quality — Agent-selected rules have a clear, specific description for relevance matching.

Claude Code (CLAUDE.md and .claude/rules/*.md)

• [ ] Conciseness — CLAUDE.md under ~200 lines. Longer files reduce adherence.
• [ ] Imperative voice — Specific, verifiable directives.
• [ ] No secrets — No API keys, passwords, connection strings, or environment-specific values.
• [ ] No duplication — Nothing repeated between CLAUDE.md and .claude/rules/ files.
• [ ] Valid frontmatter — Scoped rules have paths with correct glob patterns. Rules without paths are intentionally unconditional.
• [ ] Correct paths — Glob patterns match intended files (verified against actual repo paths).
• [ ] Kebab-case filename — Named <domain>.md.
• [ ] One topic per file — Each rule file covers a single domain.
• [ ] Import hygiene — @path imports in CLAUDE.md point to files that exist.

Common pitfalls

• [ ] Vague directives — "Write clean code" → Replace with specific rules.
• [ ] Wall of text — Paragraph-style prose → Convert to bullet-point directives.
• [ ] Aspirational rules — Rules the team doesn't actually follow → Remove or mark as goals.
• [ ] Overly narrow glob — src/components/Button.tsx → Broaden to src/components/**/*.tsx.
• [ ] Missing context — References internal terms without definition → Add brief clarification.

Scoped Rule — Starter Templates

Templates for path-specific rules. Choose the format matching your editor.

---

GitHub Copilot (.github/instructions/<name>.instructions.md)

---
applyTo: "<glob-pattern>"
---

- 
- 
- 

Optional: add excludeAgent: "code-review" or excludeAgent: "coding-agent" to limit which Copilot agent uses the file.

---

Cursor (.cursor/rules/<name>.mdc)

See assets/cursor-rule-template.mdc for the full starter template.

---
description: "<what this rule covers>"
globs: "<glob-pattern>"
alwaysApply: false
---

- 
- 
- 

---

Claude Code (.claude/rules/<name>.md)

See assets/claude-rule-template.md for the full starter template.

---
paths:
  - "<glob-pattern>"
---

# <Rule title>

- 
- 
- 

Omit the paths frontmatter to make the rule load unconditionally (every session).

Changelog

0.1.1 - 2026-05-07

patch

• #170 `5e43223` - Apply caveman-compress prose style to SKILL.md.

• Drop articles, filler, hedging from SKILL.md activation body

0.1.0 - 2026-03-21

minor

• #116 `2037597` - Add fusion-rule-author support skill with workflow, templates, and references

Internal support skill providing the canonical 7-step authoring workflow, starter templates, frontmatter scenarios, follow-up questions, quality checklist, and tech-stack examples for GitHub Copilot, Cursor, and Claude Code rule files.

Examples of well-written AI coding rules

Concrete examples across different tech stacks, showing good patterns and common anti-patterns for GitHub Copilot, Cursor, and Claude Code.

---

Example 1 — TypeScript / React monorepo

Root instructions (copilot-instructions.md)

# Copilot Instructions

## Language and runtime

- Use TypeScript strict mode for all source files.
- Target ES2022. Do not use legacy patterns (var, arguments object).
- Use Bun as the package manager and test runner.

## Code style

- Use named exports, not default exports.
- Prefer `interface` over `type` for object shapes.
- Use `camelCase` for variables and functions, `PascalCase` for types and components.
- Keep files under 300 lines. Extract when larger.

## React conventions

- Use functional components with hooks exclusively.
- Co-locate component, styles, and tests in the same directory.
- Prefer composition over prop drilling; use context sparingly.

## Testing

- Write tests with Vitest. Place test files next to source as `*.test.ts(x)`.
- Test behavior, not implementation. Avoid mocking internals.
- Every bug fix must include a regression test.

## Error handling

- Use Result types for expected failures. Reserve exceptions for unexpected errors.
- Never swallow errors silently. Log or propagate.

Scoped instruction (instructions/api-routes.instructions.md)

---
applyTo: "src/api/**"
---

- Use Hono framework patterns for route handlers.
- Validate request bodies with Zod schemas before processing.
- Return consistent error shapes: `{ error: string, code: string, status: number }`.
- Log all 5xx errors with request context. Never log request bodies containing PII.
- Keep route handlers thin — delegate business logic to service modules.

Cursor equivalent (rules/api-routes.mdc)

---
description: "Conventions for API route handlers using Hono"
globs: "src/api/**"
alwaysApply: false
---

- Use Hono framework patterns for route handlers.
- Validate request bodies with Zod schemas before processing.
- Return consistent error shapes: `{ error: string, code: string, status: number }`.
- Log all 5xx errors with request context. Never log request bodies containing PII.
- Keep route handlers thin — delegate business logic to service modules.

Claude Code equivalent (.claude/rules/api-routes.md)

---
paths:
  - "src/api/**"
---

# API Route Conventions

- Use Hono framework patterns for route handlers.
- Validate request bodies with Zod schemas before processing.
- Return consistent error shapes: `{ error: string, code: string, status: number }`.
- Log all 5xx errors with request context. Never log request bodies containing PII.
- Keep route handlers thin — delegate business logic to service modules.

---

Example 2 — Python / FastAPI backend

Root instructions (copilot-instructions.md)

# Copilot Instructions

## Language

- Use Python 3.12+. Use type hints for all function signatures.
- Use `ruff` for linting and formatting. Do not use `black` or `isort` separately.

## Architecture

- Follow hexagonal architecture: `domain/`, `adapters/`, `ports/`.
- Domain layer must not import from adapters or infrastructure.

## Naming

- Use `snake_case` for functions, variables, and modules.
- Use `PascalCase` for classes.
- Prefix private methods with underscore.

## Testing

- Use `pytest`. Place tests in `tests/` mirroring `src/` structure.
- Use factories (not fixtures) for test data setup.
- Target 80% coverage minimum for new code.

## Dependencies

- Pin all dependencies in `pyproject.toml`.
- Avoid adding new dependencies without team review.

Scoped instruction (instructions/db-models.instructions.md)

---
applyTo: "src/adapters/db/**"
---

- Use SQLAlchemy 2.0 declarative style with `Mapped[]` type annotations.
- Every model must define `__tablename__` explicitly.
- Use Alembic for migrations. Never modify the database schema directly.
- Add an index for any column used in WHERE clauses or JOINs.
- Include `created_at` and `updated_at` timestamps on all tables.

Cursor equivalent (rules/db-models.mdc)

---
description: "SQLAlchemy model and migration conventions"
globs: "src/adapters/db/**"
alwaysApply: false
---

- Use SQLAlchemy 2.0 declarative style with `Mapped[]` type annotations.
- Every model must define `__tablename__` explicitly.
- Use Alembic for migrations. Never modify the database schema directly.
- Add an index for any column used in WHERE clauses or JOINs.
- Include `created_at` and `updated_at` timestamps on all tables.

Claude Code equivalent (.claude/rules/db-models.md)

---
paths:
  - "src/adapters/db/**"
---

# Database Model Conventions

- Use SQLAlchemy 2.0 declarative style with `Mapped[]` type annotations.
- Every model must define `__tablename__` explicitly.
- Use Alembic for migrations. Never modify the database schema directly.
- Add an index for any column used in WHERE clauses or JOINs.
- Include `created_at` and `updated_at` timestamps on all tables.

---

Example 3 — C# / .NET service

Root instructions (copilot-instructions.md)

# Copilot Instructions

## Language and framework

- Use C# 12 with .NET 8. Enable nullable reference types.
- Use minimal APIs for new endpoints. Do not use controller-based routing.

## Naming

- Follow Microsoft naming guidelines: PascalCase for public members, camelCase for locals.
- Prefix interfaces with `I` and use PascalCase (for example, `IOrderRepository`).

## Architecture

- Use vertical slice architecture. Each feature gets its own folder.
- Use MediatR for command/query separation.

## Error handling

- Use Result<T> pattern for domain operations.
- Map domain errors to HTTP status codes at the API boundary only.
- Never throw exceptions for expected business rule violations.

## Testing

- Use xUnit with FluentAssertions.
- Use Testcontainers for integration tests with real databases.
- Keep unit tests focused on one behavior per test method.

---

Anti-patterns to avoid

❌ Too vague

Write good code. Follow best practices. Keep things clean.

Why it fails: Not actionable. Copilot cannot derive specific conventions from this.

❌ Too verbose / explanatory

When writing TypeScript code, it is generally considered a best practice to use
the `interface` keyword rather than the `type` keyword when defining object shapes.
This is because interfaces support declaration merging and provide better error
messages in many cases. However, there are situations where type aliases are more
appropriate, such as when defining union types or mapped types...

Why it fails: Wastes context window on explanation instead of giving a directive. Better version: "Prefer interface over type for object shapes."

❌ Duplicated between root and scoped

Root file says: "Use Zod for validation." Scoped api.instructions.md also says: "Use Zod for validation."

Why it fails: Redundant instructions dilute context. Put shared conventions in root only.

❌ Overly broad glob

# GitHub Copilot
applyTo: "**/*"

# Cursor
globs: "**/*"

# Claude Code
paths:
  - "**/*"

Why it fails: Matches every file — use root instructions (copilot-instructions.md), alwaysApply: true (Cursor), or CLAUDE.md / rule without paths (Claude Code) instead.

❌ Includes secrets or environment specifics

Use API key `sk-abc123...` for the staging environment.
Connect to database at `postgres://admin:password@prod-db:5432`.

Why it fails: Secrets must never appear in instruction files. Use environment variables and reference them by name only.