DEV Community: Alfredo Augusto

How to Write a CLAUDE.md That Actually Changes Claude Code's Behavior

Alfredo Augusto — Sat, 06 Jun 2026 16:39:05 +0000

Most developers write a CLAUDE.md, get slightly better output for a week, then forget about it.

The reason: their CLAUDE.md doesn't change Claude's behavior — it just reminds Claude of things it would have done anyway.

Here's how to write one that actually works.

What Claude does with your CLAUDE.md

Claude reads the entire file before starting any task in your project. It uses it to:

Understand your architecture (so it puts code in the right place)
Follow your conventions (so you don't have to correct it)
Avoid your known anti-patterns (so you don't get burned by the same mistake twice)

The key word is specific. Claude responds to specifics, not generalities.

The structure that works

Here's a template that covers the essentials:

# Project: [Name]

## Stack
[List your actual stack — framework, database, auth, key libraries]

## Architecture
[Folder structure + what goes where. Be explicit.]
- `src/services/` — business logic only
- `src/routes/` — HTTP layer only, calls services
- `src/db/` — all database queries

## Critical Rules
[The 5-10 things Claude must never get wrong]
- Never expose [X] to the client
- Always validate [Y] before [Z]
- Auth happens in [specific place], nowhere else

## Code Conventions
[Language-specific patterns you actually use]

## Error Handling
[How errors should be handled, logged, returned]

## Testing
[What to test, how to test it, what not to mock]

## Environment Variables
[List every env var and what it does]

The rule of thumb: if Claude got it wrong once, write a rule

Every time Claude makes a mistake that surprises you, add a rule to your CLAUDE.md.

Claude put business logic in a route handler? → Add an architecture rule
Claude used the wrong auth pattern? → Add a critical rule
Claude wrote a test that mocked the database? → Add a testing convention

Over time, your CLAUDE.md becomes a record of the project's institutional knowledge.

Stack-specific sections worth adding

For Next.js App Router

## Next.js Rules
- Server Components by default — "use client" only for event handlers and hooks
- Never useEffect for data fetching — use Server Components or React Query
- Auth: middleware.ts handles route protection — never in page components
- Stripe: sync subscription state via webhooks only — never trust client data

For FastAPI

## FastAPI Rules  
- Routers: HTTP parsing + service calls only — no business logic
- Services: business logic only — no HTTP or DB concerns
- Repository: all DB queries — never in routers or services
- Always use Pydantic v2 validators — never raw dict access

For any AI agent project

## Agent Rules
- Max iterations on all agent loops: 10
- 30s timeout per tool execution
- Human-in-the-loop for: file deletion, email sending, payments
- Never pass LLM output directly to SQL or shell
- Log every LLM call: input, output, tokens, latency

How long should it be?

Long enough to cover your real conventions — short enough that every rule earns its place.

A 50-line CLAUDE.md with 10 specific, enforced rules beats a 500-line one where Claude picks and chooses what to follow.

Start lean. Add rules when Claude makes mistakes. After 2-3 projects, you'll have something worth copying to your next project.

Skip the blank page

If you'd rather not start from scratch, I packaged 25 production-ready CLAUDE.md files — one per stack.

Each covers the architecture, conventions, anti-patterns, env vars, and testing patterns for its framework.

→ CLAUDE.md Starter Pack ($47) — 5 stars, used daily by developers.

Free excerpts for Next.js SaaS, FastAPI, and AI agents: GitHub.

7 CLAUDE.md Anti-Patterns That Are Killing Your Claude Code Output

Alfredo Augusto — Sat, 06 Jun 2026 16:38:32 +0000

If you use Claude Code, you probably have a CLAUDE.md. But most CLAUDE.md files I've seen actually hurt output quality more than they help.

Here are the 7 most common anti-patterns — and what to do instead.

1. Writing generic instructions Claude ignores

Bad:

- Write clean, readable code
- Follow best practices
- Use meaningful variable names

Claude already tries to do these things. Generic instructions add noise without changing behavior.

Good:

- Never use `var` — always `const` or `let`
- All async functions must handle errors with try/catch — no unhandled promise rejections
- Variable names: `userId` not `id`, `userEmail` not `email`

Specific beats general every time.

2. No architecture rules (the most expensive mistake)

Without explicit architecture rules, Claude will write code wherever is convenient. That means business logic in route handlers, DB queries in components, and utils files that become dumping grounds.

Good (Next.js example):

## Architecture

- `app/` — routing and layouts only, no business logic
- `lib/services/` — all business logic
- `lib/db/` — all database queries, never in components
- `components/` — UI only, no data fetching except via hooks

One rule like this saves hours of refactoring.

3. Forgetting stack-specific gotchas

Every framework has footguns. Claude doesn't know which ones matter to you unless you tell it.

FastAPI example:

- Never use `async def` for CPU-bound operations — use `def` or offload to a thread pool
- Always validate with Pydantic v2 `model_validator` — never raw `dict` access
- DB sessions must use `async with AsyncSession() as session` — never hold sessions open

Next.js App Router example:

- Never use `useEffect` to fetch data — use Server Components or React Query
- Client components only for interactivity — never for data
- Protect routes in `middleware.ts` — never inside page components

4. No testing conventions

Without this, Claude writes tests that technically pass but test nothing meaningful. Or skips tests entirely.

Good:

## Testing

- Unit test business logic in `lib/services/`
- Integration tests for all API endpoints
- Never mock the database in integration tests — use a test DB
- Test file naming: `*.test.ts` colocated with source
- Minimum: happy path + one error case per function

5. Missing environment variable reference

Claude will invent env var names. Then your app breaks in production.

Good:

## Environment Variables

- `DATABASE_URL` — PostgreSQL connection string
- `STRIPE_SECRET_KEY` — never expose to client
- `STRIPE_WEBHOOK_SECRET` — used in `/api/webhooks/stripe` only
- `NEXT_PUBLIC_APP_URL` — only public var, safe for client

6. No error handling conventions

Claude's default error handling is inconsistent — sometimes throws, sometimes returns null, sometimes logs and swallows.

Good:

## Error Handling

- Never swallow errors silently
- Use `Result<T, E>` pattern for recoverable errors
- Throw for programmer errors (invalid state, unexpected data)
- Log at the boundary where the error is first caught — never re-log when wrapping
- User-facing errors: always return a user-safe message, log the real error

7. Writing your CLAUDE.md once and never updating it

Your CLAUDE.md should evolve with your project. Every time Claude makes a mistake that surprised you — add a rule.

That mistake means you found a gap. The next project benefits from it.

The most valuable CLAUDE.md files are the ones with comments like "never do X — we tried this in v2 and it caused Y."

The fix

If writing your CLAUDE.md from scratch sounds like work, I packaged up 25 of them — one for each major stack.

Each one already has specific conventions, architecture rules, anti-patterns, env var references, and testing conventions built in.

→ CLAUDE.md Starter Pack on Gumroad ($47) — or grab 3 free ones from the GitHub repo.

The pack has 5-star reviews from developers who are using it daily. At $100/hr, one saved hour covers it twice.

What's the worst CLAUDE.md anti-pattern you've seen? Drop it in the comments.

CLAUDE.md templates by stack: what Go needs vs. Next.js vs. AI agents (with examples)

Alfredo Augusto — Sat, 06 Jun 2026 16:09:42 +0000

Every time I start a new project with Claude Code, the first 20 minutes used to be wasted.

Not on architecture. Not on setup. On writing the CLAUDE.md file from scratch.

After doing this for the 10th time across different stacks, I mapped out exactly what goes into a high-quality CLAUDE.md for each major framework — and the patterns are very different depending on the stack.

Here's what I learned.

CLAUDE.md for a Go REST API vs. a Next.js SaaS: completely different files

Go REST API needs:

## Error Handling
- Always fmt.Errorf("context: %w", err) — never return raw errors
- Log once at the top of the call stack; never re-log when wrapping
- Domain errors in internal/domain/ as sentinel errors

## Code Structure
- cmd/: Entry points only — no business logic
- internal/handler/: HTTP parsing + calling services
- internal/service/: Pure business logic — no HTTP, no DB
- internal/repository/: All DB queries — none elsewhere

Next.js SaaS needs completely different rules:

## Critical Rules
- Server Components by default; "use client" only for event handlers
- Never useEffect to fetch data — use Server Components or React Query
- Auth: protect routes in middleware.ts only — never in page components
- Stripe: sync subscription state via webhooks — never trust client data
- Never expose Supabase service key to client components

These files solve different problems. One is about Go's error wrapping conventions. The other is about React's rendering model and auth patterns. A generic CLAUDE.md doesn't help either project.

The 5 sections every CLAUDE.md needs (regardless of stack)

After comparing templates across 25 stacks, every effective CLAUDE.md has:

1. Architecture map — where each type of code lives

- handlers/: HTTP only — no business logic
- services/: Business logic — no HTTP, no DB
- models/: DB models only

2. Anti-patterns — what Claude should never do

## Never
- Never put business logic in route handlers
- Never call DB directly from controllers
- Never return raw errors — always wrap with context

3. Domain-specific rules — the stack's non-obvious gotchas

## Stripe
- Webhooks are the source of truth — never trust client-sent state
- Always verify signatures with constructEvent()
- Idempotency keys required for all payment operations

4. Testing conventions

## Tests
- Unit tests for all service layer functions
- Integration tests hit real DB — no mocks
- E2E with Playwright for critical user flows only

5. Environment variables — referenced by name so Claude uses them correctly

## Env vars
- DATABASE_URL: PostgreSQL connection string
- STRIPE_WEBHOOK_SECRET: for webhook verification
- NEXT_PUBLIC_SUPABASE_URL: safe to expose to client

Which stacks need the most specific CLAUDE.md?

From most to least critical to get right:

Multi-tenant SaaS — one missing organizationId filter = data breach
Stripe billing — webhook idempotency is non-obvious and breaks production
AI Agent apps — max iterations and timeout patterns prevent infinite loops
React Native — navigation patterns differ completely from web React
Go APIs — error wrapping conventions are strict and Claude gets them wrong without guidance

Free templates for 3 stacks

I packaged these into production-ready templates. Three are free:

👉 github.com/alfredolancelote-crypto/claude-md-starter-pack

Includes: Next.js SaaS, FastAPI Python, AI Agent/LLM App.

Full pack of 25 stacks (Go, React Native, Shopify, Rust, T3, Django, Electron, AWS Lambda, Turborepo, SvelteKit, n8n, and more) is $47:

👉 alfredolance.gumroad.com/l/uxwvom

What stack are you using Claude Code with? Drop it below and I'll share what the most important rules are for that specific stack.

The CLAUDE.md mistake 90% of Claude Code users make (and how to fix it)

Alfredo Augusto — Sat, 06 Jun 2026 14:48:05 +0000

If you're using Claude Code and your CLAUDE.md looks like this:

Use TypeScript. Write clean code. Follow best practices.

Claude is ignoring it. Here's why — and what to write instead.

The problem with generic rules

Claude doesn't respond to vague instructions. "Write clean code" means nothing to an LLM. It has no way to evaluate whether code is "clean" in your specific context.

What Claude actually follows: specific, verifiable rules that leave no room for interpretation.

What a good CLAUDE.md actually looks like

Generic (ignored):

Handle errors properly

Specific (followed):

Error handling:
- Always fmt.Errorf("context: %w", err) — never return raw errors
- Log once at the top of the call stack, never re-log when wrapping
- Domain errors in internal/domain/ as sentinel errors

The second one is checkable. Claude can verify compliance. The first is subjective noise.

The 3 categories that matter most

1. Architecture rules (where things go)

## Architecture
- api/endpoints/: HTTP parsing + calling services only
- services/: All business logic — no HTTP concerns
- repository/: All DB queries — none in handlers or services

2. Critical anti-patterns (what never to do)

## Never do this
- Never expose Supabase service key to client components
- Never sync Stripe state from client — webhooks only
- Never put auth checks inside page components — use middleware.ts

3. Stack-specific gotchas

## Stripe webhooks
- Always verify webhook signature with stripe.webhooks.constructEvent()
- Make handlers idempotent — check if event already processed
- Store webhook events in DB before processing

Free templates

I packaged these patterns into 25 stack-specific templates. Three are free:

Next.js SaaS (App Router + Supabase + Stripe)
FastAPI Python (async + Pydantic v2)
AI Agent / LLM App (Anthropic SDK + tool use)

Free templates: github.com/alfredolancelote-crypto/claude-md-starter-pack

Full pack of 25 stacks at $47: alfredolance.gumroad.com/l/uxwvom

What's in your CLAUDE.md right now? Drop it in the comments — happy to tell you if Claude is actually using it.

I Made 25 CLAUDE.md Templates So You Don't Have To (Free Ones Included)

Alfredo Augusto — Sat, 06 Jun 2026 00:07:21 +0000

If you use Claude Code, you already know what a CLAUDE.md file is. It's the file Claude reads before doing anything in your project — it tells Claude your conventions, your architecture, and the mistakes to avoid.

The difference between a project with a good CLAUDE.md and one without is massive. Without it, Claude writes generic code that technically works but doesn't fit your codebase. With it, Claude acts like a senior dev who's been on the project for months.

The problem I kept running into

Every time I started a new project, I had to write a new CLAUDE.md from scratch. It took 2-4 hours to figure out the right structure for each stack. What do you put in a FastAPI CLAUDE.md? What about a Shopify app? A Rust CLI?

After doing this for the 8th time, I decided to just build a proper pack.

Here are 3 free templates to try right now

Free Template 1: Next.js SaaS (excerpt)

## Critical Rules

- Server Components by default; add "use client" only for event handlers and hooks
- Never use useEffect to fetch data — use Server Components or React Query
- All DB calls go through server-side Supabase client — never expose service key to client
- Auth: protect routes in middleware.ts, not inside page components
- Stripe: sync subscription state via webhooks only — never trust client-sent data

Free Template 2: FastAPI Python (excerpt)

## Code Conventions

### Separation of Concerns
- commands/: CLI parsing and calling lib functions only
- lib/: Pure business logic — no HTTP concerns, no DB
- repository/: All DB queries — none in handlers or services

### Error Handling
- Always wrap errors with context — never return raw errors
- Log once at the top of the call stack; never re-log when wrapping

Free Template 3: AI Agent / LLM App (excerpt)

## Safety & Reliability

- Set max iterations on all agent loops — 10 is a sensible default
- Timeout on individual tool executions (30s)
- Human-in-the-loop checkpoints for destructive actions
- Never trust LLM output as safe input to SQL or shell
- Log every LLM call with input/output for debugging and cost tracking

The full pack

25 templates: Next.js, FastAPI, React Native, Shopify, T3, Django, Electron, Go, React SPA, Supabase Edge Functions, AWS Lambda, Stripe billing, AI agents, e-commerce, Turborepo, Rust CLI, n8n, Vue/Nuxt, Docker Compose, SvelteKit, Python scraper, and a general fill-in-the-blank template.

Full pack at $47: https://alfredolance.gumroad.com/l/uxwvom

Drop questions about specific stacks in the comments.

15 Production-Ready MCP Servers for Claude: Notion, Stripe, HubSpot, Slack, Supabase and 10 more

Alfredo Augusto — Fri, 05 Jun 2026 19:54:32 +0000

I kept rebuilding the same MCP server infrastructure for every project. After the 5th time setting up a Notion integration from scratch, I packaged everything into a reusable bundle.

What's in the bundle

15 fully functional MCP servers:

#	Server	Key tools
01	Notion	search, pages, databases, blocks
02	Airtable	full CRUD, search, schema
03	HubSpot	contacts, deals, companies, notes
04	Stripe	MRR calc, subscriptions, invoices, payment links
05	Slack	send, read, search, thread replies
06	Google Sheets	read/write ranges, format, append rows
07	Supabase	queries, insert/update/delete, RPC
08	Resend	email, batch send, audience management
09	Cal.com	availability, bookings, create/cancel
10	Linear	issues, projects, teams, search
11	Typeform	forms, responses, insights
12	Webflow	CMS CRUD, publish items
13	Lemon Squeezy	orders, subscriptions, license validation
14	Cloudflare	DNS records, Workers deploy, cache purge
15	PostgreSQL	safe SELECT + writes, schema introspection, transactions

All servers use @modelcontextprotocol/sdk, stdio transport (Claude Desktop compatible), Node.js ESM, typed tool schemas, full error handling.

Pricing

$107 for all 15. MIT license.

👉 https://alfredolance.gumroad.com/l/agency-mcp-stack

Happy to paste source of any server in the comments.

GitHub Copilot Billing Went Live June 1. Here's the Full Token Cost Breakdown (So You Don't Get a $180 Day-1 Bill)

Alfredo Augusto — Thu, 04 Jun 2026 19:58:47 +0000

Copilot's usage-based billing went live June 1, 2026. Visual Studio Magazine ran a headline on Day 1: "Slammed by Copilot Usage-Based Billing on Day 1, Facing $180 Bill for June." Today they followed up: "Copilot Billing Shock Hits Developers."

The problem isn't the new billing model itself — it's that most developers have no idea what each action actually costs. GitHub published the per-token pricing in their docs, but didn't map it to real-world usage patterns.

Here's the complete breakdown.

The Credit Math

1 AI Credit = $0.01 USD.

Your plan includes a fixed credit allowance:

Copilot Pro: 1,500 credits ($15 value) for $19/mo
Copilot Pro+: 7,000 credits ($70 value) for $39/mo
Copilot Max: 20,000 credits ($200 value) for $99/mo

Code completions are free — they don't consume credits. Everything else does.

Model Pricing (What GitHub Buried in Their Docs)

Model	Output Cost/1M tokens	Credits/1M out
Gemini Flash	$0.30	30 cr
GPT-5 mini	$2.00	200 cr
GPT-4o	$10.00	1,000 cr
Claude Sonnet 4.6	$15.00	1,500 cr
Claude Opus	$75.00	7,500 cr

Real-World Cost Table (The Part That Shocks People)

What You're Doing	Model	Est. Output Tokens	Credits	Cost
Simple rename	Sonnet	~5K	7	$0.07
Add unit tests	Sonnet	~15K	22	$0.22
Fix a bug	Sonnet	~30K	45	$0.45
Complex refactor	Sonnet	~80K	120	$1.20
Architecture review	Opus	~50K	375	$3.75
10-file agent run	Opus	~200K	1,500	$15.00
Heavy agent day	Opus	~500K	3,750	$37.50

That last row is your entire Pro+ monthly credit budget. In one day.

Why This Is Happening

Copilot's default in agent mode often routes to frontier models (Opus, GPT-5). It uses the same model for a quick rename as for multi-file architectural changes. Nobody configured it otherwise because under flat-rate billing, it didn't matter. Now it does.

The Fix (5 Minutes)

Add this to your VS Code settings.json:

"github.copilot.chat.defaultModel": "gpt-4o",
"github.copilot.advanced": { "length": 500, "temperature": 0 },
"github.copilot.enable": {
  "markdown": false,
  "yaml": false,
  "json": false
},
"github.copilot.chat.agent.runCommand": false

Also: go to github.com/settings/billing and set a hard spending limit to $0 overage. This stops Copilot from charging your card after credits run out.

The Model Selection Rule That Saves 70%

Route by task complexity:

Tests, docs, renames → Gemini Flash or GPT-5 mini ($0.30–$2/M output)
Feature dev, bug fixes → Sonnet or GPT-4o ($10–15/M output)
Architecture, complex multi-file → Opus or GPT-5 (only when genuinely needed)

65% of daily coding tasks don't need a frontier model. Matching model to task is where the 70% savings comes from.

Going Further

I put together a complete kit: full model cost reference card, VS Code config templates (copy-paste ready), a cost calculator spreadsheet, and a migration guide for Cursor/Continue.dev if Copilot is still too expensive after optimizing.

→ GitHub Copilot Billing Survival Kit — $37

Or use the free tips above — the settings change alone cuts most bills by 40-70%.

Happy to answer questions in the comments.