I’ve been trying to figure out a good way to share how I’ve built some of my projects. People ask about them, and I usually end up walking through the same explanation a few different times in different conversations. Sometimes I’ll share a repo, but that’s often either too much or not enough. The code is there, but the context around it isn’t. Why I chose one approach over another, what I tried first, the tradeoffs I made along the way.
In Build or Buy May Have Changed I talked about how the cost of building custom tools has dropped to where more people can realistically build their own versions of things. Near the end of that article I mentioned that the write-up itself could be a starting point for someone’s assistant to help them build something like it. That idea kept pulling at me. If someone’s assistant can read a description of how something works and help them build their own version, what’s the right format for that description?
It’s somewhere between a README and a full codebase. Not a spec, and not really documentation in the traditional sense either. More like a write-up from one builder to another, or from one assistant to another. For now, I’m calling them build notes. I could see these eventually becoming part of a more structured system design document or something like that, but right now they’re just practical descriptions of things I’ve built.
Each note covers what the thing does, why I built it that way, how the pieces connect, and the key decisions with their tradeoffs. There’s reference code included, but they’re not full codebases and they’re not install scripts. They’re closer to showing a friend how you wired something up in your garage, with enough detail that they could go build their own version.
Each note also has a short “for AI assistants” section near the top. If you point your assistant at one of these and say “help me build something like this,” it should have enough to work with. That was the main thing I wanted to get right.
The first three
Mac Services API is how I give my assistant access to my Mac’s Calendar, Reminders, and Contacts without running the assistant on the Mac itself. It’s a REST API that the assistant calls over the network.
Notes Inbox is a capture workflow. I press a button on my iPhone, say what’s on my mind, and it shows up in my assistant’s inbox immediately. An Apple Shortcut handles the dictation and sends it to a small API server exposed through a Cloudflare Tunnel.
Hugo Blog covers this blog’s setup. Hugo with PaperMod, Cloudflare Pages for hosting, and optionally a Cloudflare Worker for newsletter subscriptions. The hosting costs me nothing.
I’ll keep adding more as I write them up. Some of the things in my setup are more involved than these first three, so the depth will vary.
Everything is at github.com/chriscantey/build-notes .