How do you keep AI up to speed on your project?
by•
I keep running into this while building with AI: after a few sessions, I end up re-explaining the project, the decisions we made, and what changed.
How do you handle that? Do you keep a project file updated, rely on chat history, or have another system that works?
160 views
Replies
What would you include in a minimal project context files so the AI stays informed without wasting tokens on unnecessary details?
@ryangumm I would keep the current goal, constraints, run and test commands, and the next unfinished step
Link to longer decisions instead of copying them. Add the commit where the context was last checked so the next session can compare it with what changed
@ryangumm @ryangumm i'd also add what you already tried and dropped. otherwise it just suggests the same thing again
A file, and one boring rule that makes it work: never shorten it. Mine is called HANDOFF.md. Every session ends by writing what got done, what broke and the single next action at the top. The next session starts by reading the top. It's over two thousand lines now. Every time I let the model tidy it into a summary it lost the one detail I needed a week later, so now it only gets added to. Chat history I treat as gone.
@neelagiri_chettiyar 2000 lines and never shortened, ok thats the opposite of what i do. i keep trimming mine, maybe thats why it forgets stuff
@kumarr_rittik Probably. The trick is it never reads the whole thing. The top twenty lines are the current state and the next action that's all it reads at the start. The rest is there to search when a question comes up like why did we drop X and the answer is always some small detail a summary would have cut. Keep the top short and the bottom long.
@neelagiri_chettiyar top short, bottom long, got it.
thanks, that’s easier than what i was doing
An agent seemed to understand the codebase until it gave a clean fix with a green test. Reverting the code showed the test still passed because it had written a check that couldn't fail. Never trust its context until a failing test turns green.
@konstantin_tikhaev lol a test that cant fail. do you make it show the failing test first now?
@kumarr_rittik Make it write only the failing test first and run it. If it cannot produce a clean failure on the current code, it does not touch the fix.
@konstantin_tikhaev ok failing test first, will try that.
thanks, that’s a good trick
@kumarr_rittik Make sure it fails for the exact reason you expect, not because of an import error or a broken mock. That saves another layer of headaches.
Two layers. The durable one lives in the repo, not the chat: each project has a README written as its memory (what exists, what was tried and dropped; old conclusions get marked superseded, never deleted), and the roadmap has a section for things deliberately deferred, each with a reason. The second layer is my agent's long-term memory, which pulls relevant facts into each new session. One gotcha I just hit: it's scoped per working folder. A long session I started in /tmp kept everything it learned there, so none of it would show up when I open the agent inside the actual repo. Worth checking where yours stores things.
@wwenioaguiar wait its per working folder? didnt know that. going to check where mine saves
One big project file stops scaling fast. What worked for me: short ADRs for decisions, a typed, task-scoped memory the agent writes to as it goes, and checkpoints it resumes from instead of re-reading the whole chat. I open-sourced my setup as maggy if you want to steal ideas.
@ali_shaheen will check maggy. checkpoints is the part i dont have, mine re-reads everything every time
@ali_shaheen had a look at maggy, the checkpoints are smaller than i thought.
taking some of that
thanks all, didnt expect this many real answers. mostly hearing a file in the repo + never trim it + write down what you dropped.
i asked because i work on Pryveo, we're trying to fix the same thing from the other side (it keeps context from places you approve so you dont paste it every chat). still early. the handoff file ideas here are honestly useful for us too
Fair! The project file helps, but I need to see what changed since the last session or agents keep reviving dead ideas. I usually leave the rejected approach beside the decision.
@matheus_paranhos1 yeah dead ideas coming back is the annoying part.
rejected one next to the decision makes sense, trying that
A file the agent reads at the start of every session, plus skills. I've got around 100 skills and slash commands now, so most jobs follow one of them instead of the agent figuring it out again. And every project lives under one path, so any session can open another project and see how it already solved the same problem.
And when something does go wrong, I've got a command for keeping it from happening again. It finds the actual cause and builds something that stops or catches it mechanically instead of just writing a note, then checks that it really fires.
@hisashispace a command that checks instead of a note is new to me.
what does yours actually check at session start?
@kumarr_rittik Ah, it doesn't run at session start actually. I run it when something goes wrong. It finds the cause and adds a hook that blocks it before it happens, like a DROP on the database, a force push, editing files directly on the production server, or even a dash in my writing. Those hooks then fire on every session automatically, so I don't have to remember anything.
@hisashispace oh so it fires when something goes wrong and blocks the drop before it happens. that’s stronger than a note, the agent has no way to skip it. does it ever block something that was actually fine?
@kumarr_rittik It fires every time, that's the whole point. A hook isn't the agent remembering a rule. It's a script that runs before the command, so the agent can't skip it or talk its way around it.
I have a folder (./docs) where i store a README.md, but also architecure, future things (like product roadmaps), implementation trackers, and so on, so it not just work for the LLM but also for me to track everything.
And in the prompt, I asked the LLM to read the relevant files from it, and just before committing changes, update the relevant artifacts.
@gocova docs folder you read yourself is nice, you and the agent work from one source. updating the docs right before the commit means they change with the code, that’s the part i like.
An agent once made a failing test pass by weakening the assertion instead of fixing the code, and the suite stayed green for days. Context files now explicitly forbid editing test files. Give it all the background you want, but keep assertions read-only.