Templates & Checklists¶
Checklists for the reviews and quality gates in a software or firmware project, and templates for the records a team keeps along the way. They are written for embedded and connected products, but most of them work for any software team.
Copy them into your own repository, tracker or wiki and change them to suit. A checklist nobody adapts tends to become a checklist nobody reads.
Checklists¶
Each checklist is a task list, so it can go straight into a pull request, an issue or a review record. Every item has an ID, so review comments and records can refer to it.
| Checklist | Use it when |
|---|---|
| Definition of Ready | Deciding whether a backlog item can go into a sprint |
| Definition of Done | Deciding whether a work item is finished |
| Architecture review | Reviewing a system architecture or high-level design |
| Design review | Reviewing the detailed design of a component or module |
| Code review | Reviewing a pull request |
| Debugging | Investigating and fixing a fault |
| Defect report | Raising a defect, setting its severity, and closing it |
The checklists.
Templates¶
Grouped by when in a project you are likely to need them.
| Template | Use it for |
|---|---|
| Project vision | Agreeing why a project exists, who it is for and what success looks like |
| Architecture vision | Describing where a system’s architecture is heading, and why |
| Architecture principles | Recording the principles a product or team has agreed |
| Architecture document | Describing a system’s architecture, with C4 diagram starters |
| Architecture canvases | Starting or explaining an architecture on one page |
| Crosscutting concerns | Security, logging, errors and configuration across a whole system |
| Architecture decision record | Recording one significant decision |
| Request for comments | Proposing a change and gathering views before deciding |
Templates for vision and architecture.
| Template | Use it for |
|---|---|
| Requirements and quality scenarios | Writing requirements that can be traced and tested |
| NFR scenario | Writing one non-functional requirement as a testable scenario |
| Requirements traceability matrix | Tracing requirements to design, code and tests |
| Interface specification | Describing an interface between components or systems |
| Software design specification | The detailed design of a system or module |
| Experiment record | Running a spike, prototype or piece of research |
| Test plan | Planning how a product, system or component is tested |
Templates for requirements, design and testing.
| Template | Use it for |
|---|---|
| Systems engineering management plan | Running the engineering of a larger multi-discipline project |
| Team working agreement | Agreeing how a team works together |
| Meeting minutes | Recording a meeting’s decisions and actions |
| Decision log | A running list of a project’s decisions |
| Risk register | Tracking risks, their owners and what is being done about them |
| Technical debt register | Recording technical debt and the plan to pay it down |
| Release plan | Planning a release or deployment, including the rollback |
| Software bill of materials | Summarising the components a product is built from |
| Pull requests and commits | Pull request descriptions, commit messages and a commit message hook |
| Postmortem | Learning from an incident or a defect found in the field |
| Lessons learned | Looking back at the end of a project or phase |
| Task brief for an AI agent | Handing a coding task to an AI agent |
| AGENTS.md for AI agents | Telling AI agents how to work in a repository |
| Conformance profile and component register | Tailoring guidelines to a product, and listing its components |
Templates for delivery and operations.
Files to download¶
The templates that tools read are also available as files.
| File | What it is |
|---|---|
requirement.yaml |
A requirement record |
component-register.yaml |
A component register |
c4-workspace.dsl |
A starter Structurizr workspace |
commit-msg |
A Git hook that checks commit messages |
| Architecture Inception Canvas, draw.io | The inception canvas, to edit in draw.io |
| Architecture Inception Canvas, PowerPoint | The inception canvas, as slides |
| Architecture Communication Canvas, draw.io | The communication canvas, to edit in draw.io |
| Architecture Communication Canvas, PowerPoint | The communication canvas, as slides |
Template files.
The canvases are by Gernot Starke, Patrick Roos, Ben Wolf and the arc42 contributors, under a Creative Commons Attribution-ShareAlike licence (see Architecture canvases).