So at the beginning of this month I came across what I think is one of the best ways I’ve heard of using AI. I implemented it at the end of last month, used it throughout this month, and now it’s time to give a one-month review of it. Here are the pros, the cons, and what I’ve learned in the process.
Learning Log
But before we get into that, here’s my learning log. I think I shortchanged myself some hours because I spent time doing some stuff at work, and it’s hard to track my time there. However, I’m still happy with the time I did log, especially considering I have two newborns at home!
| Headline | Time | | |
|--------------------------------+---------+-------+-------|
| *Total time* | *65:05* | | |
|--------------------------------+---------+-------+-------|
| GOAL: 6500 Hours | 65:05 | | |
| \_ Book Study | | 11:18 | |
| \_ The Pragmatic Programmer | | | 8:28 |
| \_ Game Engine Architecture | | | 2:50 |
| \_ Emacs | | 8:21 | |
| \_ ABX Development | | 45:26 | |
| \_ Programming | | | 32:41 |
| \_ Art | | | 3:00 |
| \_ Business | | | 7:45 |
| \_ Learning | | | 2:00 |AI as an Assistant
I know the idea of an AI assistant isn’t new, but this way of using it was new to me when I read about it, and I think it’s the most reasonable way to use it in this era of AI where people are either fully embracing the vibes with multiple agents that spawn more agents, yada yada yada, or people being so anti-AI that they don’t see how powerful it can be when used with restraint so that it empowers you but doesn’t turn off your brain.
Power Through Restraint
The idea is to use your AI coding agent of choice: Claude, Codex, OpenCode, Pi, etc.—but to put hard limits on the agent so that it looks at the current state of the code but only gives advice and guidance on what to do. The idea is to use the agent as a harness for thinking and decision-making. It does not do all the thinking for you. It’s meant to challenge you, point out contradictions, explain tradeoffs, and suggest alternatives. The goal is to improve your understanding of what you’re working on and to help you get unblocked when you’re stuck. This is all done through an AGENTS.md doc that you have to point the agent to, and by creating subagents that don’t have editing access (I just learned about this second way, but I have yet to use it). Here is my AGENTS.md if you want to see the bounds I’ve placed. I’m hoping to try using subagents alongside the AGENTS.md this month, and I’ll let you know how it goes.
Setting Project Knowledge
So you can set a strong, restrictive AGENTS.md, but all that does is put restraint on the agent. Besides looking at the code, how does the agent know where you’re headed and what you’re thinking so that it can guide you? This is where a /docs/ folder comes in handy. It contains five files that help keep the agent going in the right direction, and these are the only files that the agent can edit: PROJECT.md, ARCHITECTURE.md, DECISIONS.md, ROADMAP.org (you can just use ROADMAP.md if you don’t use Emacs), and SESSION.md.
PROJECT.md
What the project is
Here is where you define your project, the what of the project. What is it? What technology does it use? What is the goal of the project? What is the current state of the project? Of all the files in the docs folder, this one gets edited the least. Once the project takes shape, this information doesn’t change. Early on it might change frequently since you’re still trying to feel out the shape of the project. However, for me it’s barely changed because I’m in the “long dark tunnel” of my project. Therefore, not much of the project’s shape has changed, just the details.
ARCHITECTURE.md
How the project is structured
Use this to describe the intended design of the project, the how of the project. How does it work? How does the project flow? How is every part supposed to operate? Out of all the docs, this one changes the second least. However, sometimes as you’re working you run across things that don’t work the way you think they should, and you need to change how it’s structured, how it’s supposed to work, or add something you haven’t thought of before. That’s when you change this file.
DECISIONS.md
What decisions were made and why
Use this document to record every decision made in the project and why. It helps you keep track of why you’re doing what you’re doing, and it keeps the AI from adding unnecessary things while keeping you within the scope you’ve defined. Expect to add to it frequently, especially while you’re still developing the shape of the project.
ROADMAP.org
The steps to get to the released product
These are the steps to get the project to a stable release. The roadmap keeps you and the AI organized on what to work on to get there. Expect to add to, change, and update it frequently, especially as you make more decisions and get a more complete picture of your project. I’ve found this one helps me stay on track and actually see linear progress toward a final product.
SESSION.md
What was done
Keep track of what you worked on between roadmap steps here. It also explains what was done the last time you sat down to work on your project and what you need to do next. Update and adjust it constantly. Basically, every time you save or have the AI do a code review, keep this up to date so you know what you’re doing.
My Review
I’ve been using this for a little over a month now, and I think it’s probably one of the best ways I’ve found to use AI. It’s helped me progress much faster than I would have otherwise. It was also great for pointing out all the areas I hadn’t thought of, and there were many! So here’s my quick pros and cons list.
Pros
- Helps with organization
- Great at finding bugs or errors in logic
- It’s like rubber duck debugging but it actually talks back
- Helpful for finding gaps in logic
- Weighs pros and cons of decisions and helps guide you if you don’t know where to go
- AI model agnostic
Cons
- It can be quite… verbose
- Sometimes it wants to make decisions when you just want to code
- Feels like it just runs in circles sometimes
- Every once in a while, it wants to take control and you have to rein it in
Wrap Up
Overall, I’ve really enjoyed this approach to using AI, and I think it’s more true to the strength of AI: a tool for connecting ideas. AI is great as an assistant to your brain that fills in the gaps, but not as a replacement for your brain. I’m going to keep using it this way, and I’m interested in getting better at harnessing it. If you have questions, feel free to reach out!
“If you’re always on time, it implies that you never have anything better you should be doing.”
— Brandon Sanderson, Mistborn: The Final Empire