Actors

What counts as an actor#

An actor is anyone or anything outside your code that interacts with the system. It starts behavior, receives results, or both. Actors give scenarios a subject and make it obvious whom a requirement serves.

Actor fields#

For example, Northwind's Payment provider is an external system that authorizes and captures card payments. It interacts with Billing only. Its note records that an authorization expires if it is not captured within a set number of days, which Billing's requirements have to respect.

Actors in scenarios#

Scenarios name actors in their steps, and SpecsGraph links those names to the actor the same way it links glossary terms. Start the Given step with the actor, so the reader knows whose point of view the scenario takes.

Scenario: Reservations lapse after 15 minutes idle
  Given a Customer has started checkout with 2 line items
  And the Customer has been idle for 15 minutes
  When the reservations are released
  Then the stock for both line items is available again
  And the Customer is asked to confirm the cart before paying

Scenario: Payment is captured once stock is reserved
  Given a Customer has a reservation for every line item
  When the Customer confirms payment
  Then Billing asks the Payment provider to capture the order total

Use the actor's name exactly as it is defined. A step that says the user or the client hides which actor you mean, and reviewers cannot check the scenario against that actor's description.

Keep the list short#

A long actor list is often a list of permissions in disguise. Northwind started with Guest, Customer, Returning customer and VIP customer, then kept only Guest and Customer, because those were the only two its requirements treated differently.

• Skip an actor that no requirement or scenario names yet. Add it when the first one does.
• Merge two actors that appear in the same scenarios with the same outcomes.
• Model things the system stores, such as a product or a warehouse, as glossary terms rather than actors.
• Describe the role, not the person. Support rep outlives whoever holds the job today.

Agents and the actor list#

Agents read the actor list with list_actors before they draft scenarios, so they reuse your names instead of inventing new ones. No MCP tool adds or changes actors. When an agent needs one that is missing, it says so in its reply to you or in a review thread, and a person adds the actor in the web app, in a proposal like any other change. Removing an actor works the same way, and the diff shows every scenario that still names it.

The list is published to specsgraph/actors.md in your repository, next to the glossary.

Next steps#

• Requirements and scenarios to write scenarios around your actors.
• Domain glossary for the terms your actors work with.
• Domain-driven and behavior-driven foundations for the ideas behind actors and scenarios.