The context rot concern is real but I've found it's more about structure than size. My CLAUDE.md is ~500 lines but it's organised into quick reference tables, critical rules (the stuff that MUST be followed), and project architecture notes. The key is frontloading the high-signal stuff.
What's worked for me: having separate sections for "things Claude needs every session" vs "reference material it can look up when needed". The former stays concise. The latter can grow.
The anti-pattern I see is people treating it like a growing todo list or dumping every correction in there. That's when you get rot. If a correction matters, it should probably become a linting rule or a test anyway.
My problem is that Claude often don't consult the reference materials.
And I am back to manually including markdown files in the prompt.
Say I have a TypeScript.md file with formatting and programming guidelines for TypeScript. Sometimes Claude edit TypeScript files without consulting it, despite it being linked referenced CLAUDE.md.
Are you seeing a benefit above doing this in the prompt / project structure?
Currently, I have Claude set up a directory with CLAUDE.md, a roadmap, a frequently used commands guide, detailed by-phase plans, and a session log with per-session insights and next steps.
After each phase is done, I have it update the documents and ask what could have been done to make the session easier—often the answer is clearer instructions, which eventually leads to topic-specific documents or a new Claude Skill.
(edit) These reflection tasks are spelled out in the CLAUDE.md and in the docs directory, so I don't have to type them. Each new session, I paste a guide for how Claude should access the information from the last session.
I keep the context concise by linking from claude.md to markdown files with the hardware architecture, the network architecture, the processing tech stack. Concise and specific. And a current project md.
I mix in the parts that are relevant.
I don't have a roadmap and session log though. Good idea.
Your workflow sounds solid - and honestly more disciplined than most. The difference I was going for: catching implicit corrections you don't consciously document.
So probably complementary to what you're doing, not a replacement. If you're already doing post-phase reviews, you might catch most of this anyway.
I totally understand that this is not really a small ask, but if you could put together some sort of example repo of this setup I and probably a lot of people with me would be most grateful! I don't mean with running code or anything, just the doc structure for Claude.
No problem! I recommend asking Claude for these sorts of things so they can better match your own processes.
----
New session:
## Prompt
Set up project documentation structure for this new project.
Create the following:
1. \*CLAUDE.md\* (project root) - Concise (<40 lines) entry point with:
- One-line hypothesis/goal
- "Start Here" pointing to docs/ROADMAP.md
- Quick Reference (key commands)
- Key Files table
- Documentation links
- "End of Session" protocol (append to docs/session_log.md)
2. \*docs/ROADMAP.md\* - Status dashboard:
- Current state table (what exists)
- Blockers table (with links to plans)
- Priority actions table (with links to plans)
- Success criteria (minimum + publishable)
3. \*docs/plans/\* directory with plan templates:
- Each plan: Priority, Status, Depends on, Problem, Goal, Steps, Success Criteria
- Name format: plan_descriptive_name.md (not numbered)
4. \*docs/runbook.md\* - Common operations:
- How to add new data sources
- How to run analysis
- How to run tests
5. \*docs/session_log.md\* - Work history:
- Template for session entries
- "Prior Sessions" section for context
6. \*docs/archive/\* - For completed/old docs
If this is a data pipeline project, also set up:
- SQLAlchemy + Pydantic architecture (see sqlalchemy_pydantic_template.zip)
- tests/ directory with pytest structure
- you can copy the file from ./generic_claude_project_src.zip to the current folder and unzip the copy. DO NOT modify the original file or try to move the original file
Keep all docs concise. Link between docs rather than duplicating.
---
## After Setup Checklist
- [ ] CLAUDE.md is <50 lines
- [ ] ROADMAP.md fits on one screen
- [ ] Each plan has clear success criteria
- [ ] runbook.md has actual commands (not placeholders)
- [ ] session_log.md has first entry from setup session
---
## python
use the py-PROJECT pyenv
ensure pyenv is installed
## Example Structure
project/
├── CLAUDE.md # Entry point (<50 lines)
├── docs/
│ ├── ROADMAP.md # Status + plan links
│ ├── runbook.md # Common operations
│ ├── session_log.md # Work history
│ ├── plans/
│ │ ├── plan_data_loading.md
│ │ ├── plan_analysis.md
│ │ └── plan_validation.md
│ └── archive/
│ └── plans/ # Old plans with date prefix
├── src/ or project_name_src/ # Code
└── tests/
└── test_*.py
## Session log example
## YYYY-MM-DD: Brief Title
\*Goal\*: What you aimed to do
**Done**: What was accomplished (be specific)
**Discovered**: Non-obvious findings about codebase/data/tools
**Decisions**: Choices made and brief rationale
**Deferred**: Work skipped and why (not just "next steps")
**Blockers**: Issues preventing progress (or "None")
The key shift: less about tasks completed, more about knowledge gained that isn't captured elsewhere.
Continuation prompt
Review the project state and tell me what to work on:
1. Read docs/ROADMAP.md
2. Read docs/session_log.md (last entry)
3. Read the highest-priority plan in docs/plans/
Then summarize:
- Last session (1 line)
- Current blockers
- Recommended next step
Ask if I'm ready to proceed.
The zip archive above is just a standard Python module with __init__ and hints at how I'd like things to be named.
I won't lie, this sounds like a recipe for context rot.
LLMs degrade as the context / prompt size grow. For that reason I don't even use a CLAUDE.md at all.
There are very few bits that I do need to routinely repeat, because those are captured by linters/tests, or prevented by subdividing the tasks in small-enough chunks.
Maybe at times I wish I could quickly add some frequently used text to prompts (e.g. "iterate using `make test TEST=foo`"), but otherwise I don't want to delegate context/prompt building to an AI - it would quickly snowball.
It's worth noting that the Claude Code team themselves add corrections to their CLAUDE.md file. So as long as you curate the corrections you're probably fine.
Agree, thats why I did 2 things:
1) HITL - you review/approve changes
2) Added some instructions around limiting the claude.md size and keeping it concise
# Check for POSITIVE patterns (new in v3)
elif echo "$PROMPT" | grep -qiE "perfect!|exactly right|that's exactly|that's what I wanted|great approach|keep doing this|love it|excellent|nailed it"; then
I use claude code extensively, and lately it does all the coding for me. I've been asking it to go through claude.md to see if it needs to be updated after making changes.
I'm now thinking that I will let claude code write code, but never touch claude.md. It needs to be as short and I need to have full control over it.
As i lead the direction of the development the claude.md is my primary way of influencing it, in every single session.
Interesting approach. Since this tool suggests claude.md entries based on your corrections and feedback, and there is a human in the loop for you to precisely control whats added, I think it should work fine for your setup.
I usually ask Claude Code to write entries to the md file but I also ask for a prompt to test the rule in a new session. Sometime the rules cc writes are not good enough
I like the idea, but usually when something goes wrong I just "choose violence" , so my conversation goes like "this approach is stupid because X, try harder", followed by a "Finally!" when it works. Also, add a trigger to "You are absolutely right..." this is the most common pattern I see when it screws up.
I use the same motion to iterate on linter config and hooks (both claude code hooks and git hooks). So guardrails are actually enforced and iterated upon and do not clutter the context.
I’ve been wondering why this isn’t more of a thing (knowledge extraction from the conversation in general). The big providers must already be training on this stuff anyway, no?
2 thoughts:
1) they are, but they wont catch unique patterns very specific to your project
2) privacy - afaik they only train if you have model improvement enabled.
The context rot concern is real but I've found it's more about structure than size. My CLAUDE.md is ~500 lines but it's organised into quick reference tables, critical rules (the stuff that MUST be followed), and project architecture notes. The key is frontloading the high-signal stuff.
What's worked for me: having separate sections for "things Claude needs every session" vs "reference material it can look up when needed". The former stays concise. The latter can grow.
The anti-pattern I see is people treating it like a growing todo list or dumping every correction in there. That's when you get rot. If a correction matters, it should probably become a linting rule or a test anyway.
My problem is that Claude often don't consult the reference materials.
And I am back to manually including markdown files in the prompt.
Say I have a TypeScript.md file with formatting and programming guidelines for TypeScript. Sometimes Claude edit TypeScript files without consulting it, despite it being linked referenced CLAUDE.md.
The growing todo list can often port nicely to skills.
If your CLAUDE.md approach is public, would be interested to learn from it.
Are you seeing a benefit above doing this in the prompt / project structure?
Currently, I have Claude set up a directory with CLAUDE.md, a roadmap, a frequently used commands guide, detailed by-phase plans, and a session log with per-session insights and next steps.
After each phase is done, I have it update the documents and ask what could have been done to make the session easier—often the answer is clearer instructions, which eventually leads to topic-specific documents or a new Claude Skill.
(edit) These reflection tasks are spelled out in the CLAUDE.md and in the docs directory, so I don't have to type them. Each new session, I paste a guide for how Claude should access the information from the last session.
I keep the context concise by linking from claude.md to markdown files with the hardware architecture, the network architecture, the processing tech stack. Concise and specific. And a current project md. I mix in the parts that are relevant. I don't have a roadmap and session log though. Good idea.
Your workflow sounds solid - and honestly more disciplined than most. The difference I was going for: catching implicit corrections you don't consciously document.
So probably complementary to what you're doing, not a replacement. If you're already doing post-phase reviews, you might catch most of this anyway.
I totally understand that this is not really a small ask, but if you could put together some sort of example repo of this setup I and probably a lot of people with me would be most grateful! I don't mean with running code or anything, just the doc structure for Claude.
No problem! I recommend asking Claude for these sorts of things so they can better match your own processes.
----
New session:
Continuation prompt The zip archive above is just a standard Python module with __init__ and hints at how I'd like things to be named.Do you have a public repo showing your setup? I’d be curious to see it in practice.
I responded to a sibling thread in this chain: https://news.ycombinator.com/item?id=46486664
I won't lie, this sounds like a recipe for context rot.
LLMs degrade as the context / prompt size grow. For that reason I don't even use a CLAUDE.md at all.
There are very few bits that I do need to routinely repeat, because those are captured by linters/tests, or prevented by subdividing the tasks in small-enough chunks.
Maybe at times I wish I could quickly add some frequently used text to prompts (e.g. "iterate using `make test TEST=foo`"), but otherwise I don't want to delegate context/prompt building to an AI - it would quickly snowball.
It's worth noting that the Claude Code team themselves add corrections to their CLAUDE.md file. So as long as you curate the corrections you're probably fine.
There is some amount of additions / corrections that can merge into simpler explanations over time.
Agree, thats why I did 2 things: 1) HITL - you review/approve changes 2) Added some instructions around limiting the claude.md size and keeping it concise
I like the idea, but this [1]:
is fanciful.[1] https://github.com/BayramAnnakov/claude-reflect/blob/main/sc...
Sorry, i will fix that
Created an issue to track , will fix tomorrow: https://github.com/BayramAnnakov/claude-reflect/issues/2
Lately I've been thinking the opposite of this.
I use claude code extensively, and lately it does all the coding for me. I've been asking it to go through claude.md to see if it needs to be updated after making changes.
I'm now thinking that I will let claude code write code, but never touch claude.md. It needs to be as short and I need to have full control over it.
As i lead the direction of the development the claude.md is my primary way of influencing it, in every single session.
Interesting approach. Since this tool suggests claude.md entries based on your corrections and feedback, and there is a human in the loop for you to precisely control whats added, I think it should work fine for your setup.
Wdyt?
I usually ask Claude Code to write entries to the md file but I also ask for a prompt to test the rule in a new session. Sometime the rules cc writes are not good enough
I like the idea, but usually when something goes wrong I just "choose violence" , so my conversation goes like "this approach is stupid because X, try harder", followed by a "Finally!" when it works. Also, add a trigger to "You are absolutely right..." this is the most common pattern I see when it screws up.
I use the same motion to iterate on linter config and hooks (both claude code hooks and git hooks). So guardrails are actually enforced and iterated upon and do not clutter the context.
I’ve been wondering why this isn’t more of a thing (knowledge extraction from the conversation in general). The big providers must already be training on this stuff anyway, no?
2 thoughts: 1) they are, but they wont catch unique patterns very specific to your project 2) privacy - afaik they only train if you have model improvement enabled.
here is their privacy policy: https://privacy.claude.com/en/articles/10023580-is-my-data-u...
but, again, in my case this is more about my project/user specific corrections and preferences
Released v2 that addresses some of the issues reported in comments + windows compatiblity
I recently learned about the hooks and skills feature. This is cool
i would love to see this on cursor as well
Nice to see you on HN, Bayram aga.