Skip to main content

​
AI Development

Refract is designed to work with AI coding agents. The functional patterns, strict TypeScript, and clean boundaries aren’t just good architecture — they make AI-generated code dramatically more accurate and easier to review. This step shows you how to get the most out of Cursor (or any AI agent) when building on Refract.

​
What ships in .cursor/rules/

Refract comes with a comprehensive set of Cursor rules that constrain AI generation to the right patterns. These live in .cursor/rules/ at the repo root and load automatically in Cursor:
Rule fileWhat it enforces
ai-directives.mdcGeneral AI behaviour and boundaries
core-principles.mdcArchitectural principles every agent must follow
backend-patterns.mdcBackend code patterns — resolvers, tools, functional core
frontend-patterns.mdcReact + MUI patterns, component structure
graphql-mutations.mdcGraphQL mutation conventions
tool-implementation-modules.mdcHow to implement new tooling adapters
testing.mdcTest patterns, what to test, how to structure specs
test-isolation.mdcTest isolation rules — no shared state, no side effects
error-handling.mdcError handling conventions across the stack
file-organization.mdcWhere files go, naming conventions
development-workflow.mdcHow to use make commands, local dev workflow
documentation-style.mdcHow to write docs — tone, format, agent context blocks
security.mdcSecurity rules — what never to do
technology-stack.mdcApproved technologies and versions
theme.mdcMUI theme conventions
shell-scripts.mdcShell script conventions
changelog.mdcChangelog entry format
These rules do a lot of the “don’t put business logic in a resolver” enforcement automatically — you don’t have to remind Cursor every time.

​
Why Refract is AI-friendly

Three things make Refract work particularly well with AI agents: Functional patterns and clear boundaries — every layer has a single responsibility. Business logic lives in the Functional Core. HTTP handling lives in resolvers. UI logic lives in components. AI agents generate code in the right place because the boundaries are explicit. Strict TypeScript — the type system catches bad AI generations before they reach runtime. If Cursor puts something in the wrong layer, TypeScript will tell you immediately. Separation of concerns — config, tools, resolvers, and UI are clearly separated. Agents have obvious, named targets. “Add a new queue adapter” has a specific file to touch. “Add a new GraphQL resolver” has a specific pattern to follow. Before asking an agent to generate or modify code in any domain, attach the relevant doc as context. This gives the agent the full picture of how that system works before it touches anything. 
1. Find the relevant doc:
   - Changing a tool or adding a provider? → apps/documentation/tooling/<tool>/
     (e.g. tooling/queue/bullMQ.md, tooling/payment-processor/stripe.md)
   - Changing auth, billing, or core architecture? → apps/documentation/architecture/
     (e.g. billing.md, authentication.md, tooling-system.md)
2. Attach the doc in Cursor's context panel
3. Ask for changes that follow existing patterns
4. Name the specific files you want touched
The tooling docs are especially useful for agents — every implementation page includes the exact file paths, config shape, agent context block, and anti-patterns for that tool.

​
The difference a good prompt makes

✅ Good:
"Read apps/documentation/architecture/billing.md, then add a new
plan called 'Agency' with these entitlements: [...]. Match the
existing seed patterns and GraphQL conventions exactly. Touch only
these files: [list them]."

❌ Bad:
"Add a new billing plan called Agency."
The bad prompt will get you code. The good prompt will get you code that fits.

​
What AI handles well in Refract

These are the tasks where AI agents shine with Refract’s architecture:
  • New tooling adapters — the contract is explicit, the pattern is consistent
  • Tests — existing specs are clean templates to follow
  • GraphQL resolvers — thin by design, easy to generate correctly
  • Refactors within a single layer — boundaries prevent collateral damage
  • Documentation — the writing guide and style rules make consistent output easy

​
What to do yourself first

Some things are too important to delegate to an agent — at least until you understand the codebase well:
  • Core billing invariants and pricing policy — understand how plans and entitlements work before asking an agent to change them
  • Auth flows and session changes — security-sensitive, review carefully
  • Destructive migrations and data backfills — always write and review these yourself
  • Anything that touches multiple layers at once — break it into single-layer tasks first
Never paste real credentials, API keys, or secrets into an AI chat window — not even “just to test.” Use placeholder values and fill in real ones manually.

​
A note on the documentation itself

These docs are also written to be AI-readable. Every architecture page includes a 🤖 Agent context block with explicit boundary rules, file paths, and anti-patterns. When you’re working in a specific domain, attaching the relevant doc gives your agent everything it needs to generate correct, pattern-consistent code.
The fastest way to get good results: "Read [doc path], follow the existing patterns, touch only [specific files]." Every extra word of context you give Cursor is a mistake it won’t make.
You’re set up. The rules are loaded, the docs are here, and the architecture is designed to work with you — and your AI agent. Go build something. → Next: Architecture Overview