They aren't really "explaining the project" either, but more module- or task-specific preferences, hand reference pointers, or other things like "there are mixed examples of how to do certain things in this project, prefer X to Y." I use a write-everything-twice approach. After I find myself having to correct an implementation because it didn't figure out one of these things on its own from the existing code, I'll add an entry. That also avoids bloating things with "I think this is relevant" compared to "I have noticed that this is necessary."
I keep doing this because it lets me experiment with different approaches to problems without risk of it fixating on things from a previous abandoned attempt, and particularly because sometimes I'm wrong and I haven't found the agent harnesses particularly reliable at taking my word for it from a POV of "yes I know I said we need xyz earlier, but let's please entirely forget about that."
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.
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.
I've been running Claude and GPT in my own agent harness. The main difference I notice is that tasks take about 7x longer to complete if they're run in the official Claude or Codex harness (and cost me 7x more).
You would think this would lead to increased correctness, but that doesn't seem to be the case. Today I tested both side by side. They both resulted in data loss. (I had a backup obviously.)
GPT running in the official harness did a bunch of extra tests and double checking, and ended up with the same result regardless (it permanently deleted a bunch of documentation).
All else being equal, I like getting my data loss 7x faster and cheaper ;)
It's slightly bigger now, but here's a ~50 line version for reference. I added the missing outer while-loop, so it takes user input etc.
https://gist.github.com/a-n-d-a-i/bd50aaa4bdb15f9a4cc8176ee3...
I mostly use it with GLM via their coding plan, I got a year for like $20 when it was on sale. But I also hooked it up to Sonnet, Opus, GPT, etc.
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.
I have used this same pattern in my own harness and it works well there too. https://github.com/computerex/z
I hooked an instance of my harness up to telegram and now I talk to it from everywhere it and dispatches work out to subagents.
It basically takes care of itself, or at least as close as it can.