Join the discussion
Write your take first — we'll ask for email only when you're ready to publish.
- Hacker News
- I have a documentation vault in my repo, organised using Obsidian (bases, wikilinks, frontmatter, etc), and accessible using obsidian-cli (and related Claude skills, thanks kepano). I started the repo agreeing with Claude the structure and front matter of documents and how to edit and read, all stored in a markdown file in the vault, and a specific instruction in the CLAUDE.md file on when and how to access it. Any updates require consistency sweeps. Any decisions made and agreed during implementation of new features get added to the vault. It's been amazing how I just don't need to explain the project anymore. An empty context and a few sentences on what I'd like to spec next and the LLM finds what it needs in the vault.by aubreykilian
- Yes I've found this to be the case as well. I've also found that it's useful to split these documents into three broad distinguished classes: goals, design, and idioms.
The goal docs provide directionality - helping the agent generally make consistent design decisions. Scoping constraints and stuff are useful to put here, but also feature goals a general idea of where the project is heading long-term (even if none of the items there are on the implementation roadmap anytime soon). It keeps more of the sessions aligned with each other.
The design docs specify the state of the project as it is, and are kept in sync during implementation sessions, by instructing the agents to treat their updates as part of the implementation plan for any work.
The idioms docs keep track of incidental decisions that don't relate to long term goals per se, but things like code style detail, specific project-related investigative techniques, code organization rules, build process guides, etc.
It's a single anecdote but I found that overall the work encountered fewer low-level design mismatches where one session doing work on one thing would make a design decision that didn't really mesh well with another session doing work on another thing. Overall hygiene took less work to maintain.
There are likely a variety of superior ways of organizing things, but at the very least it seems there's a ton of value to be squeezed from just organizing your project meta-information in certain ways. Definitely worth spending some time experimenting with.
- Doesn't Claude have memories like Codex?by reckless
- It does.by LetMeLogin
- The question I find myself asking very often these days: Is this better than asking claude to do the same things the plugin/repo does?by dimitrios1
- With all due respect, this github repo looks really like an AI-generated project.by rabbitlord
- I think the majority here have stated the same... That CLAUDE.md or AGENTS.md effectively do this. Either that or the readme.
The only tip I can give is that your skill that builds or wraps up work. You should have it update those files if anything has changed.
Claude/Agents files shouldn't be bloated, but should imho act as a basic amount of context on the project so your agent and skills can pick up and go, with even the most basic initial prompt.
by intothemild - > The only tip I can give is that your skill that builds or wraps up work. You should have it update those files if anything has changed.
Depending on the scope of work you’re doing, it might be better to have this removed from the context of the work that was done.
I keep a “Last Updated Hash” in my md and every so often will have the LLM pull a diff from that hash to the current head, then determine what doesn’t match.
by devmor - How does this beat a Session specific README?by tt_dev
- I use Deepseek and just as it to generate a state.md file with a summary of the project every time I've reached a goal or milestone. I then take a few minutes to edit this and add in or take out details. Between token pricing and generous cache discounts This has proved very efficient so far, I reset every few hours of work and bypass the muddle of having too many priorities or over-extrapolation from un-nuanced instructions I gave at an earlier stage.
I do think that this project is interesting in several ways - prioritizing privacy, minimizing spend, and using objective semantic markers to sift and consolidate the key takeaways from long sessions. I'd like to try it on my cline project history. But while it would make a great recording of project history, I wonder if a lot of it doesn't end up detailing blind alleys the project went down and had to back out of.
Generally when this happens I feel that it's due to vague specification on my part, or avoiding architectural decisions I didn't want to deal with and implicitly inviting the model to implement a lowest-common-denominator solution.
by anigbrowl - > But while it would make a great recording of project history, I wonder if a lot of it doesn't end up detailing blind alleys the project went down and had to back out of
Yes, I've run into this as well. I had the agent document the changes it would make along the way, but it would want to keep making note of things that we switched away from. Eg, "In phase3 we used mysql instead of sqlite". On some projects I let the agwnt do all the documentation and plan.md and state.md files, and every so often go through manually and delete some of the cruft that's no longer needed.
by KetoManx64 - Hm, I just keep a folder called something like `status_docs/` in any project I work on and I create a new file in that folder any day I'm working on a project that's dated (e.g. `project/status_docs/2026_06_21_status.md`). It's basically a project diary that both me and the LLM can reference.
I have the LLM at some point in the day while working on the project create that file with all the relevant context. And then I'll periodically have it update that file (often before I compact the context window, or before I switch to a new task). And then I just have the LLM update it whenever I'm done working on the project for the day.
Then no matter what, if I come back that project again a day later, a week later, a month later, whatever – I just literally point a fresh session at the most recent status doc to help both me and the LLM orient ourselves to the work at hand. What's really nice too is having it reference the status docs from previous days to help orient it for creating the new status doc for the current day.
I've been doing this informally for probably over a year now, and have started formalizing it so I do it with every project. It's been a big help to me personally given all the context switching between projects I've been doing more and more since using AI coding tools.
by cootsnuck - IntelliJ handles this for you. Basically it sends half your project to Claude even if you're asking some question about Star Wars.by comrade1234
- > IntelliJ handles this for you. Basically it sends half your project to Claude
Not sure I’d call that “stopping wasting my tokens”.
by lxgr - Sometimes its good to start fresh. LLMs need large context restart's sometimes so they can better identify holes that they become blind to.
- Back in the human age of coding, I felt the same way sometimesby derwiki
- I might be missing out on something but I never had to explain my project. Just give it a task, or if you really want to, type it quickly, then you are good to go.
I can’t imagine this being worth optimizing. The issue is never that Claude can’t figure out what the projects is about…
Am I missing something or does this project not solve a problem most regular people have?
by serial_dev - I guess that depends on the kind of project, how common the intent is, how self contained, etc.by torben-friis
- >I might be missing out on something but I never had to explain my project. Just give it a task, or if you really want to, type it quickly, then you are good to go.
This means its changes will either be out of alignment with the overall project and its "style" and goals, or it waste tokens re-getting to know the basics about the project each time.
No third case.
by coldtea - I specifically have instructions for claude explaining the purpose of the project in pretty much all repos. Just a simple PROJECT.md is enough - and referenced from AGENTS.md
There I usually lay out stuff like "this is a personal greenfield project" and "don't bother with multi-user support" etc. Or Claude will default to creating something WEBSCALE for a simple tool that won't run outside of my local LAN-only Proxmox setup. And that'll also skip massive database migration support for a project that's 3 days old - the agent doesn't know that. I'm just dropping it on the project after a full memory wipe.
by theshrike79 - Depending on the scale of the project and the complexity of the specific thing you need to work on, it's advantageous to bring specific context into the session instead of hoping the model will connect the right dots.by airstrike
- What I've finally come to understand is that there is a large amount of people who are now able to write and use software through claude and coding agents. Those people have different needs than more traditional software engineers who have more knowledge because even best llms often need steering, correction, and refactoring suggestions when iterating on code and it's fine to let it lose context because exactly like you said, you tell it to read file and then have to regurgitate the understanding so you can correct or validate it before continuing.
For those where the code is almost entirely a black box and cannot easily recover when something goes wrong. They are much more keen on this context management and planning because recovering from derailments is much harder (and takes longer) because its often a conversation with llm to try to recover to where they were before.
by bfeynman - There are many other posts here which agree with you. Filling context with what you think the model needs adds nothing and possibly just inflates context which is harmful.
A good method seems to be only make a skill or memory when the LLM gets something wrong, or if you actually observe it's always doing the same step and you can get the model to the same place with less tokens.
by suprjami - I apparently use Claude differently the most people who talk about using Claude on the internet.
I’ll typically have a bunch of short sessions over the course of a day. Anytime I start a task that isn’t going to very directly benefit from the existing context I start fresh.
I don’t find a lot of benefit in explaining the project overall to Claude — I’ve deleted a lot of that explanation from my Claude.md because it didn’t seem to impact much.
I typically start a task by pointing it to 1-2 files and giving it some explanation of what I want done, and it figures it out.
Basically never hit context window limits or compactions, and can’t remember the last time I hit a 5 hour or a weekly limit.
by mikeocool - I work in a completely different manner. I have a chief of staff agent, which is one Claude code instance that orchestrates work across all my projects simultaneously with sub agents. In this way the agent helps me context switch and drive work towards everything I’m working on. I only use 1 session, I compact when necessary with todos and on file system files to track wipby computerex
- Honestly sounds like you’re not doing anything difficult. If I’m doing easy tasks it’s fine but if you need to do a major architectural project that spans 3 codebases and 2 clouds you’re gonna have a hard time without substantial context/memory management.by whalesalad
- I work similar, but still have architecture mds for a few selected cross cutting features. As useful for human readers as for AI.
Normally I do it exactly as you say, point at a few files, but if I know these features are involved I point at the corresponding mds instead. Its a shortcut for me to type less.
by canpan - In some sessions I find claude to be incredibly dumb - other times we are on the same wavelength and everything flows.
I guess I need to do some claude.md work or find other ways to prime the session so i get the good personality and not the evil twin.
by blitzar - I keep a plan file that records what I’m doing, how I’m doing it, and what I’ve done so far - every time I sit down to have another session, I feed Claude the plan file first, then tell it to begin on the next unchecked todo. Every time I run into something new, I tell it to add it to the todos in the plan file.
It basically takes care of itself, or at least as close as it can.
by mock-possum - This is my usage pattern and I agree it works really well. I start almost every conversation by asking Claude to read, not write. Then once it's explored a particular slice I let it rip.
This takes a couple minutes (and I suppose I'm spending tokens each time), but sessions rarely reach compaction length and I like that I'm not trying to keep a whole separate pile of docs in sync.
by bengotow