From Prompts to Project Memory: Spec-Driven Development for Coding Agents

Here, spec-driven names a repository practice in which specifications own product requirements within a broader authority-by-concern system. It does not make a specification universally authoritative: constitutions preserve project-wide constraints, ADRs preserve rationale, plans and tasks preserve approach and execution state, code shows implementation, and tests show what was checked.

Version control gives consequential decisions an address a later agent can recover. It does not make those decisions correct or current. The agent still has to find the relevant records, interpret them against the task, inspect the implementation, and verify the resulting behavior.

The Claim Came Back

A sentence on my homepage once claimed:

“15+ years of experience designing scalable web architectures, design systems, and enterprise platforms.”

It sounded credible. It was also broader than the evidence I had established.

What I could support was substantial experience with reusable UI components, component architecture, frontend patterns and systems, UI architecture, and engineering standards. Formal design-system ownership was different, and the repository did not establish it.

I treat that mistake as a context-persistence failure. A distinction we had already made did not survive into a later piece of generated copy.

Correcting the sentence fixed the page. Recording the constraint in the repository gave the same mistake a durable address a later agent could recover before repeating it.

That second fix is the subject of this article.

Conversation Context Is Not Project Memory

Conversation remains useful for the work in front of us: goals, tradeoffs, corrections, and discoveries.

The problem is that a later session, agent, or tool cannot be assumed to inherit all of it. A new session may see the repository without the discussion that produced its current decisions.

In this repository, the durable substrate is version-controlled project memory: a small set of artifacts that record constraints, requirements, implementation intent, execution state, and decision rationale at different scopes.

Code and tests are adjacent implementation and verification evidence. They are durable and necessary to inspect, but they are not interchangeable with records of intent.

This does not make an agent correct. It gives the next agent something more stable than recollection to inspect, challenge, and follow.

A project should not depend on one conversation remaining available forever.

What Became Durable

The wording incident eventually produced two durable guardrails at different scopes.

The project constitution now says not to describe my professional experience as design systems unless that experience is explicitly established. It gives grounded alternatives such as reusable UI components, component architecture, frontend patterns and systems, UI architecture, and engineering standards.

The site-foundation specification carries the same positioning constraint inside the requirements for the site itself.

That duplication is deliberate because the artifacts answer different questions.

The constitution establishes a project-wide invariant. The site specification narrows that invariant into the requirements of this product.

The important change is not that a correction exists somewhere in the repository. It is that the correction now has an address that later work can recover.

A Small Authority Model for Project Memory and Evidence

Project memory records and implementation evidence are related but not interchangeable. Each answers a different question.

Constitution — What must remain true across the project?

Feature specification — What behavior or outcome is required in this scope?

Plan — How does the repository intend to implement that requirement?

Tasks — What work remains or has been completed in the current execution sequence?

ADR / decision record — Why was a consequential product or architectural choice made?

Code and tests (adjacent evidence) — What has been implemented, and what behavior has been checked?

The first five preserve intent, requirements, rationale, constraints, or execution state. Code and tests provide adjacent implementation and verification evidence; selecting them does not turn them into records of intent.

That separation matters when sources disagree. Durability alone does not make an artifact authoritative for every concern.

A requirement can outlive a particular implementation strategy. Code can reveal that an old plan was never completed. A decision record can preserve useful reasoning while its operational details become stale. When artifacts diverge, the conflict has to be exposed rather than silently flattened into one story.

The Agent Entry Point: Route, Then Narrow

AGENTS.md stays deliberately thin. Its job is to route an agent into the repository’s existing memory:

1. Read the constitution.
2. Consult the relevant feature specification.
3. Review the plan and tasks.
4. Consult ADRs before structural changes.
5. Never fabricate content.
6. Update durable specs when requirements change.

It is a routing layer, not a mega-prompt.

Routing can bring both project memory and adjacent implementation evidence into the task. Selecting code or tests does not turn them into records of intent; it makes comparison possible.

The point is not to load every artifact into every task. Start with the records and implementation surfaces the task makes relevant; follow their references and disagreements when that first selection is not enough. The aim is a bounded, inspectable selection—not a claim that the repository can identify a uniquely minimal context.

A positioning change begins with project-wide factual guardrails and the site-foundation specification. A publication change narrows into the publication-gating specification and its related decisions. Only then does the agent need the implementation surfaces that realize those requirements.

Today, that routing is mostly explicit and human-authored. The repository does not contain an automated relevance engine.

This is context selection rather than context accumulation.

Worked Example: Publication Gating

Publication gating makes the pattern more concrete because the same concern exists at several layers.

The feature specification says new Research and Project entries must fail closed until deliberately published. The content schema implements part of that rule directly:

published: z.boolean().default(false)

The specification then defines what unpublished state means across public listings, detail pages, indexing, RSS, and local preview behavior. The publication-gating decision record preserves why publication state is separate from lifecycle status.

Those are different forms of evidence.

The specification establishes intended behavior. The schema establishes one implementation default. The route and feed implementations expose additional implementation surfaces. The figure samples that chain; it does not certify every publication-gating acceptance criterion.

That distinction prevents repository memory from becoming self-validating documentation. A requirement is not proof that the implementation satisfies it.

When the Requirement Changes

Durable memory only helps if the records that own a requirement change when the requirement changes.

The historical account for publication gating is that unpublished collection cards moved from non-clickable summaries to inline status interactions. The current branch records the resulting behavior across the feature specification, the publication-gating decision, the URL/SEO policy, and maintainer guidance in the README.

The current branch shows that these artifacts now describe the same interaction model. It does not, by itself, establish that every record changed in one atomic step.

The maintenance rule is a coordinated workflow across owning artifacts: update the durable records that own the changed requirement and rationale with the implementation, then verify what the implementation actually does. A specification is authoritative for the requirement within its concern, not a passing test; code shows what exists, but does not preserve every reason behind a choice.

Durable Memory Can Drift Too

Version control preserves a record. It does not keep that record aligned with the system it describes.

The deployment documentation in this repository provides a useful example.

ADR 003 records an explicit manual publishing model centered on npm run live from main, and it says no repository-authored GitHub Actions workflow is required for that model.

Current AGENTS.md, however, documents three supported production paths: local npm run live, a GitHub Actions workflow, and a remote trigger branch. The repository now contains the workflow that the earlier ADR said was unnecessary.

The important point is not which document should win automatically. The important point is that durable memory can preserve an earlier account after the operating model has changed.

That inconsistency is inspectable because both artifacts survive. It still requires someone to reconcile them.

Project memory therefore has a lifecycle: create it, scope it, consult it, update it, and retire or amend it when the system changes.

When a durable requirement changes, the artifact that owns that requirement should change with the implementation.

What This Does Not Solve

Version-controlled memory still has failure modes:

• Wrong specs stay wrong. Durability does not make an assumption true.
• Specs and ADRs can become stale. The deployment example above is evidence of that maintenance problem.
• Agents can misread explicit context. Documentation reduces ambiguity; it does not eliminate interpretation errors.
• Documentation can become noise. Overlapping or redundant artifacts make retrieval harder and can disagree.
• Specifications do not replace tests. Requirements and passing behavior are different evidence.
• Implementation evidence can be incomplete. Code shows what exists on inspected paths; tests show only what was checked.
• Implementation does not explain every decision. Code can show what exists without preserving why a choice was made.
• Human judgment remains necessary. Engineers still decide what becomes durable, which artifact owns a concern, and how conflicts are resolved.

The practical gain is narrower than determinism: consequential decisions have an address that later work can inspect. That creates an opportunity to catch a repeated mistake; it does not establish that the mistake will be caught or become less frequent.

The Next Problem Is Relevance

Once a project can remember, the next question is not how to accumulate more context.

It is how to select the context relevant to the task without hiding conflicts or overwhelming the agent.

An unpublished Repository Context Engine for Coding Agents concept explores that direction: task-aware selection of relevant specs, decisions, and repository patterns, plus explicit context delivery through MCP or another mechanism.

That is proposed work, not an implemented system.

For now, this repository supports a smaller conclusion: project memory becomes useful when it is scoped, inspectable, connected to implementation, and maintained as the system changes.