What Spec Coding Learned from Screenwriting

March 5, 2026

Before I wrote software, I wrote screenplays. Four of them. Two features, two pilots. None of them got produced. All of them taught me how to write specs for AI agents.

That’s not the connection people expect. But it’s the real one.

What screenwriting actually is

Screenwriting isn’t creative writing. It’s technical writing with a narrative wrapper.

A screenplay is a set of instructions. You write precise descriptions that other people execute — the director, the actors, the cinematographer, the set designer, the editor. You are not in the room when they work. You can’t clarify. You can’t watch and correct. The document has to stand alone.

When I write:

INT. OFFICE - NIGHT

Sarah sits at her desk, the only light coming from her monitor.
She scrolls through emails. Stops. Reads one twice. Closes
her laptop without responding.

That’s a specification. The director knows the lighting (monitor only). The actor knows the behavior (reads twice, doesn’t respond). The set designer knows the location (office, desk, one monitor). Nobody needs to ask me what I meant. The document is complete.

Software specs work the same way. The AI agent wasn’t in your head when you designed the feature. It doesn’t know your preferences unless you write them down. The spec is the document that bridges intent and execution.

The parallels

Screenwriting and spec coding share structural DNA. The connection isn’t metaphorical — it’s mechanical.

Scene headings = File paths

Every scene in a screenplay starts with a heading: INT. OFFICE - NIGHT. Location. Setting. Context. Before anything happens, the reader knows where they are.

Every spec starts with file paths. src/api/routes/creators.ts. Before the agent builds anything, it knows where the code lives. Without this, the agent guesses. A screenplay without scene headings is a mess of floating dialogue. A spec without file paths is a mess of files created in the wrong directories.

Character objectives = Function behavior

In screenwriting, every character in every scene has an objective — what they want. Sarah wants to ignore the email. The antagonist wants a response. The scene works because the objectives are clear and conflicting.

In a spec, every function has a behavior — what it does. getMetrics() returns an object with impressions, clicks, and conversions for a given date range. The spec works because the behavior is defined and bounded.

The parallel goes deeper. In screenwriting, you learn that a character’s objective must be specific and actable. “Sarah is sad” is not an objective. The actor can’t play “sad” — it’s too abstract. “Sarah wants to avoid confrontation, so she closes the laptop” is actable. It produces a specific behavior.

“The function should handle errors well” is not a behavior. The agent can’t build “handles errors well” — it’s too abstract. “If the API returns a 404, return an empty array. If it returns a 500, throw a ServiceError with the response body” is buildable. It produces specific code.

Constraints = Dramatic rules

Every screenplay operates under rules. The genre sets expectations. The world has established logic. If you’re writing a grounded thriller, nobody flies. If the character has been established as honest, they don’t suddenly lie without setup.

These constraints make the writing better. They force creative decisions into a narrow channel. The constraint isn’t a limitation — it’s a design tool.

Specs work identically. “No batch export.” “Don’t modify the schema.” “No new dependencies.” These constraints don’t limit the agent. They focus it. Without constraints, the agent builds comprehensively — every edge case, every nice-to-have, every adjacent feature. With constraints, it builds exactly what you asked for.

I learned this writing my second screenplay. The first draft was sprawling — every idea I had, every subplot that occurred to me. The rewrite was brutal cutting. What’s left after you remove everything unnecessary is the actual story.

Specs go through the same process. The first version has too much scope. The good version is the one where you’ve removed everything that doesn’t need to be in this task.

Action lines = Implementation guidance

Screenwriting has a rule: write what the camera sees. Not what the character feels. Not backstory. What’s visible on screen.

“Sarah is furious about the merger and regrets trusting David” — the camera can’t see any of that.

“Sarah crumples the report and throws it in the trash” — the camera sees that.

Specs have the same rule. Describe what the code does. Not why the product team wants it. Not the business context. What the function accepts, what it returns, what side effects it has.

“This endpoint supports our analytics initiative by providing key stakeholder metrics” — the agent can’t build that.

“GET /api/metrics accepts a range parameter and returns { impressions, clicks, conversions }” — the agent builds exactly that.

Why this cross-pollination matters

Engineering specs tend toward one failure mode: they describe the system but not the behavior. UML diagrams, architecture docs, data flow charts — useful for humans, but they don’t tell an AI agent what to build next.

Screenwriting specs tend toward the opposite failure: all behavior, no system. “She opens the door” tells you what happens but not where the door is in the building’s floor plan.

Spec coding takes from both. The file paths and interfaces are engineering. The behavioral descriptions and constraints are screenwriting. The combination produces documents that AI agents can actually execute.

The discipline of writing for absent executors

The deepest lesson from screenwriting isn’t structural. It’s emotional.

When you write a screenplay, you accept that you will not be present during execution. The director will make choices you didn’t anticipate. The actor will interpret a line differently than you heard it in your head. The editor will cut your favorite scene. You have to write clearly enough that even with all that interpretation, the story you intended comes through.

Spec coding requires the same acceptance. The AI agent will make implementation choices you didn’t specify. It will structure code differently than you would have. It might use a different hook, a different pattern, a different variable name. If your spec is clear on what and where and constraints, those choices don’t matter. The feature you intended comes through.

People who struggle with spec coding often struggle with this specific thing. They want to control the implementation. They want to dictate the how. That’s not speccing — that’s writing code in English, which is slower than writing code in code.

Screenwriters learn to let go of execution details. You write the scene. Someone else shoots it. If you wrote it well, the result is what you intended — even if the specific shot choices weren’t what you pictured.

Write the spec. The agent builds it. If you wrote it well, the result is what you intended — even if the specific code isn’t what you would have typed.

Where to go from here

If you want the full methodology, read the spec coding complete guide. For the tactical side — the five elements, the before/after examples — that’s in the spec that makes AI agents work independently. And for how spec coding compares directly to the alternative, there’s vibe coding vs spec coding.

The screenwriting background isn’t necessary for spec coding. But the discipline it taught me — writing for someone who can’t ask you questions — is the core skill underneath all of it.