rule-making-skill

Analyze a directory and generate .claude/rules/ files for Claude Code domain memory.

Core Concept

Generalized agents fail because they're "amnesiacs with a tool belt." Each session starts with no grounded sense of where we are.

Solution: Domain Memory - persistent structured representation containing:

1. Goals - What we're trying to achieve, requirements, constraints
2. State - What's passing/failing, what's been tried, what broke
3. Scaffolding - How to run, test, extend the system

Rules files distill domain knowledge into quick-reference format.

When to Use

User asks to:

• "Analyze frontend/ and create rules"
• "Set up Claude rules for the backend"
• "Create domain memory for e2e/"

---

Workflow

1. Check Existing Documentation

Read root CLAUDE.md and target directory CLAUDE.md. Pull down what's already documented. We don't want to duplicate everything, but the main CLAUDE.md still have to keep core overview of the application.

2. Detect Concerns

Scan the target directory to detect which concerns exist. Only generate rule files for concerns that are actually present.

3. Mine Domain Memory

Check planning board and tasks under /.tasks/ for decisions, gotchas, and patterns related to each detected concern.

Globpattern: ".task-board/done/*.md"

Use tasks older than #150

4. Generate Rule Files

Create focused .md files only for detected concerns.

---

Concern Detection Matrix

Scan for these patterns to detect which concerns exist:

| Concern | Detection Signals | Rule File | |---------|-------------------|-----------| | auth | **/auth/**, AuthContext, AuthProvider, login, logout, session, token, OAuth, EasyAuth | auth.md | | data | **/models/**, cosmosdb, database, mongoose, prisma, orm, migrations, Container | data.md | | api | **/routes/**, **/controllers/**, router.get, router.post, express.Router, endpoints | api.md | | validation | **/validators/**, zod, yup, joi, schema, .parse(, .safeParse( | validation.md | | state | useQuery, useMutation, QueryClient, zustand, redux, recoil, Context.Provider | state.md | | components | **/ui/**, **/components/**, .tsx files with Props interfaces, forwardRef | components.md | | styling | tokens.css, theme, tailwind, styled-components, css modules, design system files | styling.md | | charts | d3, recharts, chart.js, victory, **/charts/**, <svg, useEffect with DOM manipulation | charts.md | | forms | **/forms/**, useForm, handleSubmit, <input, <form, form validation patterns | forms.md | | calculations | **/calculation*, pure functions returning numbers, financial formulas, Math. heavy files | calculations.md | | llm | openai, langchain, anthropic, agent, tool calls, completion, langfuse | llm.md | | errors | **/errors/**, AppError, ErrorBoundary, errorHandler, custom error classes | errors.md | | testing | *.spec.ts, *.test.ts, fixtures, beforeEach, describe(, it(, expect( | testing.md | | middleware | **/middleware/**, app.use(, request/response interceptors, next() | middleware.md | | services | **/services/**, business logic classes, dependency injection patterns | services.md | | onboarding | wizard, onboarding, setup, multi-step flows, Step*.tsx | onboarding.md | | integrations | Third-party SDK imports, API clients, webhooks, external service calls | integrations.md |

Detection Algorithm

For each concern in matrix:
  1. Glob for folder patterns (**/auth/**, **/models/**, etc.)
  2. Grep for keyword patterns (AuthContext, useQuery, etc.)
  3. If matches found → concern is DETECTED
  4. If no matches → skip this concern

Threshold: A concern is detected if:

• At least 1 folder pattern matches, OR
• At least 3 keyword matches across files

---

Rule File Format

# [Concern] Rules

## Stack
[One line: key libs/frameworks for this concern]

## Structure
- `/path` - Purpose
- `/path` - Purpose

## Patterns
- Established pattern 1
- Established pattern 2

## Decisions
- Choice X because Y

## Gotchas
- Problem → Solution

## Commands
- `pnpm <command>` - What it does

Not every file needs all sections - include only what's relevant.

---

Example: Detected Concerns → Generated Files

Target: backend/

Detection results:

• ✅ auth → middleware/auth.ts, routes/authRoutes.ts
• ✅ data → config/cosmosdb.ts, models/*.ts
• ✅ api → routes/*.ts, controllers/*.ts
• ✅ validation → validators/*.ts, zod imports
• ✅ services → services/*.ts
• ✅ calculations → services/calculationService.ts
• ✅ llm → services/importAgentService.ts, openai imports
• ✅ errors → errors/AppError.ts, middleware/errorHandler.ts
• ✅ middleware → middleware/*.ts
• ❌ components → not found
• ❌ styling → not found
• ❌ charts → not found

Generated files:

backend/.claude/rules/
├── auth.md
├── data.md
├── api.md
├── validation.md
├── services.md
├── calculations.md
├── llm.md
├── errors.md
└── middleware.md

Target: components/

Detection results:

• ✅ components → ui/**, cards/**, layout/**
• ✅ styling → styles/tokens.css
• ✅ charts → charts/*.tsx, d3 imports
• ✅ forms → forms/*.tsx
• ✅ errors → system/ErrorBoundary
• ❌ auth → not found
• ❌ data → not found
• ❌ api → not found

Generated files:

components/.claude/rules/
├── components.md
├── styling.md
├── charts.md
├── forms.md
└── errors.md

Target: e2e/

Detection results:

• ✅ testing → *.spec.ts, fixtures
• ✅ auth → login helpers, auth fixtures
• ❌ everything else → not found

Generated files:

e2e/.claude/rules/
├── testing.md
└── auth.md

---

Content Guidelines

What to Include

| Section | Source | |---------|--------| | Stack | package.json deps for this concern | | Structure | Folder layout for this concern only | | Patterns | Code analysis + task-board history | | Decisions | Task-board "decided to..." entries | | Gotchas | Task-board "had issues with..." entries | | Commands | package.json scripts for this concern |

What NOT to Include

• Anything in root CLAUDE.md (no duplication)
• Generic patterns (only project-specific)
• Obvious things (React uses JSX, etc.)

---

Example Rule Files

backend/.claude/rules/data.md

# Data Rules

## Stack
CosmosDB (NoSQL), @azure/cosmos SDK

## Structure
- `/config/cosmosdb.ts` - Connection, container getters
- `/models/` - Document type definitions

## Patterns
- Containers: `users` (partition: /id), `portfolios` (partition: /userId)
- Documents are denormalized (snapshots store full account data)
- Use singleton pattern for database instance

## Decisions
- Denormalized snapshots for historical accuracy (accounts change over time)
- Co-locate user data by userId partition for fast queries

## Gotchas
- Date strings "dd.MM.yyyy" don't sort correctly in CosmosDB
- Always sort dates in JS using `compareDatesAsc` from dateUtils.ts
- Zod strips unknown fields - add to schema or they're dropped

## Commands
- `pnpm --filter backend seed` - Seed demo data
- `pnpm --filter backend seed:reset` - Reset database

components/.claude/rules/charts.md

# Charts Rules

## Stack
D3.js for all visualizations

## Structure
- `/charts/AreaChart` - Single line/area
- `/charts/StackedAreaChart` - Multiple stacked areas
- `/charts/DonutChart` - Pie/donut charts

## Patterns
- SVG-based, responsive via viewBox
- Data prop: `{ date: string, value: number }[]`
- Colors from design tokens (--muted-sage, --pale-blue, etc.)
- Tooltips via D3 mouse events

## Gotchas
- D3 selections in useEffect with cleanup
- Don't mix D3 DOM manipulation with React state
- Mobile: increase touch targets for tooltips

e2e/.claude/rules/testing.md

# Testing Rules

## Stack
Playwright

## Structure
- `/tests/*.spec.ts` - Test files
- `/tests/fixtures.ts` - Shared helpers, constants

## Patterns
- `PROTECTED_PAGES` array for auth-required pages
- `login()` helper handles demo authentication
- `clearAuthState()` between tests

## Decisions
- Integration + E2E only, no unit tests
- Sanity checks over comprehensive coverage
- Test user flows, not implementation details

## Gotchas
- Demo login has rate limiting (5 req/min)
- Always clearAuthState() in beforeEach
- Mobile tests use fixtures/mobile-viewports.ts

## Commands
- `pnpm test:e2e` - Run all tests
- `pnpm test:e2e --ui` - Interactive mode

---

Best Practices

1. Detect first - Only create files for concerns that exist
2. Mine task-board - Decisions and gotchas are gold
3. No duplication - If root CLAUDE.md has it, skip it
4. Be specific - "Port 3000" not "default port"
5. Keep short - Each file <50 lines
6. Update on discovery - Rules are living documentation