Guide · Requirements management
Requirements-as-code: choose a workflow that survives change
Keeping requirements beside source code makes them easier to version and review. A useful workflow also preserves who authorized the promise, which code implements it and what evidence supports the current version.
Requirements-as-code is a working process
Requirements-as-code keeps structured requirements in version-controlled files and uses engineering workflows to review, validate and publish them. Useful records have stable IDs, a testable statement, a rationale or source of authority, and relationships to the implementation and verification work.
Git supplies a history of edits. The team still has to decide who may change a requirement, what approval means and which evidence supports acceptance. A syntactically valid file can contain an ambiguous promise. A connected graph can contain a test that never ran or an assertion that checks the wrong outcome.
Choose a tool by following a real change through those decisions. The important costs often appear after the initial import: repairing links, preserving review history, refreshing evidence and explaining an unresolved exception to the next engineer.
Shortlist tools by the work you need
These are starting points for evaluation, not exclusive categories or a completeness ranking.
| Workflow | Consider | Challenge in your pilot |
|---|---|---|
| Structured requirements and published traceability | StrictDoc: SDoc authoring, source links and documentation exports. | Edit a requirement, rename linked code and import a real report. Confirm format and feature maturity. |
| YAML items and hierarchy validation | Doorstop: file-based items, link validation and suspect fingerprints. | Change a parent requirement and review its suspect links. Establish what evidence is required before clearing them. |
| Requirements inside engineering documentation | Sphinx-Needs: linked engineering objects in Sphinx, with a test-report extension available. | Keep custom fields and test-result provenance intact through a document build and an implementation change. |
| Requirements connected to ongoing software assurance | Proof: repository requirement lifecycle, traces, evidence, issues and configured change checks. | Inspect a failure, repair and actual Proof results, then evaluate what a subsequent change makes relevant to review. |
Official sources checked October 3, 2026: StrictDoc user guide, Doorstop overview, Doorstop validation, Sphinx-Needs and Sphinx-Test-Reports. The linked comparisons explain the narrower feature and maturity boundaries.
Evaluate authority, links and results separately
Can the right people review a change?
Test the authoring experience with both an engineer and a stakeholder who does not normally edit repository files. Show them the changed statement, rationale and prior approval. Decide whether repository review is sufficient or whether an established requirements platform should remain part of the process. Compare that decision with Jama Connect.
Can the graph survive ordinary refactoring?
Rename a function, split a module and retire a requirement. Inspect missing IDs, orphaned code, suspect relationships and deleted references. Establish which links the tool derives and which the team maintains. A complete-looking matrix is useful only if its denominator and relationships are understood.
Can a reviewer identify what actually ran?
Follow a requirement to the assertion, runner, source revision, inputs and observed result. Then replace the result with an older one and inspect what changes. Freshness may depend on configuration and the evidence type. Publishing a report, linking a fixture or recording approval is a different action from executing verification.
Run a small selection exercise before migrating
Illustrative pilot: a file-upload service promises to discard an incomplete upload after its lease expires. Use a single component and a small requirement set, including this behavior and its error paths.
- Establish the authority. Record the agreed expiry rule, clock assumptions and the person or policy allowed to amend it.
- Connect the implementation. Link the upload handler, lease record and cleanup worker. Retain the meaning of each relationship.
- Exercise the boundary. Run cases before and after expiry and a worker restart. Inspect actual storage cleanup, not only a returned status.
- Introduce a controlled change. Alter the lease calculation in a test branch. Ask the tool and reviewer to identify the affected obligation and the checks that need attention.
- Evaluate the handoff. Give the record to another engineer. Measure the time and manual repairs needed to explain the rule, reproduce the result and identify the remaining gap.
The pilot succeeds when the team can make and explain an acceptance decision with known limitations. A generated artifact or a green demonstration screen is not a substitute for those observations. Record unsuccessful mappings and unsupported cases alongside the useful results.
Where Proof fits in the shortlist
Proof is worth evaluating when requirements, code, verification and issue history need to remain connected across changes. It includes requirement authoring and lifecycle work as well as checks; it is broader than a detached CI status. The relevant question is which parts of that workflow your repository can support today.
Start with proof req for requirement records, trace inspection for recorded relationships and the configured checks appropriate to the component. Keep test planning, actual execution and report generation distinct. Inspect the scope, skipped cases and evidence behind every result. Repository protection must separately require the checks you intend to enforce.
For a migration, inventory custom fields, IDs, relationship types, approvals, attachments and exports before moving data. Compare the source and destination record by record on a small sample. The comparisons here do not establish lossless imports or ready-made synchronization with the listed tools.
Try the workflow on one component
Bring a requirement set and one change whose evidence was hard to assess. We can identify a bounded Proof workflow to evaluate, the verification it can support and the migration work you would need.