Your First Requirements Project
In this chapter, we'll build a complete requirements hierarchy for a simple project: a task management application. You'll learn how to structure requirements across multiple levels and establish traceability.
Planning the Hierarchy
A typical requirements hierarchy has multiple levels:
- User Requirements (USR) - High-level needs from the user's perspective
- System Requirements (SYS) - Technical specifications that satisfy user needs
- Software Requirements (SWR) - Detailed implementation requirements (optional)
- Test Requirements (TST) - Test cases that verify requirements (optional)
For our task app, we'll use USR and SYS levels.
Setting Up the Project
Create and enter a new directory:
mkdir task-app-requirements
cd task-app-requirements
Creating User Requirements
User requirements describe what users need, not how it's implemented.
req add USR # USR-001
req add USR # USR-002
req add USR # USR-003
Edit each file to add content:
USR-001.md:
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
---
# USR-001 Create Tasks
Users shall be able to create tasks with a title and description.
USR-002.md:
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
---
# USR-002 Mark Tasks Complete
Users shall be able to mark tasks as complete.
USR-003.md:
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
---
# USR-003 Filter Tasks
Users shall be able to filter tasks by completion status.
Creating System Requirements
System requirements break down user requirements into technical specifications.
For USR-001 (creating tasks), we need:
req add SYS --parents USR-001 # SYS-001
req add SYS --parents USR-001 # SYS-002
SYS-001.md:
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
parents:
- uuid: <USR-001 uuid>
fingerprint: <auto-generated>
hrid: USR-001
---
# SYS-001 Task Data Structure
The system shall provide a Task data structure with fields: id, title, description, completed, created_at.
SYS-002.md:
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
parents:
- uuid: <USR-001 uuid>
fingerprint: <auto-generated>
hrid: USR-001
---
# SYS-002 Task Title Validation
The system shall validate that task titles are non-empty strings with maximum 100 characters.
For USR-002 (marking complete):
req add SYS --parents USR-002 # SYS-003
SYS-003.md:
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
parents:
- uuid: <USR-002 uuid>
fingerprint: <auto-generated>
hrid: USR-002
---
# SYS-003 Toggle Task Completion
The system shall provide a method to toggle the completed status of a task.
For USR-003 (filtering):
req add SYS --parents USR-003 # SYS-004
SYS-004.md:
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
parents:
- uuid: <USR-003 uuid>
fingerprint: <auto-generated>
hrid: USR-003
---
# SYS-004 Filter Tasks by Status
The system shall provide a method to filter tasks returning only those matching the specified completion status.
Creating Cross-Cutting Requirements
Some requirements affect multiple user needs. For example, persistence:
req add SYS --parents USR-001,USR-002,USR-003 # SYS-005
SYS-005.md:
---
_version: '1'
uuid: <auto-generated>
created: <auto-generated>
parents:
- uuid: <USR-001 uuid>
fingerprint: <auto-generated>
hrid: USR-001
- uuid: <USR-002 uuid>
fingerprint: <auto-generated>
hrid: USR-002
- uuid: <USR-003 uuid>
fingerprint: <auto-generated>
hrid: USR-003
---
# SYS-005 Task Persistence
The system shall persist all tasks to disk and load them on startup.
This requirement has three parents because it affects creating, completing, and filtering tasks.
Reviewing Your Requirements Structure
Your directory now contains:
task-app-requirements/
├── USR-001.md (Create tasks)
├── USR-002.md (Mark complete)
├── USR-003.md (Filter tasks)
├── SYS-001.md → USR-001 (Task data structure)
├── SYS-002.md → USR-001 (Title validation)
├── SYS-003.md → USR-002 (Toggle completed)
├── SYS-004.md → USR-003 (Filter method)
└── SYS-005.md → USR-001, USR-002, USR-003 (Persistence)
Version Control Integration
Requirements are plain text, so they work great with Git:
git init
git add *.md
git commit -m "Initial requirements for task management app"
Every requirement change will now show up in your Git history with clear diffs:
--- a/USR-001.md
+++ b/USR-001.md
@@ -4,4 +4,4 @@
created: 2025-07-22T12:19:56.950194157Z
---
-Users shall be able to create tasks with a title and description.
+Users shall be able to create tasks with a title, description, and due date.
Best Practices Demonstrated
This example shows several best practices:
- Start high-level - Begin with user requirements before diving into technical details
- One concept per requirement - Each requirement addresses a single, testable concept
- Use clear language - Requirements use "shall" to indicate mandatory behavior
- Establish traceability - Every system requirement traces to at least one user requirement
- Support multiple parents - Cross-cutting concerns can satisfy multiple needs
Next Steps
Now that you understand the basics, explore:
- Core Concepts - Deeper dive into requirements management principles
- Working with Requirements - Advanced features and techniques
- Configuration - Customizing Requiem for your project
Continue reading to learn how Requiem supports advanced requirements management practices.