Architecture-aware coding agents.
Understanding a system is not the same as reading a file.
An architecture-aware coding agent reasons about a codebase at the level of components and their relationships rather than the files currently open. In practice this means a persistent map of the repository, selective retrieval of the parts relevant to the task, and project knowledge that survives between sessions. Lucid Train maintains that map and writes what it learns to .lucid/knowledge.md so the next session does not start from zero.
The problem with file-level context
An agent that sees only the open file will make a locally sensible change that is globally wrong: duplicating a helper that exists two directories away, adding a third caching layer, or calling a service directly when everything else goes through a gateway. None of those look like errors in the diff. They look like reasonable code, which is exactly why they survive review.
Mapping before retrieving
The alternative is to build a structural map of the repository first, the file tree and the symbols it defines, and then select what to put in front of the model per turn based on the task. This is a retrieval problem rather than a context-window problem, and treating it as the latter is why simply buying a longer context does not fix it: a million tokens of irrelevant code is still irrelevant.
Knowledge that outlives a session
Architectural understanding is expensive to rebuild every conversation. Lucid Train writes what it establishes into .lucid/knowledge.md and records changes in .lucid/CHANGELOG.md, both inside the repository, so the understanding is versioned with the code and reviewable in a pull request like anything else. A teammate can read it, correct it, and commit the correction.
The visual check on the model
A map you cannot see is a map you cannot correct. Drawing the architecture the agent believes exists is the cheapest possible audit of its understanding: a missing service, an edge pointing the wrong way or a component in the wrong tier is obvious in a picture and invisible in a prompt. This is the part most agents skip, and it is the part that catches a misunderstanding before it becomes a pull request.
What awareness does not buy you
A correct map does not make the agent's judgement correct. It removes one class of failure, the locally reasonable and globally wrong change, and leaves every other class intact. Review still matters, tests still matter, and an agent confident about a system it has mapped accurately can still choose a bad design within it.
Two ways an agent can see a codebase
| File-level | Architecture-aware | |
|---|---|---|
| Unit of reasoning | The open buffer | Components and their edges |
| Finds an existing helper | Only if it is open or grepped | Through the symbol map |
| Knows the call goes via a gateway | No | Yes, if the map is right |
| Survives a new session | No | Written to .lucid/knowledge.md |
| Can be audited by a human | Read the transcript | Look at the drawn architecture |
Questions
Related
- What Is a Systems-Design-First Coding Agent?The architecture is the input, not the write-up.
- AI System Design Tools, ComparedThree different products share one search term.
- From System Design to CodeWhat has to be true for a drawing to become a build.
- AI Software Architecture ToolsThree jobs, three very different reliabilities.