client contract · markdown

Frontend Standards

When a team decides to include agents into their workflow — getting the agent to write code isn’t the hard part — it will write code regardless. The hard part is giving it enough architectural context to write the right code.

If you’re starting form scratch this can be pretty straightforward; however, most startups don't have the luxury of starting over. They already have a production application — sometimes several applications — and a very lean team building them. Therefore, the goal isn't a greenfield rewrite; it's making what exists understandable to both engineers and now, agents.

decisions written as questions

The standard was assembled from seventeen architecture decision records, each framed as a question rather than an answer.

• How is server state managed?

• How are forms validated and submitted?

• How are domain types modelled?

• How are errors represented and handled?

• How is the standard enforced?

• How do AI agents consume and apply it?

Framing them as questions does two things. It turns the architecture into a reviewable queue instead of a monolith you either accept or reject whole. And it lets you be honest about which decisions are actually contested — most of these ratified what the member app already did, while one, routing, was genuinely open. Saying so in the brief kept the review pointed at the decision that needed making.

Accepted decisions became numbered rules, and every rule was traceable end to end:

None of these files are new ideas. What's new is where the knowledge in them lives. Each one replaces a conversation — an onboarding walkthrough, a Slack thread, a decision made in a meeting and then quietly abandoned. The files are the process placed somewhere both a person and an agent can read it.

Written for agents, not only for people

This is the part that made it different from a standard I'd have written three years earlier. The document is machine-readable, agents are wired into authoring, review and migration, and deterministic CI checks are what block bad code — not a reviewer happening to notice.

Those two halves matter in that order. Agents are good at following a rule they can read and bad at inferring one they can't, so making the standard legible to a model is what turns it from documentation into a default. Making CI the enforcement layer is what stops it degrading the first time someone is in a hurry.

How it’s meant to prove itself

Member-first. Every rule proven in the member app before the coaching dashboard or the portal were brought to it, with one feature built on the standard as the proof. Each app then got its own scorecard — its health assessment scored against the standard and turned into a phased checklist rather than a mandate.

Standards that arrive as something already working somewhere get adopted.

The order matters

Start with the scorecard. It answers one question: how close is this application to the standard you're trying to reach?

Then write ADRs, but only backward-looking ones. Record the decisions you've already made that are still true.

Then write the canonical standard. This is where you resolve the contradictions the ADRs surfaced, and it's the expensive step, because it isn't writing. It's architecture.

Finally, write the AGENTS.md. It's the entry point for any development agent, and it should be the smallest file in the tree, because everything real lives in the documents it points at. We used Claude Code so the CLAUDE.md file remained a thin wrapper for Claude-specific instructions.

How to enforce it

Context files drift faster than code, and a standards file that no longer describes the repository is worse than having none, because the agent actually believes it.

Hooks, CI checks, a review step that treats the standard as a spec — the mechanism matters less than the fact that something fails when the two diverge.

Where it landed & what i’d change

The brief went into review in June 2026 and I left before it was resolved, so I can't tell you whether it was adopted.

The document treated seventeen items as open decisions when three or four were. That's what makes a mostly-settled architecture look contested. I'd separate them now — the frame and the boundary rule approved on their own, the genuinely open decisions as a short queue, and everything already working written down as standard rather than as a choice.