A practical architecture for linking stakeholder intent, specifications, decisions, code, tests, and production evidence.
AI can write code quickly. That is no longer the interesting bottleneck.
The harder problem is keeping a changing product coherent: making sure a new request still respects the product model, architecture decisions, data contracts, operational constraints, and work already being done by other developers or agents.
This is where many AI-assisted projects break down. A feature is specified in one conversation, implemented in another, reviewed against a partial repository view, and deployed without updating the documents that future work will rely on. Each individual output can look convincing while the system as a whole drifts.
I have been developing a different operating model. I call it Graph-Grounded Specification-Driven Development (GG-SDD): a traceability-first implementation pattern within the broader AI-Driven Development Lifecycle, backed by a project-scoped graph, evidence-aware retrieval, explicit approval gates, and a closed loop from stakeholder intent to production verification.
GG-SDD is not a claim that specification-driven development, knowledge graphs, RAG, requirements traceability, MCP, or an AI-native lifecycle are new. They are not. The proposal is to make them work as one lean, project-level control system.
The central idea is simple:
Every change should be derived from a versioned map of the project, carry its source evidence and impact path into implementation, and write verified knowledge back after delivery.
Vibe coding optimizes a prompt. GG-SDD optimizes the continuity of the product.
The bottleneck moved from code generation to coherence
Vibe coding is useful. It is excellent for exploration, disposable prototypes, interface experiments, and short feedback loops where a person can continuously inspect the result.
It is a weak control model for a long-lived production system.
The limitation is not that the model cannot produce enough code. It is that the model usually sees a temporary and incomplete representation of the project. A prompt might include a ticket and a few files, but omit an architectural decision, a data migration constraint, a security rule, an incident history, or another specification being implemented in parallel.
Larger context windows do not remove this problem. Anthropic's guidance on context engineering treats context as a finite attention budget: the objective is not to load everything, but to select the smallest set of high-signal information that maximizes the likelihood of the desired result.[1]
The result is a shift in engineering work. As code generation becomes cheaper, context selection, semantic consistency, verification, and accountability become more important.
Specification-driven development is necessary, but not sufficient
Specification-driven development improves the situation by making intent explicit before implementation.
GitHub Spec Kit formalizes an agentic process that can include a project constitution, specification, clarification, technical plan, requirement checklist, implementation tasks, cross-artifact analysis, implementation, and convergence checks.[2] Kiro follows a related requirements–design–tasks workflow and combines it with persistent steering files and MCP integrations.[3]
This is a major improvement over an isolated prompt. A specification becomes a durable artifact, and quality gates can catch ambiguity before code is produced.
However, a set of good specification files is not automatically a coherent project memory.
Three problems remain:
- Scope. A feature specification may not include the product decisions, cross-service dependencies, incidents, deployment rules, or work in progress that affect it.
- Persistence. Specs, plans, tasks, and implementation can diverge unless the team explicitly chooses how changes flow back through the artifact set. GitHub's own Spec Kit documentation identifies silent divergence as a risk in mutable, flow-back models.[4]
- Coordination. Two agents can follow the same template and still make contradictory choices if they retrieve different evidence or do not know that a shared decision has changed.
GG-SDD adds a persistent relationship model around the specification workflow.
The broader lifecycle already has a useful industry name. AWS introduced the AI-Driven Development Lifecycle (AI-DLC) in 2025, organizing work from business intent through inception, construction, and operations while maintaining context and human validation.[20] Its 2026 AIDLC Collaborative sample goes further: it models requirements, stories, designs, decisions, and code as typed graph artifacts; supports bidirectional traceability, impact analysis, MCP-based agent access, human gates, parallel work, and pull-request output.[21]
That is very close prior art. GG-SDD should therefore be understood as an independent, lightweight, cloud-neutral and traceability-first implementation pattern within AI-DLC — not as the invention of a new lifecycle.
What already exists
The industry is clearly converging on better context infrastructure.
Sourcegraph described Cody's context engine and graph context in 2023.[5] Aider uses a concise repository map and graph ranking to select important symbols within a token budget.[6] Augment and Qodo now use the term Context Engine for multi-repository code understanding, semantic retrieval, history, documentation, and agent workflows; both also expose context to other tools through MCP.[7][8]
Tabnine is an even closer commercial analogue. Its Enterprise Context Engine is described as a continuously updated knowledge graph of artifacts, decisions, incidents, ownership, and dependencies. Its Requirements Planning workflow ingests code, documentation, Jira, ADRs, and operational data, then generates an executable PRD, stories, acceptance criteria, testing plan, and deployment checklist linked back to components and files.[22]
Other products extend the idea beyond code. Factory Threads links discussions, code, and documents into shared dynamic context.[9] Allstacks describes a Context Graph connecting strategy, tickets, commits, and other delivery signals across the software lifecycle.[10] OneTrace versions relationships among PRDs, stories, acceptance criteria, tests, commits, and pull requests, then uses them to identify coverage gaps and drift.[11] Strata19 describes a typed project graph, living documentation, impact analysis, verification gates, and MCP queries.[12] SpecGraph combines brownfield discovery, versioned specification packs, MCP delivery to coding agents, pull-request citations, and a live amendment loop.[23]
Academic work points in the same direction. DraCo retrieves from a repository-specific context graph built from data-flow relations.[13] CodexGraph uses a code graph database as an interface between an LLM agent and a repository.[14] TraceLLM applies LLMs to requirements trace-link recovery while retaining human validation.[15] TraceDev, accepted at ISSTA 2026, uses a heterogeneous traceability graph as shared structured context and memory for requirement, design, development, testing, and validation agents.[24] Trust-Aware Multi-Agent Traceability describes a shared knowledge graph as a coordination surface with confidence calibration and conflict resolution.[25] A 2026 systematization of software-artifact traceability maps 22 artifact types and 23 associations, while noting that research is still disproportionately focused on code-related links.[16]
So the useful question is not, "Has anyone thought about persistent context or traceability before?"
They have.
The more precise question is:
How do we combine specification synthesis, project-wide impact analysis, provenance, human approval, and multi-agent access into a practical delivery loop that a team can operate?
That is the design space for GG-SDD. Its defensible contribution is not a new category; it is a deployable production synthesis: brownfield-first ingestion, a broader intent-to-operations thread, explicit provenance and freshness, vendor-neutral MCP access, and longitudinal evidence that the workflow improves real delivery.
A working definition
A project-owned traceability graph turns scattered artifacts into a governed change loop.
Graph-Grounded Specification-Driven Development is a traceability-first AI-DLC pattern in which each proposed change is derived from and written back to a versioned, project-scoped graph linking product intent, requirements, constraints, decisions, implementation, verification, and operational evidence.
The graph is not a giant prompt. It is not merely a vector store. It is not automatically the canonical source for every artifact.
It is a typed and permission-aware traceability layer that helps the system answer questions such as:
- Which product goal motivates this request?
- Which approved requirements and constraints govern it?
- Which architectural decisions apply, and which have been superseded?
- Which services, schemas, APIs, code modules, tests, and owners may be affected?
- What evidence supports each claim in the proposed specification?
- What changed during implementation, and was the specification reconciled afterward?
The project traceability graph
A useful graph schema should include more than code symbols.
Example node types include: ProductGoal, Requirement, Constraint, ArchitectureDecision, Component, Service, API, SchemaEntity, CodeModule, Test, Deployment, Incident, Metric, Owner, ChangeRequest, SpecificationVersion.
Example relationships include: motivates, refines, constrains, depends_on, implemented_by, verified_by, deployed_as, observed_by, owned_by, derived_from, supersedes, conflicts_with, changed_by.
The relationship model matters because many engineering questions are multi-hop questions.
"Where is authentication implemented?" is largely a repository retrieval problem.
"If we add team-level billing limits, which product commitments, authorization rules, database constraints, webhooks, tests, operational dashboards, and rollout decisions must change?" is a traceability and impact-analysis problem.
A graph does not eliminate semantic search. The strongest retrieval architecture is usually hybrid:
- deterministic graph traversal for known relationships;
- sparse retrieval for exact terms, identifiers, and domain language;
- dense retrieval for semantic similarity;
- ranking by freshness, approval status, and source authority;
- optional agentic exploration when the relevant path is not yet known.
The goal is not to send the whole project to the model. It is to construct a minimal, evidence-rich impact packet for the decision being made.
Provenance is more important than volume
A context layer becomes dangerous if it is confidently stale.
Every material node and edge should carry operational metadata:
- canonical source URI;
- source owner;
- version, hash, or timestamp;
- validity interval and environment;
- approval status;
- confidentiality and access controls;
- extraction confidence;
- last verification time.
Generated relationships should not be indistinguishable from approved ones. An LLM may propose that a requirement is implemented by a particular service, but the link should retain its evidence and review state.
Similarly, old decisions should not simply disappear. An architecture decision record captures the context and consequences of a decision; when the decision changes, a new record should supersede the old one instead of rewriting history.[17]
This makes the graph a materialized view of project truth, not an opaque replacement for the systems that own that truth.
From a stakeholder request to a reviewed specification
Consider a stakeholder request:
Let workspace administrators set a monthly AI-usage budget and prevent overages.
An ordinary coding agent may search for "usage," find billing code, and begin editing.
A GG-SDD workflow should first produce an impact-aware specification.
A small request can have a large impact path. The graph makes that path inspectable before implementation.
1. Normalize the intent
The system separates the desired outcome from the proposed solution:
- Who is allowed to set the budget?
- Is the limit hard or soft?
- Is usage measured in tokens, cost, requests, or a normalized credit?
- What happens to in-flight work when the limit is reached?
- Are enterprise contracts allowed to override the default behavior?
Only material ambiguity should trigger clarification. The objective is not to turn every request into a bureaucratic interview.
2. Retrieve an impact subgraph
The system follows relevant relationships across:
- pricing and entitlement requirements;
- authorization decisions;
- usage accounting;
- database tables and billing events;
- background jobs;
- customer notifications;
- existing tests;
- incident history;
- deployment and rollback constraints.
3. Synthesize a source-grounded draft
The resulting specification should include:
- clarified behavior and non-goals;
- acceptance criteria;
- affected components and owners;
- data, API, and migration changes;
- known conflicts with approved decisions;
- implementation options and trade-offs;
- test and observability requirements;
- rollout and failure-recovery plan;
- references to the evidence used.
4. Apply human approval gates
The system can prepare the evidence and detect inconsistencies, but responsibility remains human.
A product owner approves behavior. An engineer approves architecture. Security or operations approves high-risk changes. The approved snapshot becomes the contract passed to implementation.
5. Execute through any compatible client
MCP can expose approved specifications, impact packets, graph queries, and controlled actions to Codex, Kiro, or another agent host.
This is an interoperability layer, not the consistency engine itself. The MCP specification is explicit that it standardizes context exchange but does not dictate how an AI application manages the provided context.[18]
6. Reconcile after implementation
After the pull request, tests, and deployment, the system compares what was delivered with what was approved:
- Did the implementation touch an unplanned service?
- Were all acceptance criteria verified?
- Did an implementation discovery change the design?
- Was a new operational constraint learned?
- Does an ADR need to be created or superseded?
Only verified changes should update approved project knowledge. This closes the loop that ordinary documentation workflows often leave open.
Why this helps multiple developers and agents
The value of GG-SDD is not that one agent becomes omniscient. It is that multiple participants have a shared semantic frame.
Without a shared context layer, each developer or agent reconstructs the project from local files, conversations, and memory. That produces repeated discovery, inconsistent assumptions, and incompatible plans.
With a traceability graph:
- two agents can retrieve the same approved constraints;
- a change to a shared API can identify parallel specifications that depend on it;
- an architecture decision can propagate as a constraint without copying the full ADR into every prompt;
- reviewers can inspect the evidence path instead of trusting an unattributed summary;
- implementation discoveries can be written back once and reused by the team.
This does not eliminate coordination. It makes coordination observable.
Vercel and Supabase are implementation choices, not the methodology
Vercel and Supabase are convenient for this style of work because they provide strong programmable interfaces and MCP integrations. A development agent can inspect projects, deployments, logs, schemas, migrations, functions, and other operational state without relying entirely on manually prepared documents.
The architecture is cloud-neutral. AWS, Hetzner, self-hosted systems, or another stack can participate as long as the project has secure and inspectable interfaces.
The important design rule is least privilege.
Supabase explicitly warns against connecting its MCP server to production data, recommends development environments, project scoping, read-only mode, feature-group restrictions, branching, and manual approval of tool calls.[19] A GG-SDD implementation should treat these controls as part of the methodology, not as optional deployment details.
What can go wrong
A graph-backed workflow introduces its own failure modes.
The graph can be stale
If ingestion lags behind the canonical systems, retrieval can produce a coherent but outdated answer. Freshness service-level objectives, invalidation, visible timestamps, and reconciliation jobs are essential.
The graph can encode false relationships
An extracted link may be plausible without being true. Critical edges require source evidence, confidence, and an approval state. Automated extraction should propose knowledge, not silently canonize it.
Sources can disagree
The requirements, code, and deployment may describe three different realities. The system should surface the conflict and route it to an owner, not choose whichever source happens to rank highest.
Permissions can leak through retrieval
The context layer must preserve source-system access controls. A user who can query an MCP server should not automatically see every node in the graph.
Untrusted content can attack tools
Tickets, logs, or database records can contain prompt-injection content. Retrieval and action permissions must be separated, and state-changing tools should require explicit approval.
The process can become heavier than the problem
A small greenfield feature in one repository may not justify ontology management and multi-stage approval. GG-SDD needs a lightweight path. "Use the smallest process that preserves the required evidence" is a better principle than forcing every change through the same machinery.
How to test whether GG-SDD actually works
The framework should be evaluated against baselines, not marketed through anecdotes.
A useful study would take 30–50 historical feature requests of different complexity and run them through four modes:
- Repository only: request plus ordinary repository tools.
- Static SDD: request, steering files, and a structured specification workflow.
- Semantic RAG: static SDD plus vector and sparse retrieval.
- GG-SDD: typed traceability graph, provenance-aware retrieval, impact analysis, consistency validation, and approval gates.
The study should freeze the source snapshot, control the model family and token budget, repeat runs to measure variance, and use blinded senior-engineer review.
Relevant metrics include: time from request to approved specification; number of clarification rounds; affected-component precision and recall; source-grounding precision; conflict-detection precision and recall; percentage of specifications accepted without major revision; cross-run and cross-developer consistency; architecture-review rework; pull-request cycle time; escaped regressions; token and infrastructure cost; freshness and permission-policy violations.
Until these measurements exist, claims such as "higher consistency" or "less rework" should be presented as design goals and hypotheses, not established outcomes.
The real opportunity
The market does not need another promise that an agent can write an application from one prompt.
It needs a reliable way to preserve why a product works the way it does while humans and agents change it.
Specification-driven development makes intent explicit. Context engines improve retrieval. Requirements traceability connects artifacts. Knowledge graphs make relationships queryable. MCP makes those capabilities portable across agent clients.
GG-SDD proposes that these should be operated as one closed-loop system:
request → evidence → impact → specification → approval →
implementation → verification → reconciliation
That is the difference between generating code quickly and evolving a software product coherently.
The model will change. The IDE will change. The preferred agent will change. The durable asset is the project's traceable, governed understanding of itself.
If you are experimenting with spec-driven workflows, context engines, or traceability graphs on a real codebase, I would like to hear where they break for you — the comments are open.
References
- Anthropic, "Effective context engineering for AI agents", September 29, 2025
- GitHub Spec Kit, "Agentic SDD"
- Kiro, "Specs" and structured planning workflow
- GitHub Spec Kit, "Spec Persistence Models"
- Sourcegraph, "Cody is generally available", December 14, 2023
- Aider, "Repository map"
- Augment, "The Context Engine"
- Qodo, "Introducing Qodo's Context Engine", September 10, 2025
- Factory, "The Command Center for Software Development"
- Allstacks, "Engineering Context Graph"
- OneTrace, "System of record for AI-built software"
- Strata19, "An engine-driven platform for structured software development"
- Cheng, Wu, and Hu, "Dataflow-Guided Retrieval Augmentation for Repository-Level Code Completion", ACL 2024
- Liu et al., "CodexGraph: Bridging Large Language Models and Code Repositories via Code Graph Databases", NAACL 2025
- Alturayeif, Ahmad, and Hassine, "TraceLLM", 2026
- Chen et al., "SoK: Systematizing Software Artifacts Traceability", 2026
- AWS Prescriptive Guidance, "Architectural decision record process"
- Model Context Protocol, "Architecture overview"
- Supabase, "MCP Server" and security guidance
- AWS, "AI-Driven Development Life Cycle: Reimagining Software Engineering", July 31, 2025
- AWS Samples, "AIDLC Collaborative", 2026
- Tabnine, "Context-Driven Requirements Planning", 2026
- SpecGraph, brownfield specification and MCP workflow
- "TraceDev: A Traceability-Driven Multi-agent Framework for Requirement-to-Code Development", ISSTA 2026
- "Trust-Aware Multi-Agent Traceability", 2026
Publication note: This article presents a proposed framework and implementation pattern based on practical development work. It is not a patent-landscape review or a claim that the underlying techniques are individually novel.
Top comments (2)
Where do we go to try using it?
I can share private access, but for the next several months we will decide whether to publish it or not, mostly depending on the interest from the community