Cursor and Claude Code: Configuring Your Repo for Preview-Aware AI Development

Cursor and Claude Code are the two AI coding tools most engineering teams have settled on. Both are reasonably good out of the box. Both are dramatically better when the repo they’re operating on gives them clear, structured context about how the project is built, deployed, and verified.

The difference between an agent that produces preview-friendly code on the first try and one that hardcodes localhost:3000 into a config file is almost always a difference in what the agent was told before it started. This post is about telling it the right things.

What “preview-aware” means in practice

A preview-aware change is code that works correctly when deployed to an ephemeral preview environment without manual intervention. Specifically, it:

• Reads URLs from environment variables instead of hardcoding them
• Respects the project’s seed data conventions and doesn’t assume a fresh empty database
• Handles dynamic preview URLs for OAuth callbacks, webhooks, and CORS
• Doesn’t assume localhost, doesn’t assume HTTPS-everywhere, doesn’t assume the production domain
• Runs in containers or whatever the project’s preview mechanism is, not just on the developer’s laptop
• Includes the migrations, seed updates, and config changes a preview needs to deploy successfully

Most agents will produce code that violates at least one of these assumptions if you don’t tell them not to. The fix isn’t reviewing every PR for the same five issues — it’s putting the rules in the agent’s context once, and letting both Cursor and Claude Code pick them up automatically.

The configuration files that matter

Cursor and Claude Code both read project-local configuration files when they start a session. They overlap, but not completely.

The right answer for most teams in 2026 is: maintain CLAUDE.md and AGENTS.md as the canonical sources, with overlapping content, and use .cursor/rules/ only when you need rule scoping that the markdown files can’t express.

What to put in CLAUDE.md

We’ve covered this in depth in the CLAUDE.md guide for preview-aware repositories. Short version:

# Project context
Rails 7 + React. Local dev via `docker compose up`. Per-PR previews
deploy automatically at `pr-<number>.preview.example.com`.

# Environment variables
All config comes from environment variables. The canonical list
lives in `.env.example`. New env vars must be added there with a
comment and default to a preview-safe value.

Do not hardcode URLs. The app's URL is `APP_URL`. External services
are `STRIPE_API_URL`, `SENDGRID_API_URL`, etc.

# Seed data
Previews load `db/seeds/preview.rb`. Seed data is owned by humans
and reviewed separately from feature PRs. Do not silently modify
the seed file as part of a feature change. Assume the canonical
seed set exists; do not write code requiring an empty database.

# Webhooks and callbacks
Preview URLs are dynamic. OAuth callbacks, Stripe webhooks, and
similar must derive their URL from `APP_URL` at runtime.

The pattern: state the project shape, name conventions explicitly, call out specific things the agent tends to get wrong.

What to put in AGENTS.md

AGENTS.md has emerged as the cross-tool standard. Cursor reads it natively, Claude Code increasingly does, and other tools (Aider, OpenCode, etc.) treat it as the canonical agent-instructions file.

In practice, you can either:

1. Put the canonical content in AGENTS.md and have CLAUDE.md link to it
2. Maintain near-identical files and accept the duplication
3. Use a generation script to produce both from a single source

We do (1) for newer projects. For legacy repos with extensive CLAUDE.md history, the duplication of (2) is fine — these files are usually only a few hundred lines.

Cursor-specific: scoped rules

Cursor’s .cursor/rules/ directory takes .mdc files (Markdown with frontmatter) that scope rules to specific paths. Useful when one part of the codebase has different conventions than another.

---
description: "Backend API conventions"
globs: ["app/api/**", "app/services/**"]
alwaysApply: false
---

When writing API endpoints:
- All endpoints must check `current_tenant` before any query
- Errors return JSON with `error.code` and `error.message`
- Long-running operations enqueue background jobs, not synchronous calls

---
description: "Frontend UI conventions"
globs: ["app/javascript/**", "components/**"]
alwaysApply: false
---

When writing React components:
- Use the existing `useApi` hook, not raw `fetch`
- Loading and error states are required
- Empty states have explicit components, not just `null` returns

This scoping is genuinely useful. Without it, you either bloat CLAUDE.md with rules that only apply to one corner of the repo, or the agent applies frontend conventions to backend code.

Claude Code-specific: nested CLAUDE.md

Claude Code reads CLAUDE.md at the repo root, then merges in any CLAUDE.md files found in subdirectories as you navigate into them. This is a nice analogue to Cursor’s scoped rules — put project-wide content at the root, and area-specific content in app/api/CLAUDE.md, app/javascript/CLAUDE.md, etc.

For preview-awareness specifically, the root file is usually enough. The conventions are project-wide.

How configurations differ between tools

• Cursor weights .cursor/rules/*.mdc heavily and respects globs precisely. Path-scoped rules apply only on those paths.
• Claude Code weights CLAUDE.md heavily and applies all of it to every interaction. Subdirectory CLAUDE.md files are additive.
• Cursor is more aggressive about following rules verbatim — it will copy phrasing into commit messages and PR descriptions.
• Claude Code is more flexible about interpreting context. It occasionally deviates from rules; explicit “always” / “never” framing helps.

Maintenance cost

These files drift. New conventions get added in code reviews and never make it to CLAUDE.md. Old rules persist after they stop being relevant.

Two practical maintenance habits:

• Quarterly review. Read CLAUDE.md end-to-end every quarter, with a recent set of agent-authored PRs in front of you. Anything the agent got wrong repeatedly that the file doesn’t address — add it. Anything the file says that’s no longer true — remove it.
• PR review prompts. When reviewing an agent-authored PR that did something stupid, ask “should this be in CLAUDE.md?” Most of the time the answer is yes, and writing it down once saves catching the same bug ten more times.

A short, honest plug

Configuring your repo for AI tools is high-leverage and free. Do it. The impact on the quality of agent-authored PRs is larger than any other single change you can make.

But config alone doesn’t close the verification gap — preview-aware code still needs to actually be verified in a running preview before it merges. That’s the part where PreviewProof helps: per-PR previews, structured review, captured sign-off. Configure your repo so the agent writes preview-aware code, then verify what it wrote in an actual preview. Preview it. Prove it.