What should go in a CLAUDE.md file?

The decisions the agent cannot infer from the code: the stack, the architectural rules, where database access must live, the commands to run before declaring work done, and the things it must never do, such as reading env files or adding dependencies without asking.

Should Claude Code have access to my API keys?

No. Keep secrets in a gitignored env file, deny reads of that file in your permission settings, and reduce how many provider keys exist at all. With Squiid your project carries one SQUIID_API_KEY and the provider credentials never reach your machine.

Which framework works best with a coding agent?

The one with the most public code and documentation, which today means Next.js or a mainstream Vite setup. Agents write correct code far more often for popular, stable frameworks, so familiarity to the model is a legitimate selection criterion at this stage.

What is the best starter stack for a Claude Code project?

September 1, 2026 · The Squiid team · 5 min read

The stack: Next.js on Vercel, Supabase for database and auth, Resend for email, Cloudflare R2 for file storage, and Sentry when you have users. Five services, one of which you add later. The reasoning below matters more than the picks, because the picks are defensible rather than uniquely correct.

Claude Code is a terminal agent with real filesystem and shell access. That makes it excellent at multi-file refactors, migrations and anything that involves running a command and reading the output. It also means the project structure, the written instructions and the permission settings do more work than they would with an autocomplete tool, because the agent acts rather than suggests.

Why these five

Next.js on Vercel. Not because it is the best framework in the abstract, but because the volume of public code and documentation means an agent writes correct Next.js on the first attempt far more often than it writes correct anything else. With an agent doing the typing, familiarity to the model is a real engineering criterion.

Supabase. Postgres plus auth, storage policies and realtime in one project. One account instead of three, and a schema that is portable if you outgrow it. Claude Code is comfortable writing SQL migrations and running them, which turns schema changes into a reviewable diff rather than clicking in a console.

Resend. Transactional email in one POST, templates as React components, and domain verification that takes ten minutes. Add it on day one and verify the domain before you need it.

Cloudflare R2. Object storage with no egress charge, which removes an entire category of billing surprise. Supabase Storage is fine too, and moving later is a day of work.

Sentry, later. Error tracking is week two, once real people can hit real errors.

The env file

Commit the example, never the values:

# .env.example
# one credential, held by Squiid, replaces the eight below it
SQUIID_API_KEY=

# what it stands in for:
# SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY
# RESEND_API_KEY
# R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY
# SENTRY_DSN

NEXT_PUBLIC_SITE_URL=http://localhost:3000

Requests go to https://api.squiid.io/v1/<service>/ with an Authorization: Bearer header, and the official SDKs work by pointing their base URL at the gateway. If you would rather hold the provider keys directly, the rest of this post is unchanged; you just have eight lines in the env file instead of one, and eight places to rotate when something leaks.

Setup, in order

Create the repository and commit a .gitignore containing .env and .env.local before anything else.
Scaffold the framework yourself with its own create command. Do not have the agent hand roll a project skeleton; it is slower and less standard.
Deploy the empty app. Prove the pipeline works while there is nothing to debug.
Write CLAUDE.md before writing features. Fifteen minutes here saves hours of correcting patterns later.
Add the database, the schema and sign-in. One feature end to end, with real persistence.
Add email, verify the domain, send yourself a test from production.
Point the domain at it.

A CLAUDE.md that earns its place

The mistake is writing a summary of the codebase, which the agent can read for itself. Write the decisions it cannot infer:

# CLAUDE.md

## Stack
Next.js App Router, TypeScript, Tailwind, Supabase (Postgres + Auth),
Resend for email, deployed on Vercel.

## Rules
- Server components by default. Client components only for interactivity.
- All database access goes through lib/db.ts. No queries in components.
- Migrations live in supabase/migrations and are applied with the CLI,
  never by editing tables in the dashboard.
- Never read, print or commit .env files. Refer to variables by name.
- Run the type checker and the test suite before saying a task is done.

## Conventions
- No new dependencies without asking.
- Small commits, one concern each, conventional commit messages.

Two lines there do most of the work. "No new dependencies without asking" prevents the quiet accumulation of half-used libraries. "Run typecheck and tests before saying a task is done" converts a confident claim into a verified one, and is the single highest value instruction in the file.

Permissions worth setting

Claude Code asks before running commands and can be configured to allow or deny categories of action. The exact setting names move between releases, so check the current documentation, but the shape to aim for is stable.

Allow freely: reading files in the project, running the test suite, running the type checker, running the linter, git status and git diff. These are the loop the agent should be able to run without interrupting you.

Always ask: anything that writes outside the project directory, anything that installs packages, anything that touches production, database migrations against a hosted project, and any command containing a force push or a recursive delete. Deny outright: reading env files and secrets directories.

How to actually work with it

Plan before building. Ask for the approach and the file list first, read it, correct it, and only then let it write. Correcting a plan costs a minute; correcting nine files costs an evening.

Keep the unit of work small. One feature, one branch, one review, one commit. Long sessions accumulate context that drifts from the code on disk, and a thirty file change is a change nobody reviews properly, including you.

Make it run things. The reason a terminal agent is better than a suggestion engine is that it can execute the test, read the failure and fix it. Any workflow where you copy an error back in by hand is wasting the tool, and also the way keys end up in chat windows.

Check the diff yourself, every time. Not because the code is bad, but because the pattern it quietly established in file three will be in twenty files by Friday.

Git is the safety net, so use it properly

An agent that edits files directly is only safe if reverting is trivial. Branch per task, commit at every working state, and never let a session run for an hour against an uncommitted working tree. A clean git status at the start of a task is what makes "undo all of that" a five second operation rather than an archaeology exercise.

If you find yourself wanting two things in flight at once, a bug fix while a feature is half built, reach for a second checkout or a worktree rather than stashing. Two directories with two branches lets you run two sessions without either one stepping on the other, and it costs nothing but disk. The failure this prevents is the specific and demoralising one where an agent helpfully fixes something in the middle of a change you had not finished, and you can no longer tell which edits belonged to which task.

Week two

Add error tracking, one analytics tool, and a RUNBOOK.md listing which console answers which question and where every credential lives. Add payments only when someone wants to pay. Add background jobs only when a task genuinely must survive a deploy. Everything else can wait, and waiting is the whole discipline.