Prompt & Spec Libraries

Two engineers on the same platform team, three weeks apart, sit down to do the same kind of work: stand up a new internal CRUD service behind the company gateway. Neither knows the other has done it recently. Each writes a spec from scratch. Each rediscovers, independently, that the gateway silently drops idempotency keys longer than sixty-four characters, that the team’s pagination convention wants a cursor and not an offset, and that “add authentication” actually means three different things depending on whether the caller is a service, a browser session, or a batch job. Both specs end up good — eventually — after the same afternoon of poking at the same undocumented gateway behavior the other engineer already poked at, three weeks earlier, in a spec nobody else ever read.

Nothing about this is exotic. It is the ordinary condition of most engineering organizations doing AI-assisted work in 2026: every well-specified session produces an artifact worth more than the code it generated, and that artifact is thrown away the moment the pull request merges. This volume’s earlier chapters treated the spec and the constitution as durable within a single project — worth writing carefully, worth keeping alive, worth reviewing. This chapter asks the question those chapters left open: what happens to a good spec once the project it was written for is done? For almost every team today, the honest answer is nothing. It sits in a closed pull request or a deleted worktree, exactly as invisible to the next engineer as an unrecorded decision was to the reader in Volume I.

What the industry already ships

The tooling layer has started to notice the problem, even where organizational practice has not caught up. GitHub ships reusable prompt files as a first-class Copilot feature — Markdown templates saved under a repository’s `.github/prompts` directory and invoked on demand for tasks like scaffolding a component or running a migration, distinct from the standing instructions that load into every request. Anthropic’s Agent Skills give the same idea more structure: filesystem-based bundles of instructions, scripts, and resources that Claude loads on demand, published as an open standard explicitly so that, in Anthropic’s framing, “anyone can now specialize their agents with composable capabilities by capturing and sharing their procedural knowledge.” DORA’s platform-engineering research describes the adjacent, older pattern at the infrastructure layer: “golden paths,” self-service templates for an organization’s most common workflows, built once by a platform team and reused by everyone else.

What these three examples share is the shape of the solution and the location of the gap. Each gives a team a place to put something reusable and a mechanism to retrieve it. None of them — not the GitHub docs, not Anthropic’s own announcement, not DORA’s platform-engineering material — says anything about who decides a prompt file or a skill is good enough to keep, what happens when the codebase moves out from under it, or who is accountable when it quietly starts giving wrong advice. The industry has solved storage and retrieval. It has not touched curation. That is the gap a spec library and a prompt library have to close by organizational practice, because no tool is going to close it by default.

Intent as a reusable asset class

Treat a well-refined spec the way an engineering organization already treats a well-written internal library: as intellectual property worth the overhead of maintaining, because the alternative is paying the same discovery cost every time the underlying problem recurs. A spec library, in this sense, is a curated collection of vetted templates for recurring categories of work — onboarding a new service, adding a standard CRUD endpoint, running a security-review pass — each one already encoding the constraints and edge cases a team learned the hard way once, so the next engineer doesn’t have to relearn them at the gateway’s expense. A prompt library serves the identical function at a smaller grain, for well-defined recurring subtasks that don’t justify the ceremony of a full spec: “write a database migration with a reversible down-step,” “summarize a flaky test’s failure history before filing an issue.” Different scale, same argument — the reuse pays for the curation cost only if the pattern actually recurs and the artifact has actually been proven.

Earning a place in the library

Most specs and prompts should stay one-off. The temptation, once a team has a place to put reusable things, is to put everything there — every spec a developer is even slightly proud of becomes a “template.” This is the same mistake software engineering has made with code reuse for decades, and the field has a durable rule of thumb for resisting it. The “rule of three” — first observed in reuse literature and popularized for a general engineering audience by Jeff Atwood — holds two things at once: building something genuinely reusable is roughly an order of magnitude harder than building it for one use, and a component isn’t provably general until it has been exercised successfully in three different real applications, not just imagined to be general by whoever first wrote it. A spec or prompt is under exactly the same obligation. The one written for last Tuesday’s task is a hypothesis about generality, not evidence of it.

Two conditions have to hold before an entry earns a place in the library, and both are checkable rather than a matter of taste. Genuine recurrence: the category of work comes up often enough, across enough engineers or enough projects, that the ongoing cost of curating and maintaining the entry is smaller than the discovery cost it would otherwise repeat. Genuine refinement: the artifact has been used successfully more than once and had its rough edges worked out in the field, not merely drafted with good intentions. A spec that has only ever produced the one pull request it was written for has not been refined; it has been written. Refinement is a claim about track record, and track record requires more than one data point.

Reviewing specs the way we review code

Software engineering has a decades-old answer to the general problem of “someone wants to add something to a shared resource everyone else will depend on”: review it before it merges, by someone other than the author. Nobody accepts a pull request to a shared internal library on the strength of the author’s say-so that it works; a second engineer reads it, checks it against the library’s existing conventions, and looks for the failure modes the author was too close to the problem to see. A spec or prompt entering a shared library deserves exactly that scrutiny, and for exactly the same reason: once it is in the library, engineers who were not in the room when it was written will trust it by default.

A spec review, concretely, asks three questions a code review already knows how to ask about a utility function. Does it encode a constraint incorrectly — a security assumption that was true of the original service but isn’t universal, a rate limit copied from one vendor and silently applied to all of them? Does it conflict with the project’s constitution — the standing principles Chapter 4 described, which a spec written in isolation has no visibility into and may unknowingly override? And is it actually general, or was it accidentally over-fit to the one task that produced it — the classic reuse failure, dressed up as a template because nobody stress-tested it against a second case before publishing it. None of these questions require new tooling. They require deciding that a spec entering a shared library is a change to shared infrastructure, not a personal note somebody happened to check in.

The library entry that has never been used twice is not a template. It is a draft with a permanent address.

This also explains why a spec library entry is not really a new kind of artifact — it is Decision Memory operating one level up. An individual decision record answers “why did we do X, here, in this session.” A vetted spec-library entry answers the more durable question, “here is the currently correct way to do X, in general” — and it should be exactly as supersedable as any single decision. The right way to add a CRUD endpoint changes as the gateway changes, as the auth model changes, as the team learns a new failure mode the hard way. A library entry that can’t be superseded isn’t stable; it’s ossified, quietly wrong, and still being handed to every engineer who trusts the library’s cover more than its contents.

The library nobody weeds

The honest caveat is the same one this volume has already applied to the constitution: a standing artifact decays without an owner and a pruning discipline, and a spec library is no exception. Notably, even the vendors building the storage layer for this haven’t solved the maintenance layer either — Anthropic’s own announcement of Agent Skills describes capturing and sharing procedural knowledge at length and says essentially nothing about how a team is supposed to detect that a skill has gone stale, version it, or retire it. That gap is not a criticism of the tooling; it is a reminder that curation was never going to be something a platform ships for a team automatically.

A library nobody weeds becomes a library nobody trusts, and that is the mild failure mode. The severe one is worse: an unmaintained collection of “reusable” specs, some of them quietly describing a gateway behavior that changed eighteen months ago, looks exactly as authoritative as a well-maintained one to the engineer — or the agent — pulling from it in good faith. A spec library with no owner and no expiration doesn’t fail by going empty. It fails by staying full of confident, plausible, wrong answers, which is a strictly worse state than having no library at all, because nothing about it signals that it needs to be checked.