Hichoi-Dev

Posted on Mar 20

Specs Cannot be Source of Source Code — Why Intent Management Matters in AI-Driven Development

The Seductive Idea

There's a compelling narrative in AI-driven development right now: write a detailed spec, feed it to an AI agent, and get working software out.

GitHub's Spec Kit, AWS's Kiro, and a growing ecosystem of tools all converge on the same premise — that specifications can become the "source of source code." The product requirements document isn't just a guide for implementation; it is the source that generates implementation.

It's an attractive idea. If specs are the source, then developers become spec writers, AI becomes the compiler, and code becomes a generated artifact. Clean. Elegant. Almost too good.

And that's the problem.

Source Code Is Deterministic. Specs Are Not.

Let's start with what "source" actually means in software engineering.

When you compile main.c, you get the same binary. Every time. On every machine. This property — determinism — is what makes source code source. It's the reproducible foundation on which everything else stands: builds, tests, deployments, debugging.

Now consider a specification:

"The system should handle user authentication with proper security measures."

Feed this to an AI agent three times. You'll get three different implementations — different OAuth flows, different session strategies, different error handling patterns. The same spec produces different code across different runs, different models, and different context windows.

This isn't a bug in the AI. It's a fundamental characteristic. Specifications are written in natural language, which is inherently ambiguous. LLMs are non-deterministic by design. The combination means that specs cannot serve as "source" in any meaningful engineering sense.

Source code has a contract: same input, same output. Specifications don't — and can't — honor that contract.

Then What Are Specs? Intent, Not Source.

If specs aren't source, what are they?

They're intent. Initiative. Direction. A spec says what you want and why you want it — but it doesn't deterministically produce how. The "how" emerges through the act of implementation, whether done by a human or an AI agent.

This distinction matters more than it seems:

	Source	Intent
Determinism	Same input → same output	Same input → many valid outputs
Verification	Compile, run, test	Interpret, judge, review
Authority	The code is the truth	The intent guides the truth
Drift	Doesn't drift from itself	Drifts from implementation over time

Treating intent as source is a category error. It's like treating a compass bearing as a GPS coordinate — useful for direction, useless for pinpointing where you actually are.

Why We Still Need to Manage Intent

But here's the thing: just because specs aren't source doesn't mean they don't matter.

In AI-driven development, intent management is arguably more critical than ever:

Context loss — AI agents forget everything between sessions. Without persisted intent, every session starts from zero.
Knowledge decay — Decisions made in session 12 are invisible in session 13. Architecture rationale evaporates. Business rules get re-debated.
Drift without anchor — Without a persistent record of intent, AI agents make locally reasonable but globally inconsistent decisions. The codebase slowly becomes incoherent.

The question isn't whether to manage intent. It's how.

How Teams Have Managed Specs (A Brief History)

Software teams have tried many approaches to capture and maintain design knowledge. Here's how the major ones compare — especially through the lens of AI-assisted development:

Approach	Strengths	Weaknesses	AI-Era Fit
RFC — proposal for collecting feedback (Pragmatic Engineer)	Structured deliberation	Point-in-time, never updated	Low
ADR — records one decision + rationale (Candost)	Lightweight, captures why	Accumulates without sync	Medium
Design Docs — comprehensive pre-impl design (Google, Uber-style)	Thorough analysis	Goes stale fast	Low
CLAUDE.md / AGENTS.md — repo-level AI instructions (agents.md)	Zero-friction, always loaded	No sync, grows stale silently	Medium
Spec Kit — Spec → Plan → Task → Implement (GitHub Blog)	Structured workflow	One-shot, no cross-session continuity	Medium
Kiro — IDE with built-in spec workflow (kiro.dev)	Integrated experience	Static specs, manual updates, IDE-locked	Medium

Every approach above shares a common failure mode: they treat specification as a one-time event, not a continuous process. You write the RFC, make the decision, and move on. You create the design doc, build the feature, and the doc rots. You set up CLAUDE.md on day one, and by week three it describes a project that no longer exists.

Drew Breunig captured this perfectly with the Spec-Driven Development Triangle — specs, code, and tests form a triangle that must stay in sync, but keeping them in sync is where everyone fails.

The Sync Problem Is a Workflow Problem

Here's the insight that most tools miss: spec drift isn't a documentation problem. It's a workflow problem.

You can't solve it by writing better specs. You can't solve it by adding a linter that checks specs against code. You can't solve it with a pre-commit hook that nags you to update the docs.

You solve it by making knowledge maintenance an inseparable part of the development workflow itself — not something you do after the "real work," but part of the work.

This requires three things:

A knowledge base that's structured enough for AI to reference, but lightweight enough for humans to maintain
A sync mechanism that's embedded in the development lifecycle, not bolted on as an afterthought
An iterative workflow that revisits and evolves knowledge across sessions, not just within a single feature

Most tools get one or two of these. Almost none get all three.

REAP's Answer: Genome + Sync + Recursive Workflow

This is the problem REAP was built to solve. Not by treating specs as source code, but by building a recursive workflow where knowledge evolves alongside the code it describes.

The Genome: A Living Knowledge Base

REAP maintains a "Genome" — a structured collection of project knowledge stored in .reap/genome/:

.reap/genome/
  principles.md      # Architecture decisions (ADR-style, with rationale)
  conventions.md      # Development rules and enforced standards
  constraints.md      # Technical choices and validation commands
  domain/             # Business rules that can't be derived from code

The Genome isn't a spec. It doesn't try to describe what to build. It captures what you've learned — architecture principles, business rules, constraints, conventions. It's the accumulated knowledge that makes your project your project, not a generic codebase.

Every time an AI agent starts a session in a REAP project, the Genome is automatically injected into its context. The agent doesn't start from zero — it starts with your project's institutional knowledge.

Sync Through the Lifecycle, Not After It

Here's where REAP diverges from every tool listed above. Knowledge sync isn't a separate activity — it's built into the development lifecycle.

Each "Generation" (a unit of work) follows a five-stage cycle:

Objective → Planning → Implementation → Validation → Completion

During Implementation, when you discover something that contradicts the Genome — a business rule that changed, an architectural assumption that proved wrong — you don't stop to update docs. You log it as a backlog item and keep building.

During Completion, those discoveries are reviewed and the Genome is updated. Knowledge evolution happens as a natural part of finishing work, not as a separate maintenance chore that everyone skips.

This is the critical difference. The Genome stays in sync with reality because updating it is part of the workflow, not something you do "when you have time" (which means never).

Recursive, Not One-Shot

But the most important differentiator isn't the Genome or the sync — it's that the workflow is recursive.

Spec Kit gives you: Specify → Plan → Task → Implement. Done. Start over from scratch for the next feature.

REAP gives you an endless chain of generations, where each generation inherits the knowledge from all previous ones:

Gen 1: Build auth → learns "we use JWT" → Genome updated
Gen 2: Build API → starts knowing "we use JWT" → learns "rate limiting needed" → Genome updated
Gen 3: Build dashboard → starts knowing both → builds on accumulated knowledge
...
Gen N: Genome reflects N generations of accumulated learning

Each generation archives its artifacts in a Lineage — a complete history of what was decided, what was built, and what was learned. The Genome is a living summary; the Lineage is the full record.

This recursive structure means:

No cold starts — Every generation begins with the full context of everything that came before
No knowledge loss — Decisions made in generation 5 are still accessible in generation 50
Natural evolution — The Genome grows more accurate over time, not less — the opposite of traditional specs

The Right Mental Model

Here's how to think about it:

	Traditional	SDD	REAP
Code is...	The only truth	A generated artifact	The truth, always
Spec is...	Pre-work that rots	Source of truth	Per-generation Objective (scoped, disposable)
Knowledge is...	In people's heads	In spec documents	In an evolving Genome
Workflow is...	Ad hoc	One-shot pipeline	Recursive generations
Sync happens...	Never	Manually	Built into each generation's completion

Code remains the source of truth. The Genome doesn't replace it — it complements it by capturing the intent, rationale, and constraints that code alone can't express. And the recursive workflow ensures the two stay in sync, generation after generation.

Try It

npm install -g @c-d-cc/reap
reap init my-project

# In Claude Code or OpenCode:
> /reap.start
> /reap.evolve "Implement user authentication"

REAP is open source, MIT licensed, and supports Claude Code and OpenCode today.

GitHub | Documentation | npm

Specs can't be source code. But the intent behind them — the decisions, the constraints, the hard-won lessons — that's worth managing. The question is whether your workflow makes that management automatic or optional. Because optional means it won't happen.

References:

DEV Community