Traceability in software development: from requirement to release

Two years after release somebody asks why a validation rule was implemented exactly that way. The person who knew is on the next project. The ticket sits in a decommissioned system. The commit says “fix validation”. That is where it is decided whether a project had traceability – not in an audit, but in ordinary maintenance.

1. The problem

In most projects the link between requirement and code does exist – but only in the heads of those involved and spread across tools maintained independently of each other. It is therefore present as long as nothing happens, and disappears exactly when it is needed: when people change, during a defect analysis under time pressure, during a change assessment, during an inspection.

AI-assisted development sharpens this. Not because generated code is worse, but because more changes arrive in less time and the commit author is no longer automatically the person who made every decision. What used to run along implicitly now has to be recorded explicitly.

2. Clarifying the terms

Traceability is the ability to follow relationships between artefacts of the development process in both directions. Three terms are frequently conflated:

• Forward traceability: from the requirement to everything that came out of it – design, code, tests, release. Answers: “is the requirement implemented and tested?”
• Backward traceability: from an artefact back to its cause. Answers: “why does this code exist, and who wanted it?”
• Bidirectional simply means both work. Only then is the chain solid, because the two directions expose different gaps.

The traceability matrix is not a concept of its own but merely a presentation of these relationships – usually requirements against tests. It is a report, not a document to maintain. Keeping it by hand means maintaining a second truth alongside the first.

3. What the chain is really for

Regulatory requirements are the best-known reason but the rarest day-to-day benefit. In practice traceability pays off in four places:

• Change assessment. What hangs on this requirement? Without a chain only estimation remains – and estimates turn optimistic under deadline pressure.
• Defect analysis. From the production defect back to the requirement, to the test that should have found it, and to the gap in the test case.
• Maintenance and handover. New team members read not only code but intent.
• Evidence. In regulated projects the chain is part of the release – see regulated software development with AI.

4. The chain and its links

Regardless of sector and tooling, the chain looks essentially the same. What matters is not its length but that each link is connected to the next by machine:

The chain is exactly as strong as its weakest link. In practice it breaks almost always in the same place: between requirement and change – because the connection there is manual work.

5. Stable identifiers: the smallest worthwhile investment

Everything stands or falls on an identifier that does not change. Four rules are enough:

1. Immutable. A requirement keeps its identifier even when title, content or ownership change.
2. Tool-independent. The identifier must not be the internal ID of a system that will be replaced in five years.
3. Machine-recognisable. A fixed pattern such as REQ-1042 can be found reliably in commits, tests and reports.
4. Not reusable. Deleted requirements do not release their identifier; the history stays unambiguous.

6. Technical implementation

The connection is created at three points that are passed through anyway. The effort is a few characters per change – provided the pipeline enforces it.

On the change set

feat(billing): add dunning level to invoice model

Implements the escalation rules agreed in REQ-1042.
Generated with an AI coding assistant, reviewed and adjusted manually.

Requirement: REQ-1042
Reviewed-by: a.beck
Assisted-by: ai-coding-assistant

The trailer is machine-readable and survives rebase, cherry-pick and changes of tooling, because it lives in the repository and not in a database.

On the test case

@Requirement("REQ-1042")
@Test
void escalatesToSecondDunningLevelAfterGracePeriod() {
    // Acceptance criterion 2 of REQ-1042: escalation after 14 days.
    ...
}

Whether annotation, marker or naming convention is secondary – what matters is that the identifier ends up in the test report and not only in the source.

In the pipeline

# Reject changes without a requirement reference on protected branches.
# The rule is worthless as a team agreement; it has to block the merge.

check-traceability:
  script:
    - git log --format=%B origin/main..HEAD | grep -qE '^Requirement: REQ-[0-9]+' 
        || (echo "Missing 'Requirement:' trailer" && exit 1)

The same run should also retain test reports, checksums and the dependency list as artefacts – not as a display in an interface that clears out after 30 days.

7. Generate the matrix, do not maintain it

When identifiers hang on requirement, commit and test, the traceability matrix is an analysis step. It is best produced where the release is produced:

• read all requirements from the source,
• scan the commits in the release range for trailers,
• group test results by identifier,
• build an overview from that: requirement → changes → tests → result,
• and – the most important part – flag the gaps: requirements without a test, tests without a requirement, changes without a reference.

The real value lies in that gap list. A completely green matrix maintained by hand says little; a generated matrix with three open points says exactly what to do.

On the platform side it helps when models, roles, validation rules and their history are already explicit and builds come from a versioned project definition – then several links of the chain are machine-readable already. How CodamAI implements this is on the features page.

8. How fine is fine enough?

The most common overreach comes from granularity that is too fine. “Attribute every line of code to a requirement” is neither feasible nor useful. A workable gradation follows the risk:

• High-risk functions: requirement → test case → test result, individually traceable.
• Ordinary functions: requirement → change set → test suite; grouping is enough.
• Internal improvements with no domain effect: labelling them as such is enough; forced pseudo-requirements only create noise.

9. Trade-offs and limits

• Traceability proves no quality. It shows that a test exists and ran – not that it checks the right thing.
• Discipline is still required. A trailer can be inserted mechanically without anybody thinking about the reference. The pipeline check recognises the pattern, not the intent.
• Tool landscape. The more systems involved, the more transitions have to be maintained. Fewer systems beat better integrations.
• Retrofitting is expensive. In a running project a cut usually pays off: from version X the chain applies, and the existing stock is only brought along when it changes.

Common mistakes

• Maintaining the matrix as a document instead of generating it.
• Using tool IDs as identifiers and losing the entire history when systems change.
• Linking forward only – the question “why does this exist?” stays unanswered.
• Not retaining test results; a green build is a state, not evidence.
• Evidencing everything at the same depth until the process gets bypassed.
• Writing the rule only into the handbook instead of enforcing it in the pipeline.

Checklist: traceability that holds

Conclusion

Traceability rarely fails on willingness and almost always at the point where a connection stays manual. Introduce stable identifiers, carry them at three points and enforce the rule in the pipeline, and the chain comes practically for free – including a matrix nobody has to maintain.

The effort is a few days of setup. The return shows up not on the day of introduction but at the first production defect, the first change assessment and the first question somebody asks two years later.