This analysis examines why Claude Code Gets Worse in Long Sessions, what evidence supports the argument, and where the conclusion still has limits.
Read the evidence below as a decision trail: what changed, why it matters, which trade-offs shaped the result, and where the conclusion still depends on context.
After using Claude Code for a long time, it will start to "forget" your instructions, the output format will be unstable, and processes that should be run will be skipped. It’s not that the AI has become dumb, it’s that there’s something wrong with your system design. The Claude Code project was reconstructed using the thinking of Six-Layer Architecture, and the stability of instruction compliance was significantly improved.
- The context window of Claude Code has about 200K tokens, but system commands, tool definitions, CLAUDE.md, and Memory are all competing for space - your command budget is only 100-150 instructions left, and attention (Attention) will decrease with the amount of information.
- The six-layer architecture (context, execution, control, subagent, cache, validation) is a system design framework that helps you determine which problems should be solved at which layer, instead of cramming everything into CLAUDE.md.
- Actual measurement results: After splitting the 300 lines of CLAUDE.md into 40 lines of core instructions + 3 skills loaded on demand, the stability of Claude's instruction following is significantly improved, and fact-check is no longer skipped.
Is your Claude Code getting dumber the more you use it?
If you use Claude Code for more than two weeks, you will probably go through this process: you will be amazed at its capabilities at first, and then as the project becomes more complex, you will start to stuff increasingly rules into CLAUDE.md. Role setting, workflow, format specifications, precautions... After writing to a certain critical point, Claude began to behave strangely - the fact-check that should be run was skipped, the output format was correct and the time was wrong, and the clearly written rules were ignored.
I have two Claude Code projects: blog-writer (AI content production line) and gwarket-site (website reconstruction). Blog-writer's CLAUDE.md has 300 lines, which is mixed with role settings, command list, topic selection process, transcription process, source list of 14 companies, output format specifications for three platforms, and fact-checking rules. The result is that Claude forgets to run fact-check from time to time and the output format is unstable. Another project, gwarket-site, has no verification mechanism at all. After changing the code, I have to check with my own eyes whether there are any problems.
I spent two days reconstructing the Claude Code architecture of these two projects. What this article records is not the operation steps, but how to apply system design thinking to AI Agent projects from the perspective of a manager.
CLAUDE.md The more you write, the more disobedient Claude becomes.
Intuition tells you: the more instructions you give, the better the AI should perform. But large language models (LLMs) work in exactly the opposite way.
Physical limitations of Context Window
Claude's context window is about 200K tokens. It sounds like a lot, but this space must accommodate system commands, tool definitions, CLAUDE.md, Memory, your conversation history, every file read by Claude, and the output of every command execution. According toZenML analysis of Claude Code architecture, when the context usage reaches about 92%, the system will automatically trigger compaction (Compaction). Compression means forgetting - early architectural decisions, your carefully written rules, can all be abstracted away during the compression process.
The scarcity of Attention is more fatal than Token
The more critical issue is the limited nature of attention. According toHumanLayer Research Analysis, the number of instructions that the frontier thinking model can stably follow is about 150-200. Claude Code's own system instructions account for about 50. In other words, your CLAUDE.md only has a budget of 100-150 instructions left. The more information there is, the less attention each command gets. The "just in case" mentality is actually diluting every rule that really matters.
This is exactly the same as the management team: if you give an employee 200 SOPs, he will not remember every one of them, but he will remember the 10 that are most often reminded. The remaining 190 do not exist.
Six-layer architecture: Design Claude Code as a system
After understanding the nature of the problem, the solution becomes clear - not "write a better prompt", but "design a better system". Anthropic in《Building Effective Agents》emphasized: "The most successful Agent implementations do not use complex frameworks, but simple, composable patterns."
The following six-layer architecture is the thinking framework I summarized when reconstructing my own project:
The first layer: context layer (CLAUDE.md + Skills + Memory) - determines what Claude "knows"
The core question at this level is: Which information needs to be permanent and which needs to be loaded on demand?
According toAnthropic official Skills file, Skills adopts a Progressive Disclosure mechanism: only metadata (about 100 tokens) is loaded at startup, and the complete content (no more than 5K tokens) is read only when triggered. This means you can install many Skills without context burden.
My approach: blog-writer compressed CLAUDE.md from 300 lines to about 40 lines, leaving only the instruction skeleton. Writing style, output format specifications, and fact-check rules are each separated into independent Skills, which are only loaded when corresponding tasks are performed.
Second layer: Execution layer (Tools + MCP) - determines what Claude "can do"
The more tools the better - Claude needs to decide which tool to use in each agent loop (Agentic Loop). Too many tools will increase the decision-making burden.Principles of Context EngineeringYes: Tools should be "self-contained, non-overlapping, purpose-specific".
Practical example: gwarket-site uses preview server for instant visual verification, and blog-writer uses WebFetch to crawl source articles. The toolsets for the two projects are completely different because of the different nature of the tasks.
The third layer: Control layer (Hooks + permissions) - ensure that what is supposed to happen happens 100%
This is the most underrated layer.Anthropic official documentationThere is a clear distinction: the instructions in CLAUDE.md are "advisory" (advisory), and Hooks are "deterministic" (deterministic).
To put it bluntly: If you write in CLAUDE.md "Run build verification every time you change the code," Claude will sometimes forget it. But if you set a Hook to automatically trigger the build after each file edit, it will be executed 100% of the time. If text commands are not stable enough, you should move to Hooks.
The fourth layer: Subagent layer (Subagents) - isolate context to avoid token pollution
The architecture of Claude Code isSingle-threaded Master LoopDesign, all conversations share the same message history. When you ask Claude to research a problem, each file it reads eats the context of the main conversation. The subagent operates in a separate context window and only returns summary results.
Just like you wouldn’t have your entire team attend every meeting—for tasks that require in-depth research, just send one person to investigate and come back with conclusions.
Layer 5: Prompt Caching—reduces repeated calculations
System commands and CLAUDE.md, which are the same content every time, can significantly reduce latency and cost through prompt caching. You don't need to manually optimize this layer, but understanding its existence can help you make architectural decisions - keep CLAUDE.md stable and infrequently changed, the more efficient the cache will be.
The sixth layer: Verification layer (testing, Lint, manual confirmation) - the more important it is for the Agent to run through the automatic verification
The official Anthropic document lists "a way for Claude to verify his work" asBest Practices for Maximum Leverage。
The rule after gwarket-site refactoring is: automatically execute every time the code is modified.npm run build, it will be considered complete only if zero errors are confirmed. This is not a suggestion written in CLAUDE.md, but a validation enforced through the workflow.
Before / After: Actual refactoring of two projects
Blog-Writer: From chaos in 300 lines to precision in 40 lines
Before：A 300-line CLAUDE.md, everything mixed together - role setting, instruction list, topic selection process, transliteration process, source list of 14 companies, WordPress/Facebook/LinkedIn three format specifications, fact-check rules. Claude often skips fact-check and the output format is unstable.
After：
- CLAUDE.md is compressed to about 40 lines (only the instruction skeleton, filtering rules, and process summary remain)
- 3 Skills are loaded on demand: writing-style (writing style), output-formats (three-platform format specifications), fact-check (checking rules)
- The source list is independent of sources.md
- Added article-log.md to track already written articles to avoid duplication of ideas
- Added HANDOFF.md for cross-session handover
Gwarket-Site: From zero verification to structured management
Before：There is no verification layer, no handover documents, and all code modifications must be confirmed with the naked eye.
After：Modified changes
- CLAUDE.md 59 lines (via custom 80 line limit)
- 2 Skills: ui-design (design style guide), code-conventions (technical conventions)
- Added HANDOFF.md to record project status
- Working rules: Automatically run build verification after modifying the code. Modifications of more than 3 files must be planned first.
The judgment logic of splitting
Information required for each session → stay in CLAUDE.md. Knowledge required for specific tasks → split into Skills (loaded on demand, does not occupy permanent context). Actions that rely on text instructions are not stable enough → Use Hook (deterministic execution) instead. State to remember across sessions → HANDOFF.md.
There is also a shared CLAUDE.md (about 30 lines) in the upper directory of the two projects, which only contains role positioning, communication style, and session management rules. It's like a company's general specification that doesn't need to be rewritten for every project.
Verification result:After the refactoring is completed, let Claude Code verify itself - the number of lines in CLAUDE.md is qualified, the YAML frontmatter format of Skills is correct, HANDOFF.md is consistent with the project status,npm run buildPassed (4 static pages with zero errors).
My opinion: Context Engineering is replacing Prompt Engineering
After completing this refactoring, my biggest realization is: Claude Code is not a "stronger programming AI", it is an agent system that needs to be designed.
In the past, we talked about Prompt Engineering - how to ask good questions and how to give good few-shot examples. But when you use Claude Code to run a project that lasts for several weeks, the quality of a single prompt is just the tip of the iceberg. What really determines success or failure is Context Engineering: how to design the system so that AI has the correct context for every interaction.
This is not a problem unique to Claude Code. Any agent tool—Cursor, Windsurf, Copilot—faces the same architectural challenges. Context window is a physical limitation, and attention is a scarce resource. It doesn’t matter which tool you use, it’s how you design the information architecture that matters.
HANDOFF.md This little mechanism helps me the most. I am not a full-time engineer, I only work on these projects a few hours a week, and the sessions are often interrupted. HANDOFF.md allows you to catch up quickly every time you come back, without spending 20 minutes recalling "what you did last time." If you are also someone who uses Claude Code in spare time, it is strongly recommended to add this mechanism.
The goal is not to let AI help you solve problems, but to make AI "a tool for you to make tools." And good tools require good system design.
How long should the CLAUDE.md of Claude Code be?
According to HumanLayer's analysis, the frontier model can stably follow about 150-200 instructions, while the Claude Code system instructions itself account for about 50. It is recommended that CLAUDE.md should be kept within 60-80 lines, and only the information needed for each session should be placed, and the rest should be split into Skills and loaded on demand.
When should you use Hooks instead of writing rules in CLAUDE.md?
Use Hooks when an action must be executed 100% of the time. The instructions in CLAUDE.md are essentially "suggestions" that Claude may ignore when the context is crowded. Hooks are deterministic scripts, such as automatically running ESLint every time a file is edited, and do not rely on LLM's attention allocation.
What is the difference between Context Engineering and Prompt Engineering?
Prompt Engineering focuses on "how to ask good questions" and is the optimization of a single conversation. Context Engineering focuses on "how to design the system so that AI has the correct context every time" and is the design of the entire Agent architecture. The former is technique and the latter is engineering.
This article is original content from gwarket, written by Aaron Huang.
What to take away
The useful decision is not to accept the headline at face value, but to test whether the evidence supports Claude Code Gets Worse in Long Sessions in the reader's own context.