Next.js + Claude, actually: the workflow I’d send my past self

A developer with years of Next.js experience describes a workflow for using Claude as an AI coding assistant that treats it like a coworker rather than autocomplete-plus, achieving significantly better results by running /init to generate a CLAUDE.md file, hand-editing it with three to five real conventions, and creating scoped Skills for component libraries, data patterns, and testing. The workflow includes slash commands /init, /review, and /security-review, the last of which caught a real authz bug in a server action that would have shipped otherwise.

I’ve been writing Next.js since the pages/ directory was the only directory. I've watched this ecosystem cycle through "this changes everything" moments enough times that I am, on principle, suspicious of new tools. So when AI coding assistants first hit, my honest reaction was: yeah, autocomplete-plus. Fine. I was wrong about the ceiling. Not about most of them being autocomplete-plus, they were, but about how high the ceiling actually goes once you stop treating Claude like Copilot and start treating it like a coworker who needs to be onboarded. This is roughly the workflow I’ve landed on after a year of shipping Next.js apps this way. It is opinionated, some of it will not apply to your stack, and I reserve the right to change my mind about half of it within six months. Most people open Claude, paste a question, and judge the model on the answer. Which is like judging a chef by handing them a knife with no ingredients. In a new repo, the first thing I run is /init. It scans the project and drops a CLAUDE.md at the root. Framework version, scripts, where the tests are, what the conventions look like. Claude reads that on every turn after. It's twenty seconds of work and the single highest-leverage thing you'll do all week. Then I hand-edit it. Usually I add: That’s it. Three lines. The difference in output quality from those three lines is not subtle and I cannot overstate it. I used to think I’d write a giant elaborate CLAUDE.md. I tried it on a side project. It made the output worse because the model was juggling too many constraints. Three to five real conventions, written like you'd tell a new hire on their first day. That's the move. Skills are the part nobody talks about and they’re the thing that made this actually click for me. They’re scoped instructions Claude pulls in automatically when relevant. The ones that matter for Next.js work specifically: A skill that knows your component library. We have an internal design system, and before I built a skill for it, Claude kept inventing components that didn’t exist. <Card variant="ghost" does not ship at my company, friend. With the skill installed, it grounds itself in what actually exists. A skill for your data pattern. Server Action vs route handler vs RSC fetch. The decision tree is short but nontrivial and you do not want Claude guessing. We use Server Actions for mutations, RSC fetch for reads, route handlers basically only for webhooks. Took me an embarrassingly long time to settle on this. A skill for testing. Vitest + Playwright in my case, with the fixture conventions baked in. I built my first skill with the skill-creator skill yes, a skill for making skills, the framework people will love this and it took twenty minutes. I am not exaggerating. The payoff is that I stop re-explaining the same conventions every session, which is the single most exhausting thing about working with any AI assistant. A handful of slash commands ended up in muscle memory. Not all of them, just these: /init. Already covered. /review. Point it at a diff or a directory. It reads the code against CLAUDE.md and flags issues. I run it before every PR I open. It catches roughly half of what my human reviewers used to catch, which means they get to spend their attention on the half that actually matters. The other half is mostly nits about naming and missing tests, and yeah, fair. /security-review. This is the one I'm evangelical about. Runs against pending changes on the current branch, looks for the usual suspects: auth holes, XSS, SSRF, leaky env vars, the unsafe sinks, server actions that don't check the session. A few months back this command found a real one. I had a server action that took an accountId from the client and ran a query with it. No authz check. I would have shipped it. The PR was clean, tests passed, my reviewer almost certainly wouldn't have caught it because the bug was a missing thing, not a wrong thing. /security-review caught it. I bought the team coffee that week. Plan mode in general. I won’t shut up about plan mode. For anything bigger than a tweak, I tell Claude to plan first. I read the plan. I push back on what I don’t like. Then it writes code. This one habit moved my “Claude generated something I had to throw away” rate from around 30% to under 5%. The model is genuinely better at planning than at correcting bad code it’s already written, and getting that feedback loop right is most of the game. Claude has an Agent tool that spawns a fresh subagent for a defined task. Useful, but easy to misuse. The cases where I reach for it: Auditing the codebase for a pattern. “Find every place we do client-side fetching that should be a server action.” It comes back with file paths and line numbers, I review, I decide. The advantage over me grepping is that it understands what “should be a server action” means, not just where fetch appears. Independent code review. The code-reviewer subagent gets the diff and almost no other context, which is the point. It's not anchored to whatever I was reasoning about ten minutes ago. Closest thing to a second pair of eyes I have when I'm shipping at 11pm. Migrations. Pages router to App Router for marketing routes. Adding loading.tsx everywhere it should exist. The well-defined, mechanical stuff that I do not want to do by hand. Things I do not delegate: anything where I haven’t yet thought through what the right answer looks like. A subagent will produce confident output for the wrong goal and now I have a PR-shaped pile of code to throw away. The model is good at the thing in front of it. It’s not good at knowing which thing should be in front of it. That part’s still you. Last week, search page. Streams results from Postgres, renders incrementally with RSC. I needed it done in an hour because I had a call at 3. Plan mode first. I asked for the file structure and the suspense boundary layout before any code. Claude proposed app/search/page.tsx, a SearchResults server component, a <Suspense boundary, and a SearchSkeleton client component. I pushed back on the skeleton because we already have one in the design system. It corrected. Fine. Code generation, took maybe ten minutes. Then /review app/search. Two things flagged: not debouncing the URL param, empty state not handled. Both real. Fixed both. Then /security-review. Clean. Pushed. Made the call. The thing this replaces is not the typing. The typing was never the bottleneck. What it replaces is the forty-five minutes of context-switching between the Tailwind docs, the Next.js docs, our design system docs, and Stack Overflow when I can’t remember exactly how unstable cache interacts with revalidatePath. I am still the one making every decision. I'm just not the one doing the lookups. I want to say this clearly because I’ve watched it happen to people: this is not autopilot. Every senior engineer I know who tried to fully delegate to Claude came back chastened within two weeks. The codebase gets weird. The patterns drift. Code that “works” but nobody understands the shape of starts to accumulate, and three months later you’re the one trying to debug it at midnight. It’s also not a substitute for knowing Next.js. The engineers getting the most leverage out of this workflow are the ones who already had Next.js in their bones and now move faster. The ones using it to avoid learning Next.js are the ones whose codebases I keep getting hired to clean up. There’s a version of this that turns you into a worse engineer over time. There’s a version that turns you into a better one. The difference is whether you’re using Claude to skip the thinking or to skip the typing. Spend an hour on your CLAUDE.md and one custom skill before you write another line of code with an assistant. The model is fine. The bottleneck is context. Give it some. Anyway. Going to run /review on this post next, see what it says. Next.js + Claude, actually: the workflow I’d send my past self https://blog.stackademic.com/next-js-claude-actually-the-workflow-id-send-my-past-self-048b38c99c39 was originally published in Stackademic https://blog.stackademic.com on Medium, where people are continuing the conversation by highlighting and responding to this story.