What is requirements traceability?
Requirements traceability is the ability to follow a requirement through its whole life: where it came from, why it exists, which code implements it and which tests prove it. Forward traceability runs from a requirement to its code and tests; backward traceability runs from a line of code or a failing test back to the rule it serves.
It is how teams answer everyday questions with confidence. What breaks if we change this rule? Is this behavior intended, or a bug? Which tests cover it? Who approved it, and why?
Why traceability breaks in AI-assisted development
Traditional software requirements management leans on tickets and matrices that people update by hand. That was fragile when people wrote all the code. With agents producing changes around the clock, a traceability matrix kept in a spreadsheet is out of date by lunchtime. Traceability has to fall out of how the team works, not be a separate job.
Traceability built into the workflow
- Stable requirement IDs. Every requirement gets an ID from its context key, such as
ORD-12. It stays the same when the text changes, and numbers are never reused. - A linked model. Requirements link to the glossary terms, actors, decisions and other requirements they depend on.
- Proposals and reviews. Every change records who proposed it, person or agent, the review threads and who approved it.
- A decision log. Numbered decisions explain why a requirement exists and what it replaced.
- Git commits with trailers. Every published change is a commit whose trailers name the proposal and the approver.
Spec to code traceability
Approved specs are committed to the specsgraph/ folder of your repository, next to the code they describe. Commit messages and pull requests cite requirement IDs, so git log --grep ORD-12 lists every code change made for that rule. A short CI check can fail any pull request that cites no requirement ID, or one that does not exist, by reading the machine-readable graph.json.
Spec files in your repository includes a ready-to-use GitHub Actions workflow, and Branches and pull requests shows the commit format.
Requirements to test
Each requirement is published as a Gherkin feature tagged with its ID. Your BDD runner can execute the scenarios of a single requirement, and test names that include the ID make the link visible in test output too:
npx cucumber-js features --tags "@ORD-12"That is spec-driven development paying off twice: the scenarios the team agreed on before building are the same ones that verify the result.
A traceability matrix that maintains itself
Here is how one rule in the Northwind Commerce sample traces from end to end, with nothing kept up to date by hand:
Software requirements management without the overhead
SpecsGraph is specification management for teams that build with AI: requirements live in a typed, versioned model rather than a document or a ticket queue. PMs and BAs shape them, agents draft and cite them, QA tests against them and developers ship against them. Traceability is simply what you get when all of them work from the same IDs, which is the heart of AI-native software development.