Claude Code Writes Your Code, but Do You Know What's in It?
Claude Code Writes Your Code, but Do You Know What's in It?
The code compiles. The tests pass. The feature works. But the module structure is nothing like what you expected. Functions moved between files. New abstractions appeared that you did not design. Dependencies were added that you did not approve.
The Structural Drift Problem
When an AI agent writes code, it optimizes for making things work. It does not optimize for maintaining the architectural vision you had in mind. Over hundreds of commits, small structural decisions compound:
- A utility function gets created instead of using an existing one
- A module gets split into three files because the agent thought it was cleaner
- An abstraction layer appears that adds indirection without clear benefit
- Dependencies get added for convenience when a built-in solution existed
Each change is defensible in isolation. Together, they drift the architecture away from your intent.
Why This Happens
AI agents do not have a persistent mental model of your architecture. Each session starts fresh. The agent reads the code, infers the structure, and makes decisions based on that inference. If the inference is slightly wrong - if the agent misreads a naming convention or a module boundary - the structural change follows the misreading.
How to Maintain Control
- Review diffs for structure, not just correctness - does the code work is a different question from does the code belong here
- Maintain an architecture document - give the agent explicit module boundaries
- Run periodic audits - every two weeks, review the dependency graph and module structure
- Reject clean-up PRs that reorganize without clear justification
The agent writes the code. You own the architecture. Do not let those responsibilities blur.
Fazm is an open source macOS AI agent. Open source on GitHub.