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 page 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:
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.Recommended workflow
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.The difference a good prompt makes
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
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.
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