> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-testing/architecture-tests.md). # Architecture tests An agent optimises for one objective: make it compile and make the existing tests pass. The shortest path to that goal frequently violates a boundary the compiler cannot see. A controller reaches straight into a repository, skipping the service layer. A domain object imports an infrastructure class. A new module closes a dependency cycle. None of these is a compilation error. None of them fails a unit test. Each one is a small, permanent loss of the structure somebody designed on purpose. Architecture tests make those invisible constraints visible and enforceable. They are ordinary tests: no infrastructure, no containers, no network, milliseconds to run. A rule says what may depend on what, and a violation fails the build in the same breath as a syntax error. ## Why this layer matters more with agents **It is a feedback loop the agent can use.** A failing architecture test is a precise, machine-readable statement of what the code did wrong. The agent reads it and corrects itself, without a human having to explain the layering convention for the tenth time. **It turns migration decisions into enforcement.** Models are trained on years of published code, so they default to what was popular then: the deprecated HTTP client, the old test annotations, the date type your team abandoned. A rule that forbids the retired API converts "please stop using that" into something that cannot merge. **It freezes the past without blocking the present.** Legacy violations can be recorded as accepted, so the rule blocks new breaches while leaving the existing ones for a deliberate cleanup rather than an accidental one. ## What it is worth In a controlled comparison, the same agent was given the same CRUD task ten times. Without architecture rules it bypassed the service layer in ten runs out of ten, and every violation compiled and passed the existing tests. With the rules in place, none of the ten runs produced a violation that reached the build. That is the whole argument for this layer: it is cheap, deterministic, and it removes a class of error from the review queue entirely rather than catching it later. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.visdom.virtuslab.com/visdom-testing/architecture-tests.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.