On a recent project, we were rebuilding parts of an application using an established design system. Some of the designs deviated from the system, often in subtle ways. One example was a border token that the existing component didn’t support through its API.
An engineer looking at this would see a decision that needed to be made. Was the difference intentional? Should the component support a new variant? Could the existing token be used? Or had the design drifted away from the system without anyone noticing?
The AI didn’t see a decision. It saw that the design couldn’t be reproduced with the existing component, so it built a new one from scratch. Viewed in isolation, the resulting code was perfectly reasonable. It matched the design as specified, but it had also bypassed the design system entirely and introduced another component for the team to maintain.
The prompt wasn’t the problem
The obvious thing to do would be to add more instructions to the prompt: always use components from the design system; never create a new component when one already exists; follow the patterns established in the codebase.
That may have prevented this particular component from being created, but it still wouldn’t have resolved the conflict between the design and the design system.
Sometimes a new component is the right choice. Sometimes the existing component needs to support another variant. Sometimes the design has drifted and needs to be brought back into line. The important thing is recognising when there is a decision to make instead of blindly implementing what’s in front of you.
The AI couldn’t make that distinction because it didn’t have the context behind those decisions. Much of that knowledge existed in the heads of the people working on the project. We could keep adding that knowledge to the prompt, but at some point the prompt becomes a substitute for documenting how the organisation builds software.
Improving the environment
As the project progressed, we started documenting playbooks for common situations. We captured how to build a new page layout, how forms should be structured and which patterns we wanted engineers to follow.
We also brought the design system into the application’s monorepo. This made its source code, component APIs and existing usage easier for AI to discover alongside the application consuming it. The AI could inspect the system directly instead of relying on our prompts to explain how it worked.
It began following the established patterns more consistently. The playbooks and design-system changes also gave engineers clearer examples to work from and reviewers a shared understanding of what the implementation should look like. The whole project became easier to work with.
Let’s not get carried away
It’s tempting to solve this by giving AI access to everything. More documentation, more files, more examples and a larger context window. More context only helps when it is relevant, current and consistent.
If the documentation recommends one pattern, the codebase contains three others and the design system supports something else entirely, AI has to decide which source to trust. It will usually make that decision without telling you there was any ambiguity.
The codebase, design system, architecture documentation and project playbooks all contribute to how AI understands a system. The goal is to make the intended way of building software clear enough that both engineers and AI can follow it.
Look at what your team keeps correcting
A good place to start is with the mistakes your team repeatedly corrects in AI-generated code.
If AI keeps recreating components that already exist, adding another instruction to the prompt may stop it happening next time. However, it’s more useful to ask why the existing component was difficult to discover in the first place.
The answer tells you what needs to become clearer or easier to access. Whatever the fix, the repeated correction has exposed a gap in the context surrounding the work.
Closing that gap makes the right decision easier to reach before any code is generated.
Workarounds become part of the system
Teams get very good at navigating their own systems. Experienced engineers know which documentation is current, where the reliable examples live and who to ask when the code doesn’t tell the whole story.
After a while, those workarounds become part of how the team operates. AI exposes this hidden context because it doesn’t share the team’s history. When it struggles to find the right component or understand why the system is structured a certain way, it may be surfacing friction that engineers have simply learned to work around.
Optimise your context
The component from our project wasn’t a spectacular AI failure. It compiled, matched the design and looked reasonable in isolation. The problem only became visible when we considered how it fit into the wider system.
The next time AI produces reasonable code that still feels wrong, pay attention to the correction your team makes. Ask what information would have helped it recognise that a decision was needed, then put that information somewhere the next engineer or AI assistant can find it.
Repeated corrections will show you where the project’s architecture, conventions and shared knowledge are unclear or difficult to access. Start there. Choose one source, make it more reliable and easier to find, then see whether the same mistake happens again.
These gaps can be difficult to see when your team has learned to work around them. An outside perspective can help make them visible and identify which foundations are worth improving first.
The next prompt is one interaction. The context around it shapes every decision that follows.
