Claude Code Without the Magic: Habr Breaks Down Architecture, Context Noise and Engineering Practices

Habr has published a translation of a long, practical text about Claude Code, based on half a year of intensive work with the agent. It is not a recap of features. It examines why an AI development tool starts to fail when it is given too much context, too many rules and too much freedom all at once.

Where context gets lost

The article's main idea is simple: Claude Code breaks down not because the model is "not smart enough" but because the engineering environment around it is poorly designed. The author describes the agent as a loop of gathering context, acting and verifying the result. If even one layer of that loop is overloaded, quality drops sharply: a long CLAUDE.md adds noise, dozens of tools complicate selection, and the lack of a quick check turns every edit into a lottery. In this mode, developers keep tweaking prompts endlessly, even though the problem runs deeper.

The article takes a separate look at the cost of context. Claude Code formally has a large window, but a significant share of tokens is spent before work even begins: on system instructions, skill descriptors, MCP tool descriptions, LSP state, memory and the project's CLAUDE.md. The author gives a telling estimate: a single typical MCP server can take up thousands of tokens on tool schemas alone, and several connected servers easily consume a noticeable share of the available window. Add long test output, grep results and logs, and the useful dialogue history starts getting pushed out on its own.

• System instructions and base rules
• Descriptions of skills and MCP tools
• Project memory and the contents of CLAUDE.md
• Results of shell calls, tests and searches
• A compressed, but no longer always accurate, session history

This leads to a practical conclusion: rarely used knowledge should not live in permanently loaded context. When switching tasks, it is better to clear the session more often; when continuing in the same direction, use managed compaction. Another tip from the article is to ask the agent, before a new session, to write a HANDOFF.md covering progress, dead ends and verification status. This is cheaper and more reliable than hoping automatic compaction will preserve the architectural decisions that really matter.

Skills, hooks and agents

The second major section is about separating roles. The author recommends not lumping MCP, tools, skills, hooks, plugins and subagents together. The logic: a tool adds a new capability, a skill defines a workflow, a hook builds in a mandatory automatic check, and a subagent moves a separate task into an isolated context. This is a useful distinction, because many teams try to cure every failure with a new prompt or yet another tool, when the problem may be solvable at an entirely different level.

The article also explains what a good skill looks like. It has a short, precise descriptor, a clear usage trigger, and spelled-out inputs, outputs and a stop condition. Everything heavy, such as examples, runbooks and helper files, should be pulled in on demand rather than sit in the main SKILL.md. For actions with side effects, the author advises explicitly disabling automatic invocation by the model. The idea is that the agent first sees an index and a route, and loads details only at the moment they are actually needed.

In this analysis, subagents are presented not as a way to "speed everything up in parallel" but as a means of isolation. Codebase exploration, review, test runs and other noisy operations are better sent to child threads with limited permissions, a separate model and a fixed response format. Hooks, by contrast, should catch deterministic things as early as possible: run a quick check after a file edit, block dangerous changes, and inject technical context at session start. The earlier the system catches an error, the fewer tokens, less time and fewer unnecessary edits go to waste.

Cache, verification and the contract

One of the most interesting parts of the text explains how heavily Claude Code's architecture depends on prompt caching. The author writes that a stable prompt prefix saves not only money but also reduces friction with usage limits. This yields several non-obvious rules: do not insert dynamic data into the system prompt, do not shuffle the order of tools, do not switch models in the middle of a long session without need, and, where possible, defer full loading of rarely used tool schemas. Even Plan Mode, the article notes, is better implemented without changing the entire toolset, so as not to break the cache.

The final emphasis is on verification and on the role of CLAUDE.md. The author calls this file not a knowledge base but a contract between the project and the agent: how to build, how to test, which boundaries must not be crossed, what must be preserved during compaction, and which prohibitions always apply. CLAUDE.md should not carry API references or long introductions; it should hold only the rules that are critical in every session. Another tip is to ask the agent to update its contract after each recurring error, so that typical mistakes do not return.

"If you cannot explain how to tell that

Claude did the right thing, the task is most likely not suited to fully automatic execution."

What this means

This material matters for more than Claude Code users. In essence, it is a guide to maturing any AI development agent: less magic, more isolation, explicit verification and control over context. The more teams move from a "chatbot for code" to a semi-autonomous engineer, the more valuable these practices become, compared with yet another collection of prompts.