cborgia.me — Field Notes on Software & Systems

I've been using Claude Code daily. Here are some patterns that work well.

Use CLAUDE.md for project context

Drop a CLAUDE.md in your project root with instructions about your codebase conventions. Claude reads this automatically at the start of every conversation.

Things worth putting in there:

Preferred package manager
Database conventions (e.g., "never use drizzle-kit push")
Framework-specific notes (e.g., Next.js version quirks)
File naming conventions

The Claude Code team shares a single CLAUDE.md checked into git and updates it multiple times a week. Anytime Claude does something incorrectly, they add it to CLAUDE.md so future sessions avoid it. Institutional knowledge compounds over time.

Be specific about what you want

Instead of:

"Fix the bug"

Try:

"The login form submits but doesn't redirect. Check the auth callback handler in app/api/auth/callback/route.ts."

Let it read before it writes

If you're asking Claude to modify code, let it read the file first. Saying "read the file first" or just pointing it at the right file gives much better results than describing the code from memory.

Use slash commands

/commit — generates a commit with a good message
/review-pr — reviews the current PR

You can also create custom commands in .claude/commands/ for workflows you repeat often — component scaffolding, deploy scripts, whatever. These are checked into git so the whole team benefits.

AGENTS.md for version-specific warnings

If you're using a framework version that differs from Claude's training data, put warnings in AGENTS.md. For example:

# This is NOT the Next.js you know
 
This version has breaking changes. Read the relevant guide
in `node_modules/next/dist/docs/` before writing any code.

Plan first, execute second

Start most sessions in Plan Mode (Shift+Tab twice). Go back and forth with Claude until you like the plan, then switch to auto-accept and let it execute. Boris Cherny (creator of Claude Code) calls this his default workflow — planning up front means Claude can usually one-shot the implementation.

This is especially important for multi-file changes. A Next.js route refactor touching layouts, server components, and client components benefits massively from having a plan before any code gets written.

Next.js-specific CLAUDE.md rules

Generic CLAUDE.md instructions help, but Next.js projects need specific guardrails. Here's what I put in mine:

## Next.js conventions
 
- App Router only — never use Pages Router patterns
- Server Components by default, `"use client"` only when needed
- Fetch data in Server Components with async/await
- Use server actions for mutations, not API routes
- Use Next.js primitives: Image, Font, Link — not raw HTML equivalents
- No useEffect for data fetching

Without these, Claude tends to reach for useEffect and client-side fetching even when a server component would be simpler. Encoding the anti-patterns explicitly prevents entire classes of mistakes.

Give Claude a verification loop

The single biggest quality multiplier is giving Claude a way to check its own work. The Claude Code team uses a browser extension so Claude can open the app, navigate the UI, and iterate until it works. If Claude has that feedback loop, the quality of the output goes up dramatically.

For Next.js specifically, this means:

Let Claude run npm run build to catch type errors and build failures
Use the preview tools to verify the page actually renders
Have it check the console for hydration mismatches

A build that passes is worth more than code that looks right.

Use /compact and /clear to manage context

Long sessions degrade Claude's focus. Use /compact to summarize progress between major tasks and /clear when switching to something unrelated. This keeps responses sharp and reduces token costs significantly.

Commit after every successful change

This one seems obvious but it's easy to forget when you're in flow. Commit after every working change so you can roll back when something breaks. Run git diff before accepting changes to check for surprises — Claude sometimes adds dependencies or modifies files you didn't expect.

Run /init on new repos

Before working on any repo for the first time, run /init to auto-generate a CLAUDE.md by analyzing your codebase. It gives you a starting foundation you can then customize with your own conventions.

Post-edit hooks for formatting

Claude doesn't always match your formatter config. Set up post-tool hooks in .claude/settings.json to auto-format files after Claude edits them. This handles the last 10% and avoids formatting failures in CI.

{
  "hooks": {
    "afterToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Claude Code Tips and Tricks