Rules for Specific Standards | Engineer Your AI

What You'll Learn

Your CLAUDE.md and AGENTS.md cover the big picture: tech stack, component conventions, design system choices. But some standards are more detailed and only apply in specific contexts. In this lesson, we introduce Claude's rules system for focused, topic-specific conventions.

CLAUDE.md vs Rules

Think of it this way:

	CLAUDE.md / AGENTS.md	Rules
Scope	Whole project	Specific topic or file pattern
Content	Tech stack, commands, architecture	Detailed conventions with examples
When loaded	Every session, at startup	At startup, or dynamically if scoped to specific file patterns
Best for	"How this project works"	"How we do X specifically"

Your AGENTS.md says "every feature needs tests using AAA pattern." A rule says exactly what that means: file naming, test structure, mock conventions, assertion patterns, with examples.

The Rules Directory

Rules live in .claude/rules/ as markdown files:

Every .md file in this directory is automatically discovered and loaded alongside your CLAUDE.md. No imports needed. Just drop a file in the folder.

Creating a Testing Rule

Let's create a rule that defines how tests should be written in the AI Prompt Library.

Create .claude/rules/testing.md:

markdown

# Testing Conventions
 
## Framework
 
- Vitest + React Testing Library
- Test files: `*.test.ts` or `*.test.tsx`, adjacent to the code they test
 
## Test Structure
 
Organise tests in this order within each describe block:
 
1. Initialisation tests: initial state and setup
2. Success cases: expected successful behaviour
3. Error handling: error conditions and failures
4. Edge cases: boundary conditions and special cases
 
## Naming
 
Use the pattern: `"should [action] when [condition]"`
 
Good:
- `"should fetch prompts successfully when API returns valid data"`
- `"should show empty state when no prompts match filter"`
 
Bad:
- `"test fetch"` (not descriptive)
- `"it works"` (unclear what's tested)
 
## Mock Data
 
- Prefix all mocks with `mock` (e.g., `mockPrompts`, `mockResponse`)
- Define mock data at the top of the describe block
- Keep mock data realistic
 
## Assertions
 
- `toEqual()` for objects and arrays (deep equality)
- `toBe()` for primitives
- `toHaveLength()` for array length
- Prefer specific matchers over generic ones
 
## Async Testing
 
- Always use `async/await` with `waitFor`
- Never use arbitrary timeouts

This is significantly more detail than what belongs in AGENTS.md. But when Claude is writing tests, this is exactly the guidance it needs.

Creating a UI Components Rule

Now create a rule for how UI components should be built:

markdown

# UI Component Conventions
 
## shadcn/ui First
 
Before building any UI element, check if shadcn/ui has a component for it:
- Cards → `Card`, `CardHeader`, `CardContent`
- Loading states → `Skeleton`
- Buttons → `Button` with variant props
- Inputs → `Input`, `Textarea`
- Dialogs → `Dialog`, `DialogContent`
 
Install with: `bunx shadcn@latest add <component>`
 
## Component Structure
 
- One component per file
- Named exports only: `export function PromptCard()` not `export default`
- Props interface defined above the component
- Use `cn()` for all conditional class logic
 
## Styling
 
- Semantic tokens only: `bg-card`, `text-foreground`, `text-muted-foreground`
- Never use raw colour values: no `bg-zinc-900`, no `text-gray-400`
- Use shadcn variant props: `variant="outline"`, `size="lg"`
- Use `asChild` for polymorphism: `<Button asChild><Link href="/">...</Link></Button>`

Save this as .claude/rules/ui-components.md.

Path-Scoped Rules

Rules can optionally be scoped to specific file patterns using a paths frontmatter field:

markdown

---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
---
 
# Testing Conventions
...

When a rule has paths, it only activates when Claude is working with files that match those patterns. Rules without paths apply everywhere.

For our project, we won't scope the rules yet. The project is small enough that all rules are relevant all the time. But in a larger codebase with distinct areas (frontend, backend, infrastructure), path scoping keeps rules focused on where they matter.

The Full Memory Structure

Here's what your project memory looks like now:

Each file has a clear purpose:

CLAUDE.md: the entry point, kept minimal
AGENTS.md: the project overview, what any new contributor (human or AI) needs to know
Rules: detailed, topic-specific standards that would bloat the main file

Commit Your Rules

bash

git add .claude/rules/
git commit -m "feat: add testing and UI component rules"

In the next lesson, we put all of this to the test. We'll run the exact same infinite scrolling prompt from Section 2 and see how Claude's decisions change with proper project memory in place.

What You'll Learn

CLAUDE.md vs Rules

Think of it this way:

	CLAUDE.md / AGENTS.md	Rules
Scope	Whole project	Specific topic or file pattern
Content	Tech stack, commands, architecture	Detailed conventions with examples
When loaded	Every session, at startup	At startup, or dynamically if scoped to specific file patterns
Best for	"How this project works"	"How we do X specifically"

Your AGENTS.md says "every feature needs tests using AAA pattern." A rule says exactly what that means: file naming, test structure, mock conventions, assertion patterns, with examples.

The Rules Directory

Rules live in .claude/rules/ as markdown files:

Every .md file in this directory is automatically discovered and loaded alongside your CLAUDE.md. No imports needed. Just drop a file in the folder.

Creating a Testing Rule

Let's create a rule that defines how tests should be written in the AI Prompt Library.

Create .claude/rules/testing.md:

markdown

# Testing Conventions
 
## Framework
 
- Vitest + React Testing Library
- Test files: `*.test.ts` or `*.test.tsx`, adjacent to the code they test
 
## Test Structure
 
Organise tests in this order within each describe block:
 
1. Initialisation tests: initial state and setup
2. Success cases: expected successful behaviour
3. Error handling: error conditions and failures
4. Edge cases: boundary conditions and special cases
 
## Naming
 
Use the pattern: `"should [action] when [condition]"`
 
Good:
- `"should fetch prompts successfully when API returns valid data"`
- `"should show empty state when no prompts match filter"`
 
Bad:
- `"test fetch"` (not descriptive)
- `"it works"` (unclear what's tested)
 
## Mock Data
 
- Prefix all mocks with `mock` (e.g., `mockPrompts`, `mockResponse`)
- Define mock data at the top of the describe block
- Keep mock data realistic
 
## Assertions
 
- `toEqual()` for objects and arrays (deep equality)
- `toBe()` for primitives
- `toHaveLength()` for array length
- Prefer specific matchers over generic ones
 
## Async Testing
 
- Always use `async/await` with `waitFor`
- Never use arbitrary timeouts

This is significantly more detail than what belongs in AGENTS.md. But when Claude is writing tests, this is exactly the guidance it needs.

Creating a UI Components Rule

Now create a rule for how UI components should be built:

markdown

# UI Component Conventions
 
## shadcn/ui First
 
Before building any UI element, check if shadcn/ui has a component for it:
- Cards → `Card`, `CardHeader`, `CardContent`
- Loading states → `Skeleton`
- Buttons → `Button` with variant props
- Inputs → `Input`, `Textarea`
- Dialogs → `Dialog`, `DialogContent`
 
Install with: `bunx shadcn@latest add <component>`
 
## Component Structure
 
- One component per file
- Named exports only: `export function PromptCard()` not `export default`
- Props interface defined above the component
- Use `cn()` for all conditional class logic
 
## Styling
 
- Semantic tokens only: `bg-card`, `text-foreground`, `text-muted-foreground`
- Never use raw colour values: no `bg-zinc-900`, no `text-gray-400`
- Use shadcn variant props: `variant="outline"`, `size="lg"`
- Use `asChild` for polymorphism: `<Button asChild><Link href="/">...</Link></Button>`

Save this as .claude/rules/ui-components.md.

Path-Scoped Rules

Rules can optionally be scoped to specific file patterns using a paths frontmatter field:

markdown

---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
---
 
# Testing Conventions
...

When a rule has paths, it only activates when Claude is working with files that match those patterns. Rules without paths apply everywhere.

The Full Memory Structure

Here's what your project memory looks like now:

Each file has a clear purpose:

CLAUDE.md: the entry point, kept minimal
AGENTS.md: the project overview, what any new contributor (human or AI) needs to know
Rules: detailed, topic-specific standards that would bloat the main file

Commit Your Rules

bash

git add .claude/rules/
git commit -m "feat: add testing and UI component rules"

In the next lesson, we put all of this to the test. We'll run the exact same infinite scrolling prompt from Section 2 and see how Claude's decisions change with proper project memory in place.