Skip to main content

​
The shared contracts between humans and AI

Blueprints are the rules for how software gets built here. They’re the design systems, architectural guidelines, security processes, testing conventions, and operational procedures that govern every piece of work, regardless of which strategy it belongs to. They transcend strategies. They outlive strategies. They bookend the process, a reference when work starts, a checklist when work ships.

Documentation says

“Here’s how authentication works.”Descriptive. Passive. Written for a reader.

A Blueprint says

“When you modify authentication, you must do X, never do Y, and verify with Z.”Prescriptive. Active. Written for an actor (human or machine).
Blueprints are live documents. They evolve as the team learns, as the architecture shifts, as decisions resolve. The system keeps them honest, see Drift Detection.

​
What a blueprint covers

Anything that governs how software gets built here and that every contributor, human or AI, needs to respect.

Design systems

Component libraries, interaction patterns, accessibility requirements, the visual language of the product.

Architectural guidelines

Service boundaries, data flow, coupling rules, which layers can call which.

Security processes

Authentication patterns, secret handling, input validation, audit requirements.

Operational procedures

Deployment, rollback, observability, on-call expectations.

Testing conventions

What to mock, what not to mock, coverage expectations, how to stage test data.

Code conventions

Naming, structure, error handling, logging. The rules that keep the codebase coherent.

​
The five properties of a blueprint

Cross-strategy

A blueprint isn’t owned by any one strategy. The deployment blueprint applies to every strategy that ships to production. The design-system blueprint applies to every strategy that ships UI. Blueprints are the shared substrate.

Scoped

A blueprint has a boundary. “How deployment works” is a blueprint. “Everything about the system” is not. Agents load only the blueprints their work item touches.

Prescriptive

Blueprints are rule guides and checklists, not explanations. They tell the actor what to do, what to avoid, and how to verify, not why the system exists.

Composable

A work item might require loading three blueprints simultaneously: frontend + api + testing. The system ensures they don’t contradict each other.

Provenance-tracked

Every rule in every blueprint links back to the decisions that produced it. You can always trace why a blueprint says what it says, which decisions set the rule, which incidents shaped it.

​
How blueprints fit the lifecycle

Blueprints bookend every piece of work:

Before work starts

The agent (or human) loads the relevant blueprints for the work item. This is the reference: how do we build things here? The execution plan is drafted against these contracts, not against a guess.

During implementation

Blueprints function as a checklist. If the code being written violates a blueprint rule, the agent stops and raises it. If a blueprint is silent on an edge case that matters, a new decision is logged.

When work ships

If the implementation changed something the blueprint describes (a deployment step, an auth pattern, an API contract), the blueprint is marked for review. The system won’t let it silently fall out of date.

Over time

Blueprints evolve. A new decision supersedes an old rule. A production incident tightens a security constraint. A design system matures. The history is preserved, so any rule can be traced back to the moment and the reason it changed.

​
Drift-detected

Blueprints don’t rot because the system actively prevents it. This is the single mechanism that makes the “shared contract” real rather than aspirational.

Read: Drift Detection

Agent-reported drift, decision-triggered review, implementation-triggered review, and scheduled audits, the four ways Memex keeps blueprints current by default.

​
What a blueprint replaces

If you’re running AI coding agents today, you almost certainly have CLAUDE.md, cursor rules, or .github/copilot files in your repo. Those are the spiritual predecessors of blueprints. They validate the need, but they’re per-repo, per-tool, manually maintained, and disconnected from the decisions that produced them.
Blueprints are the managed, multi-agent, cross-repository evolution of those files. The shared contract between every human and every machine working on your codebase.