Every developer using Claude Code or Cursor has hit the same wall at some point.
You spin up a new project, start vibing with the AI, and for the first hour everything feels like magic. Then slowly things start going sideways. The agent reformats a file it had no business touching. It runs the entire test suite to check a two-line change. It invents a new folder structure that contradicts the one you established three days ago. It adds an abstraction layer you didn't ask for and now have to maintain.
None of this is the AI's fault. It's working with what you gave it.
The uncomfortable truth about AI coding tools
AI agents don't have opinions. They infer conventions from context. If your project has strict ESLint rules, the agent follows them. If your project has no rules, the agent makes them up - differently every session.
This means the single biggest lever you have over AI code quality isn't your prompt. It's your project setup.
I spent months figuring this out the hard way, and the pattern became clear:
Lint rules act as a spec. When ESLint is configured with sonarjs, unicorn, and perfectionist, the agent produces code that passes those rules - or the pipeline rejects it and the agent fixes itself. Either way, low-quality code doesn't accumulate.
Tests change agent behavior. A project with Jest already configured gets test coverage by default. The agent writes tests because the infrastructure is there. Without it, tests are always "coming later" -and later never comes.
Architecture is contagious. Consistent folder structure and naming conventions propagate. The agent sees the pattern and follows it. An inconsistent codebase produces inconsistent AI output.
Token waste is a setup problem. By default, Claude Code reads everything it can find, runs the broadest possible test suite, and touches adjacent code "just to be safe." This is expensive and produces
noisy diffs. A well-written CLAUDE.md fixes most of it.
What CLAUDE.md actually changes
CLAUDE.md is a file Claude Code reads at the start of every session. It's essentially a standing instruction set for the agent - and it has a measurable effect on how the agent operates.
Here's what made the biggest difference in practice:
Cost Saving Rules
- Run only affected tests when possible
- If only one test file was modified, run only that file
- Read only files relevant to the current task
- Avoid scanning the entire repository unless necessary
Code Rules
- Don't add features or abstractions beyond what the task requires
- Prefer minimal diffs
- Avoid reformatting unrelated code
- Preserve existing architecture and conventions
After adding these rules, the diffs got smaller, token usage dropped, and reviews became faster. The agent stopped "helpfully" refactoring things that were working fine.
Rockpack 8.0
I've been maintaining Rockpack for several years - a CLI scaffolder for React projects. Version 8.0 is the first release built with AI-assisted development as a
first-class concern.
One command:
npm i -g @rockpack/starter
rockpack my-app
What you get:
- React 19 + TypeScript 6 with strict configuration
- Webpack 5 - CSR, SSR, library builds, bundle analysis out of the box
- ESLint 10 flat config - sonarjs, unicorn, perfectionist, no-only-tests, import-lite, Prettier integrated
- Pre-commit hooks - lint runs before every commit, bad code physically cannot get in
- Jest pre-configured with TypeScript support
- Feature-based project structure - consistent from the first file
- Optimized CLAUDE.md - included in every generated project
Supported project types: React SPA, React SPA + SSR, React Component (npm-ready), UMD Library.
Why this matters now
A year ago, "AI-friendly project setup" wasn't a thing people thought about. Today it's the difference between an AI that saves you hours and one that creates extra work.
The tools are good. The gap is the environment they work in.
Rockpack closes that gap in a few minutes instead of a few days.
https://github.com/AlexSergey/rockpack - MIT license.
If you're actively using Claude Code or Cursor, I'd be genuinely curious what's in your CLAUDE.md. There's no established best practice yet and the community is still figuring this out.
Top comments (0)