The vibe coding adventure continues… I’m sure you were hoping to hear another update from me about that. Ha! Well, today I hope I’ll share something helpful to you in life, not just on the command line.
I have a lot of code. I’ll confess some of it is pretty bad, and some of it is downright scary. I even have a few repos I haven’t touched in years. Not too long ago, I needed to update an old C++ project with a Rube Goldberg collection of bash scripts. Honestly, I couldn’t remember anything about the code. Sure, I could have spent hours poring over the classes, sifting through makefiles, and tracing if-else-fi branches, but I didn’t need to. I brought a friend. His name is Claude. I launched a chat window inside VS Code and began giving instructions.
First: “Let’s understand this codebase. I’m lost. Take a look at all the classes, functions, and scripts. Build an AGENTS.md file to document the purpose of this code, the setup, architecture, and APIs. Make it comprehensive. Create a complete but concise inheritance map in Mermaid, and unpack any call flows that will help me understand the design. While you’re at it, notice the style and best practices used and note what we should codify or correct.”
Claude went to work. It started scanning, reading, comparing, and composing. The design document emerged and it was impressive. Most sections were correct, but I adjusted a few key items around vision, goals, and project style. Claude even added a section on improvements, which I found impressive. Some of my memory came back about the code, and I found it humorous that there were so many flaws. Ok, you’re probably not surprised.
Next, I asked Claude to build a plan for new features I wanted to add, including fixing some of those bugs. It built a PLAN.md with checkboxes. We (and I mean “we” in the observer sense, Claude did all the lifting) worked through those tasks, with me occasionally making decisions. At each step, I’d review the code it updated (via visual diffs in VS Code), commit it, and sometimes coach Claude to take a different approach, sometimes regarding goals, style, or architectural changes that should match what’s in the AGENTS.md file. I’d ask it to compare its approach to the standard, and it would often say something like, “Yes, your code isn’t following the purpose of the project; let me fix that!” I find it funny that my only “coding” was chatting, and just as funny that I had to remind my AI buddy to check the AGENTS.md to stay on track.
Years ago, a mentor asked for my list of 5-year goals. I started listing things off the cuff, as usual, but he stopped me. He asked if I’d written them down. I hadn’t. He suggested that the act of writing them out would help me distill my thinking. More importantly, he said, it would become a reference point to help make decisions, prioritize, and trim away things that didn’t help with those 5-year goals. He shared his list and admitted he didn’t look at it often, but would revisit it each year or whenever he needed to prioritize. I followed his advice. It was life changing.
We all need AGENTS.md files. Maybe you’re better at this than I am, but like Claude, I often get caught up “doing” and lose sight of my key goals. I need to reference my map, my AGENTS.md, to ensure I’m focused on what matters most. That often means stopping things that don’t contribute to the overall 5-year plan for myself, my job, or my family. Other times, it means course correcting or starting something new. Whatever the case, that map is pure gold.
Do you have an AGENTS.md file for yourself? If not, may I suggest drafting one and committing it today? Start by asking: Where do you want to be in 5 years? What is important for you? Your career, your family, your world? Get specific. Set measurable outcomes. And, this is key, don’t forget to check in on it now and then. Otherwise, you’ll forget, and you may need Claude to stop by and fix things for you.