Your Architecture Is Why Your Coding Agent Keeps Writing Bad Code

A few months ago, the writer realized that the code and modules built within their structure were growing too large and developing with AI was becoming increasingly difficult. When they asked Cursor or Claude Code to make a small change to a frontend module, it often made unrelated changes. For example, it would alter state management, duplicate helper functions, pull in unnecessary third-party packages, and ignore design configurations.

The writer initially thought this was a problem with the LLMs, but soon discovered the issue lay in their architecture. If they had written the code themselves, they would have known how everything fit together, but without clear guidelines for the AI, it struggled to understand the context. As the repository grew more complex, the agent's context bloated, and its reasoning became unreliable.

To address this, the writer implemented monorepo architecture as a context management strategy. In a monorepo, all code lives in one repository but with explicit boundaries, such as separate folders for apps, packages, and config files. This approach allows the AI agent to work directly on the relevant shared packages workspace, rather than needing to scan the entire repository.

Another crucial aspect is enforcing strict boundaries between independent micro frontends. Modules should only connect vertically through shared packages and the shell application, preventing horizontal connections that could lead to unwanted interactions. Additionally, the writer introduced a version decoupling trick, ensuring that changes to shared helper packages only affect the modules that explicitly adopt the new version.

Finally, the implementation of tiered AGENTS.md files helps prevent convention drift by allowing specific rules for different modules, while avoiding overly broad rules that could bloat the context and reduce reasoning efficiency.