When Scaffolding Becomes Architecture in AI Agent Code
When Scaffolding Becomes Architecture in AI Agent Code
Scaffolding you refuse to take down becomes architecture eventually. Every agent codebase has these - the "temporary" retry wrapper that now handles 40% of all API calls, the debug logging that became the only observability layer, the hardcoded timeout that turned into an undocumented system constant.
How It Happens
The pattern is always the same. You are building fast, shipping an agent feature, and you need something to work right now. So you write a quick solution. A polling loop instead of proper event handling. A string comparison instead of a type-safe enum. A flat file instead of a database.
It works. You ship. You move on to the next feature. Six months later, three other modules depend on that flat file format and changing it would require rewriting half the system.
Why Agent Code Is Especially Vulnerable
AI agent codebases are more susceptible to this than typical software for a few reasons. First, agent behavior is inherently experimental. You are constantly trying new approaches to tool use, memory management, and error recovery. Each experiment leaves behind scaffolding.
Second, agents interact with external systems that change unpredictably. That "temporary" workaround for a specific app's accessibility tree structure becomes permanent because the app never fixes its tree and your workaround actually works.
Third, the feedback loop is long. A bad architectural decision in a web app shows up immediately when the page breaks. A bad decision in an agent system might not surface until the agent encounters a rare edge case months later.
What to Do About It
The honest answer is not "always clean up your scaffolding." Sometimes the scaffolding is good enough. The real skill is recognizing which temporary solutions are load-bearing and documenting them as such. If your hack is going to stay, at least give it a proper name and a comment explaining why it exists.
The worst outcome is scaffolding that everyone treats as temporary but nobody ever replaces.
- AI Agent Code Looks Plausible
- Code Quality Through CLAUDE.md Standards
- Architecture Problem Not Claude Code Problem
Fazm is an open source macOS AI agent. Open source on GitHub.