Spec-Driven Development (SDD) & Lore — Stopping AI Code Drift

You ask an LLM to build a new feature in a large codebase. It writes clean code, passes the immediate requirements, and everything looks great—until you realize it silently broke an unrelated feature built two weeks ago 🤦‍♂️

As AI tools like OpenCode, Codex, and Claude Code become integral parts of our daily developer workflows, we are encountering a new class of engineering challenges. One of the most frustrating is AI code drift.

The Problem: AI Code Drift

As codebases grow over months and are developed across different AI coding tools, LLMs lack persistent, long-term context about design intent. When you feed a prompt into an AI model, it inspects the current state of the code, but it doesn’t know why a particular abstraction was created, what invariants must be preserved, or which edge cases were solved in previous iterations.

When multiple AI tools or models touch a large codebase over an extended period, each prompt runs in isolation without memory of past trade-offs. Without this design context, running AI across 20 iterations inevitably leads to unintended design shifts, architectural erosion, and subtle regressions.

Feature-Driven Development vs. Test-Driven Development

To understand where Spec-Driven Development fits, let’s briefly compare how software is traditionally built:

Feature-First Development (Code-First)

In traditional or feature-first development, developers write the feature code first. Tests are written afterwards—if at all.

While fast for prototyping, test-after development provides weak guardrails for AI agents. An LLM editing code might modify logic without updating or even running existing test suites unless explicitly instructed.

Test-Driven Development (TDD)

In TDD, developers write failing unit or integration tests before writing implementation logic. TDD enforces tight feedback loops and functional correctness.

However, the problem with TDD in an AI-first workflow is that all test cases might pass while the LLM still decides to change architecture and alter core design choices.

Architecture and design choices are extremely critical for large-scale, production applications handling heavy usage. A feature built by an LLM that passes every unit test might work seamlessly for 1,000 users, but completely break down when scaled to 10,000 users. That failure comes down to architectural choices and design decisions that unit tests simply cannot enforce.

What is Spec-Driven Development (SDD)?

Spec-Driven Development (SDD) is an AI-first development paradigm where every major feature, refactor, or architectural change begins with a Markdown specification file stored directly in the repository under a spec/ folder.

spec/
├── 1770000000-init.md
└── 1770034800-add-vector-similarity-search.md

Key Principles of SDD:

1. Repo-Native & Permanent: Specs live alongside the code in Git. They travel through clones, forks, and branches.
2. Chronological Decision Log: Specs are prefixed with timestamps or order sequence, providing a clear history of design choices.
3. AI Context Invariant: Before an LLM works on a module, it reads the spec to understand why the feature exists and what rules must not be broken.
4. Co-created with AI: Developers draft specs with the help of LLMs before writing a single line of code.

How is SDD Different from ADRs?

You might wonder how SDD differs from Architecture Decision Records (ADRs).

While ADRs document broad architectural trade-offs, SDD specs act as granular guardrails that guide day-to-day AI feature implementations.

Introducing lore CLI 🚀

To make Spec-Driven Development seamless, I built lore—a fast CLI tool written in Rust for managing spec documents and performing local semantic vector search.

lore keeps track of your project’s spec files and uses embedded vector search so AI tools or developers can instantly retrieve relevant specs.

1. Initialize a project

lore init

This creates a spec/ directory and a lore.toml config file in your project root.

2. Create a new spec

lore new "add vector similarity search"

Generates a timestamped file like spec/1770034800-add-vector-similarity-search.md pre-populated with author and date frontmatter:

---
author: "octocat"
date: "2026-08-02T12:00:00Z"
---

<!-- your spec document goes here -->

3. Open or filter specs

lore open
lore open vector

4. Semantic Search across Specs

lore search "vector search implementation" --limit 3

lore automatically chunks markdown headings and uses local embedding models to find exact requirements, making context injection effortless for AI workflows.

Conclusion

As software engineering shifts toward AI-augmented development, preserving design context is as critical as writing clean code. Spec-Driven Development with lore ensures your AI assistants build new features with full awareness of your codebase’s accumulated wisdom.

To learn more, check out the source code, or download lore for your own projects, visit github.com/vsnthdev/lore.