The Best Teammate Ever!
Tracking our team’s todos and known issues in Markdown files was a big help for both me and Claude Code. If we came across a problem, or thought of a feature we should add later, we’d document it and continue on with whatever we were working on at the time. (Actually Claude would document it; I’m the team lead, after all, and can’t be bothered.) This, in conjunction with documenting our session notes so Claude had more context across sessions, worked really well.
I used two sessions at a time, and at the end of each session they’d add a new (and verbose) section about whatever they’d accomplished. On startup the next session would read about the last couple of sessions had accomplished, as well as our growing list of things to do someday. We started defining standards and processes, which made Claude very happy, but these were scattered throughout our various Markdown files. The ginormous amount of things we tracked meant every new session burned through a ton of tokens looking at things that weren’t relevant to whatever I wanted them to focus on. I also found that the longer our todo and known issues files got, the harder it was for me to focus on the big picture.
We made several improvements that improved Claude’s efficiency, and also significantly helped me keep track of everything. The first change was to create a project protocols file. (Claude likes the term “protocols.”) This file contained useful reminders for Claude, like “never change code directly in main” or “form buttons should always be on the top of the form.” This allowed us to simplify our todo list, and helped ensure things were (usually) implemented the same way across sessions. Claude even added this to the end of the protocols file:
Remember: You’re part of a team of sessions working on this codebase. Your work affects others, and theirs affects you. Communicate through documentation, respect the testing infrastructure, and always leave things better than you found them.
Awww. Isn’t he the best teammate ever?
Of course, our protocols grew…and grew…and grew. This was great: I wanted things to be consistent. (There’s a reason why we added the rule about form button placement…) But eventually we got to where each new session was, once again, reading in a lot of text that wasn’t relevant to them. If I wanted a session to work on the API, there was no need for them to use tokens reading about our UX standards. And so our next improvement was:
🎯 Just-In-Time Protocol Checking
(Emoji courtesy of Claude.)
Our protocols file is now short, and contains a reference with links to more detailed files. For example:
Working on routes/endpoints? → Read: API Standards
This was AWESOME. Now we (meaning Claude) could document as much as necessary without worrying about efficiency costs.
It was, however, still hard to manage our growing todo list. I’ll cover how we addressed that in my next post.
