The CLAUDE.md Guide for Preview-Aware Repositories

If you’ve worked with Claude Code, Cursor, or any of the other AI coding agents that shipped in the last year, you’ve encountered the convention: a top-level file that gives the agent context about how the codebase works. Claude Code uses CLAUDE.md. Cursor uses .cursorrules and increasingly the shared AGENTS.md standard. The idea is the same — write down repository-specific knowledge so the agent doesn’t re-derive it on every prompt.

Most of these files focus on coding conventions: “use single quotes,” “prefer functional components.” That’s fine, but it leaves the bigger lever untouched: operational context — how the application deploys, what the preview environment looks like, what the seed data contains, what the verification workflow expects. An agent that knows those things produces dramatically better PRs. An agent that doesn’t writes code that compiles, passes tests, and falls over the moment it hits an ephemeral environment.

What goes in, what stays out

Write down anything an experienced engineer would tell a new hire about how this codebase deploys and gets reviewed. Leave out anything the agent can derive from the code.

In: the deployment model, preview-specific gotchas, seed data conventions, secrets handling, the verification workflow, background job conventions, third-party integration test modes.

Out: code style rules already enforced by your linter, long architecture explanations the agent can read from the code, aspirational standards nobody follows, anything that changes monthly.

The agent reads this file with every prompt. Every kilobyte costs context window. Be terse.

A skeleton that works

# Repository Context for AI Coding Agents

## What this is
One-paragraph description. What it does, who uses it, what stack.

## Stack
- Backend: Rails 7.1, Ruby 3.3
- Database: PostgreSQL 16, primary + read replica
- Cache/queue: Redis 7, Sidekiq
- Frontend: React 18, esbuild
- Deployed to: AWS ECS via GitHub Actions

## How this deploys
- Production: main branch auto-deploys via GHA
- Preview: every PR gets an ephemeral environment at
  https://pr-{number}.preview.example.com
- Preview includes: web, worker, db (with seed data), redis
- Preview does NOT include: real Stripe, real SendGrid, S3
  (we mock these — see below)

## Preview-specific behavior
- PREVIEW_ENV=true is set in previews
- Sidekiq runs but cron schedules are suppressed unless explicitly enabled
- Outbound mail goes to MailHog at port 8025
- Stripe: test mode keys, see config/initializers/stripe.rb
- File uploads: MinIO local S3, never the real bucket

This is the spine. The next sections are where the real value is.

Seed data conventions

The agent will write code that assumes data shapes. If the seed script always creates a user with email [email protected] and role ADMIN, write that down — and the agent will use it in tests and reproduction steps instead of inventing fictional users.

## Seed data

`db/seeds.rb` produces:
- 1 admin user: [email protected] / preview123
- 20 faker-generated users with role MEMBER, faker.seed(42)
- 5 organizations, each with 3-5 members
- 30 days of synthetic activity feed entries per org
- No invoices (so the invoicing flow can be tested from scratch)

When adding entities:
- Update db/seeds.rb in the same PR
- If it appears in dashboards, seed at least 5 instances
- If the creation flow is under test, leave the table empty
- Always use faker; never copy production-shaped data

See Seeding a Postgres Database for Ephemeral Preview Environments.

Secrets and environment variables

Agents are cautious about secrets when told to be. They will happily commit a hardcoded key when not. State the rules.

## Secrets

- All secrets live in 1Password and are injected at runtime.
  Nothing real is in the repo.
- Local dev uses .env.local (gitignored). The repo includes
  .env.example with placeholder values.
- Preview gets test-mode credentials only:
  STRIPE_SECRET_KEY=sk_test_...
- Never write a literal credential anywhere in the repo.
- If you need a new secret, add it to:
  1. config/secrets.example.yml
  2. .env.example
  3. The deploy pipeline (mention in PR description)

See Environment Variables in Ephemeral Preview Environments.

The verification workflow

The agent should know what humans expect to see when reviewing a PR. This bridges “code that compiles” to “code that ships.”

## Verification workflow

Every PR must:
1. Pass CI (rspec, rubocop, eslint)
2. Deploy successfully to its preview environment
3. Include a test plan in the PR description
4. Get sign-off from a code reviewer AND a feature stakeholder

For agent-authored PRs:
- Include a test plan listing user-visible flows that changed
  and steps to verify them in preview
- If a flow involves email, link to the MailHog inbox
- If a flow involves background jobs, link to Sidekiq Web
- Don't claim "tested" without specifying where (CI? preview?)

This section does the most work. An agent that emits PRs with test plans rooted in the preview environment is fundamentally easier to review than one that emits “added feature, tests pass.”

Stack-specific gotchas

Agents make stack-specific mistakes this file can preempt.

## Common gotchas

- ActiveStorage: in preview, files go to MinIO, not S3.
- Webhooks: don't generate URLs from request.host. Use
  Rails.application.config.preview_external_url.
- Time-zones: never call Time.now; use Time.zone.now.
- Feature flags: in preview default ON, in production default OFF.

These read like inside jokes to a new engineer. Write them down anyway. The agent will use them.

What about AGENTS.md and .cursorrules?

AGENTS.md is becoming a cross-tool standard supported by Cursor, Codex CLI, and others. CLAUDE.md is the Claude Code convention. If your team uses one tool, write the appropriate file and don’t worry about the others. If your team uses multiple, write AGENTS.md and have CLAUDE.md import it.

@AGENTS.md

See Cursor and Claude Code Configuration for Preview-Aware Repos for tool-specific configuration.

What changes when agents respect this file

Three things. The PRs come with realistic test plans because the agent has seen the seed data conventions. The agent stops inventing fictional credentials and uses environment variables. The agent’s PR descriptions reference the preview URL and what to check, not just what the diff does.

None of this matters if your verification workflow doesn’t actually use the preview environment. Writing the CLAUDE.md is the easy half. Building the workflow is the hard half. See What Is Verified Software Delivery? for that side.

A reasonable target: under 4KB. Most of mine sit around 2-3KB.

If you want a workflow where the agent doesn’t just write preview-aware code but also receives structured feedback from preview reviews — comments, checklist failures, sign-offs — and uses that feedback to drive iteration, that’s what we’re building at PreviewProof. The CLAUDE.md gets the agent to write better PRs. The verification loop gets the human and the agent to converge on the right outcome. Either piece is useful alone; together they’re how AI-assisted development stops being a quality regression.