I’ve tried to flip the script on this and adopt a document-driven development approach. I update the docs (README.md, whatever), and tell Claude to implement the changes in the docs. And then, after implementation, I reverse the process and instruct Claude to ensure the documents are up to date.
These are two simple Claude commands I use in about every repo:
update.md
Implement any code changes described in the documentation (\*.md) changes (git diff).
Note for this command, the documentation is driving the code changes, not the
other way around.
update-docs.md
Update any relevant documentation for the current code changes (git diff)
The changelog should describe changes as benefits to the user. It should not
include technical details of the change, that is what git log is for.
It’s not perfect, and I should probably learn to plan better, etc. However, I feel like this gets me out of the prompt-it ‘til you make-it spiral. And in the end, my docs are done.
I’ve also looked at spec-kit, but have not had time to process what it does – offhand, it seems a little heavy for most things I do.
Thanks for sharing what you are learning!