Comment by zenapollo
12 hours ago
I started with .agents/notes-and-plans/ but the agents were overzealous about putting every random thought there, so i made new system.
.agents/plans/<plan-name>/
.agents/notes/<topic>/
.agents/knowledge/<topic>/
I only commit knowledge and if knowledge gets big i add .agents/knowledge/INDEX.md
This is a good mix of human readable and agent fluent. Notes are ephemeral, knowledge is permanent.
I have a rule for knowledge that it has to be stable and mostly permanent (though updatable). And the agents are not allowed to post there unless docs are clean organized and with permission.
Notes are for jotting things down and handoffs, massaging a featureset. Agent can document at will.
Still WIP.
No human reads those md anymore
That’s my biggest critique of this. I am working on a project with another dev and I try to keep docs as clean and “straight to the point” as possible. In my previous team, one dev went full “spec driven” and the project started having dozens and dozens of markdown files with hundreds of lines to the point any human being would give up trying to trim it. It just becomes noise, a lot of it not even correct because the specs themselves were mostly AI generated with lots of verbosity and wrong assumptions.
I started writing specs recently in a directory that I don’t allow the agent to write to. There has to be somewhere that the engineering intention behind the app is recorded. But it’s terse, minimal and all human generated, not like “hey Claude, write me specs for an app”
Then what do they actually read?
HN
agent's output summarized by a chatbot.
This is literally how memory works.
And then a random model/reasoning setting has a stroke and pollutes it all with ai slop.
[dead]