Common Claude Code setup mistakes

In this section I'd like to offer a few comments to protect you from starting out with bad practices for setting up your Claude Code workflow. Let's look at typical mistakes and how they can be avoided.

Vibe-setups (configuring AI with AI)

My favorite category of setups: someone has only just launched Claude Code and, without any further study, writes a prompt like "I need 20 agents, 40 MCPs, and skills for all of it, so that it works..." — and the output is an absolute mess (and that's if it works at all).

A real case from work: a colleague asked me to help with a setup of agents for design and illustration work. He said everything worked, but not quite the way he wanted. I thought: "Well ok, I'll just tweak the agents a bit and that's it." Then, like the experienced person I am, I opened a text editor to find the agent files in the .claude directory, but there were exactly zero of them. Trick question: "So where are the agents?", answer: "I don't know, but they exist"... It turned out he had been creating agents with prompts, which Claude had simply saved into its "auto memory" (a mechanism that lets Claude save and retrieve information between conversations), but in reality the agents never existed.

Please, install yourself some kind of editor and keep an eye on what the AI is configuring for you in there. This is a very important point that will affect how well everything works from then on.

A huge system prompt (CLAUDE.md)

If you still don't know what this is for, welcome to the documentation.

Do you treat this file as a single source of truth where everything should go (the style guide, the project history, the list of commands, the docs)? Then it grows into a wall of text that gets loaded into context at every step, devouring the context window in a second.

Keep it short and store only the general, most important rules. Everything that's needed situationally should be moved out into skills — they activate when they're needed. The system prompt is what the agent must remember at all times.

Conflicting instructions

A continuation of the previous point. Usually, once there are too many settings, contradictions begin: CLAUDE.md says "always answer in Russian," a skill says "talk to me in English," and the agent's prompt says something else entirely.

As a result, the model receives mutually exclusive instructions and picks between them unpredictably, and then the questions come: "So what's the deal here?!"

Before writing an instruction, check whether it's already specified somewhere else.

Wrong model choice

If you put the most expensive model on simple tasks like "rename these variables" — you'll burn a lot of tokens on resources that weren't needed. At the same time, if you put a weak model on a complex task, you'll then be left wondering why the agent can't cope.

The model should be matched to the complexity of the task. A simple mechanical agent will do fine with a cheaper and faster model. An agent that designs things or untangles complex logic needs a stronger model.

Bad skill descriptions

A skill triggers off its description, not its name. Claude reads this description and decides on its own whether it's appropriate to use the skill right now or not. In effect, the description is not documentation for humans, but a trigger for the model.

If you write it too abstractly, the skill will either fail to activate when it's needed, or suddenly show up when it's not required. A good description states directly when to apply it and, just as importantly, when not to.

Abstract agent roles

"You're an awesome assistant, help me out" — and the output is exactly the same kind of answer you'd get from GPT-3.5.

The more specific the role and constraints, the more useful and precise the result. An agent is a specialist for a specific task, not a generalist.

The agent can do everything

Tools should match the role. A reviewer only needs reading, because it points out problems, while fixing them is up to a human or another agent. A researcher agent needs search and reading, but definitely not writing. The narrower the set of permissions, the more predictable the behavior we get on the output.

Be careful with this and explicitly delineate what your agents can do. Give them excessive freedom, and one day you'll run into unexpected behavior that could cost you deleted files.

An interim result and my wishes

Let's pause for a bit and sum up the information we've gathered. At this point we've gotten acquainted with the entire modern foundation (as of 20.06.2026), which is enough for confident everyday use. If you've understood all the terms, read the attached links, and studied the main problems of the technology you're using, then that's more than enough for you — I'm serious. The social bubble around AI is so enormous that people are under perpetual pressure and constantly feel like they don't know enough, even though that's not the case at all. A solid foundation of the core concepts everything is built on is always more important than phantom knowledge. Remember that.

Come across yet another post where yet another person (or maybe an AI model, who even knows anymore) tells you, without any evidence, how they replaced an entire company and are living happily? You should always subject that kind of "content" to criticism, trusting only numbers and proof. In particular, you should absolutely question me and my approach too.

What's coming next in the article? I want to break down using LLMs for composite tasks that are hard (or not quite efficient) to solve with a single prompt or agent. We'll look at my approach to building multi-agent systems in the Theory of building multi-agent systems article.