OpenSpec keeps a living source of truth in specs/ and proposes every change as a self-contained folder. (Replace with real hero image before publishing.)

Last time, we walked through spec-driven development and GitHub’s Spec Kit — the idea that you agree on what to build before the AI writes code. The most common reply I got was some version of: “Sounds great, but it looks like a lot of ceremony.”

This one is for that reply.

The problem OpenSpec exists to solve

AI coding assistants are fast. They are also unpredictable — because the requirements usually live in one place: your chat history.

You describe what you want. The agent builds something. Three prompts later, the original intent is buried under corrections. Nobody — human or AI — can point to a single source that says “this is what we agreed to build.”

The result is familiar:

• The agent forgets a constraint you mentioned 20 messages ago.
• Two features quietly contradict each other.
• You re-explain the same context every session.
• “Why does it work this way?” has no answer except scrolling.

OpenSpec adds a thin layer of written specs between you and the agent, so you agree on what to build before any code is written — and that agreement survives after the chat window closes.

Assumption flagged: I’m treating “AI coding agent” as your main workflow (Claude Code, Cursor, Windsurf, and similar). OpenSpec supports 25+ tools. If you code without an agent, most of this still applies, but the payoff is smaller.

(OpenSpec is one of a few tools in this space; GitHub’s Spec Kit is another. This piece stays focused on OpenSpec.)

What OpenSpec actually is

In plain terms: OpenSpec is a folder of Markdown files plus a small command-line tool (open-source, from Fission-AI). No IDE lock-in, no heavy framework.

It gives your project one honest answer to the question “what is this system supposed to do?” — written down, versioned in git, and updated every time you ship a change.

Its philosophy, stated by the project itself:

• Fluid, not rigid — no forced phases; work on what makes sense.
• Iterative, not waterfall — refine as you learn.
• Easy, not complex — set up in seconds.
• Brownfield-first — built for existing codebases, not just fresh ones.

The one idea to remember: two folders

Everything lives under a single openspec/ directory, split in two:

openspec/
├── specs/      ← Source of truth: how the system works TODAY
└── changes/    ← Proposals: modifications, each in its own folder

• specs/ is the durable asset. It describes current, agreed behaviour.
• changes/ is the workbench. Each proposed change is a self-contained folder that lives here until it’s done, then merges into specs/.

That separation is the whole trick. You can have three changes in flight at once without them stepping on each other, review each one in isolation, and keep specs/ always reflecting reality.

The killer concept: delta specs

Most spec tools make you rewrite the whole specification for every change. OpenSpec doesn’t. It uses delta specs — you only write what’s changing, tagged into three buckets:

## ADDED Requirements      → new behaviour, appended to the spec
## MODIFIED Requirements   → changed behaviour, replaces the old version
## REMOVED Requirements    → deprecated behaviour, deleted from the spec

Think of it as a git diff for requirements. Instead of “here’s the entire 400-line auth spec again, spot the change,” you write:

## MODIFIED Requirements

### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)

Why this matters, in points:

• Clarity — reviewers see the change, not unchanged noise.
• No conflicts — two changes can touch the same spec file if they hit different requirements.
• Brownfield fit — real work is modifying existing systems; deltas make that first-class.

When a change is finished, OpenSpec merges those deltas into the main spec automatically. Your specs/ folder grows organically, one change at a time.

How a spec is written

Specs aren’t prose. They’re structured so both humans and agents read them the same way:

# Auth Specification

## Requirements

### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.

#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits the login form
- THEN a JWT token is returned
- AND the user is redirected to the dashboard

Three things to notice:

• Requirements are the what — observable behaviour, not code.
• Scenarios are the when — concrete, testable Given/When/Then examples.
• SHALL / MUST / SHOULD (RFC 2119 keywords) signal how strict each rule is.

The golden rule: a spec is a behaviour contract, not an implementation plan. No class names, no library choices, no step-by-step code. If the implementation can change without changing what the user sees, it doesn’t belong in the spec.

The workflow: three commands, no phases

OpenSpec’s current workflow is called OPSX, driven by slash commands you type to your AI agent. The core loop is three moves:

/opsx:propose   →   /opsx:apply   →   /opsx:archive

Here’s a real session — adding dark mode:

You: /opsx:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist

You: /opsx:apply
AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     All tasks complete!

You: /opsx:archive
AI:  Archived to changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

• Propose — the agent turns your idea into a change folder with a plan you can read and correct before it codes.
• Apply — the agent implements the checklist, ticking off tasks.
• Archive — the change merges into specs/ and moves to a dated archive folder for history.

Two more commands are worth knowing:

• /opsx:explore — think through an idea with the agent before committing to a change. A thinking partner, no structure required.
• /opsx:verify — check that the implementation actually matches the specs.

The key design choice: these are actions, not phases. Real work isn’t linear — you implement, realise the design was wrong, update it, keep going. OpenSpec lets you edit any artifact at any time instead of forcing plan → build → done.

Inside a change folder

Each change is one folder holding everything needed to understand it:

openspec/changes/add-dark-mode/
├── proposal.md   ← WHY and WHAT (intent, scope, approach)
├── design.md     ← HOW (technical approach, architecture decisions)
├── tasks.md      ← STEPS (implementation checklist with checkboxes)
└── specs/        ← the delta specs (what's changing)

These artifacts build on each other — proposal informs specs, which inform design, which inform tasks. But you’re never forced to create all of them. Skip design for a trivial change; that’s fine.

Getting started (2 minutes)

# Requires Node.js 20.19.0+
npm install -g @fission-ai/openspec@latest

cd your-project
openspec init

Then tell your AI agent:

/opsx:propose <what-you-want-to-build>

openspec init generates skill/command files your agent auto-detects (in .claude/skills/ or the equivalent for your tool). Re-run openspec update after upgrades to refresh them.

Making it yours: customization

OpenSpec’s defaults are deliberately plain so you can start in seconds. But real teams have real conventions, and OpenSpec gives you three levels to bend it to yours — use the lightest one that does the job.

Level 1 — Project config (openspec/config.yaml). The easiest lever, enough for most teams. One file lets you:

• Set a default schema, so you skip --schema on every command.
• Inject project context — your tech stack, API style, testing tools — which OpenSpec feeds into every artifact the agent generates.
• Add per-artifact rules — e.g. “every proposal must include a rollback plan,” applied only to proposals.

# openspec/config.yaml
schema: spec-driven
context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  Testing: Jest + React Testing Library
rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format

The point: instead of re-typing “we use Postgres and value backwards compatibility” into the chat every session, you write it once and the agent always sees it.

Level 2 — Custom schemas. A schema defines what artifacts exist and how they depend on each other. The default (spec-driven) is proposal → specs → design → tasks. When that doesn’t fit, fork it and edit:

openspec schema fork spec-driven my-workflow

You get the schema plus its templates in openspec/schemas/my-workflow/, version-controlled with your code. From there you can drop artifacts (a “rapid” workflow of just proposal → tasks), add them (insert a review step before tasks), or rewrite the templates that guide what the agent produces. Validate before use with openspec schema validate.

Level 3 — Global + community schemas. Store schemas at the user level (~/.local/share/openspec/schemas/) to reuse across projects, or pull in community schemas — opinionated workflows shared as standalone repos that wire OpenSpec into other tools. The maintainers recommend keeping schemas project-local when you can, since versioning them with your code is cleaner.

The mental model: config tunes the words, schemas tune the workflow. Reach for config first; only build a schema when your process genuinely differs.

OpenSpec Stores (very early beta)

Heads-up: Stores landed in v1.5.0 (June 2026) and the maintainers explicitly label it “very early beta — expect breaking changes.” Treat this as a preview, not production.

Everything so far assumes your specs live inside one repo. But planning often spans repos — a backend, a frontend, a mobile app that all share the same contracts. Where does the “source of truth” live then?

Stores are OpenSpec’s answer: planning that lives in a repo of its own.

• A store is a standalone OpenSpec repo — the same openspec/ shape you already know (specs + changes) — that you register on your machine.
• Once registered, normal commands (list, show, status, validate, new change, archive, …) can act on that store from anywhere by adding --store <id>.
• Because it’s just a git repo, it’s shared the way everything else is — git push. One planning source your whole team, and every coding agent, can read across every repo.

In plain terms: instead of specs being trapped inside each service, you can have a dedicated planning repo (or a contracts repo) that every project points at. Stores replaces OpenSpec’s older “workspace and initiative” model with something simpler.

Why it matters: it’s the step from “specs for this project” to “specs for this system,” which is where spec-driven development starts paying off for teams rather than solo developers. Just remember the beta label before you bet a team workflow on it.

Honest caveats

I’d be selling you something if I skipped these:

• It wants strong models. OpenSpec recommends high-reasoning models for planning and implementation; weaker models produce weaker specs.
• Context hygiene matters. Clear your context before implementation; a cluttered window degrades results.
• It’s discipline, not magic. OpenSpec gives you the structure. You still have to actually read the proposal before saying “apply.”

Why this is worth your attention

Spec-driven development isn’t new. What OpenSpec gets right is removing the ceremony — no rigid gates, no framework to learn, just Markdown and three commands.

The real payoff isn’t the specs themselves. It’s that your intent stops living in a disposable chat and starts living in a versioned, reviewable source of truth your agent reads every time.

For anyone shipping real features with an AI agent, that’s the difference between directing the work and hoping the agent remembered.

Next in this series: turning delta specs into a team review workflow — how a change folder becomes a pull-request-shaped conversation. If you’ve tried spec-driven development with your agent, I want to hear what stopped you or what clicked — drop a response below.

Last week we discussed Spec-Driven Development — the idea that you should write a clear spec first and let your AI agent build from it, instead of nudging a chat box until the code looks right.

We also pointed at the easiest on-ramp: plan mode. You ask the agent to write a plan, it shows you what it intends to change, you approve, it builds. Good habit. But it has one quiet flaw.

The plan is disposable. It lives inside that one chat session. Approve it, run it, close the window — and it’s gone. No version history. Nothing your teammate can read. Nothing the next agent can pick up. Great for a single change. Useless for code that has to live for years.

That gap is exactly what GitHub’s Spec Kit fills. This is the deep dive we promised.

What Spec Kit actually is

Spec Kit is a free, open-source toolkit from GitHub. In one line: it turns the throwaway spec into a real, versioned file inside your repository — and gives your AI agent a set of structured commands to write, refine, and execute against it.

You don’t learn a new editor or a new language. Spec Kit installs into a project, then adds a handful of slash commands to the AI coding agent you already use. It works with 30+ agents — Claude Code, GitHub Copilot, Gemini CLI, Cursor, and more.

The mental shift is small but important:

With plan mode, the spec is a message. With Spec Kit, the spec is a file — one that gets committed, reviewed in a pull request, and evolved like any other part of your codebase.

That’s the whole point. The thing you agreed on stops vanishing.

Setting it up (about two minutes)

Spec Kit ships as a small command-line tool called specify. You install it once, then bootstrap any project with it.

1. Install the tool. It runs on Python and is installed with uv (a fast Python package manager):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

(Replace vX.Y.Z with the latest release tag. Pinning a version keeps your setup reproducible.)

2. Initialize a project. Tell it which agent you use:

specify init my-project --integration claude
cd my-project

This drops a .specify/ folder into your project — templates, helper scripts, and a place to keep your project’s rules. From here on, everything happens through slash commands inside your AI agent.

Prerequisites are modest: Python 3.11+, Git, and one supported AI agent. That’s it.

The workflow, command by command

Spec Kit’s core loop is Constitution → Specify → Clarify → Plan → Tasks → Implement, with two optional quality checks along the way. Each command produces a real file you can read and edit. Here’s what each one does, in plain terms.

1. /speckit.constitution — write the house rules, once

Before any feature, you set your project’s non-negotiables: code quality bar, testing standards, performance expectations, UX consistency.

/speckit.constitution Create principles focused on code quality, testing
standards, UX consistency, and performance requirements.

This writes a constitution.md file. Every later step is checked against it — so the agent stops quietly drifting from your standards. Think of it as the rulebook the rest of the work has to obey.

2. /speckit.specify — say what and why, not how

Describe the feature in plain language. No tech stack yet — just the goal and the user experience.

/speckit.specify Build a photo-album app. Albums are grouped by date,
re-orderable by drag-and-drop. Inside an album, photos show as tiles.

The agent drafts a full specification — user stories and requirements — and saves it to a new, dedicated branch and folder (e.g. specs/001-photo-albums/spec.md). This is the document that replaces the chat message. It’s yours to refine.

3. /speckit.clarify — let the agent interview you

This is the step most people skip and later regret. The agent asks you targeted questions about everything you left vague, and records your answers right in the spec.

/speckit.clarify

Catching a missing rule here — as a sentence — is the cheapest bug fix you’ll ever make. Run it before planning.

4. /speckit.plan — now bring the tech stack

Only now do you talk architecture: language, framework, database, constraints.

/speckit.plan Use React Native with a local SQLite store. No cloud uploads.

The agent produces a technical blueprint — and usually supporting files like data-model.md, research.md, and API contracts. This is where you confirm it’s building the thing the right way, before any code exists.

5. /speckit.tasks — break it into reviewable chunks

/speckit.tasks

The plan becomes a tasks.md checklist: small, ordered steps, each with the exact files it touches. Tasks that can run in parallel are flagged, and dependencies are respected (models before services, services before screens). You can read the entire build as a to-do list before a line is written.

6. /speckit.implement — let it build

/speckit.implement

The agent works through the task list in order, checking off each step. Because the spec, plan, and tasks are all written down, it has nothing left to guess — and you can review progress against a plan you already approved.

The two optional power-ups

• /speckit.checklist — generates a quality checklist for your spec. GitHub calls it “unit tests for English”: it checks your requirements for gaps, vagueness, and contradictions before you build.
• /speckit.analyze — run after tasks, before implement. It cross-checks the spec, plan, and tasks against each other and flags anything inconsistent or uncovered.

There’s also /speckit.taskstoissues, which turns your task list into GitHub issues — handy for team tracking.

What you’re left with — and why it matters

After a feature, your repo contains real, committed artifacts:

.specify/memory/constitution.md     ← your project's rules
specs/001-photo-albums/
  ├── spec.md                       ← what & why
  ├── plan.md                       ← how
  └── tasks.md                      ← the steps

This is the difference from plan mode, made concrete. The spec is versioned (it changes through commits and pull requests), shared (your teammate reads the same source of truth you do), and durable (six months later, the next agent — or the next engineer — picks up exactly where you left off).

You’re no longer maintaining software by editing code and hoping the docs keep up. You evolve the spec, and the code follows.

Plan mode vs Spec Kit — pick the right weight

These two aren’t rivals so much as different settings on the same dial.

• Plan mode is SDD-lite — zero setup, perfect for a single change. But the spec is disposable: it lives in the session and vanishes when you close it.
• Spec Kit is the structured, gated version — a constitution, explicit gates, and a file for every phase. More ceremony up front, but the spec becomes a permanent, versioned part of your repo.

Plan modeSpec KitSetupNoneOne-time installThe specA message in the chatA file in your repoSurvives the session?NoYes — committed & versionedShareable with the team?NoYes, via pull requestsBest forA single, quick changeFeatures and systems that must last

The rule of thumb: reach for plan mode when you’re making one change you’ll never revisit. Reach for Spec Kit when the code — and the reasoning behind it — has to live.

Make it your own: Extensions and Presets

Out of the box, Spec Kit gives you the core loop. But two mechanisms let you reshape it for your team — and this is where it gets genuinely powerful.

Extensions add new capabilities. They introduce brand-new commands and phases that don’t ship with the core — think Jira integration, a post-implementation code-review step, or project health diagnostics. You browse and install them from the command line:

specify extension search
specify extension add <extension-name>

Presets change how the existing workflow behaves — without adding new capabilities. They override the templates, commands, and terminology Spec Kit already uses. Real examples from the community catalog: a Security Governance preset that bakes secure-coding and compliance checks into every spec, a Jira preset that makes the “tasks to issues” step create Jira tickets instead of GitHub ones, a Table of Contents preset that adds navigation to long specs — even a Pirate Speak preset that renames specs to “Voyage Manifests” (a fun demo of how deep the customization goes).

specify preset search
specify preset add <preset-name>

The simple way to remember it: extensions teach Spec Kit new tricks; presets change how it does the tricks it already knows.

A concrete extension worth knowing: agent-assign

Here’s the limitation it solves. By default, /speckit.implement runs every task in one flat context — the same generalist AI handles your database models, your UI, and your tests. As a project grows, that one-size-fits-all approach leaves quality on the table.

The community spec-kit-agent-assign extension fixes this. It scans the specialized agents you’ve defined (a backend specialist, a frontend specialist, a test writer) and routes each task to the best-fit one, then runs each in its own focused context. It adds three commands that slot in after /speckit.tasks:

/speckit.agent-assign.assign     → matches each task to the right agent
/speckit.agent-assign.validate   → checks every task has a valid agent
/speckit.agent-assign.execute    → runs each task with its assigned specialist (replaces /speckit.implement)

The author benchmarked it by building the same app twice — once with standard Spec Kit, once with agent-assign — and had three frontier models grade both. The specialized version scored roughly 40% higher overall. The intuition is simple: a focused agent with relevant context does better work than a generalist juggling everything at once.

(Note: extensions and presets are community-built and not audited by GitHub — review the source before installing. agent-assign currently targets Claude Code agent definitions and needs Spec Kit 0.3.0+.)

When to use it (and when not to)

Use Spec Kit when the code has to live: real features, team projects, anything you’ll maintain or hand off. The versioned spec pays for itself the first time someone asks “why does it do that?” and the answer is a file, not a memory.

Skip it for throwaways. A one-off script doesn’t need a constitution. Plan mode, or just a good prompt, is plenty.

The old skill was writing code fast. The new one is being precise about what you want — and then keeping that precision somewhere it won’t disappear. Spec Kit is where you keep it.

Notes: command names use the current /speckit.* prefix (mid-2026); some agents in “skills mode” use a speckit-* form instead. Exact generated files vary slightly by agent and version. Always pin a release tag when installing. Verify against the official docs at github.github.io/spec-kit, as the toolkit is evolving quickly.

Last week I asked an AI agent to “add a password reset flow.” Thirty seconds later I had working code. It just wasn’t my code — it emailed a 6-digit code that never expired, ignored rate limiting, and silently logged the user out everywhere.

Fast, confident, and quietly wrong. That gap — between what I said and what I meant — is the whole story of building software with AI right now. And it has a fix.

The trap of vibe coding

The default way most people use coding agents looks like this:

You type a short prompt. The agent generates a change. You run it, eyeball the result, and it’s almost right. So you go back to the chat, nudge it, run it again, nudge again.

This loop has a name now — vibe coding — and it feels productive because something is always moving.

The problem isn’t speed. It’s that the only record of what you wanted lives in a messy chat history. There’s no contract. The agent is guessing, you’re guessing, and the bugs are the difference between the two guesses.

For a throwaway script, fine. For anything you have to maintain, this is technical debt being created at machine speed.

What Spec-Driven Development actually is

Spec-Driven Development (SDD) flips the order of operations.

Instead of code first, document later, you write a clear specification first — a plain-language description of what to build and why — and let the agent generate the code, tests, and docs from it.

The spec becomes the primary artifact. The code is just its expression in a particular language. Maintaining software stops being “editing code” and becomes “evolving the spec.”

That one shift changes everything downstream. The spec is the source of truth that both you and every AI agent align on before a line of code is written.

The four phases

Good SDD isn’t a free-for-all. It runs as four reviewable steps, each a checkpoint you approve before moving on:

1. Specify — Describe the goal and the user journey in plain language. The agent drafts a detailed spec; you refine it.
2. Plan — Declare the architecture, stack, and constraints. The agent proposes a technical design.
3. Tasks — The agent breaks the work into small, independently testable chunks.
4. Implement — The agent writes each task; each one is small enough to review and validate on its own.

The magic is in the gates. You catch the “code never expires” mistake in the Specify step — as one sentence to edit — instead of in production.

Where it sits next to TDD and BDD

If you’ve written tests-first before, SDD doesn’t replace that. It sits above it.

SDD answers what and why — the intent. BDD checks behavior across the system. TDD locks in correctness at the code level. You still write tests; SDD just gives them something authoritative to be tested against.

Think of the spec as the constitution, and TDD/BDD as the laws that enforce it.

The password reset, done right

Back to my example. Here’s the same feature as a spec instead of a prompt:

• WHEN a user requests a reset, THE SYSTEM SHALL email a single-use link valid for 15 minutes.
• WHEN a link is used or expires, THE SYSTEM SHALL invalidate it immediately.
• WHEN more than 3 requests come from one account in an hour, THE SYSTEM SHALL rate-limit further attempts.
• WHEN a reset completes, THE SYSTEM SHALL invalidate all active sessions.

That’s not code. A non-engineer could read it and catch a missing rule. But it’s precise enough that the agent has nothing left to guess — and the four mistakes from my first attempt are now impossible by definition.

That WHEN… THE SYSTEM SHALL… shape is borrowed from aerospace requirements writing. It turns out jet-engine rigor is exactly what fuzzy AI prompts were missing.

Start where you already are: Claude Code’s plan mode

You don’t need to install anything to feel this. If you use Claude Code, plan mode is SDD’s core idea compressed into one keystroke.

Turn it on and the agent flips to read-only. It can read your files, search the codebase, and ask clarifying questions — but it cannot write to disk, run commands, or change anything. It uses that window to hand you a numbered plan: which files it will touch, in what order, and why.

Then you’re the gate:

• Review it — read the plan like a diff of intent.
• Push back or edit — open it, rewrite the bits that are wrong.
• Approve — only now does the agent execute, step by step, still asking before each real change.

The cost is about 30 seconds of reading. The payoff is that you catch the “wait, why is it touching the auth module?” moment before the file gets touched — not in code review, not in production. For my password reset, plan mode is where I’d have seen “no expiry, no rate limit” while it was still a sentence.

That’s the whole SDD loop in miniature: agree on the intent, then build.

Why plan mode isn’t enough for the long run

Here’s the catch — and it’s the reason the dedicated tools exist.

The plan is disposable. It’s a message in your session, not a managed artifact. Approve it, run it, close the terminal — and the plan is gone. There’s no file to keep.

That breaks down the moment software has to live:

• No version history. You can’t diff how the intent changed between releases.
• No shared source of truth. Your teammates — and the next AI session, or a different agent entirely — don’t inherit that plan. Everyone starts from a blank context again.
• Nothing to evolve. SDD’s core promise is that the spec is the primary artifact you maintain. Plan mode gives you the gate but never the durable spec to manage.

Plan mode is perfect for a single change today. It’s not built to carry a feature’s intent across months, people, and dozens of sessions.

When you need managed specs: Spec Kit & OpenSpec

To make the spec a real, persistent artifact — checked into the repo, versioned, evolved — you move up to a dedicated tool. Two open-source ones lead, and I’ll cover each in its own piece:

• GitHub Spec Kit — a structured, gated take on the four phases. Thorough and agent-agnostic; works with Copilot, Claude Code, Gemini, and more.
• OpenSpec — a lighter, “fluid not rigid” alternative. Each change gets its own folder of spec, design, and tasks, stored in your repo, and it’s built to work on existing codebases, not just greenfield ones.

So think of it as a spectrum: plan mode for the in-the-moment gate, Spec Kit / OpenSpec when the spec needs to outlive the session. Detailed walkthroughs of both tools are coming separately.

Zoom out: this is context engineering

Step back and SDD stops looking like a niche workflow. It’s one piece of the bigger shift happening in how we work with AI.

We’ve moved past prompt engineering — the art of phrasing one clever instruction. The discipline that actually predicts whether an agent succeeds is context engineering: giving the model the right information, in the right form, at the right time. Not how you ask, but what it can see when it answers — memory, files, history, the lot.

A spec is exactly that, for the part that matters most: your intent.

Prompt engineering is how you ask. Context engineering is what the model knows when you ask. A spec is the cleanest, most durable context you can give it.

That reframes the whole piece:

• Vibe coding fails because the context is a messy, disappearing chat.
• Plan mode improves the context — but only for one session.
• Managed specs make the right context permanent — versioned in the repo, identical for every teammate and every agent, so nobody re-explains the intent from scratch.

SDD is context engineering applied to intent. The spec is how you stop re-explaining yourself to the machine.

When to use it — and when not to

SDD is worth the overhead when the software is serious: long-lived, shared across a team, or carrying real consequences if it’s wrong.

For a one-off script or a quick experiment, the chat loop is fine. Don’t write a constitution for a sticky note.

The line is simple: the longer the code has to live, the more the spec earns its keep.

The takeaway

Writing code got cheap. Being precise about what you want is now the rare skill.

So the question isn’t whether AI can write your next feature. It’s whether you can say, clearly enough, what that feature should do.

The real skill shifted from writing the perfect prompt to managing everything the model looks at — and that shift has a name.

The context window is a desk. The craft is deciding what goes on it.

Last time, we left off with a small fleet — agents running many jobs in parallel while you stepped away to do something else.

But anyone who has run one for more than ten minutes knows the deflating part. The agent starts strong. Then it drifts. It forgets a decision it made three steps ago. It confidently invents a function that doesn’t exist. And the longer the task runs, the worse it gets.

The reflex is to blame the model — it’s just not smart enough yet. Almost always, that’s the wrong diagnosis. The culprit isn’t intelligence. It’s context.

The failures have names now

These aren’t random glitches. The field has settled on names for them, and each one points back to the same root cause.

• Context rot — quality quietly decays as a long task fills the window. The agent isn’t getting dumber; its workspace is getting more crowded.
• Lost-in-the-middle — hand a model a long stretch of text and it pays the most attention to the beginning and end, the least to the middle. Bury the key detail in paragraph forty of sixty and it may as well not be there.
• Context poisoning — one hallucination gets read back into the next step, then the next, compounding like a rumor that hardens into “fact.”

Notice what they share. None is a reasoning failure. All three are what-the-model-sees failures. Fix what it sees, and most of them simply stop.

From wording the prompt to managing the view

For a couple of years, the prized skill was prompt engineering — finding exactly the right words to coax a good answer out. And wording does matter.

But here’s the reframe: the model has no memory. On every single call, it sees only what’s in front of it — its context window — and nothing else. Whatever it “knew” a moment ago is gone unless you put it back.

So the skill that moves the needle stopped being how you phrase the question and became how you manage everything the model sees around it. That’s context engineering. Prompt engineering didn’t die — it became a subset. The prompt is now one input among many you design.

Context engineering is putting just enough of the right information in front of the model — and nothing else.

The desk

The cleanest picture: the context window is the model’s desk.

Everything it needs for this step has to fit on that desk. Too little, and it guesses. Too much clutter, and it loses the thread — and pays for every scrap of paper, in money and time. Engineering the context means keeping exactly the right things on the desk, in the most compact form that still works.

And the surprising part: a bigger desk doesn’t fix it.

The obvious move is to give the model more room, and windows have ballooned into the millions of tokens. But stuff a giant window full and performance degrades — slower, pricier, less accurate, lost-in-the-middle and all. More context isn’t better. The right context is. That’s why curation is a real skill, not a storage problem.

Four ways context gets in — two questions

So what actually goes on the desk? It arrives through four channels, easiest to hold as answers to two questions.

How do we bring the right knowledge in?

• Retrieval. Our running example throughout: an AI agent fixing a bug in the checkout flow of a large codebase. It doesn’t read the whole repo — it fetches the few files that touch checkout. Pulling the right pages and leaving the rest on the shelf is retrieval.
• Memory. At the start, you gave it one rule: the payments module sits right next to checkout — leave it alone, it’s out of scope and too risky to touch. Several steps later, that rule only holds if it’s been carried forward onto the desk. Memory is how earlier decisions survive into the present step — because the model won’t remember them on its own.

How do we let it act and bring results back?

• Tool results. The agent runs the test suite and reads the failure back into the window — fresh context it didn’t have a second ago. (This is where tools and MCP, the standard way agents plug into the outside world, come in. I won’t re-explain them here — that’s its own piece: Tools & MCP.)
• Multi-agent handoffs. For a messy side-quest — say, a thousand lines of logs — the agent spins up a subagent, lets it wade through, and takes back only a short summary. The mess stays off the main desk. (If “subagent” is new, that’s the previous rung: Agents 101.)

The one move underneath all four

Lay the four side by side and the same decision repeats: what gets onto the desk, and in what compressed form?

That’s the whole craft. Context engineering isn’t four tricks to memorize — it’s one discipline with four entry points. Retrieval, memory, tool results, handoffs: each is just another place where you choose what the model sees and how tightly you can pack it.

The craft is shipping as tooling

You can tell a principle has matured when people build software whose only job is to enforce it. Context engineering is there.

1. RTK (“Rust Token Killer”) sits between your shell and the agent and squeezes noisy command output — git status, test logs, package-manager chatter — by 60–90% before it reaches the window.
2. Repomix packs an entire codebase into one AI-friendly file, dropping tests and build artifacts so only signal gets in.
3. Gitingest and friends do the same “filter the noise, fit the window” job.

There’s a commercial edge here, not just an accuracy one. Every token on the desk is money and time — a bloated context is a slower, pricier request on every call, so trimming it compounds across thousands of runs. Better answers are the headline; cheaper and faster are the quiet bonus.

(A proper head-to-head on these tools comes later in the series — this is just proof the lever is real.)

Why this points somewhere bigger

Here’s the catch that sets up everything after this. All of this curation — the retrieval, the carried-forward decisions, the summaries — you reassemble it by hand, every session. The window resets, and your careful context evaporates. You build the same desk again tomorrow.

Which raises an obvious question: what if you didn’t? What if the context that matters were written down once, durable — the source everything else is rebuilt from?

That artifact has a name. It’s where we go next — and it’s the moment the spec stops being paperwork and becomes the source code.

This is Post 3 in a series on how AI is changing the way software gets made. Next: the spec as the source of truth.

In the last piece, we landed on a simple line: an agent is only as capable as the tools it can actually reach. A prediction engine with a goal and a loop is still just talking until it can do something — read a file, query a database, send a message, look up an order.

So this piece is about the hands. What a “tool” actually is, how you write one, and what MCP — the standard everyone’s suddenly talking about — really changes. We’ll end with working code, but let’s start with the idea that makes all of it click.

What a tool actually is

A tool is a described capability the agent can choose to call.

That’s it. Not magic, not a plugin in the app-store sense. Under the hood a tool is two ordinary things bolted together:

• A description — a name, a plain-language explanation of what it does and when to use it, and the inputs it expects.
• A function — normal code that actually does the work and returns a result.

Here’s the part that surprises people: the model never runs your code. It can’t. It only emits text. So the loop works like a relay:

1. The agent decides it needs a tool and produces a structured request — “call get_order_status with orderId: 8842".
2. Your program sees that request and runs the real function.
3. You hand the result back into the conversation.
4. The agent reads the result and continues its loop.

The model proposes; your code disposes. Hold onto that — it matters for everything below.

The shift: HTTP binds by address, agents bind by intent

If you’ve built anything on the web, you already know the old model. You call a URL.

GET https://api.shop.com/v1/orders/8842

A URL is an address. It points at one exact place, and to use it you have to know that place in advance — the precise path, the method, the parameter names. A developer wires that call by hand, at coding time. Get one character wrong and it breaks. The binding between “what I want” and “what I call” is literal, fixed, and brittle.

In code, that wiring looks like this:

// The developer decides — at code time — exactly what to call.
async function getOrder(orderId) {
  const res = await fetch(
    `https://api.shop.com/v1/orders/${encodeURIComponent(orderId)}`
  );
  return res.json();
}

// Nothing "chooses" this for you. You name the endpoint, by hand.
const order = await getOrder("8842");

A human looked at the need (“I want this order’s status”) and hard-coded the mapping to one exact address. The computer never decides which call fits the situation — that decision was already made, in advance, by the person who wrote the line.

And on the other end — the server — that address is bound to a function just as literally. This is how a URL gets “linked” to the code that runs it:

// Express: the URL path is mapped to exactly one handler.
app.get("/v1/orders/:id", async (req, res) => {
  const data = await getOrderById(req.params.id);
  res.json(data);
});

The string "/v1/orders/:id" is the link. The router does a dumb, literal match: this exact path → this exact function. Spell the path differently and the request misses entirely. Nothing reads the meaning of the request; it only matches the address.

Keep that snippet in mind — because the tool we write later links to its function a completely different way. Same job (request reaches the right code), opposite mechanism: a path does the linking in HTTP, a description does it for a tool.

An agent doesn’t get an address. It gets a menu — a list of tools, each with a plain-language description of what it’s for. Then it does something a URL never could: it reads your actual request, works out the intent, and picks the tool whose description best matches.

You say “any update on order 8842?” Nobody told the agent to call get_order_status. It chose that tool because the description said "use this when the user asks where their order is," and that matched what you meant.

HTTP routes by address. Agents route by intent. The description is the new endpoint.

This flips where the important work lives. On the web, the contract is the URL and the data shape. With tools, the contract is the description — because that sentence is what the model reads to decide whether your tool is the right one. A vague description is a broken API, even if the code is perfect.

One honest clarification, so nobody emails me: MCP often travels over HTTP on the wire. The contrast isn’t HTTP-the-protocol versus MCP. It’s about who decides what to call, and how — a developer matching an exact address at code time, versus a model matching an intent to a description at run time.

Side by side:

HTTP / RESTMCP / agent toolsYou call it byAn exact address (URL + path)A plain-language description (intent)Who picks which to callPre-wired by the developer; the framework (Spring, Servlets, Express…) dispatches by literal path matchThe model, at run time, by matching intentThe link to the codeA route string — /v1/orders/:idThe tool's descriptionHow it's matchedLiteral: path matches or it doesn'tSemantic: by meaningInputs defined byPath / query / body paramsA typed input schema (JSON Schema / Zod)DiscoveryRead the API docs yourselfAgent asks the server "what can you do?"Reuse across appsEach client wires its own callsWrite once; any MCP host can use itWhen it driftsWrong path → 404Vague description → tool ignored or misused

The row that matters most is the first one. Everything else follows from address versus intent.

How a tool is written

Let’s make it concrete. A tool has two parts: the description the model sees, and the function your code runs.

First, the description — this is what’s handed to the model. (This shape is the function-calling format used by the major model APIs.)

{
  "name": "get_order_status",
  "description": "Get the current status of a customer's order. Use this when the user asks where their order is or what's happening with an order.",
  "input_schema": {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "description": "Order ID, e.g. '8842'"
      }
    },
    "required": ["orderId"]
  }
}

Notice there’s no logic here at all — just meaning. The description field is the intent contract. The input_schema tells the model exactly what to fill in.

Now the function that actually runs when the model asks for it:

async function getOrderStatus({ orderId }) {
  const res = await fetch(
    `https://api.shop.com/v1/orders/${encodeURIComponent(orderId)}`
  );
  const data = await res.json();
  return `${data.status}, ETA ${data.eta}`;
}

Look closely and you’ll see both worlds in one place. The agent reached this function by intent. But the function itself reaches the orders service by address — a plain HTTP call. That’s the relationship in a nutshell: intent on the outside, exact addresses on the inside. The tool is the translator between the two.

And the round trip, end to end:

1. You ask: “Where’s my order 8842?”
2. The model replies not with prose but with a request: use get_order_status, orderId = "8842".
3. Your loop catches that, runs getOrderStatus, gets back "Shipped, ETA Tuesday".
4. You feed that string back into the conversation.
5. The model turns it into: “Order 8842 has shipped and should arrive Tuesday.”

The model supplied the judgement; your function supplied the fact.

How the agent wires it all together

We’ve written a tool. But how does the agent actually receive it, decide to use it, and act on the result? That’s the loop from the last piece — here it is in code, with the model’s API doing the talking (TypeScript, using Anthropic’s SDK as the example):

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// 1. The menu — every tool's description (its intent) handed to the model.
const tools = [
  {
    name: "get_order_status",
    description:
      "Get the current status of a customer's order. Use when the user asks where their order is.",
    input_schema: {
      type: "object",
      properties: {
        orderId: { type: "string", description: "Order ID, e.g. '8842'" },
      },
      required: ["orderId"],
    },
  },
];

// 2. The matching real functions, keyed by tool name.
const executors = {
  get_order_status: async ({ orderId }) => {
    const res = await fetch(`https://api.shop.com/v1/orders/${orderId}`);
    const data = await res.json();
    return `${data.status}, ETA ${data.eta}`;
  },
};

async function runAgent(userMessage) {
  const messages = [{ role: "user", content: userMessage }];

  // 3. The loop — keep going until the model stops asking for tools.
  while (true) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 1024,
      tools,            // the menu goes in on every turn
      messages,
    });

    // Model answered in plain text — the goal is met, we're done.
    if (response.stop_reason !== "tool_use") {
      return response.content.find((b) => b.type === "text")?.text;
    }

    // 4. The model asked to use a tool. Run it — YOUR code, not the model's.
    messages.push({ role: "assistant", content: response.content });

    const toolResults = [];
    for (const block of response.content) {
      if (block.type !== "tool_use") continue;
      const run = executors[block.name];
      const result = await run(block.input);
      toolResults.push({
        type: "tool_result",
        tool_use_id: block.id,
        content: result,
      });
    }

    // 5. Hand the results back; the loop runs again with them in context.
    messages.push({ role: "user", content: toolResults });
  }
}

await runAgent("Where's my order 8842?");

That’s the entire mechanism, and it’s the relay from earlier made literal:

• The menu (tools) is sent on every turn — that's how the model knows what it could call.
• When the model wants one, it doesn’t run anything; it returns a tool_use block, and the loop stops to act.
• Your code looks up the function, runs it, and packages the answer as a tool_result.
• The result goes back in as the next message, and the model continues — often turning a raw "Shipped, ETA Tuesday" into a friendly reply, or deciding it now needs a different tool.

Two things are worth staring at. First, the loop is dumb on purpose — it just shuttles requests and results back and forth; all the judgement lives in the model. Second, notice the two pieces you hand-maintain: the tools menu and the executors map. Keep those in mind — because automating exactly that wiring is the whole reason MCP exists.

Enter MCP — and the problem it solves

So far so good for one app. Now multiply it.

Every team that wanted to give an agent tools used to wire them up its own way. Your order-lookup tool for your assistant didn’t work in my code editor’s agent, which didn’t work in someone’s chat app. Ten tools across five different agents meant fifty bespoke integrations. The classic M×N mess.

MCP — the Model Context Protocol — is the standard that turns M×N into M+N. The usual one-liner is “USB-C for AI”: agree on one connector, and anything plugs into anything.

The shape is simple:

• An MCP server exposes your tools (your order-lookup tool, your database tool, your file tools).
• An MCP host — the agent app — connects to that server.
• On connecting, the host asks, “what can you do?” and the server returns its list of described tools.
• From then on, the agent picks among them by intent, exactly as before — except now those tools are reusable by any MCP-compatible agent, not just yours.

In loop terms: the tools menu is now fetched from the server instead of hand-written, and the executors live inside the server. The two pieces you were maintaining by hand both move behind a standard interface — so any agent can borrow them.

Write the tool once; every agent that speaks MCP can use it. That’s the whole pitch, and it’s why MCP spread so fast.

Writing the same tool as an MCP server

Here’s the order-lookup tool again — this time as a proper MCP server, so any agent can reach it. With the official TypeScript SDK:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "orders", version: "1.0.0" });

server.registerTool(
  "get_order_status",
  {
    description:
      "Get the current status of a customer's order. Use when the user asks where their order is.",
    inputSchema: { orderId: z.string().describe("Order ID, e.g. '8842'") },
  },
  async ({ orderId }) => {
    const data = await fetchOrder(orderId);
    return { content: [{ type: "text", text: `${data.status}, ETA ${data.eta}` }] };
  }
);

Look at what’s doing the work. The description is the same intent contract from before — the sentence the model reads to decide whether this tool fits. The inputSchema (a Zod schema) declares the inputs it must fill in. The handler does the real work and returns the result. Same anatomy as the raw tool earlier — a name, a description, typed inputs, a function — now wrapped so any MCP-compatible agent can discover and call it.

Now put this beside that Express route from earlier. There, the link was a literal path — app.get("/v1/orders/:id", handler). Here, there is no path at all. The handler is linked by its description — "Get the current status of a customer's order…" — and the model matches your request to it by meaning. Same shape (something → a handler), but the "something" changed from an address you must know to an intent the model infers.

Different language, identical anatomy: a name, a description carrying the intent, a typed input schema, and a handler that does the real work and returns a result. MCP didn’t change what a tool is. It standardised how a tool is offered, so it stops being trapped inside one app.

Why this matters — and what’s next

Pull it together:

• A tool is a described capability plus a function — the agent’s hands.
• Agents bind to tools by intent, not by address, so the description is the real interface.
• MCP standardises that offer, so a tool written once works across every agent that speaks the protocol.

But there’s a catch sitting in plain sight, and it’s the thread that runs through this whole series. Every tool result — every order status, every query row, every file you hand back — lands right back in the agent’s finite working memory. Give an agent twenty tools and let it run a long loop, and that desk fills up fast.

Which is exactly the problem the next piece is about: when the model can reach everything, the hard part is no longer access. It’s deciding what deserves a place in the window at all. That’s context engineering — and it’s where this series has been heading all along.

Have you written a tool or an MCP server yet? I’d love to hear what you plugged into your agent — and where it surprised you.

Have you written a tool or an MCP server yet? I’d love to hear what you plugged into your agent — and where it surprised you.

It isn’t a smarter chatbot. It’s the same forgetful prediction engine — handed a goal, a loop, and a set of tools.

Ask a chatbot a question and it answers, then stops. Then you watch a coding “agent” open a file, run the tests, read the errors, fix the code, and run the tests again — on its own, until it works.

Same underlying AI. Completely different behaviour. The gap isn’t intelligence. It’s structure — and once you see the structure, the whole “agent” buzzword stops being mysterious.

First, what’s actually underneath

Before “agent” makes sense, you need to know what the model at the centre really does.

A large language model isn’t a database you look things up in, and it isn’t a brain that knows facts. It does one humble thing: it predicts the next chunk of text, again and again, choosing the most likely continuation of what came before.

It learned those patterns from a huge amount of writing. So it absorbed how language tends to go — not a clean file of facts.

That one mechanism explains its talents and its failures at once. The engine that writes a fluent paragraph can also state something false with total confidence. Creativity and hallucination come from the same place.

Two limits matter most. Keep them in your back pocket:

• No memory between calls. Every request starts blank. When a chat app seems to remember your earlier messages, it’s quietly re-sending the whole history each time.
• A finite working memory. Everything it can weigh at once — your request, the conversation, whatever it’s looking at — must fit in a fixed space called the context window. Too little and it’s clueless; too much and the important part drowns in noise.

A forgetful engine, working on a small desk. Hold that picture.

From answering to acting

A plain chatbot takes your message and gives one reply. That’s the entire transaction.

An agent is built around something larger: a goal. Instead of replying once, it keeps working until the goal is met. To pull that off, it needs three ingredients.

• A goal — the outcome it’s aiming for. “Fix the failing test,” not “tell me about the failing test.”
• A loop — it doesn’t answer once; it cycles: think, act, look at the result, decide what’s next, repeat.
• Tools — ways to actually do things instead of just talking: read a file, run a command, search the web, call a service.

A chatbot holds a conversation. An agent works through a checklist.

That’s the shift in a single line. Everything else is detail.

The loop, made concrete

Say the goal is “find and fix a broken link on my website.” The agent doesn’t answer in one breath. It moves in steps:

1. Plan — work out what “broken link” means and how to check.
2. Act — run a tool that scans the pages.
3. Observe — read what came back: one link returns a 404.
4. Decide — find that link in the source and correct it.
5. Check — scan again to confirm nothing’s broken.
6. Stop — goal met, so it ends.

Step 3 is the interesting one. Observing — reacting to real results instead of guessing — is where an agent earns its keep, and also where it goes wrong. Misread a result and the whole loop heads down the wrong road.

Why the window is the real ceiling

Now those two limits come due.

Every pass through the loop piles more onto that small desk: the original plan, the output of each tool, the growing record of what it has already tried. On a short task, no problem. On a long one, the desk fills up.

When it does, the agent slips. It forgets a decision from twenty steps ago. It drifts from the goal. It repeats work it already finished.

None of this is the model getting “dumber.” It’s the working memory overflowing, and older context getting crowded out. Deciding what deserves a place on that crowded desk turns out to be the core skill of working with these systems. It has a name — context engineering — and it’s a story for the next piece.

What an agent is not

A few myths cause most of the confusion:

• Not conscious. No intentions, no understanding. A prediction loop with a goal bolted on.
• Not infallible. It can take a confident, completely wrong step — then build on it.
• Not meant to run unwatched. Good setups keep humans at the checkpoints that matter, especially before anything irreversible.

Picture a tireless junior worker: fast, capable, occasionally confidently wrong, and in need of review. That gets you far closer than “genius” or “toy.”

Where this leaves us

An agent is less exotic than the word suggests. A prediction engine, pointed at a goal, running in a loop, reaching for tools — and boxed in by a forgetful, finite memory.

Which raises the obvious next question: an agent is only as good as the tools it can actually reach. So how do you hand it those tools — and is there a standard way to do it?

That’s where we go next. If you’ve worked with an AI agent that surprised you — for better or worse — I’d love to hear what it did.