I'm sure this is not new thinking, but it was part of my discovery process. My objective wasn’t to crank out an app, I wanted to understand the process of using an agent to build something. I went into it thinking about how I’d work with a new employee. When I work with someone new, I explain ‘my API’ and try to understand theirs. How do I communicate, what’s my level of understanding, how can we collaborate most effectively. That’s been refined into the working_with_me.md doc.
I knew the context.md file, but read how big and cumbersome that file can get, and that as memory fills in a session, more of that context can be left behind. My project wasn’t about speed; I knew I would need a way to pass the latest session details - status, open items, decisions made in session, etc - to the next agent in a new clear session. That was the thinking behind a session state doc.
I created those two docs outside of claude.md, with session.md living in each project directory, and working_with_me.md available in the claude root directory.
My starting instructions are for the agent to read those docs - plus other project info, and my ending instructions are to update working_with_me and handoff.md. If mid-sessions something is lost - like the agent gets sycophantic, I’ll stop and dig into that, trying to understand how context was lost and how to firm up the point.
Let me know what you think, or what I’m missing.