The agents aren't broken. Your documentation is.
I've watched engineers blame AI coding tools for months now. "It hallucinates." "It doesn't understand our codebase." "It's overhyped." And every time, I ask the same question: if you handed this task to a new hire on day one, would they do any better?
The answer is almost always no. Because the problem isn't the agent. It's that nobody can succeed without context, human or machine.
Here's what I've learned from seven years of teaching machine learning at Northeastern: content that works is content that's been refined, documented, and pressure-tested. My first year of lecturing was rough. My lectures felt like those of a comedian working out a new bit, some classes bombed, others clicked. I tuned from there. Years two through seven? Almost rinse and repeat, because I did the unglamorous work of getting my material right.
That's the same work your agents need from you. And I know you don't want to do it. Documentation is the broccoli of engineering. We know it's good for us. We avoid it anyway. That avoidance has stalled organizations for the last decade (if not more), and agents just made the cost visible.
Think of it like watching LeBron at age 41 throwing down dunks, then walking outside expecting to do the same. You have legs. You can hold a basketball. Why can't you get off the ground? Because fundamentals matter. Just because a YouTuber demos it in a perfect environment doesn't mean it'll work in yours.
Here's the good news: you can fix this faster than I can fix my vertical.
The unlock is using agents to create documentation while you code. With agentic capabilities now built into modern IDEs (Integrated Development Environments—the software where developers write and manage code), you can run two processes simultaneously. One agent writes or refines your code. Another documents what you're building as you build it. Need a prompt to spin up your agent, ask your favorite CustomGPT for instructions and now you have the prompt to put into Cursor or VSCode to build your agent (instructions in links below).
Then in Cursor or VSCode just prompt: "I'm developing code from table X to build a new table with Y features and use best practices in document Z. Use the documentation agent to document the work as we go."
That's it. You're no longer choosing between shipping and documenting. You're doing both. The agent handles the tedious part while you focus on verification and judgment calls. Work that used to take days now takes hours.
Will the output be perfect? No. But neither are humans. Last Friday I submitted an IT ticket and was told something couldn't be done. I reached out to someone else who said it absolutely could. Neither person was hallucinating. They just had different context. That's the whole point. Context is everything (feels like maybe other smart people in AI have said before 😀).
So if your instinct right now is "we need to invest millions in change management or data governance," slow down. That's not how you fix your documentation problem and a mistake I've seen many organizations make. The fix is one small win at a time. One skeptical engineer sees this new workflow save them four hours a week. Then another. That's how this spreads.
Change The Narrative Today
The tooling just caught up to this idea. Modern IDEs now support Skills (documentation files the agent actually reads) and Subagents (parallel agents that can write code and documentation simultaneously). The workflow I described above is no longer a workaround. It's a feature.
Start small. Pick one task you've been avoiding because documentation felt like too much overhead. Let the agent handle that part while you focus on the code. See what happens.
The next time someone tells you agentic coding is overhyped, ask them: "If you gave this same task to someone who started today, would they have the context to do any better?"
If the answer is no, the agent was never the problem.
Thank you for reading. If you like the newsletter feel free to forward along and help drive new eyes to Syllabi!
