The Death of the User Story: Why AI Needs System-First Specifications , Can Zachman Framework Help?

Most software specifications are written for humans. That’s becoming a problem.

The standard format — User Story → Acceptance Criteria → Technical Tasks → QA Cases — exists because humans need narrative context to coordinate. When a developer reads:

“As a library member, I want to check out a book so I can read it at home.”

They can infer what to build. The story acts as a compression format for human communication, relying on shared intuition and "common sense" to fill in the gaps.

But when AI is doing the building, that compression works against you.

The AI fills these blanks with plausible defaults. Those defaults might be correct—or they might not. Every ambiguity becomes a coin flip. In a codebase of 10,000 lines, you're flipping that coin hundreds of times.

The Cost of Guessing: A Counter-Example

Consider the story: "As a member, I want to cancel my book loan."

• The Story-Only AI: Might simply delete the Loan record to "cancel" it.
• The .spec AI: Consults the WHY section ("All financial transactions must be archived for 7 years") and the WHAT section ("A Loan status can only be CANCELLED if it has no associated late fees") and realizes it must update the status and trigger an audit log, not delete the record.

Without the system boundaries, the AI chooses the shortest path to "Success," which often leads to technical debt or data loss.

From Narrative to Determinism: The Plain English Specification

Now compare that narrative story with a System-First Specification. Instead of writing a single user story and hoping the AI "gets it," we describe the system across dimensions using plain English.

You don't need to define database schemas or write complex DSLs. You simply explain the system to the AI like you're talking to a smart colleague.

The System-First Input (Plain English):

• WHAT: "The system manages Books, Members, and Loans. A loan tracks which member has which book and when it's due. Books are either available or out."
• WHO: "Library Staff can handle all book operations. Members can only view their own active loans."
• WHY: "Crucial rule: A member is blocked from checking out new books if they have more than $10 in late fees."
• HOW: "Build this as a Spring Boot backend with a simple React frontend using a PostgreSQL database."

From these simple, conversational inputs, the AI can deterministically derive the technical architecture—within the bounds of a well-written specification. It doesn't need to guess because you've provided the system boundaries, not just a user's desire.

It generates the DDL for the database, the REST controllers for the API, and the business logic for the fee-blocking—not because it's "smarter," but because you've removed the ambiguity through descriptive coverage.

It stops feeling like "autocomplete" and starts feeling like leverage.

---

The Panoramic Specification: Mapping the Darkness

The reader might ask: Why use a legacy framework like Zachman? Why not just write better bullet points?

For the unfamiliar, the Zachman Framework is an enterprise architecture standard that organizes system descriptions into a grid—intersecting six fundamental questions (WHAT, HOW, WHERE, WHO, WHEN, WHY) with different stakeholder perspectives. We are modernizing this "legacy" idea for the AI era.

The difference is Topology vs. List. A list of bullets is arbitrary; you don't know when you're finished or what you've forgotten. Zachman is a coordinate system for a system's soul. It provides a "Definition of Done" for architectural description. By covering these six dimensions, you ensure the AI has a complete set of bounds, leaving no "pitch black" areas where hallucinations can breed.

1. The WHAT: Mapping the Domain

A story tells us what a user wants to do; the "What" hub describes the landscape they are doing it in. If the AI knows we are managing "Books" and "Members" through "Loans," it develops a permanent mental model of the data structures it must respect, regardless of the individual features we build later.

2. The HOW: Establishing the Spine

AI is a polyglot, but a project needs a spine. Without a "How" specification, the AI might give you a Python script for one feature and a Node.js service for the next. This hub anchors the AI to your chosen architecture (e.g., Spring Boot + React), ensuring every generated line of code fits the existing skeleton.

3. The WHO: Enforcing the Perimeter

Security is usually the first casualty of ambiguity. A story says "I want to see my books," but it rarely specifies "and I should be blocked from seeing anyone else's." By declaring Actor-to-Capability mapping in the "Who" section, security becomes a first-class engineering constraint that the AI must satisfy for every function it generates.

4. The WHEN & WHERE: Contextualizing the System

Software doesn't exist in a vacuum. It has a pulse (When/Events) and a home (Where/Infrastructure). Describing triggers like "overdue book alerts" and environments like "VPN-protected AWS instances" provides the environmental context that allows AI to generate production-ready code rather than "tutorial-grade" snippets.

5. The WHY: Protecting the Invariants

This is the "Logic Hub." It captures the invariants—the business rules that can never be broken. By stating "late fees over $10 block checkouts," we give the AI a logical North Star. Instead of just writing code, the AI is now solving a constraint-satisfaction problem where the "Why" rules are the ultimate truth.

---

Putting it into Practice: The .spec Workflow

So, how do you actually apply this? We've codified this into a simple, three-step workflow called System-First Spec (zeespec). It treats your system description as a version-controlled asset.

1. Initialize the Scaffolding

Run a simple command to create your architectural coordinates:

npx spec-cli init

This scaffolds a .spec/ directory with eight files: what.md, how.md, who.md, when.md, where.md, why.md, upstream.md, and downstream.md.

2. Describe in Plain English

Instead of writing a 40-page PRD, you spend 20 minutes filling these files in plain English.

• In why.md, you write: "A member cannot check out more than 5 books."
• In how.md, you write: "Standard Node.js/Express backend with a Vite/React frontend."

3. Generate the Master Prompt

Once your dimensions are defined, you assemble them:

npx spec-cli generate

This merges your plain English descriptions into a single, structured Master Prompt (AGENTS.md). When you hand this to an AI (like Cursor, Claude Code, or Windsurf), the AI stops guessing. It sees the "What," the "Who," and the "Why" simultaneously. It stops writing "stories" and starts generating a coherent system.

---

The Shift: Moving Human Judgment Upstream

When we stop building from stories and start generating from systems, the role of the human engineer moves to the edges:

1. Upstream (The Architect): You are no longer a "ticket-taker." Your job is to describe the boundaries, constraints, and data of the world accurately. You focus on the integrity of the description. If the description is correct, the ambiguity is gone, and the implementation becomes trivial for the machine.
2. Downstream (The Clinical Reviewer): You are no longer a boilerplate-writer. You review generated candidates to ensure they satisfy the spec. You are looking for edge cases in logic and "Why" violations rather than syntax errors or missing imports.

This shift compresses the weeks of "Implementation" into hours, but it expands the "Design" phase. It forces us to think harder about what we are building before we type a single line of npm install.

The final result is software that isn't just "built" but is architected by design.

Software isn't built from stories; it's generated from systems.