Spec-Driven Development for AI Projects

AI makes it much easier to produce code quickly. It also makes it much easier to produce the wrong code quickly. That is the central reason spec-driven development matters more in AI-assisted projects, not less.

When a human team writes software without a clear specification, the result is usually drift over time. When an AI assistant writes software without a clear specification, that drift can happen in a single afternoon. The code may compile. The UI may look polished. The tests may even pass if they were written against the wrong assumptions. But the product can still move away from its real purpose.

Why AI changes the risk profile

Traditional software development already had interpretation gaps between product intent, design, implementation, and documentation. AI compresses that timeline. A single prompt can generate architecture, copy, validation rules, naming, and interface patterns all at once.

That speed is useful. It is also dangerous when the source of truth is vague.

In practice, AI tends to optimize for what is most visible in the moment:

• the latest prompt
• the nearest file
• the easiest implementation path
• the most common pattern in its training distribution

None of those automatically equal the correct product decision.

What a spec does in an AI-assisted workflow

A strong product spec does at least four jobs.

First, it defines purpose. The team can tell whether a feature supports the actual product or simply adds output.

Second, it defines boundaries. It clarifies what is in scope, what is out of scope, what is optional, and what must work even when optional systems fail.

Third, it defines the review standard. Instead of asking only whether a change works technically, reviewers can ask whether it matches the intended workflow and product commitments.

Fourth, it acts as memory. AI systems do not hold stable institutional memory on their own. A repository specification does.

This is especially visible in Let Books. The project specification in AGENTS.md repeatedly makes two things clear:

• the manual workflow must remain useful without paid AI services
• physical book copies and bibliographic records must stay separate concepts

Those are not implementation details. They are product boundaries. If an AI assistant generates a flow that blocks manual entry or collapses physical-copy data into edition metadata, the issue is not style. The issue is product drift.

Why documentation cannot wait until later

In many projects, documentation is treated as a delayed clean-up task. That becomes much more expensive when AI is part of delivery.

Without current documentation:

• prompts become inconsistent
• review becomes subjective
• demos start to redefine the product by accident
• future contributors inherit behavior without knowing whether it was intentional

That is why documentation should be treated as an operating asset. In this repository, README.md describes the current public state, AGENTS.md defines product intent, AGENTS-Implementation.md defines tactical guidance, and the docs area defines publishing and evidence rules. That layered structure is not overhead. It is how the project keeps meaning attached to the output.

The role of demos

Demos are useful. They show what exists, reveal usability issues, and help institutions or collaborators react to something concrete. But a demo should not silently become the product specification.

The repository already draws that distinction in its documentation rules. Public writing should treat specs and docs as canonical evidence, while implemented demo behavior can be mentioned as implementation status. That is a healthy rule because it prevents accidental governance by prototype.

If a demo reveals a better workflow, the answer is not to let the demo quietly win. The answer is to update the spec, the docs, and the review standard so the better workflow becomes intentional.

Markdown, tests, and CI are not separate concerns

One common mistake is to treat written specs, technical validation, and CI/CD as unrelated layers.

In a spec-driven workflow, they are one chain.

• Markdown stores intent in reviewable form.
• Documentation explains how the intent should be interpreted.
• Tests check executable expectations.
• Validation rules catch structural drift.
• CI enforces the rules repeatedly.

Each layer is incomplete on its own. Together they create product memory that survives speed, iteration, and team changes.

What this means for teams using AI

Teams that use AI effectively do not remove process. They move process closer to the source of generation.

That usually means:

• writing clearer product specs before asking for implementation
• keeping implementation guidance explicit
• updating docs when product behavior changes
• checking demos against specs instead of assuming parity
• adding validation rules gradually so consistency does not depend only on human memory

This is not anti-AI. It is how AI becomes dependable.

The durable lesson

AI can generate code, content, and interfaces quickly. It cannot by itself guarantee that all of those outputs still describe the same product.

Spec-driven development is how a team keeps speed from turning into drift.

In AI-assisted projects, the spec is not paperwork after the fact. It is the boundary, the memory, and the review standard that make fast delivery trustworthy.

Related Reading

• ../../wiki/spec-driven-development.md
• ../../wiki/validation-layers.md
• ai-as-an-oracle.md
• responsibility-after-intelligence.md
• spec-driven-development-in-let-books.md