Thariq Shihipar, an engineer on the Claude Code team at Anthropic, describes a prompt that directs AI models to maintain a running implementation-notes file recording decisions, tradeoffs, and specification changes
Tenobrus proposes an append-only worklog.md variant for the same logging.
#861Thariq@TRQ212a prompt I've been using a lot recently:
implement <SPEC> and while you do, keep a running implementation-notes.html file (or markdown) with decisions you had to make weren't in the spec, things you had to change, tradeoffs you had to make or anything else I should know
#861Thariq@TRQ212as much as you spec there are always still ambiguities and unknown unknowns that come up and this gives the model a good out to make decisions but keep you in the loop
Thariq@trq212a prompt I've been using a lot recently: implement <SPEC> and while you do, keep a running implementation-notes.html file (or markdown) with decisions you had to make weren't in the spec, things you had to change, tradeoffs you had to make or anything else I should know
#861Thariq@TRQ212okay this is going kinda viral and tbh my original text was kind of messy, so here's a second pass with the help of Claude:
-- Implement <SPEC>. As you work maintain a running implementation-notes.html file that captures anything I should know about how the implementation diverges from or interprets the spec, including:
- Design decisions: choices you made where the spec was ambiguous - Deviations: places where you intentionally departed from the spec, and why - Tradeoffs: alternatives you considered and why you picked what you did - Open questions: anything you'd want me to confirm or revise
Thariq@trq212as much as you spec there are always still ambiguities and unknown unknowns that come up and this gives the model a good out to make decisions but keep you in the loop
#861Thariq@TRQ212@tenobrus yeah this makes sense, I usually try and keep my specs fairly contained and so just keep the implementation notes for a spec which can be finished in one full assistant turn
do you keep the working log around all the time?
Tenobrus@tenobrus@trq212 if it's not append only i find the agent tends to go back and edit old entries in ways that lose context or result in a tangled . but it also is much higher level than individual commit messages and can contain design or debugging thoughts that don't belong there
#1179Minh Nhat Nguyen@MENHGUINno, it's still very important. just tell the agent to specify in detail HOW and WHY the bug happened. this has 2 benefits: 1. the agent has more context if it needs to fix the bug 2. the agent is allowed to ignore the instruction if conditions are different/bug is solved