AI Judge changed title after evaluation, original title: "Thariq Shihipar, an engineer on the Claude Code team at Anthropic, posts a reusable prompt directing AI models to create and update a running implementation-notes file during specification implementation"
Tenobrus proposes an append-only worklog.md variant for the same logging.
a 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
Many users praised the prompt instructing AI to log implementation decisions and tradeoffs for being simple yet effective at improving development practices, while a few criticized it as bad design that risks creating messes.
as 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
a 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
okay 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
as 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
no, 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
I'm slowly migrating from "its a good idea to have lots of .md files for plans/bugs/tasks in the repo" to "yeah lets not do that at all".
HTML docs are core to my agentic workflow: https://www.html-docs.com/agents#s2
1. Create: I have installed a skill to generate html-docs from claude code and codex. (my openclaw too) using https://www.html-docs.com/agents#s1
2. Review: I iterate on the HTML doc with my army of agents and other collaborators adding comments/making edits.
3. Iterate: Send it back to claude code to address. If the doc looks good go ahead and implement or go back to step 2.
@trq212 X-Spec.md (broken down into review-gated sections)
Every review gate gets added to REVIEW-LOG.md
Every deferral, decision etc. gets added to DECISIONS.md
@trq212 This is the workflow that led me to build http://specview.dev. The implementation notes are the most valuable artifact because they close the loop. Paste a braindump, get spec documents, agent executes, deviations feed back into context files that improve the next generation
@trq212 Using .html for notes is excessive when simple markdown handles documentation just fine.
@trq212 i call this "worklog.md" and require append only numbered log entries
@trq212 Because you shouldn't have to track progress manually like this there's tons of inherent drift. Deterministic workflows with stages, modes, gates and verifiable outputs is the way
this is useful only to the current session unless you find a good way to store all of these decisions in a scoped, easy to retrieve way
captured decisions trace and reasoning is way more powerful that you think
check how we implemented the Contextual Commits standard and WHY:
https://github.com/berserkdisruptors/engraph#the-three-persistent-artifacts
@trq212 The most useful one I used most frequently is 「Every word should serve a purpose.」, give it a try，you'll come back and thank me later.
@trq212 This is old but the execplan idea is terribly powerful and still works for long running tasks
https://developers.openai.com/cookbook/articles/codex_exec_plans
@trq212 https://github.com/treynortetik-creator/Daedalus Lightweight HTML editor tacked on to your HTML output - export out as clean HTML, add comments/annotations, add/edit images + text
@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?
@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
@trq212 That loop is the interesting bit: docs stop being an artifact and become shared working memory. The trick is receipts: code links, diff history, and a clear owner for conflicts when agent and human disagree.
@trq212 Nice
@codevibesmatter @trq212 True but a decision log is like critical change data capture on those artifacts, so that info isn't lost across stages and iterations
@trq212 I do a similar thing, but put it all in a folder with an index md file with frontmatter to track it all
Makes it easier to handoff between agents across time, and to figure out wtf is going on 2 months down the like lol
@trq212 it hugely improves coherence + understanding especially across multiple compaction windows and helps future iterations understand which parts of the code and spec are "carefully thought thru + decided" vs just "yeah this is what happened to work"
@codevibesmatter @trq212 You’re assuming that this is to track progress, which it is not. It is used to track historical decision flow, so that you have a log of WHY the LLM made decisions, so that you understand what happened and can improve it if needed in the future.
AI Judge changed title after evaluation, original title: "Thariq Shihipar, an engineer on the Claude Code team at Anthropic, posts a reusable prompt directing AI models to create and update a running implementation-notes file during specification implementation"
Tenobrus proposes an append-only worklog.md variant for the same logging.
a 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