Skip to content
Keshav Raj
Robot agents building an app from glowing contract scrolls and skill cards on a spec board.
AI DISTRICTCONTRACTS
SHIPPED Skills, contracts and OpenSpec that agents build against.I OWNED ArchitectOUTCOME CONTRACTS

AI dev architecture

Keshav RajArchitect · 2026 · ShippedContact meResume PDF

Context

This is the AI-assisted development setup I built for a large frontend monorepo in early 2026. It is for the engineers who use AI tools there every day, and for the tools themselves.

The problem

AI tools guessed API schemas and generated inconsistent models, widgets and pages. Each engineer got a different result for the same request, and reviewers spent time fixing guesses.

What I did

  1. I wrote reusable skills for the common jobs: create a model, create a widget, assemble a screen, build a full feature and review a change.

  2. I added contracts the agents build against: API contracts in YAML, widget contracts and design contracts. Path-scoped rules tell the tool which conventions apply to which folder, and self-updating catalogues keep the contracts from drifting.

  3. I set up a Figma-first workflow and wrote an AI development guide so the process was written down. Later I brought in OpenSpec baselines for the lesson player and the player SDK.

  4. The architecture went through three versions between February and March 2026, each reviewed as a normal pull request.

Key decision

I chose to give agents contracts to build against instead of longer prompts. A contract can be checked and updated. A prompt cannot.

The trade-off is upkeep: contracts and catalogues must stay current or they mislead. That is why I made the catalogues self-updating.

Result

It is shipped and in use for the 2026 frontend work. Company-wide figures on AI co-authored commits are not specific to this setup, so I do not attribute them to it.

What I learned

I would again start from contracts and a written guide. I would add a way to measure it, such as how often generated code passes review unchanged, so the benefit is a number rather than an impression.

Stack

  • Claude Code
  • OpenSpec
  • YAML
  • Figma
  • TypeScript
Play the world →