The guidance needs testing too
Part 5 of Building Arbor, a series about my year on Linktree’s design system.
Guidance needs checking as carefully as the code it recommends.
The earlier parts follow Arbor’s knowledge from research to Figma, documentation, and the MCP server. The next place to reach was the pull request, where an engineer could still change an implementation before it shipped.
I built a reviewer that read pull requests against Arbor’s guidance and annotated the relevant line with what to change and why. It gave the engineer a specific correction beside the code they were already reviewing.
Putting the advice there made it easier to act on. It also made the quality of that advice more important.
From a warning to a change
Documentation asks someone to remember the guidance, find it, and apply it. A lint rule can catch a pattern locally or in CI, but the person still has to work out the correction. The reviewer could bring the suggested code into the discussion.
These approaches helped at different points. A warning during development could reach the engineer before review. A pull-request annotation could explain a change in the context of the implementation. The aim was to reduce the work between recognizing a problem and correcting it.
The reviewer came out of research into other systems and an audit of our own workflow. I saw a gap in how we delivered recommendations and built a tool for that moment.
It was a communication tool as much as an engineering tool. The useful comment gave someone a reason to change the code and a way to do it. The engineer still had to judge the recommendation against the work in front of them.
Two things to test
Once people and agents could retrieve the guidance, we needed to examine two different claims.
First, did the agent surface change what a model produced? We built evals to measure that effect. Making guidance available doesn’t establish that a consumer used it or that it changed the resulting implementation.
Second, was the guidance itself true? A CI fixture checked claims in the guidance against the system they described. That is a different test from asking whether a model followed the instructions.
A model can comply with a false rule. A high compliance score would then show that we had delivered the wrong instruction effectively.
The checks caught a few claims that needed correcting, and we fixed them. The point was to make those claims available for inspection before depending on them more widely.
Give the consumer enough context
We also added provenance to guidance artifacts and MCP output, and status flags to components. A consumer could inspect where a claim came from and whether a component was ready to recommend.
Existence and readiness answer different questions. Finding a component in the system shouldn’t require the next person or agent to infer whether it is intended for their use.
These details belong alongside the component API. They affect the recommendation someone can safely make from it. A technically correct description with unclear status still leaves work for the consumer to guess at.
That was another design problem to encode explicitly.
What the foundation provides
This is what I mean by foundation before intelligence. Tokens, component contracts, documentation, and migration paths give the tools something definite to work with. They make it possible to compare a recommendation with an implementation and understand which decision needs attention.
It doesn’t mean waiting for a perfect library before doing research. Research helped us find gaps in the components and in the way we delivered the system. The foundation and the investigation informed each other.
The order matters when making a change. Understand what is consumed. Establish the intended convention. Provide a way to migrate. Then make the change easier to repeat through tooling. If those decisions remain ambiguous, an agent has to inherit the ambiguity or guess its way around it.
Automation makes that responsibility harder to ignore.
What I’d carry forward
Make documentation part of the component. A rendering shows that something exists. A useful explanation tells a team when to use it, when not to, and what they can expect from it.
Give repeatable decisions a shared home. A token, specification, or piece of guidance should have a place it can be maintained and reached from the tools that need it. Repeated copies create more work at the next change.
Keep the reasons available. Written context helps someone question a recommendation, review a release, or understand why a migration exists. That lets the system grow through other people’s contributions.
Working on the layer that lets a system see itself clearly and learn from the field was the most fun I’ve had building anything. Thanks to Linktree and the Arbor team.