# Traceability

**In short:** Traceability links requirements to the architecture that serves them. arc42 describes a full form, where every requirement is referenced, and a pragmatic form, where key decisions are explained by their requirements. It advises avoiding the full form when possible.

## Explanation

Traceability means you can follow a link from a requirement to the part of the architecture that deals with it. You can also follow it back, from a design choice to the requirement behind it.

arc42 (a template for documenting architecture, see the article arc42 Architecture Documentation Template) describes two forms.

**Full-scale traceability.** Every single requirement is referenced somewhere in the architecture or solution documentation. No requirement is left without a link.

**Pragmatic traceability.** You explain the important or fundamental decisions by naming the requirements behind them. This helps readers understand why the architecture looks the way it does.

The arc42 building block template supports linking too. Its blackbox template (a description of a building block that shows what it does, not how it works inside) has an optional field for the requirements that the block fulfills. That field connects requirements to the building blocks that implement them.

arc42 attaches a warning to this field. Add fulfilled requirements only if you really need traceability, because the effort is large.

## Example

A team builds an online shop. One requirement says customers can pay by invoice. In the description of the payment building block, the team fills the optional field with this requirement. The team also records the decision to use an external payment provider and names the requirement behind it. A new team member can now see why the provider exists. The team does not link minor requirements, such as button labels. This follows the pragmatic form.

## Trade-offs

Full-scale traceability gives complete coverage. arc42 calls it horribly expensive, slow and difficult, and advises avoiding it when you can. The pragmatic form costs less and still explains the key decisions, which helps understanding. The price is that some requirements have no recorded link to the architecture. Fill the optional requirements field only where you truly need the links.



## Checks

- The documentation states whether traceability is full-scale or pragmatic.
- Important architecture decisions name the requirements behind them.
- The fulfilled-requirements field of a building block is filled only where traceability is truly needed.

## Related

- [arc42 Architecture Documentation Template](https://arc.fuet.ch/concepts/documentation/arc42-documentation-template.md)
- [arc42 Architecture Decisions](https://arc.fuet.ch/concepts/documentation/arc42-architecture-decisions.md)
- [Architecture Decision Documentation and Requirements Management](https://arc.fuet.ch/concepts/forces-decisions/decision-documentation-and-requirements-management.md)
- [Architectural Decision](https://arc.fuet.ch/concepts/forces-decisions/architectural-decision.md)
- [SMART Requirements](https://arc.fuet.ch/concepts/functional-requirements/smart-requirements.md)
- [Modifiability](https://arc.fuet.ch/concepts/quality-attributes/modifiability.md)
- [Accountability](https://arc.fuet.ch/concepts/quality-attributes/accountability.md)
- [Architecturally Evident Coding Style](https://arc.fuet.ch/concepts/fundamentals/architecturally-evident-coding-style.md)

## Sources

- [Question H-1: What does 'traceability' mean (with arc42)? | arc42 FAQ](https://faq.arc42.org/questions/H-1/) — faq.arc42.org, accessed 2026-11-09
- [Question H-2: Shall we strive for traceability in our documentation? | arc42 FAQ](https://faq.arc42.org/questions/H-2/) — faq.arc42.org, accessed 2026-11-09
- [Tip 5-7: Use tables to efficiently document/specify blackboxes! | arc42 Documentation](https://docs.arc42.org/tips/5-7/) — docs.arc42.org, accessed 2026-11-09