But then you look closer. Some dishes are going to the wrong tables. Some customers are receiving meals they did not order. Some plates look beautiful, but the food is cold. Other dishes are correct and customers are happy, but every plate takes twenty steps, three people, two corrections, and a small argument near the oven.

That restaurant does not have one problem. It has three different questions tangled together.

It may be productive because it produces many dishes. It may be ineffective because some dishes do not satisfy the right customers. It may be inefficient because even the good results require too much waste, friction, coordination, and rework.

Software teams live inside the same confusion. We say a team is productive because it closes tickets, merges pull requests, ships features, fixes bugs, writes tests, creates dashboards, or deploys often. Sometimes that is true. Sometimes it is only motion wearing the costume of progress.

The hard part is not producing software. The hard part is producing the right software, in the right amount, with a cost of change the organization can keep carrying.

TL;DR

Productivity, effectiveness, and efficiency are related, but they are not interchangeable.

Productivity asks: what did we produce?

Effectiveness asks: did the work achieve the right result?

Efficiency asks: did we use our resources well while doing it?

In software and product development, confusing these three ideas creates bad decisions. Productivity without effectiveness creates useless output. Effectiveness without efficiency creates expensive progress. Efficiency without effectiveness creates polished waste.

The best teams do not start by asking how to produce more. They ask whether the work matters, how much waste exists in the way they work, and only then how to increase the flow of valuable output.

Index

1. Why this distinction matters in software

2. Productivity: what work was produced?

3. Effectiveness: did the work matter?

4. Efficiency: what did the work cost?

5. How the three ideas are related

6. Output, outcome, throughput, and the missing confusion

7. The first trap: productive but ineffective

8. The second trap: effective but inefficient

9. The third trap: efficient but ineffective

10. Examples from software engineering

11. How teams should use these words

12. Conclusions

13. References

Why this distinction matters in software

Software has a strange property: producing more of it is not automatically good. More code can mean more capability, but it can also mean more maintenance. More features can mean more customer value, but they can also mean more confusion. More tests can mean more confidence, but they can also mean more brittleness. More automation can mean faster feedback, but it can also mean more machinery to understand.

This is why the word “productivity” is dangerous when it is used alone. It sounds positive. It sounds objective. It sounds managerial. But without a clear object, it hides more than it explains.

A developer can look productive by pushing a lot of code. A team can look productive by closing many tickets. A department can look productive by shipping many initiatives. A company can look productive by filling a roadmap with completed items. None of that proves that the product improved, that customers received value, that risk went down, or that the system became easier to change.

Software work is not valuable because it exists. It is valuable when it changes something that matters.

That is the center of the distinction. Productivity is about output. Effectiveness is about outcome. Efficiency is about the cost of getting there. A mature team needs all three, but each one answers a different question.

The diagram matters because the same piece of work can be judged three different ways. A feature can be productive because it was shipped, ineffective because it solved the wrong problem, and inefficient because it left behind unnecessary complexity. One activity. Three questions. Three different judgments.

Productivity: what work was produced?

Productivity is the easiest of the three to see because it leaves visible traces. A pull request was merged. A ticket was closed. A feature was released. A bug was fixed. A test was added. A deployment happened. A migration was completed. A document was written.

There is nothing wrong with caring about this. A team that produces nothing is not secretly excellent. Software development must produce artifacts, decisions, learning, working behavior, and operational improvements. Output matters because without output there is no movement through the system.

The problem starts when productivity is treated as if it already included value. It does not.

A team can produce ten features that customers do not use. It can fix twenty bugs while ignoring the one problem that damages trust every week. It can merge forty pull requests that make the codebase harder to understand. It can add hundreds of tests that protect implementation details but fail to protect meaningful behavior.

Productivity tells us that work happened. It does not tell us whether the work was worth doing.

That is why “this team is productive” is an incomplete sentence. Productive at what? Producing code? Producing features? Producing learning? Producing business outcomes? Producing operational stability? Producing safer change? Producing options for the future?

The object matters. In software, different forms of output have different economic consequences. A line of code is not just a line of code. It is something that may need to be read, tested, reviewed, debugged, secured, deployed, observed, explained, migrated, and eventually removed.

Productivity can also be confused with the rate at which work is completed. A team might produce more work in the same period of time, and that may be useful. But even then, the same warning applies: producing more finished work does not prove that the finished work mattered.

This is the first aha moment: in software, output is not the end of work. Output is the beginning of responsibility.

This is why output needs judgment. Useful output becomes an investment. Useless output becomes inventory. Both may look like productivity on a dashboard, but only one improves the system.

Effectiveness: did the work matter?

Effectiveness asks a harder question: did the work achieve the right result?

A team may ship a feature exactly as requested. The user interface works. The acceptance criteria pass. The release goes out on time. Everyone can honestly say the work was completed. But if users do not need it, if the business problem remains, or if the feature solves a symptom while leaving the real pain untouched, the team was productive but ineffective.

Effectiveness is not about whether effort was spent. It is about whether the work changed reality in the intended direction.

This matters deeply in product development. Product work is not the act of filling a backlog with ideas. It is not translating stakeholder requests into tickets. It is not making roadmaps look organized. Product work is economic judgment under uncertainty. It asks what deserves to exist, why now, for whom, at what cost, with what expected return, and with what opportunity cost.

A customer may ask for a dashboard, but the real need may be faster decision-making. A stakeholder may ask for export functionality, but the real need may be trust in the data. A support team may ask for more configuration, but the real need may be clearer rules and fewer exceptions. A sales team may ask for a custom workflow, but the real question may be whether this customer segment should shape the product at all.

Effectiveness forces teams to move from “we built the requested thing” to “we improved the situation that made the request appear.”

That shift is small in wording and huge in practice. The first version celebrates delivery. The second version asks whether delivery mattered.

The important point is not that requests are bad. Many requests contain useful information. The problem appears when a request becomes work without passing through a product judgment. Building what was asked is not the same as improving the situation that made the request appear.

Efficiency: what did the work cost?

Efficiency asks a different question: did we use our resources well while producing the result?

In software, resources are not only time and money. They include attention, coordination, review capacity, test capacity, deployment capacity, operational capacity, emotional energy, and cognitive load. They also include future capacity, because every decision changes what the team can afford to do next.

A team can be effective and still inefficient. This is common in legacy systems. The team knows the right problem. The product opportunity is real. Customers care. The business case is sound. But every change is painful because the system is hard to understand, hard to test, hard to deploy, and hard to modify safely.

The direction is right, but the cost of movement is too high.

That cost matters because it compounds. If every valuable change requires heroic effort, the organization slowly becomes afraid of its own product. Good ideas become expensive. Small changes become political. Releases become stressful. Refactoring becomes hard to justify because everyone is already late. Testing becomes slower because the system was not designed for feedback. Eventually, the team still wants to improve the product, but the codebase charges a toll on every step.

Efficiency is not about squeezing people to do more with less. That is a shallow and often harmful reading. In a healthy engineering system, efficiency means reducing waste from the path of valuable work.

Waiting is waste. Rework is waste. Unclear requirements are waste. Slow feedback is waste. Fragile tests are waste. Long-lived branches are waste. Manual release rituals are waste when they could be safely automated. Relearning the same confusing module every month is waste. Creating work that another team must untangle later is waste.

Efficiency also does not mean keeping everyone fully utilized. A system can be so full that it stops moving. A road with every lane occupied is not necessarily efficient if no car can move. A team with every person overloaded is not necessarily productive if work cannot reach users.

That is the paradox: what looks efficient in a static snapshot can be destructive in a dynamic system. Full calendars, full queues, and full workloads may look responsible, but if they create waiting, task switching, congestion, and delayed delivery, they are not efficiency. They are gridlock.

Efficiency is about protecting the organization’s ability to move. It is not a photograph of busy people. It is the health of the path from need to outcome.

How the three ideas are related

The three ideas are related because software work has direction, production, and cost.

Effectiveness protects direction. It asks whether the work should exist and whether it changes the right thing.

Efficiency protects capacity. It asks whether the way of working wastes time, attention, coordination, energy, or future changeability.

Productivity protects output. It asks whether the team is producing enough work once the direction is sound and the system is not drowning in waste.

The order matters. If a team starts with productivity, it may produce more of the wrong thing. If it starts with efficiency, it may optimize the delivery of low-value work. If it starts with effectiveness, it first asks whether the work deserves to consume capacity at all.

A strong operating sequence looks like this:

1. Effectiveness first: should we do this, and what result should change?

2. Efficiency second: what is the smallest responsible way to create or test that result with less waste?

3. Productivity third: once the work is valuable and the path is healthy, how do we increase the flow of aligned output?

This sequence is not bureaucracy. It is economic discipline. If direction is wrong, more productivity scales the mistake. If the path is wasteful, more productivity burns capacity faster. If both direction and operating model are sound, productivity becomes powerful.

Output, outcome, throughput, and the missing confusion

There is a related distinction that helps sharpen the argument without replacing it: output, outcome, and throughput.

Output is what the team ships. Outcome is what changes because of that work. Throughput is how much finished work the system can complete over time. These ideas are not the same as productivity, effectiveness, and efficiency, but they help explain why teams confuse them.

Productivity often shows up as output or throughput. A team shipped five features. A team closed thirty work items. A team delivered more changes this month than last month. That may tell us something useful about production and flow, but it does not prove value.

Effectiveness is closer to outcome. It asks what changed because the work entered the world. Did users complete onboarding more easily? Did support pain decrease? Did a risky manual process become safer? Did the product become more useful? Did the business problem actually improve?

Efficiency is related to flow, but it is not the same thing as keeping everyone busy. A team can have high utilization and poor flow. Everyone may be working, switching, replying, reviewing, and attending meetings, while valuable work moves slowly through the system. In that case, the team is not efficient in the sense that matters. It is simply saturated.

This connection matters because teams often use a metric from one category as if it answered another category’s question. They treat shipped features as proof of value. They treat busy people as proof of efficiency. They treat faster delivery as proof of better product judgment.

None of those conclusions necessarily follows.

A better mapping is this:

This keeps the focus where it belongs. The article is not about creating a bigger vocabulary. It is about separating questions that teams often collapse into one vague compliment: “we are productive.”

The phrase “we are productive” becomes useful only after the team clarifies which question it is answering. Without that clarification, it becomes a fog machine. It fills the room, but it does not help anyone see.

The order of things matters

The order matters because productivity, effectiveness, and efficiency do not have the same responsibility in the system.

Effectiveness decides direction. Efficiency protects capacity. Productivity increases output. If we change the order, we change the kind of mistake the team is likely to scale.

Starting with productivity sounds tempting because output is visible. It gives managers something to count, teams something to report, and organizations something to celebrate. More tickets closed. More pull requests merged. More features shipped. More deployments completed. But if the work is not effective, increasing productivity only produces more of the wrong thing.

That is how teams create impressive movement without meaningful progress. They become faster at adding features nobody needs, fixing symptoms instead of causes, automating workflows that should not exist, and producing code the product will carry for years. Productivity is powerful only after direction is clear. Before that, it is an amplifier. It amplifies value when the work matters. It amplifies waste when the work does not.

Starting with efficiency has a different failure mode. It can make the organization feel mature because everything looks smoother. Meetings are shorter. Pipelines are faster. Boards are cleaner. Handoffs are reduced. People seem better coordinated. But if the team has not asked whether the work should exist, efficiency simply makes the wrong work cheaper to produce.

That is polished waste. The system becomes elegant, but not necessarily useful. The team removes friction from a path that may be leading to the wrong destination. A fast delivery system is valuable when product judgment is sound. When judgment is weak, speed becomes a way to move mistakes into production with less resistance.

Starting with effectiveness changes the conversation. It asks whether the work deserves to consume attention, time, money, and future maintenance. It forces the team to clarify the intended change before optimizing the work. What problem should improve? Who should benefit? What risk should go down? What behavior should be different? What would make this work unnecessary?

Once that direction is clear, efficiency becomes useful. The team can ask how to reduce waste while pursuing a meaningful outcome. Can we slice the work smaller? Can we learn before building the full solution? Can we reduce handoffs? Can we improve tests? Can we simplify the design? Can we remove friction from the path of valuable work?

Only then does productivity become healthy. At that point, producing more means producing more aligned work through a system that is not burning unnecessary capacity. The team is no longer trying to maximize activity. It is trying to increase the flow of valuable change.

The wrong order creates three predictable failures:

1. Productivity first: the team produces more before knowing whether the work matters.

2. Efficiency first: the team removes waste from a path that may still point in the wrong direction.

3. Effectiveness first: the team protects direction before improving the way it moves.

That does not mean productivity and efficiency are secondary in importance. It means they depend on context. Efficiency without effectiveness lacks judgment. Productivity without effectiveness lacks purpose. But effectiveness without productivity and efficiency can remain only a good intention.

The strongest order is not philosophical. It is practical:

1. First, ask if the work should exist.

2. Then, ask how to do it with less waste.

3. Finally, ask how to produce more of that valuable work.

Changing the order does not merely change the conversation. It changes what the system learns to reward. If the organization rewards productivity first, people learn to produce visible work. If it rewards efficiency first, people learn to optimize the process. If it rewards effectiveness first, people learn to care about whether reality improved.

That is why the order matters. The first question frames the system. The second question shapes the cost. The third question scales the result.

The first trap: productive but ineffective

The first trap is the most visible in software organizations. A team produces a lot of work, but the product does not get better.

The roadmap moves. The sprint board clears. Pull requests are merged. Demos happen. Release notes are written. Everyone can point to output. But customers do not change behavior. Support pain remains. Revenue does not move. The onboarding problem survives. The operational problem returns next week. The strategic risk stays untouched.

This is productive but ineffective.

It often happens when teams confuse stakeholder demand with validated need. Someone important asks for something. The request enters the backlog. The team breaks it into tickets. The tickets become work. The work becomes output. The output becomes a release. But nobody asks whether the original request was the best way to improve the situation.

The danger is that this trap feels responsible. Everyone is busy. Everyone is doing their part. Nobody is obviously negligent. The machine is working. The problem is that the machine is pointed at the wrong target.

In software economics, this creates inventory. Not only unfinished work, but owned work. Code that must be maintained. Features that must be supported. Configuration that must be understood. Edge cases that must be tested. Documentation that must be updated. User expectations that must be honored.

The team produced work. The system inherited responsibility.

The second trap: effective but inefficient

The second trap is more subtle because it produces real value. The team works on the right thing. Customers benefit. The business improves. The product moves in a good direction. But every improvement costs too much.

This is effective but inefficient.

You see it when a small feature requires touching seven services, coordinating three teams, manually testing ten flows, waiting days for review, and holding your breath during release. You see it when everyone agrees on the right product decision, but the codebase punishes the team for trying to implement it. You see it when the team can still deliver, but only through stress, memory, heroics, and informal knowledge.

This trap often hides behind success. Since the outcome is good, the organization underestimates the damage done by the path. The feature worked, so the process is considered acceptable. The customer is happy, so the technical pain is postponed. The release succeeded, so the release anxiety is normalized.

But the way we produce value shapes the value we can afford to produce next.

If every useful change leaves behind more coupling, more fragile tests, more operational burden, and more cognitive load, the team is not only delivering. It is borrowing against future capacity. Eventually, the organization stops asking what is valuable and starts asking what is survivable.

That is a dangerous moment. It means the cost of change has started to dominate product judgment.

The third trap: efficient but ineffective

The third trap is especially attractive in modern software organizations because it looks clean.

The team has short meetings. The pipeline is fast. The tickets are clear. The dashboards are polished. The ceremonies are optimized. Handoffs are reduced. The delivery process looks smooth. Everything moves.

But the product still does not improve.

This is efficient but ineffective.

Efficiency is not wisdom. A very efficient system can still produce the wrong thing. A perfect factory producing unwanted goods is not a good factory. A software team that delivers the wrong product with low friction is still wasting capacity.

This trap appears when organizations become better at delivery than discovery. They improve execution without improving judgment. They automate the path from idea to production, but they do not improve the quality of the ideas entering the path.

This is how teams create polished waste. The work is well-shaped, well-tracked, well-tested, well-deployed, and well-presented. It is just not worth much.

A fast pipeline does not fix a weak product decision. A clean backlog does not prove the work matters. A smooth process does not compensate for a bad bet.

These three traps are useful because they stop the conversation from becoming moral. The question is not whether a team is good or bad. The question is which kind of failure is present, and which question the team has avoided.

Examples from software engineering

A feature can be judged through all three lenses. Suppose a team delivers a new reporting screen. Productivity asks whether the screen was built and released. Effectiveness asks whether users make better decisions because of it. Efficiency asks whether the team delivered it without unnecessary complexity, rework, or future maintenance burden.

A bug fix works the same way. Productivity asks whether the bug was fixed. Effectiveness asks whether the user pain disappeared or whether the team only patched a symptom. Efficiency asks whether the diagnosis, test coverage, review, and release path were proportional to the risk and impact of the problem.

Refactoring is another useful example because it is often misunderstood. A team spends three days improving a messy module. Productivity says engineering work was produced. Effectiveness asks whether the refactoring made an actual upcoming change safer, cheaper, or easier. Efficiency asks whether the improvement was proportional or whether the team expanded the scope beyond the economic need.

This is where the idea of tidying is helpful. Sometimes the best move before changing behavior is not a grand redesign. It is a small structural improvement that lowers the cost of the next change. Rename something. Move a function. Separate two concerns. Clarify a test. Reduce a little confusion before it charges interest. The point is not to beautify the codebase. The point is to improve the economics of the imminent work.

Automated tests also need the three lenses. A team adds 200 tests. Productive? Yes, tests were produced. Effective? Only if they protect meaningful behavior and catch regressions that matter. Efficient? Only if they give useful feedback without excessive runtime, brittleness, maintenance cost, or diagnostic noise.

Test-Driven Development (TDD) should be understood the same way. It is not productive because many tests exist. It is effective when the tests help clarify behavior, discover design, protect intent, and support safe change. It is efficient when the feedback loop stays small enough to help the team learn quickly without turning the process into ceremony.

Continuous Integration (CI) and Continuous Delivery (CD) also show the distinction clearly. Building a faster pipeline is productive engineering output. It is effective if it improves integration, release safety, and feedback. It is efficient if it reduces waiting, manual coordination, rework, and release anxiety without creating unnecessary operational machinery.

The same activity can be good or bad depending on the lens. That is why teams need sharper language.

The same work should not be judged with one word. A refactoring can be technically impressive and economically weak. A test suite can be large and ineffective. A pipeline can be fast and still irrelevant if it accelerates the wrong decisions.

How teams should use these words

Teams should use productivity, effectiveness, and efficiency as separate conversation tools. Each word should trigger a different discussion.

When discussing productivity, ask what is being produced. Be precise. Do not say “the team is productive” as a general compliment. Say the team is producing more releasable changes, more validated learning, more operational improvements, more useful tests, or more customer-facing value. The object matters.

When discussing effectiveness, ask why the work matters. What problem should change? Who benefits? What behavior should be different? What risk should go down? What decision will this help us make? What would convince us that the work did not matter?

When discussing efficiency, ask where waste appears. Where do we wait? Where do we rework? Where do we lose context? Where do we hand work across boundaries? Where does cognitive load slow us down? Where does the codebase make valuable change unnecessarily expensive?

Also ask one more uncomfortable question: are we calling this efficient only because everyone looks busy? If the answer is yes, the team is probably measuring occupation, not efficiency. The system exists to move valuable work from need to outcome. If it is full but not moving, it is not healthy.

These questions should not be mixed too early. If someone asks whether a team is productive, do not answer with a velocity number before asking productive at what. If someone asks whether a feature was successful, do not answer only with delivery date. If someone asks whether a process is efficient, do not answer only with speed if the output is low-value.

A good team conversation might sound like this:

1. Effectiveness: “This feature shipped, but did it reduce the customer problem we expected to reduce?”

2. Efficiency: “The outcome was good, but why did such a small change take so much coordination?”

3. Productivity: “Now that we know this type of work matters, how can we increase the flow of similar valuable changes?”
   That order changes the culture. It moves the team away from activity worship and toward economic judgment.

This is not a semantic game. It is a practical way to avoid bad management conversations. The team stops using productivity as a moral label and starts using it as one lens among several.

Conclusions

Productivity, effectiveness, and efficiency are simple words, but software makes them easy to confuse.

Productivity means work was produced. Effectiveness means the work achieved the right result. Efficiency means the result was produced with a responsible use of resources. The three ideas are connected, but they are not interchangeable.

This matters because software output does not vanish after delivery. It becomes part of the product’s economic reality. Code must be maintained. Features must be supported. Tests must be trusted. Pipelines must be operated. Decisions must be explained. Complexity must be carried.

That is why producing more is not automatically better. More of the wrong work is inventory. More valuable work through a painful system is fragility. More efficiency in the wrong direction is polished waste.

The best software teams do not use productivity as a moral word. They do not celebrate output before asking whether it mattered. They do not confuse motion with progress, flow with value, or busyness with efficiency.

They separate the questions.

Are we doing the right work?
Are we doing it without unnecessary waste?
Are we producing enough of the work that truly matters?

That is the practical difference. Productivity tells us that the team moved. Effectiveness tells us whether it moved in the right direction. Efficiency tells us whether the movement consumed more than it should.

Strong teams need all three. But they must never pretend they are the same.

References

• Cambridge University Press. Productivity. https://dictionary.cambridge.org/dictionary/english/productivity

• Cambridge University Press. Effectiveness. https://dictionary.cambridge.org/dictionary/english/effectiveness

• Cambridge University Press. Efficiency. https://dictionary.cambridge.org/dictionary/english/efficiency

• Valverde Ramos, Emmanuel. Output, Outcome, and Throughput: What Product Teams are really measuring when they say they deliver value. https://emmanuelvalverderamos.substack.com/p/output-outcome-and-throughput-what

• Valverde Ramos, Emmanuel. The Resource Utilization Trap: Why Keeping Everyone Busy Can Destroy Real Productivity. https://emmanuelvalverderamos.substack.com/p/the-resource-utilization-trap-why

• Forsgren, Nicole; Storey, Margaret-Anne; Maddila, Chandra; Zimmermann, Thomas; Houck, Brian; Butler, Jenna. The SPACE of Developer Productivity. https://queue.acm.org/detail.cfm?id=3454124

• Noda, Abi; Storey, Margaret-Anne; Forsgren, Nicole; Greiler, Michaela. DevEx: What Actually Drives Productivity. https://queue.acm.org/detail.cfm?id=3595878

• Fowler, Martin. Outcome Over Output. https://martinfowler.com/bliki/OutcomeOverOutput.html

• Beck, Kent. Test-Driven Development: By Example. Addison-Wesley, 2003

• Beck, Kent. Tidy First?. O’Reilly Media, 2023

• Reinertsen, Donald G. The Principles of Product Development Flow. Celeritas Publishing, 2009

• Poppendieck, Mary; Poppendieck, Tom. Lean Software Development: An Agile Toolkit. Addison-Wesley, 2003

Practise designing operations as contracts: what must be true before an operation, what happens when the operation is accepted, and what must remain true when the operation is rejected.

This kata is not about records, tables, CRUD screens, or status fields. It is about behaviour, conditions, aftereffects, and safe collaboration.

Business context

A small library lends books to members.

Members can borrow available books up to a fixed limit. A book already borrowed by one member cannot be borrowed by another. A borrowed book may be reserved by another member. When a reserved book is returned, the waiting member gets priority.

Problem to solve

Build the behaviour needed to borrow, return, and reserve books safely.

A member should be able to:

• Borrow an available book

• See their borrowed books

• Return a book they borrowed

• Reserve a book borrowed by another member

• Borrow a returned book that was reserved for them

The library must reject invalid operations and preserve the previous valid state.

Vocabulary

Use this vocabulary to describe the business problem. It is not a proposed implementation model.

• Library

• Book

• Member

• Borrowed book

• Available book

• Waiting member

• Reservation

• Loan limit

• Borrowing request

• Return request

• Reservation request

• Rejected request

Fixed rules

• A member may borrow at most 3 books.

• A book can be borrowed by one member at a time.

• A member cannot reserve a book they already borrowed.

• An available book cannot be reserved.

• A returned reserved book is available only to the waiting member.

• A rejected operation must not change the previous valid state.

Business lifecycle

This diagram describes the business lifecycle of a book in this kata. It is not an implementation model.

Scenario map

Business contracts

Participant checklist

Before moving to the next scenario:

• Is the behaviour covered by a failing test first?

• Is the expected outcome observable from outside the implementation?

• Are previous scenarios still passing?

• Did a rejected operation preserve the previous state?

• Does the test describe behaviour rather than internal data?

• Is there duplication or awkward naming worth refactoring now?

Rule 1: The library starts with no borrowed books

What this rule means

A member who has not borrowed anything should have no borrowed books.

This is the smallest observable behaviour in the kata. It gives the system a clear starting point before any borrowing, returning, or reservation rules appear.

Why this rule matters

Before the library can track changes, it must be clear what the initial state looks like.

A new member should not appear to have borrowed books by default. If the system cannot represent “nothing has happened yet”, every later change becomes harder to trust.

Example

Alice is a library member. She has not borrowed any books.

When the library checks Alice’s borrowed books, none are shown.

Counterexample

Alice has not borrowed anything, but the library shows one or more borrowed books.

That would be wrong because the system would be reporting loans that never happened.

What this rule adds to the kata

This rule anchors the rest of the kata.

Every later scenario either changes this observable state or protects it from invalid operations.

Rule diagram

Scenario 1.1: Show no borrowed books for a new member

Business example

Alice is a member, but she has not borrowed anything yet.

Gherkin

Scenario: Show no borrowed books for a new member
  Given Alice has not borrowed any books
  When the library checks Alice's borrowed books
  Then no borrowed books are shown

Diagram

Rule 2: Available books can be borrowed

What this rule means

A member can borrow a book when that book is available.

After the borrowing succeeds, the book is no longer generally available, and the library can show that the member borrowed it.

This is the first operation with an aftereffect: the world changes after the operation.

Why this rule matters

Borrowing is the central behaviour of the library.

If the system cannot express what changes when a book is borrowed, later rules such as loan limits, returns, and reservations have no foundation.

The important part is not only that the operation succeeds. The important part is that the result of the operation can be observed afterwards.

Example

“Domain-Driven Design” is available.

Alice borrows it.

The book is now borrowed by Alice and appears among Alice’s borrowed books.

Counterexample

“Domain-Driven Design” is available.

Alice borrows it.

The system still reports the book as generally available.

That would be wrong because another member could now borrow the same book.

What this rule adds to the kata

This rule introduces the first accepted state transition.

The kata stops being only a query and becomes behaviour that changes what the library knows.

Rule diagram

Scenario 2.1: Borrow one available book

Business example

Alice borrows a book that nobody else has borrowed.

Gherkin

Scenario: Borrow one available book
  Given "Domain-Driven Design" is available
  When Alice borrows "Domain-Driven Design"
  Then "Domain-Driven Design" is borrowed by Alice

Diagram

Scenario 2.2: Make a borrowed book unavailable

Business example

Once Alice borrows a book, it cannot be treated as generally available.

Gherkin

Scenario: Make a borrowed book unavailable
  Given "Domain-Driven Design" is available
  When Alice borrows "Domain-Driven Design"
  Then "Domain-Driven Design" is not available

Diagram

Scenario 2.3: Show one borrowed book for a member

Business example

The library can show which book Alice borrowed.

Gherkin

Scenario: Show one borrowed book for a member
  Given Alice borrowed "Domain-Driven Design"
  When the library checks Alice's borrowed books
  Then "Domain-Driven Design" is shown for Alice

Diagram

Scenario 2.4: Show several borrowed books for a member

Business example

A member may borrow more than one book.

Gherkin

Scenario: Show several borrowed books for a member
  Given Alice borrowed 3 books
  When the library checks Alice's borrowed books
  Then the library shows 3 borrowed books for Alice

Diagram

Rule 3: Borrowing has limits

What this rule means

A member can borrow up to 3 books.

If they already have 3 borrowed books, a new borrowing request must be rejected.

The important part is not only rejection. The requested book must remain available because the borrowing did not happen.

Why this rule matters

The library has a policy that controls how many books a member can hold at the same time.

The system must protect that policy while keeping the rest of the library state consistent.

This is the first rule where borrowing depends not only on the book, but also on the member’s current situation.

Example

Alice has already borrowed 2 books.

She borrows another available book.

Alice now has 3 borrowed books.

Counterexample

Alice has already borrowed 3 books.

She tries to borrow “Refactoring”.

The request is rejected and “Refactoring” remains available.

What this rule adds to the kata

The kata now has a business policy.

Borrowing is no longer valid just because the book is available. The member’s situation also matters.

Rule diagram

Scenario 3.1: Borrow up to the loan limit

Business example

Alice already borrowed 2 books and borrows one more.

Gherkin

Scenario: Borrow up to the loan limit
  Given Alice already borrowed 2 books
  When Alice borrows another available book
  Then the library shows 3 borrowed books for Alice

Diagram

Scenario 3.2: Reject borrowing above the loan limit

Business example

Alice already borrowed 3 books and cannot borrow a fourth.

Gherkin

Scenario: Reject borrowing above the loan limit
  Given Alice already borrowed 3 books
  When Alice tries to borrow another book
  Then the borrowing request is rejected

Diagram

Scenario 3.3: Keep the book available after exceeding the loan limit

Business example

A failed borrowing request must not make the requested book unavailable.

Gherkin

Scenario: Keep the book available after exceeding the loan limit
  Given Alice already borrowed 3 books
  When Alice tries to borrow "Refactoring"
  Then "Refactoring" remains available

Diagram

Rule 4: A borrowed book cannot be borrowed again

What this rule means

A book borrowed by one member cannot be borrowed by another member.

The system must reject the second borrowing request and preserve the current borrower.

Why this rule matters

This rule protects the basic meaning of borrowing.

If the system allowed another member to borrow the same book, the library would no longer know who actually has it.

This rule also makes rejection more concrete. Rejecting an operation should not silently alter the previous valid state.

Example

Alice borrowed “Refactoring”.

Bob tries to borrow “Refactoring”.

The request is rejected.

Counterexample

Alice borrowed “Refactoring”.

Bob tries to borrow it, and the system changes the borrower from Alice to Bob.

That would be wrong because Bob’s request was invalid.

What this rule adds to the kata

The kata now checks that rejected operations preserve the previous valid state.

Rejection is not just an error result. It is also a promise that the existing library situation has not been damaged.

Rule diagram

Scenario 4.1: Reject borrowing a book borrowed by another member

Business example

Alice has already borrowed a book. Bob cannot borrow the same book.

Gherkin

Scenario: Reject borrowing a book borrowed by another member
  Given Alice borrowed "Refactoring"
  When Bob tries to borrow "Refactoring"
  Then the borrowing request is rejected

Diagram

Scenario 4.2: Keep the current borrower after a rejected borrow

Business example

Bob’s failed borrowing request must not replace Alice as the borrower.

Gherkin

Scenario: Keep the current borrower after a rejected borrow
  Given Alice borrowed "Refactoring"
  When Bob tries to borrow "Refactoring"
  Then "Refactoring" is still borrowed by Alice

Diagram

Rule 5: Borrowed books can be returned

What this rule means

A borrowed book can be returned by the member who borrowed it.

After a valid return, the book can be borrowed again, and it no longer appears among the member’s borrowed books.

Invalid returns must be rejected.

Why this rule matters

Returning is not just the opposite of borrowing. It has its own conditions.

The book must actually be borrowed, and the person returning it must be the borrower.

This rule also makes the lifecycle of a borrowed book more complete: it can move from available, to borrowed, back to borrowable again.

Example

Alice borrowed “Refactoring”.

Alice returns it.

“Refactoring” can be borrowed again, and Alice no longer has it among her borrowed books.

Counterexample

Alice borrowed “Refactoring”.

Bob tries to return it.

The request is rejected because Bob is not the borrower.

What this rule adds to the kata

The kata now has a second operation that changes the same business reality.

Borrowing and returning must agree about what it means for a book to be borrowed, available, and associated with a member.

Rule diagram

Scenario 5.1: Return one borrowed book

Business example

Alice returns a book she borrowed.

Gherkin

Scenario: Return one borrowed book
  Given Alice borrowed "Refactoring"
  When Alice returns "Refactoring"
  Then "Refactoring" can be borrowed again

Diagram

Scenario 5.2: Remove a returned book from the member’s borrowed books

Business example

After returning a book, Alice should no longer see it among her borrowed books.

Gherkin

Scenario: Remove a returned book from the member's borrowed books
  Given Alice borrowed "Refactoring"
  When Alice returns "Refactoring"
  Then the library shows no borrowed books for Alice

Diagram

Scenario 5.3: Reject returning a book that is not borrowed

Business example

Alice cannot return a book that nobody borrowed.

Gherkin

Scenario: Reject returning a book that is not borrowed
  Given "Refactoring" is available
  When Alice tries to return "Refactoring"
  Then the return request is rejected

Diagram

Scenario 5.4: Reject returning a book borrowed by another member

Business example

Bob cannot return a book borrowed by Alice.

Gherkin

Scenario: Reject returning a book borrowed by another member
  Given Alice borrowed "Refactoring"
  When Bob tries to return "Refactoring"
  Then the return request is rejected

Diagram

Rule 6: Borrowed books can be reserved

What this rule means

A member can reserve a book only when another member has borrowed it.

Reserving means the member is waiting for that book.

A member cannot reserve an available book because they can borrow it directly. A member also cannot reserve a book they already borrowed.

Why this rule matters

Reservation introduces future intent.

The book is still borrowed now, but the library must remember that someone else is waiting for it.

This changes the meaning of a later return.

Example

Alice borrowed “Refactoring”.

Bob reserves it.

Bob is now waiting for “Refactoring”.

Counterexample

“Refactoring” is available.

Bob tries to reserve it.

The request is rejected because available books should be borrowed, not reserved.

What this rule adds to the kata

The kata now has behaviour that affects a future operation.

Reserving a book does not make it available immediately, but it changes what should happen when the borrower returns it.

Rule diagram

Scenario 6.1: Reserve a borrowed book

Business example

Alice has borrowed a book. Bob wants to wait for it.

Gherkin

Scenario: Reserve a borrowed book
  Given Alice borrowed "Refactoring"
  When Bob reserves "Refactoring"
  Then Bob is waiting for "Refactoring"

Diagram

Scenario 6.2: Reject reserving an available book

Business example

Bob should borrow an available book, not reserve it.

Gherkin

Scenario: Reject reserving an available book
  Given "Refactoring" is available
  When Bob tries to reserve "Refactoring"
  Then the reservation request is rejected

Diagram

Scenario 6.3: Reject reserving a book borrowed by the same member

Business example

Alice cannot reserve a book she already borrowed.

Gherkin

Scenario: Reject reserving a book borrowed by the same member
  Given Alice borrowed "Refactoring"
  When Alice tries to reserve "Refactoring"
  Then the reservation request is rejected

Diagram

Rule 7: Reservations affect returns

What this rule means

When a reserved book is returned, it does not become generally available to everyone.

It becomes available to the waiting member.

That waiting member has priority. Other members cannot take the book first.

Why this rule matters

This is the key rule in the kata. It changes the meaning of “return”.

Before reservations, returning a book simply made it available. After reservations, returning a book may make it available only to a specific member.

Example

Alice borrowed “Refactoring”.

Bob is waiting for it.

Alice returns it.

“Refactoring” is now available to Bob.

Counterexample

Alice returns “Refactoring”, which Bob was waiting for.

Carol tries to borrow it before Bob.

The request is rejected, and the book remains available to Bob.

What this rule adds to the kata

The kata now forces the reader to think about aftereffects more carefully.

The same operation, returning a book, can have different outcomes depending on the business situation.

Rule diagram

Scenario 7.1: Return a book with one waiting member

Business example

Alice returns a book Bob was waiting for.

Gherkin

Scenario: Return a book with one waiting member
  Given Alice borrowed "Refactoring"
  And Bob is waiting for "Refactoring"
  When Alice returns "Refactoring"
  Then "Refactoring" is available to Bob

Diagram

Scenario 7.2: Allow the waiting member to borrow the returned book

Business example

Bob can borrow the book that was returned for him.

Gherkin

Scenario: Allow the waiting member to borrow the returned book
  Given "Refactoring" is available to Bob
  When Bob borrows "Refactoring"
  Then "Refactoring" is borrowed by Bob

Diagram

Scenario 7.3: Reject borrowing a returned book reserved for another member

Business example

Carol cannot borrow a returned book that is waiting for Bob.

Gherkin

Scenario: Reject borrowing a returned book reserved for another member
  Given "Refactoring" is available to Bob
  When Carol tries to borrow "Refactoring"
  Then the borrowing request is rejected

Diagram

Scenario 7.4: Keep the reservation after a rejected borrow by another member

Business example

Carol’s failed borrowing request must not remove Bob’s priority.

Gherkin

Scenario: Keep the reservation after a rejected borrow by another member
  Given "Refactoring" is available to Bob
  When Carol tries to borrow "Refactoring"
  Then "Refactoring" remains available to Bob

Diagram

This is where many organizations discover that dependency management is not really a system. It is often a collection of local habits. One team relies on package manager audits, another one checks GitHub alerts, another one uses a commercial scanner, another one exports a spreadsheet when compliance asks, and older internal projects may have no current dependency visibility at all. That can feel manageable while nothing happens. It becomes expensive when a real supply-chain incident forces the organization to answer portfolio-level questions quickly.

The TanStack npm supply-chain compromise is a useful example because it was not only a story about a malicious package version. The postmortem describes a chain that involved CI trust boundaries, GitHub Actions cache poisoning, OIDC token extraction, malicious package publishing, and payload execution during package installation. That matters because modern software delivery has more execution surfaces than production alone. Code can run on developer machines, CI runners, package installation hooks, test environments, release workflows, container builds, deployment automation, and supporting tools. Some of those places also hold credentials, tokens, caches, and publishing permissions.

Dependency-Track does not solve all of that. It will not secure a GitHub Actions workflow by itself, rotate secrets, validate every maintainer account, or prevent a malicious package from being published. Its value is different. It gives the organization a continuously updated inventory of what its software is made of, where each component is used, which risks are associated with those components, how those risks are being triaged, and which policies are being violated across the portfolio.

That is why Dependency-Track is so relevant for DevEx. Good developer experience is not only about making the happy path fast. It is about making the safe path easy, visible, repeatable, and boring. A developer should not need to become a supply-chain investigator every time a new CVE appears. The delivery system should generate the evidence, upload it automatically, analyze it centrally, and route useful feedback to the right people.

TL;DR

Dependency-Track is an OWASP software supply-chain component analysis platform built around SBOMs, especially CycloneDX

Its main value is not scanning one repository once, but continuously monitoring the components used across projects and versions

It helps teams answer impact questions when a vulnerability, malicious package, license problem, or operational policy violation appears

It works well in CI/CD because pipelines can generate SBOMs and upload them automatically after build, packaging, or release

It is ecosystem agnostic, which makes it useful for organizations with multiple languages, package managers, container images, services, and internal libraries

It supports vulnerability intelligence, policy compliance, triage workflows, notifications, REST API automation, OpenAPI documentation, and integrations with delivery and collaboration tools

It should not be treated as a replacement for secure CI, dependency update discipline, package provenance, secret hygiene, incident response, or engineering judgment

Taskfile improves the workflow because it turns SBOM generation, validation, upload, health checks, local experimentation and CI integration into repeatable commands

Its strongest DevEx value is reducing manual discovery work, lowering coordination cost, and making supply-chain risk visible before the next emergency

Index

1. The real problem Dependency-Track solves

2. Why SBOM-first changes the conversation

3. What the TanStack incident teaches us

4. What Dependency-Track is

5. What Dependency-Track is not

6. Core concepts

7. How the platform works

8. Installation options

9. First local setup with Docker Compose

10. Production setup considerations

11. Kubernetes deployment

12. Creating projects

13. Generating SBOMs

14. Uploading SBOMs

15. CI/CD integration

16. GitHub Actions example

17. Jenkins approach

18. Working with multiple ecosystems

19. Improving DevEx with Taskfile

20. Policies that actually help teams

21. Triage workflow

22. Notifications

23. Dashboards and portfolio visibility

24. REST API and automation

25. Security patterns around Dependency-Track

26. How to use it during an incident

27. How it helps with supply-chain attacks

28. Common mistakes

29. Adoption roadmap

30. Conclusions

31. References

1. The real problem Dependency-Track solves

The problem is not that teams use dependencies. Modern software is dependency-shaped. A small frontend can include hundreds or thousands of packages once transitive dependencies are counted. A backend service may depend on frameworks, logging libraries, serialization libraries, database drivers, build plugins, test libraries, container base images, operating system packages, CI actions, deployment tools, and internal shared libraries. Even if a team writes a modest amount of application code, the delivered system is usually assembled from a large amount of external and internal software.

The real problem is that dependency knowledge is usually trapped in places that are not designed to answer organizational questions. A lockfile can tell one repository what it resolved at one moment. A package manager audit can warn one project about known issues. A vulnerability scanner can raise findings. A spreadsheet can satisfy a compliance request once. A ticket can track a remediation task. None of these, by themselves, gives the organization a living view of component usage across the software portfolio.

Supply-chain incidents do not respect repository boundaries. When a package is compromised, deprecated, vulnerable, legally risky, modified, or operationally forbidden, the organization needs to know where it appears. That means direct dependencies, transitive dependencies, released versions, active branches, deployed containers, internal libraries, and sometimes build-time tools. Dependency-Track helps by turning SBOMs into a central inventory that can be analyzed continuously.

This is the core value of the tool. Dependency-Track is not merely a scanner. It is an inventory, analysis, policy, triage, notification, and automation platform for software composition. It helps teams move from local dependency awareness to portfolio-level dependency intelligence.

2. Why SBOM-first changes the conversation

A Software Bill of Materials is an inventory of the components that make up a software system. The idea sounds simple, but the operational impact is significant. Without an SBOM, every supply-chain question starts with discovery. With an SBOM, discovery becomes a maintained asset that can be queried when new information appears.

That distinction matters because incidents punish slow discovery. If an organization first has to identify every service, ask every team, inspect every repository, infer every transitive dependency, and manually compare versions, response time is constrained by organizational memory. The more systems the organization owns, the more expensive this becomes.

An SBOM-first operating model changes the flow. The build generates evidence. The pipeline uploads that evidence. Dependency-Track stores and analyzes it. New vulnerability intelligence, license data, or policy rules can then be matched against existing projects without requiring every team to manually rebuild its understanding of the dependency graph.

This is why Dependency-Track is more powerful than a one-time dependency scan. A scan answers a moment. A continuously updated SBOM portfolio answers change. That is the difference between a report and an operational capability.

3. What the TanStack incident teaches us

The TanStack npm supply-chain compromise is important because it shows how dependency risk can cross boundaries between source control, CI automation, package publishing, package installation, and credential exposure. The attack was not simply a vulnerable library being used in production. It involved trust relationships inside the delivery system.

The postmortem describes how a workflow pattern, cache poisoning, and token extraction contributed to malicious package publication. The payload could then run during package installation and attempt to collect credentials from common developer and CI locations. This is an uncomfortable reminder that installation can be execution, and that CI is part of the trusted computing base of modern software delivery.

Dependency-Track helps with one part of this situation: impact analysis. If affected package names and versions are known, a team can use Dependency-Track to identify where those components appear across the portfolio, which projects include them, and which owners need to respond. That does not replace secret rotation, runner hardening, workflow review, package provenance, or incident response. But it can reduce the time between external intelligence and internal understanding.

That time matters. During a supply-chain incident, the first cost is often not remediation. The first cost is finding out whether the organization is affected at all.

4. What Dependency-Track is

Dependency-Track is an OWASP component analysis platform focused on software supply-chain risk. Its normal workflow is straightforward: teams generate SBOMs for their software, upload those SBOMs to Dependency-Track, and the platform correlates the listed components with vulnerability intelligence, license information, policy rules, and project metadata.

The platform is API-first, which is important because the best way to use it is through automation. Developers should not need to manually upload files after every release. CI/CD pipelines should generate SBOMs and publish them automatically from trusted contexts. The platform then becomes part of the delivery feedback loop instead of an occasional compliance activity.

Dependency-Track is strongly aligned with CycloneDX. It consumes and produces CycloneDX SBOMs and supports CycloneDX VEX, which helps express whether a known vulnerability is exploitable, not affected, fixed, or otherwise understood in a specific product context. That distinction is critical because raw vulnerability counts are noisy. Useful vulnerability management depends on context, ownership, triage, and recorded decisions.

5. What Dependency-Track is not

Dependency-Track is not a silver bullet. It is not a replacement for secure build pipelines, dependency update discipline, lockfiles, package signing, provenance, secret scanning, runtime monitoring, code review, maintainership due diligence, or incident response. It improves visibility and coordination, but it does not remove the need for engineering judgment.

This boundary matters because a tool can create false confidence if it is misunderstood. Dependency-Track can show that a component exists in a project and that a vulnerability is associated with it. It cannot prove by itself that the vulnerable code path is reachable. It can raise a policy violation, but it cannot decide the organization’s risk appetite. It can record that a finding is not affected, but that statement is only useful if the analysis behind it is real.

Used well, Dependency-Track becomes part of how the organization learns and responds. Used badly, it becomes another dashboard that accumulates unresolved warnings.

6. Core concepts

A project represents a software product, application, service, library, container, firmware image, or other deliverable whose components you want to track. A project usually has a name and a version. The version can represent a release, an environment, a build number, a Git SHA, or another convention that matches how the organization needs to reason about impact.

A component is something the software is made of. That can include libraries, frameworks, application dependencies, operating system packages, containers, firmware, files, hardware, and services. Components may be identified through package URLs, CPEs, SWIDs, hashes, names, versions, licenses, and ecosystem-specific metadata.

An SBOM is the inventory uploaded to Dependency-Track. The platform is only as useful as the SBOMs it receives. An incomplete SBOM creates incomplete visibility. A stale SBOM creates historical evidence, not current operational knowledge. The practical goal is to generate an SBOM that represents what the team actually builds, packages, deploys, and operates.

A vulnerability is a known weakness associated with a component. Dependency-Track can correlate components with vulnerability intelligence sources and show where affected components exist across projects. The value is not only seeing that a CVE exists. The value is seeing how that CVE intersects with the organization’s software estate.

A policy is a rule that expresses what the organization considers acceptable or unacceptable. Dependency-Track supports security, license, and operational policy violations. A policy can raise a violation for a critical vulnerability, a forbidden license, an outdated component, an unauthorized package coordinate, or another condition that the organization wants to make visible.

An analysis state records the triage decision for a finding. Dependency-Track supports states such as exploitable, in triage, false positive, not affected, and not set. These states matter because real vulnerability management is not binary. A finding can be technically valid but not exploitable in the product’s context. Another finding can be a false positive due to incorrect component identification. Another one can be exploitable and urgent.

Suppression is used to hide or reduce noise from reviewed findings. It should be used carefully. A suppressed finding without evidence is hidden risk. A suppressed finding with context, owner, reason, and review expectations can be part of healthy triage.

7. How the platform works

The operating model is simple. Source code is built or packaged. The build process generates an SBOM. The SBOM is uploaded to Dependency-Track. The platform identifies components, correlates them with vulnerability intelligence and policy rules, and creates findings. Teams then triage those findings, remediate issues, suppress reviewed noise, or document why a project is not affected.

The important part is the loop. Dependency-Track should not be an end-of-quarter compliance exercise. It should be part of normal delivery. Every meaningful build or release should update the inventory. Every updated inventory should trigger analysis. Every important finding should create feedback. Every decision should leave history.

8. Installation options

Dependency-Track can be deployed in different ways depending on the level of maturity required. For local evaluation, Docker Compose is the fastest option. For production-like environments, Docker Compose with an external database may be enough for smaller installations. For Kubernetes environments, the official route is the Helm chart. More customized deployments can run the API server and frontend separately.

The platform has two main runtime parts: the API server and the frontend. This distinction matters because the frontend is static and the user’s browser must be able to reach the API server. A deployment that works inside the container network may still fail from the browser if the API base URL is not reachable externally.

For production, use an external database and treat the platform as security infrastructure. The Kubernetes documentation notes that the Helm chart default uses embedded H2, which is not intended for production usage.

9. First local setup with Docker Compose

For local evaluation, create a working directory and use the official Compose setup:

mkdir dependency-track-lab
cd dependency-track-lab
curl -LO https://dependencytrack.org/docker-compose.yml
docker compose up -d
docker compose ps

The frontend is commonly exposed on port 8080, while the API server is commonly exposed on port 8081. The API server is also where the OpenAPI documentation is exposed.

Frontend: http://localhost:8080
API:      http://localhost:8081

After creating an API key in the UI, set local environment variables:

export DTRACK_URL="http://localhost:8081"
export DTRACK_API_KEY="replace-with-your-api-key"

Then test connectivity:

curl -s \
  -H "X-Api-Key: ${DTRACK_API_KEY}" \
  "${DTRACK_URL}/api/version"

A small script improves the developer experience because it makes the safe path repeatable:

#!/usr/bin/env bash
set -euo pipefail

: "${DTRACK_URL:?DTRACK_URL is required}"
: "${DTRACK_API_KEY:?DTRACK_API_KEY is required}"

curl -s \
  -H "X-Api-Key: ${DTRACK_API_KEY}" \
  "${DTRACK_URL}/api/version"

10. Production setup considerations

A production Dependency-Track installation should have an external database, persistent storage, backups, TLS, authentication, authorization, restricted administration, API key rotation, monitoring, notification routing, and a clear upgrade process. It should also have conventions for project naming, versioning, ownership, tagging, stale project handling, and triage expectations.

This is not only operational housekeeping. Dependency-Track contains sensitive information about the organization’s software estate. A user with broad access can see internal projects, components, vulnerable dependencies, policy violations, and sometimes technology choices that reveal architecture and risk. Access should be granted intentionally.

A reasonable production checklist includes:

• External database

• Persistent storage

• Backups and restore tests

• TLS

• OIDC or LDAP integration

• Least-privilege teams and roles

• Separate API keys per automation context

• API key rotation

• Restricted administrator access

• Monitoring for API server and worker health

• Monitoring for BOM processing failures

• Monitoring for feed synchronization failures

• Notification routing

• Upgrade process

• Project ownership conventions

• Stale project review process

11. Kubernetes deployment

Dependency-Track can be installed on Kubernetes with Helm:

helm repo add dependency-track https://dependencytrack.github.io/helm-charts
helm repo update

helm install dtrack dependency-track/dependency-track \
  --namespace dtrack \
  --create-namespace

This is a starting point, not a production design. For production, configure an external database, ingress, TLS, resource requests, resource limits, persistent storage, OIDC or LDAP integration, network policies, secret management, backups, logs, and metrics.

A useful deployment model looks like this:

The browser must be able to reach the API server, not only the frontend. CI pipelines also need access to the API server to upload SBOMs.

12. Creating projects

Projects can be created manually, but CI automation is usually better. Dependency-Track supports uploading a BOM with projectName, projectVersion, and autoCreate=true, which allows the project to be created automatically if it does not exist.

curl -sS -X POST "${DTRACK_URL}/api/v1/bom" \
  -H "X-Api-Key: ${DTRACK_API_KEY}" \
  -F "autoCreate=true" \
  -F "projectName=checkout-api" \
  -F "projectVersion=1.0.0" \
  -F "bom=@bom.json"

Automatic creation is useful, but only if the organization has naming conventions. Otherwise, the portfolio can become polluted with inconsistent project names and versions. A practical convention is to use the repository or product name as the project name, the release version or deployment environment as the project version, and tags for team, domain, business capability, runtime, and criticality.

Good naming is not cosmetic. It improves incident response.

13. Generating SBOMs

Dependency-Track consumes SBOMs, so each ecosystem should generate CycloneDX using the most appropriate tool for that build. The organization does not need every team to use the same package manager or language. It needs every team to publish comparable evidence.

For Node.js:

npx @cyclonedx/cyclonedx-npm --output-file bom.json

For Maven:

mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom

For Gradle:

./gradlew cyclonedxBom

For .NET:

dotnet CycloneDX ./src/MyProject.sln --output ./sbom

For Python requirements:

cyclonedx-py requirements requirements.txt -o bom.json

For container images with Syft:

syft my-image:latest -o cyclonedx-json=bom.json

The key rule is to generate the SBOM as close as possible to the artifact you actually ship. Source-level SBOMs are useful, but final container image SBOMs can reveal operating system packages and image-layer dependencies that source-level generation may miss.

14. Uploading SBOMs

The most common upload approach is multipart form data through the API:

curl -sS -X POST "${DTRACK_URL}/api/v1/bom" \
  -H "X-Api-Key: ${DTRACK_API_KEY}" \
  -F "autoCreate=true" \
  -F "projectName=${PROJECT_NAME}" \
  -F "projectVersion=${PROJECT_VERSION}" \
  -F "bom=@${BOM_FILE}"

A more defensive script is better for team usage:

#!/usr/bin/env bash
set -euo pipefail

: "${DTRACK_URL:?DTRACK_URL is required}"
: "${DTRACK_API_KEY:?DTRACK_API_KEY is required}"
: "${PROJECT_NAME:?PROJECT_NAME is required}"
: "${PROJECT_VERSION:?PROJECT_VERSION is required}"
: "${BOM_FILE:?BOM_FILE is required}"

if [[ ! -f "${BOM_FILE}" ]]; then
  echo "SBOM file not found: ${BOM_FILE}" >&2
  exit 1
fi

curl -sS -X POST "${DTRACK_URL}/api/v1/bom" \
  -H "X-Api-Key: ${DTRACK_API_KEY}" \
  -F "autoCreate=true" \
  -F "projectName=${PROJECT_NAME}" \
  -F "projectVersion=${PROJECT_VERSION}" \
  -F "bom=@${BOM_FILE}"

This kind of small automation matters for DevEx. It reduces friction, avoids copy-and-paste errors, and gives teams a repeatable path.

15. CI/CD integration

The CI/CD integration should be boring. A good pipeline does not ask developers to remember Dependency-Track. It generates the SBOM and uploads it automatically from a trusted context.

A practical flow is:

The order matters. If the SBOM is generated before dependency resolution, it may not represent the real graph. If it is generated before packaging, it may miss runtime components. If SBOMs are generated manually from developer machines, the organization loses consistency.

For higher maturity, teams can generate separate SBOMs for application dependencies, container images, internal libraries, and released artifacts. That does not need to happen on day one, but the model should be understood from the beginning.

16. GitHub Actions example

A simple Node.js workflow can generate and upload an SBOM:

name: sbom

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read

jobs:
  generate-and-upload-sbom:
    runs-on: ubuntu-latest

    env:
      PROJECT_NAME: checkout-api
      PROJECT_VERSION: main
      BOM_FILE: bom.json

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Generate CycloneDX SBOM
        run: npx @cyclonedx/cyclonedx-npm --output-file "${BOM_FILE}"

      - name: Upload SBOM to Dependency-Track
        env:
          DTRACK_URL: ${{ secrets.DTRACK_URL }}
          DTRACK_API_KEY: ${{ secrets.DTRACK_API_KEY }}
        run: |
          set -euo pipefail

          curl -sS -X POST "${DTRACK_URL}/api/v1/bom" \
            -H "X-Api-Key: ${DTRACK_API_KEY}" \
            -F "autoCreate=true" \
            -F "projectName=${PROJECT_NAME}" \
            -F "projectVersion=${PROJECT_VERSION}" \
            -F "bom=@${BOM_FILE}"

For production usage, the workflow should be tightened. Keep permissions minimal, avoid exposing API keys to forked pull requests, use trusted branches or release workflows for uploads, rotate secrets, and review any workflow pattern that gives untrusted code access to privileged tokens. The TanStack incident makes this especially important because CI security is part of supply-chain security.

17. Jenkins approach

Dependency-Track has a Jenkins plugin, and Jenkins environments can also upload SBOMs directly through the API. The pipeline shape is similar: checkout, install, test, build, generate SBOM, publish SBOM.

pipeline {
  agent any

  environment {
    PROJECT_NAME = 'checkout-api'
    PROJECT_VERSION = "${env.BUILD_NUMBER}"
    BOM_FILE = 'bom.json'
  }

  stages {
    stage('Install') {
      steps {
        sh 'npm ci'
      }
    }

    stage('Test') {
      steps {
        sh 'npm test'
      }
    }

    stage('Generate SBOM') {
      steps {
        sh 'npx @cyclonedx/cyclonedx-npm --output-file bom.json'
      }
    }

    stage('Upload SBOM') {
      steps {
        withCredentials([
          string(credentialsId: 'dependency-track-api-key', variable: 'DTRACK_API_KEY'),
          string(credentialsId: 'dependency-track-url', variable: 'DTRACK_URL')
        ]) {
          sh '''
            set -euo pipefail

            curl -sS -X POST "${DTRACK_URL}/api/v1/bom" \
              -H "X-Api-Key: ${DTRACK_API_KEY}" \
              -F "autoCreate=true" \
              -F "projectName=${PROJECT_NAME}" \
              -F "projectVersion=${PROJECT_VERSION}" \
              -F "bom=@${BOM_FILE}"
          '''
        }
      }
    }
  }
}

The same security rule applies. The Dependency-Track API key should be available only in trusted jobs that need to upload SBOMs.

18. Working with multiple ecosystems

Dependency-Track is useful because it is not tied to one ecosystem. A real product may include a React frontend, a Java backend, a Python worker, a .NET internal service, a container base image, Terraform modules, GitHub Actions, and shared internal packages. A single language-specific scanner cannot represent that whole system well.

The better model is to standardize the evidence format, not the entire engineering stack. Each ecosystem can generate CycloneDX in the way that fits its build. Dependency-Track then provides the shared analysis layer.

This is especially important for DevEx. Developers keep using the tools that make sense for their context, while the organization gets consistent visibility.

19. Improving DevEx with Taskfile

Dependency-Track becomes much more valuable when developers do not need to remember how to use it. The worst version of an SBOM workflow is a README section full of long commands that every team copies, modifies, forgets, and eventually breaks. The better version is a small set of repeatable tasks that work locally and in CI with the same interface.

This is where Taskfile fits naturally. Task gives the project a cross-platform command layer that can hide incidental complexity without hiding the important decisions. A developer should not need to remember the exact CycloneDX command, the Dependency-Track endpoint, the required form fields, or the right curl flags. The repository can expose a few intention-revealing commands instead:

task sbom:generate
task sbom:upload
task sbom:publish
task dtrack:health

That changes the developer experience. Instead of asking every team to become familiar with Dependency-Track’s API, the project gives them a paved road. The details still exist, but they live in one place. The workflow becomes easier to run locally, easier to reuse in CI, easier to document, and easier to evolve when the organization changes its conventions.

A simple Taskfile can start like this:

version: '3'

vars:
  PROJECT_NAME:
    sh: basename "$(pwd)"
  PROJECT_VERSION:
    sh: git rev-parse --short HEAD
  BOM_FILE: bom.json

tasks:
  dtrack:health:
    desc: Check that Dependency-Track API is reachable
    cmds:
      - |
        set -euo pipefail

        : "${DTRACK_URL:?DTRACK_URL is required}"
        : "${DTRACK_API_KEY:?DTRACK_API_KEY is required}"

        curl -sS \
          -H "X-Api-Key: ${DTRACK_API_KEY}" \
          "${DTRACK_URL}/api/version"

  sbom:generate:
    desc: Generate a CycloneDX SBOM for this project
    cmds:
      - npx @cyclonedx/cyclonedx-npm --output-file "{{.BOM_FILE}}"
    sources:
      - package.json
      - package-lock.json
    generates:
      - '{{.BOM_FILE}}'

  sbom:upload:
    desc: Upload the generated SBOM to Dependency-Track
    deps:
      - sbom:generate
    cmds:
      - |
        set -euo pipefail

        : "${DTRACK_URL:?DTRACK_URL is required}"
        : "${DTRACK_API_KEY:?DTRACK_API_KEY is required}"

        test -f "{{.BOM_FILE}}"

        curl -sS -X POST "${DTRACK_URL}/api/v1/bom" \
          -H "X-Api-Key: ${DTRACK_API_KEY}" \
          -F "autoCreate=true" \
          -F "projectName={{.PROJECT_NAME}}" \
          -F "projectVersion={{.PROJECT_VERSION}}" \
          -F "bom=@{{.BOM_FILE}}"

  sbom:publish:
    desc: Generate and upload the SBOM
    cmds:
      - task: sbom:upload

This is already better than a loose script because the tasks communicate intent. sbom:generate creates the evidence. sbom:upload sends it to Dependency-Track. sbom:publish gives CI and developers one stable entry point. If the implementation changes later, the interface can stay the same.

For local development, environment variables can be loaded from a .env file, while CI can inject them through its secret store. That keeps secrets out of the repository and avoids forcing developers to paste API keys into commands.

version: '3'

dotenv:
  - .env
  - '{{.HOME}}/.config/dependency-track/.env'

vars:
  PROJECT_NAME:
    sh: basename "$(pwd)"
  PROJECT_VERSION:
    sh: git rev-parse --short HEAD
  BOM_FILE: bom.json

A local .env file can look like this:

DTRACK_URL=http://localhost:8081
DTRACK_API_KEY=replace-with-your-local-api-key

The .env file should be ignored by Git:

.env
bom.json

This small detail matters. Good DevEx does not ask people to choose between convenience and safety. It gives them a convenient path that is also safe by default.

Taskfile also helps when the organization supports multiple ecosystems. A frontend, backend, worker, and container image may need different SBOM generation commands, but the public interface can stay consistent.

version: '3'

tasks:
  sbom:node:
    desc: Generate SBOM for a Node.js project
    cmds:
      - npx @cyclonedx/cyclonedx-npm --output-file bom-node.json
    sources:
      - package.json
      - package-lock.json
    generates:
      - bom-node.json

  sbom:maven:
    desc: Generate SBOM for a Maven project
    cmds:
      - mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom
    sources:
      - pom.xml

  sbom:container:
    desc: Generate SBOM for a container image
    vars:
      IMAGE: '{{.IMAGE | default "checkout-api:local"}}'
      BOM_FILE: bom-container.json
    cmds:
      - syft "{{.IMAGE}}" -o cyclonedx-json="{{.BOM_FILE}}"
    generates:
      - bom-container.json

  sbom:all:
    desc: Generate all SBOMs for this repository
    cmds:
      - task: sbom:node
      - task: sbom:container

This keeps ecosystem-specific complexity inside the repository while preserving a shared organizational pattern. Teams can adapt the internal command for their stack without changing the mental model. The frontend team, backend team, and platform team can all say “run the SBOM task” and mean the same kind of workflow.

For CI/CD, Taskfile can reduce duplication. Instead of writing the full SBOM logic inside GitHub Actions, GitLab CI, Jenkins, or Azure Pipelines, the pipeline can call the same task developers use locally.

name: sbom

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read

jobs:
  publish-sbom:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Task
        uses: arduino/setup-task@v2

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Publish SBOM
        env:
          DTRACK_URL: ${{ secrets.DTRACK_URL }}
          DTRACK_API_KEY: ${{ secrets.DTRACK_API_KEY }}
        run: task sbom:publish

This is a better maintenance model. The CI file describes the delivery flow, while the Taskfile owns the project workflow. When the SBOM generator changes, the team changes the Taskfile once. When the Dependency-Track upload convention changes, the team changes the Taskfile once. When a developer wants to reproduce the CI behavior locally, they run the same command.

Taskfile can also make safety checks explicit. Before uploading an SBOM, the task can verify that required environment variables exist, that the SBOM file was generated, that the Dependency-Track API is reachable, and that the upload only happens from an expected branch or trusted CI context.

version: '3'

tasks:
  sbom:check-env:
    desc: Validate required Dependency-Track environment variables
    cmds:
      - |
        set -euo pipefail

        : "${DTRACK_URL:?DTRACK_URL is required}"
        : "${DTRACK_API_KEY:?DTRACK_API_KEY is required}"

  sbom:check-file:
    desc: Validate that the SBOM file exists
    vars:
      BOM_FILE: '{{.BOM_FILE | default "bom.json"}}'
    cmds:
      - test -s "{{.BOM_FILE}}"

  sbom:upload:
    desc: Upload SBOM to Dependency-Track
    deps:
      - sbom:check-env
      - sbom:generate
      - sbom:check-file
    cmds:
      - |
        set -euo pipefail

        curl -sS -X POST "${DTRACK_URL}/api/v1/bom" \
          -H "X-Api-Key: ${DTRACK_API_KEY}" \
          -F "autoCreate=true" \
          -F "projectName={{.PROJECT_NAME}}" \
          -F "projectVersion={{.PROJECT_VERSION}}" \
          -F "bom=@{{.BOM_FILE}}"

This is a small example, but the design principle is important. A good DevEx workflow should fail early, fail clearly, and fail before doing something risky. Missing secrets, missing SBOMs, wrong project names, and unreachable APIs should be discovered by the task, not by a developer reading a vague CI failure five minutes later.

For larger organizations, split Taskfiles can keep the workflow maintainable. A root Taskfile.yml can include a shared Dependency-Track task file. Each repository can then keep a small local file while reusing the same organizational conventions.

version: '3'

includes:
  dtrack:
    taskfile: ./tasks/Taskfile.dtrack.yml

tasks:
  sbom:publish:
    desc: Publish this project SBOM to Dependency-Track
    cmds:
      - task: dtrack:publish

The included file can contain the standard implementation:

version: '3'

vars:
  PROJECT_NAME:
    sh: basename "$(pwd)"
  PROJECT_VERSION:
    sh: git rev-parse --short HEAD
  BOM_FILE: bom.json

tasks:
  generate:
    desc: Generate CycloneDX SBOM
    cmds:
      - npx @cyclonedx/cyclonedx-npm --output-file "{{.BOM_FILE}}"

  publish:
    desc: Generate and upload SBOM to Dependency-Track
    deps:
      - generate
    cmds:
      - |
        set -euo pipefail

        : "${DTRACK_URL:?DTRACK_URL is required}"
        : "${DTRACK_API_KEY:?DTRACK_API_KEY is required}"

        curl -sS -X POST "${DTRACK_URL}/api/v1/bom" \
          -H "X-Api-Key: ${DTRACK_API_KEY}" \
          -F "autoCreate=true" \
          -F "projectName={{.PROJECT_NAME}}" \
          -F "projectVersion={{.PROJECT_VERSION}}" \
          -F "bom=@{{.BOM_FILE}}"

This pattern is especially useful when Dependency-Track adoption moves beyond one team. The organization can provide a recommended task module, while each repository can override variables such as project name, version, image name, or SBOM generator. That gives teams flexibility without losing consistency.

A mature setup can go further and use Taskfile as the local command surface for the whole supply-chain workflow:

task dtrack:up
task dtrack:health
task sbom:generate
task sbom:validate
task sbom:upload
task sbom:publish
task sbom:container
task sbom:clean

For example:

version: '3'

tasks:
  dtrack:up:
    desc: Start local Dependency-Track for experimentation
    cmds:
      - docker compose -f docker-compose.dependency-track.yml up -d

  dtrack:down:
    desc: Stop local Dependency-Track
    cmds:
      - docker compose -f docker-compose.dependency-track.yml down

  sbom:clean:
    desc: Remove generated SBOM files
    cmds:
      - rm -f bom.json bom-node.json bom-container.json

  sbom:validate:
    desc: Validate that the generated SBOM exists and is valid JSON
    vars:
      BOM_FILE: '{{.BOM_FILE | default "bom.json"}}'
    cmds:
      - test -s "{{.BOM_FILE}}"
      - jq empty "{{.BOM_FILE}}"

  sbom:publish:
    desc: Generate, validate, and upload SBOM
    cmds:
      - task: sbom:generate
      - task: sbom:validate
      - task: sbom:upload

The point is not to create a beautiful Taskfile for its own sake. The point is to reduce the cost of doing the right thing. A workflow that can be run with one command is easier to adopt, easier to teach, easier to automate, and easier to debug.

This also improves onboarding. A new developer does not need to read the whole Dependency-Track guide before contributing. They can run:

task --list

and see the available workflows. The Taskfile becomes executable documentation. It shows what the project expects, how SBOMs are generated, how they are uploaded, and which commands are safe to run locally.

The economic value is clear. Taskfile reduces coordination cost because teams share a common command vocabulary. It reduces cognitive load because developers do not need to remember long commands. It reduces operational variation because CI and local workflows can call the same tasks. It reduces incident response cost because SBOM generation and upload are already part of the normal workflow before an incident happens.

That is the right relationship between Dependency-Track and Taskfile. Dependency-Track provides the organizational memory of software composition. Taskfile provides the repeatable developer interface that keeps that memory fresh. One gives visibility. The other makes the workflow easy enough that teams actually use it.

20. Policies that actually help teams

Policies should create clarity, not noise. A useful policy is clear, actionable, explainable, owned, reviewable, and proportional to risk. A bad policy turns Dependency-Track into a noisy compliance machine that teams learn to ignore.

Good initial policies are simple. For security, a team might raise a violation when a production project has a critical vulnerability. For license governance, a team might flag forbidden licenses in customer-distributed software. For operational risk, a team might identify prohibited package coordinates or components that are too old compared with the latest known version.

A healthy rollout usually starts with visibility before enforcement. First observe findings, understand noise, define ownership, and teach triage. Then introduce policies and notifications. Only after the organization can respond reliably should selected gates be added to delivery workflows.

A policy that nobody can act on is not a control. It is just inventory with a threatening label.

21. Triage workflow

Triage is where Dependency-Track becomes useful. A finding without triage is only an alarm. A triaged finding becomes organizational knowledge.

The analysis states should be used honestly. False positive should mean the finding is wrong. Not affected should mean the finding is real but does not affect the project in its context. In triage should mean someone is actively investigating. Exploitable should mean the issue is exploitable or likely exploitable in this project. Not set should not become the place where findings go to be forgotten.

The quality of triage determines the quality of the system.

22. Notifications

Dependency-Track supports notifications for system and portfolio events. Notifications can be routed to collaboration tools, email, webhooks, Jira, and other integrations depending on the setup.

Notification design should be intentional. Sending everything to everyone creates alert fatigue. A better approach is to route different events to different audiences. Platform teams may need BOM processing failures. Security teams may need critical vulnerability summaries. Product teams may need policy violations for their own projects. Compliance teams may need license-related summaries. Automation may need webhook payloads for ticket creation or reporting.

Tickets should be created only when ownership and action are clear. Every unnecessary ticket becomes extra work in the system. The goal is not to maximize activity. The goal is to create timely, relevant feedback.

23. Dashboards and portfolio visibility

The dashboard is not the outcome. The decisions made from the dashboard are the outcome. Dependency-Track can show risk across projects, components, vulnerabilities, policies, and portfolio trends, but the organization must decide which questions matter.

Useful questions include which projects have unresolved critical findings, which teams have untriaged issues, which vulnerable component creates the largest blast radius, which policies generate the most noise, which findings are suppressed without enough context, and which projects have stopped uploading SBOMs.

Total vulnerability count is usually a weak metric. Better metrics combine severity, exploitability, exposure, ownership, business criticality, and freshness. A critical finding in an internet-facing production system with no owner is different from a low-severity finding in an internal prototype that is being deleted next week.

Metrics should improve behavior. If they only create shame, they will be gamed or ignored.

24. REST API and automation

Dependency-Track exposes a REST API and OpenAPI documentation, which makes it suitable for automation. Common uses include uploading SBOMs from CI, creating projects automatically, applying tags, exporting findings, checking BOM processing status, creating selected tickets, feeding risk data into internal developer portals, and integrating with Backstage or similar platforms.

A simple project query looks like this:

curl -s \
  -H "X-Api-Key: ${DTRACK_API_KEY}" \
  "${DTRACK_URL}/api/v1/project"

With jq, the output becomes easier to consume:

curl -s \
  -H "X-Api-Key: ${DTRACK_API_KEY}" \
  "${DTRACK_URL}/api/v1/project" \
  | jq '.[] | {name, version, uuid}'

A lookup by project name and version can be scripted:

curl -s \
  -H "X-Api-Key: ${DTRACK_API_KEY}" \
  "${DTRACK_URL}/api/v1/project/lookup?name=${PROJECT_NAME}&version=${PROJECT_VERSION}" \
  | jq '{name, version, uuid}'

Automation should use explicit inputs and CI secrets. API keys should not be committed, echoed, or shared across unrelated workflows.

25. Security patterns around Dependency-Track

Dependency-Track should be secured like any other security-sensitive platform. Use OIDC or LDAP where possible, avoid shared admin accounts, apply least privilege, rotate API keys, use separate API keys per automation context, store secrets in CI secret stores, restrict network access, protect the platform with TLS, back up the database, and monitor BOM processing failures.

The data inside Dependency-Track is sensitive because it describes the internal software estate. It can reveal technologies, vulnerabilities, ownership, architecture hints, and risk concentration. That information is valuable for defenders, but it can also be useful for attackers.

The same security thinking should apply to the automation around the platform. A Dependency-Track upload key should not be available to untrusted pull request code. It should not be stored in a repository-level .env file that can be accidentally committed. It should not be reused across all projects if separate keys would give better control. The tool is there to improve supply-chain visibility, but its own access model must be designed carefully.

26. How to use it during an incident

Imagine that a malicious version of a package has been published. The first question is whether the organization uses the affected package and version. Without a central inventory, that question becomes a manual search across teams. With Dependency-Track, the response can start from the component and move outward to projects, owners, environments, and remediation status.

A practical incident flow is to identify the affected package coordinates and versions, search for them across the portfolio, identify affected projects, contact owners, prioritize production and exposed systems, check when the affected versions entered the build, rotate credentials where install or build hosts may have been exposed, remediate or isolate affected systems, upload new SBOMs, and verify that the affected components no longer appear.

Dependency-Track does not perform the whole incident response. It provides the map. During an incident, that map is leverage.

27. How it helps with supply-chain attacks

Different supply-chain attacks work differently, but they often share the same economic pattern: the attacker compromises something that many others trust, and the downstream cost is pushed to everyone who depends on it.

In a TanStack-style npm incident, Dependency-Track helps identify projects that include affected package versions after SBOMs have been uploaded. It does not secure CI caches, OIDC tokens, or publishing workflows. Those require CI hardening and release governance.

In an XZ Utils-style incident, Dependency-Track can help identify affected versions if SBOMs include operating system and container image components. If the organization only tracks application package dependencies, this class of exposure may be missed.

In a SolarWinds-style vendor compromise, Dependency-Track can contribute to component and service visibility, but vendor risk also requires procurement controls, asset inventory, network monitoring, and incident response.

In a Codecov-style CI tooling compromise, Dependency-Track can help track software components, but the organization also needs to treat build tools, uploaders, scripts, and CI dependencies as part of the supply chain.

The dependency graph is bigger than the codebase. The visibility model must be bigger too.

28. Common mistakes

Common adoption mistakes include treating SBOM generation as a checkbox, uploading once and forgetting it, creating project versions without a strategy, failing to define ownership, suppressing findings without evidence, turning every finding into a ticket, blocking builds before teams can respond, exposing API keys to untrusted CI contexts, ignoring container and operating system packages, and confusing vulnerability count with actual risk.

Most of these mistakes have the same root cause: the organization treats Dependency-Track as a tool to install rather than a feedback loop to design. The installation is the easy part. The value comes from the operating model around it.

A particularly common mistake is adding Dependency-Track as a security requirement without improving the developer workflow. If developers have to remember long commands, manually upload files, guess project names, search for secrets, and interpret every finding alone, the organization has added friction rather than capability. Taskfile helps because it turns that friction into a small set of project commands that can be run locally and reused in CI.

29. Adoption roadmap

Start with a local evaluation. Run Dependency-Track with Docker Compose, generate one SBOM from one real project, upload it, review the components, inspect the findings, and understand the difference between vulnerabilities, policy violations, analysis states, and suppressions.

Then add a Taskfile. Create task dtrack:health, task sbom:generate, task sbom:validate, and task sbom:upload. This step matters because it turns an experiment into a repeatable workflow. The team should be able to run the same command tomorrow without rereading the setup notes.

After that, add CI integration. The main branch or release workflow should generate and upload SBOMs automatically from a trusted context. API keys should be stored in CI secrets and should not be available to untrusted pull request code. The pipeline can call task sbom:publish so local and CI behavior stay aligned.

Then define portfolio conventions. Project naming, versioning, owner tags, domain tags, criticality tags, and freshness expectations are essential if the organization wants useful incident response.

After that, introduce triage discipline. Teams need to understand when to use exploitable, not affected, false positive, in triage, and not set. Suppressions should include context, and critical findings should not remain undecided.

Only then should policies become stronger. Start with reporting, reduce noise, route notifications correctly, and introduce gates only for risks the organization is ready to act on.

Finally, practice incident response. Pick a known package, search for it across the portfolio, identify owners, simulate remediation, upload a new SBOM, and verify the result. This practice is where the tool becomes real.

30. Conclusions

Dependency-Track is valuable because it changes the shape of dependency management. It moves teams from local scanning to portfolio visibility, from static SBOM files to living operational evidence, from noisy vulnerability alerts to recorded triage decisions, and from manual dependency archaeology to faster impact analysis.

That matters because supply-chain attacks are not rare edge cases anymore. TanStack, XZ Utils, SolarWinds, Codecov, and other incidents show different versions of the same problem: trusted software, trusted automation, trusted packages, trusted vendors, and trusted build steps can become paths of compromise.

Dependency-Track does not remove that risk. It reduces blindness. In software economics terms, it creates option value because it gives the organization a faster way to respond when new information arrives. It lowers discovery cost, reduces coordination cost, and improves the liquidity of security decisions because teams can redirect attention toward affected systems instead of first trying to find them.

Taskfile strengthens that value because it makes the workflow easier to repeat. A platform that depends on manual discipline will decay. A platform connected to simple local commands and CI tasks has a better chance of staying fresh. Developers get a clear command surface. CI gets a reusable implementation. Security gets better evidence. The organization gets a healthier feedback loop.

The promise is not perfect security. The promise is better visibility, faster learning, clearer decisions, lower friction, and safer delivery.

References

• OWASP Foundation. Dependency-Track documentation.

https://docs.dependencytrack.org/

• OWASP Foundation. Dependency-Track REST API. https://docs.dependencytrack.org/integrations/rest-api/

• OWASP Foundation. Dependency-Track Continuous Integration & Delivery. https://docs.dependencytrack.org/usage/cicd/

• OWASP Foundation. Dependency-Track Policy Compliance. https://docs.dependencytrack.org/usage/policy-compliance/

• OWASP Foundation. Dependency-Track Auditing Basics. https://docs.dependencytrack.org/triage/auditing-basics/

• OWASP Foundation. Dependency-Track Analysis States. https://docs.dependencytrack.org/triage/analysis-states/

• OWASP Foundation. Dependency-Track Notifications. https://docs.dependencytrack.org/integrations/notifications/

• OWASP Foundation. Dependency-Track Deploying Docker Container. https://docs.dependencytrack.org/getting-started/deploy-docker/

• OWASP Foundation. Dependency-Track Deploying on Kubernetes. https://docs.dependencytrack.org/getting-started/deploy-kubernetes/

• OWASP Foundation. Dependency-Track Configuration. https://docs.dependencytrack.org/getting-started/configuration/

• OWASP Foundation. Dependency-Track Change Log. https://docs.dependencytrack.org/changelog/

• Task. Guide. https://taskfile.dev/docs/guide

• Task. Taskfile Schema Reference. https://taskfile.dev/docs/reference/schema

• Task. Environment Reference. https://taskfile.dev/docs/reference/environment

• Task. Taskfile Versions. https://taskfile.dev/docs/taskfile-versions

• Linsley, Tanner. Postmortem: TanStack npm supply-chain compromise. https://tanstack.com/blog/npm-supply-chain-compromise-postmortem

• GitHub Security Lab. Keeping your GitHub Actions and workflows secure: Preventing pwn requests. https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/

• Cybersecurity and Infrastructure Security Agency. Reported Supply Chain Compromise Affecting XZ Utils Data Compression Library, CVE-2024-3094. https://www.cisa.gov/news-events/alerts/2024/03/29/reported-supply-chain-compromise-affecting-xz-utils-data-compression-library-cve-2024-3094

• National Institute of Standards and Technology. CVE-2024-3094 Detail. https://nvd.nist.gov/vuln/detail/cve-2024-3094

• SolarWinds. Security Advisory RE: CERT Emergency Directive. https://www.solarwinds.com/sa-overview/certadvisory

• Cybersecurity and Infrastructure Security Agency. Detecting Post-Compromise Threat Activity in Microsoft Cloud Environments. https://www.cisa.gov/news-events/cybersecurity-advisories/aa21-008a

• Codecov. Post-Mortem / Root Cause Analysis, April 2021. https://about.codecov.io/apr-2021-post-mortem/

• Codecov. Bash Uploader Security Update. https://about.codecov.io/security-update/

• CycloneDX. CycloneDX Tool Center. https://cyclonedx.org/tool-center/

• CycloneDX. Authoritative Guide to SBOM. https://cyclonedx.org/guides/OWASP_CycloneDX-Authoritative-Guide-to-SBOM-en.pdf

Clone the repository. Install dependencies. Copy the right environment file. Start the database. Run migrations. Start the service. Seed data. Run tests. Build the app. Validate manifests. Format YAML. Parse some JSON. Push a branch. Open a PR. Wait for CI to tell you what you forgot.

Most teams do not call this a ritual. They call it “the setup”. Or “the usual commands”. Or “check the README”. But the shape is always the same: a set of important steps that live partly in documentation, partly in shell history, partly in CI, partly in the head of the person who has been on the project longest.

That is bad DevExp.

Not because developers are lazy. Because every remembered step is cognitive load. Every undocumented command is accidental onboarding cost. Every platform-specific script is a small tax on the team. Every difference between local development and CI is a future debugging session waiting to happen.

Task helps by giving the project a clear command interface.

Not a framework. Not a build system that wants to own your architecture. Not a replacement for npm, Docker, Kubernetes, Make, jq, yq or your test runner. Task is a thin, practical layer above the tools you already use. It gives those tools names, structure, dependencies, defaults, checks, prompts, descriptions and cross-platform execution.

A good Taskfile is not just automation.

It is executable project knowledge.

TL;DR

• Task is a modern, cross-platform task runner configured with Taskfile.yml

• It is especially useful when a project has repeated local, CI, container, Kubernetes, code generation or validation workflows

• A Taskfile gives developers one stable interface, such as task dev, task test, task verify, task docker:build or task k8s:apply

• It reduces setup friction because commands become discoverable with task --list

• It improves DevExp because project workflows stop depending on shell history, tribal knowledge and platform-specific scripts

• It supports variables, environment files, dependencies, includes, task aliases, prompts, preconditions, incremental execution, watch mode, loops and templating

• Dependencies declared with deps run in parallel, so sequential flows should call tasks explicitly from cmds

• sources, generates and status are key when you want Task to skip work that is already up to date

• requires, preconditions, prompt, platforms and --dry help make dangerous or unclear workflows safer

• Task is cross-platform, but the commands you run inside Task may not be

• User-specific paths should be configurable, not hardcoded into the shared Taskfile

• Secrets should not live in the Taskfile. Task should orchestrate secret loading from environment files, secret managers, Docker secrets, Kubernetes Secrets or approved platform mechanisms

• Kubernetes Secrets are not automatically a complete secret-management strategy

• Large Taskfiles can be split into multiple included Taskfiles, but the project should still feel like one coherent interface

• A Taskfile should be treated as part of the product’s engineering interface, not as a dumping ground for random commands

Index

1. Why DevExp needs a project command interface

2. What Task is

3. What Task is not

4. Where Task fits in the development workflow

5. Installation

6. Your first Taskfile

7. The mental model

8. Anatomy of a Taskfile

9. Task discovery and documentation

10. Variables, environment and dotenv files

11. User-specific paths and home directory configuration

12. Secrets: what Task should and should not do

13. Required inputs and interactive prompts

14. Dependencies and execution order

15. Calling tasks from other tasks

16. Cross-platform workflows

17. Incremental work with sources, generates and status

18. Preconditions, conditional execution and run policies

19. Includes and modular Taskfiles

20. Splitting Taskfiles by responsibility

21. Loops, matrices and repeated work

22. CLI arguments and wildcard tasks

23. Cleanup with defer

24. Output, silence and CI-friendly logs

25. Watch mode

26. Taskfile style guide

27. A complete practical single-file Taskfile

28. A complete modular Taskfile structure

29. Common mistakes

30. How to adopt Task in an existing project

31. Conclusions

1. Why DevExp needs a project command interface

A project without a command interface makes every developer reconstruct the system from pieces.

One person runs npm test. Another runs npm run test:unit. CI runs something else. Someone validates Kubernetes manifests with kubectl --dry-run=server. Another person uses kubeconform. Someone formats YAML manually. Someone else has a shell alias. The README says one thing, the Makefile says another, the package scripts say another, and the pipeline quietly contains the real truth.

This is where DevExp gets expensive.

The problem is not the individual command. The problem is the lack of a shared entry point.

A good project command interface gives the team a stable vocabulary:

task setup
task dev
task test
task verify
task build
task docker:build
task k8s:validate

The value is not only speed. The value is recoverability.

A new developer can ask the project what it knows how to do. A senior developer can encode a workflow once instead of explaining it ten times. CI can reuse the same local commands. Documentation can point to task names instead of fragile shell recipes. The project becomes easier to operate because the workflow is explicit.

That is the core reason Task matters.

It turns “ask someone who knows” into “run the project interface”.

2. What Task is

Task is a task runner configured with a Taskfile.yml.

It is inspired by Make, but it is designed around modern developer workflows and cross-platform usage. Instead of writing Make syntax, you write YAML. Instead of forcing every project command into a single shell script, you create named tasks with commands, dependencies, descriptions, variables and execution rules.

A task can be simple:

version: '3'

tasks:
  test:
    desc: Run the test suite
    cmds:
      - npm test

Then you run:

task test

That is the smallest useful idea.

The larger idea is that Task becomes the interface to the project:

version: '3'

tasks:
  setup:
    desc: Install project dependencies
    cmds:
      - npm ci

  dev:
    desc: Start the development server
    cmds:
      - npm run dev

  test:
    desc: Run the test suite
    cmds:
      - npm test

  verify:
    desc: Run local checks before pushing
    cmds:
      - task: test
      - task: build

  build:
    desc: Build the application
    cmds:
      - npm run build

A developer does not need to remember whether this project uses npm, pnpm, Docker Compose, kubectl, Helm, jq, yq, a custom script or a mixture of all of them.

They can start from the task names.

3. What Task is not

Task is not a replacement for your actual tools.

It does not replace Docker. It can call Docker.

It does not replace Kubernetes. It can call kubectl, Helm, kustomize, kubeconform or any validation tool you use.

It does not replace jq or yq. It can make them part of a repeatable workflow.

It does not replace npm scripts. It can wrap them behind stable names that survive changes in the underlying implementation.

It does not replace CI. It can make local and CI commands closer to each other.

This distinction matters.

The job of Task is not to become the center of your architecture. The job of Task is to make the useful operations of the project easy to discover, easy to run and hard to misunderstand.

That is why it works well for DevExp.

4. Where Task fits in the development workflow

Task sits between the people who need to work with the project and the tools that actually do the work.

It gives the project a small command surface.

This diagram matters because it shows the right mental model.

Task is not the whole delivery system. It is the interface to the delivery system.

That means a Taskfile should not try to hide everything. It should hide accidental complexity and expose meaningful operations.

task verify is meaningful.

task run-weird-local-thing-that-only-works-on-my-laptop is not.

The interface should teach the project.

5. Installation

Task supports several installation methods.

For macOS or Linux with the official Homebrew tap:

brew install go-task/tap/go-task

With the official Homebrew repository:

brew install go-task

With npm:

npm install -g @go-task/cli

With Winget on Windows:

winget install Task.Task

With Snap:

sudo snap install task --classic

In GitHub Actions:

- name: Install Task
  uses: go-task/setup-task@v1

After installation:

task --version

For teams, the installation choice should be part of the project documentation. If developers use different operating systems, prefer an installation path that works clearly across macOS, Linux and Windows.

6. Your first Taskfile

Create a Taskfile.yml:

task --init

Or write one manually:

version: '3'

tasks:
  hello:
    desc: Print a greeting
    cmds:
      - echo "Hello from Task"

Run it:

task hello

A task named default can be executed by running task with no task name:

version: '3'

tasks:
  default:
    desc: Show available tasks
    cmds:
      - task --list
    silent: true

  hello:
    desc: Print a greeting
    cmds:
      - echo "Hello from Task"

Now:

task

prints the available tasks.

This is a strong default for many projects because it turns the Taskfile into a self-documenting entry point.

7. The mental model

A Taskfile has four jobs.

First, it names workflows.

A name like task verify is easier to remember than a chain of package scripts, shell commands and flags.

Second, it hides implementation detail.

A task called test can call npm test today and vitest run tomorrow. The team command stays stable.

Third, it makes workflows discoverable.

A developer can run:

task --list

and see the main tasks with descriptions.

Fourth, it turns repeated project operations into executable documentation.

This is the real DevExp benefit. The project stops saying “read this long setup guide and assemble the commands yourself”. It starts saying “run these named operations”.

That changes the feeling of working with the system.

A good Taskfile does not only make the happy path shorter. It makes the project more legible.

8. Anatomy of a Taskfile

A typical Taskfile uses these sections:

version: '3'

includes:
  docker: ./taskfiles/Docker.yml

vars:
  APP_NAME: checkout-api

env:
  NODE_ENV: development

tasks:
  test:
    desc: Run tests
    cmds:
      - npm test

The usual sections are:

• version for the Taskfile schema version

• includes for importing other Taskfiles

• vars for Task variables

• env or dotenv for environment variables

• tasks for the actual project commands
  The official style guide recommends this broad ordering:

version:
includes:
# optional configurations
vars:
env:
tasks:

In practice, a clean Taskfile should read like a project interface, not like a random list of shortcuts.

A useful rule:

If a developer needs to know it to work on the project, it probably deserves a task

9. Task discovery and documentation

Task supports descriptions and summaries.

Descriptions appear in task --list:

version: '3'

tasks:
  test:
    desc: Run the test suite
    cmds:
      - npm test

  build:
    desc: Build the application
    cmds:
      - npm run build

Run:

task --list

To show all tasks, including tasks without descriptions:

task --list-all

or:

task -a

For longer documentation, use summary:

version: '3'

tasks:
  release:
    desc: Release the service
    summary: |
      Builds, verifies and publishes the service

      Required inputs:
      - VERSION
      - ENV
    cmds:
      - ./scripts/release.sh "{{.VERSION}}" "{{.ENV}}"

Then:

task --summary release

The summary is not executed. It explains.

This is important. A Taskfile can become part of the teaching material of a project. A new developer should be able to learn the operational shape of the system by listing and summarising tasks.

The Taskfile is not a substitute for all documentation. It is a bridge between documentation and action.

10. Variables, environment and dotenv files

Task has variables and environment variables.

Use vars when you want values for templating:

version: '3'

vars:
  APP_NAME: checkout-api
  IMAGE: checkout-api:local

tasks:
  print:
    desc: Print project variables
    cmds:
      - echo "App {{.APP_NAME}}"
      - echo "Image {{.IMAGE}}"

Use env when the executed command needs environment variables:

version: '3'

env:
  NODE_ENV: development

tasks:
  dev:
    desc: Start the app in development mode
    cmds:
      - npm run dev

Use dotenv when the project should load variables from .env style files:

version: '3'

dotenv:
  - .env.local
  - .env

tasks:
  dev:
    desc: Start the app with local environment variables
    cmds:
      - npm run dev

When several dotenv files define the same variable, the first file in the list takes precedence. That makes this pattern useful:

version: '3'

dotenv:
  - .env.local
  - .env.development
  - .env

The priority is intentional:

• .env.local for developer-specific overrides

• .env.development for development defaults

• .env for base defaults
  Be careful with secrets. Task can load .env files, but that does not mean secrets should be committed. Treat the Taskfile as workflow definition, not as a secret store.

There is also a subtle design question here.

A variable in vars is part of the Taskfile’s internal templating model. An environment variable in env is part of the environment passed to commands. That distinction keeps Taskfiles easier to understand.

For example:

version: '3'

vars:
  APP_NAME: checkout-api

env:
  NODE_ENV: development

tasks:
  dev:
    desc: Start the development server
    cmds:
      - echo "Starting {{.APP_NAME}} with NODE_ENV=$NODE_ENV"
      - npm run dev

APP_NAME is a Task variable.

NODE_ENV is an environment variable used by the command.

Do not mix these concepts accidentally. Use the one that matches the reason the value exists.

11. User-specific paths and home directory configuration

A Taskfile usually lives in the repository.

That creates a useful constraint: the Taskfile should describe the shared workflow, but it should not assume that every developer has the same machine.

This is where many automation files quietly become hostile.

They contain paths like this:

version: '3'

tasks:
  open-config:
    cmds:
      - code /home/emmanuel/.config/my-tool/config.yml

That works for one person.

It fails for everyone else.

A good Taskfile should separate three things:

• Project paths

• User-specific paths

• Secrets
  Project paths belong in the repository.

User-specific paths belong in environment variables, local configuration files or optional local Taskfiles.

Secrets belong in a secret manager, the local shell environment, Docker secrets, Kubernetes Secrets or another controlled runtime mechanism.

The Taskfile can orchestrate all of them, but it should not become the place where private machine state or confidential values are stored.

Project paths should be relative to the repository

Most project paths should be relative.

version: '3'

vars:
  K8S_DIR: k8s
  DIST_DIR: dist

tasks:
  build:
    desc: Build the application
    cmds:
      - npm run build

  k8s:validate:
    desc: Validate Kubernetes manifests
    cmds:
      - yq eval '.' "{{.K8S_DIR}}"/*.yaml > /dev/null
      - kubectl apply --dry-run=client -f "{{.K8S_DIR}}"

This is portable because the path belongs to the project.

No developer name. No absolute path. No operating system assumption.

When you need an absolute project path, Task gives you useful built-in variables:

version: '3'

tasks:
  paths:info:
    desc: Print useful Task paths
    cmds:
      - echo "Root directory {{.ROOT_DIR}}"
      - echo "Current Taskfile directory {{.TASKFILE_DIR}}"
      - echo "Task execution directory {{.TASK_DIR}}"
      - echo "User working directory {{.USER_WORKING_DIR}}"

This is especially useful when the Taskfile is included from another directory, or when you run a global Taskfile.

Use the home directory carefully

Sometimes a task needs something from the user’s home directory.

Examples:

• A local tool configuration

• A personal certificate

• A local kubeconfig

• A personal cache directory

• A private .env file
  The simplest form is this:

version: '3'

dotenv:
  - .env.local
  - .env
  - '{{.HOME}}/.checkout-api.env'

tasks:
  dev:
    desc: Start the app with project and personal environment files
    cmds:
      - npm run dev

This pattern says:

• First read .env.local from the project

• Then read .env from the project

• Then read a personal file from the user’s home directory
  This can be useful, but be careful. HOME is commonly available in Unix-like environments. On cross-platform teams, it is often cleaner to define explicit local paths through variables.

For example:

version: '3'

vars:
  TOOL_CONFIG_FILE: '{{joinPath .HOME ".config" "checkout-api" "config.yml"}}'

tasks:
  config:show:
    desc: Show the resolved local configuration path
    cmds:
      - echo "{{.TOOL_CONFIG_FILE}}"

  config:check:
    desc: Check that the local configuration file exists
    preconditions:
      - sh: test -f "{{.TOOL_CONFIG_FILE}}"
        msg: Create {{.TOOL_CONFIG_FILE}} before running this task
    cmds:
      - echo "Local configuration file exists"

A developer can still override the variable when needed:

task config:show TOOL_CONFIG_FILE="$HOME/dev/configs/checkout-api/config.yml"

The Taskfile no longer needs to know where every user keeps their development files.

That is the important design move.

Use path helpers when paths need to be composed

String concatenation works until paths become slightly different across platforms.

A better approach is to compose paths explicitly:

version: '3'

vars:
  LOCAL_CERT_DIR: '{{joinPath .HOME ".certs" "checkout-api"}}'
  LOCAL_CERT_FILE: '{{joinPath .LOCAL_CERT_DIR "dev.crt"}}'

tasks:
  cert:show-path:
    desc: Show the expected local certificate path
    cmds:
      - echo "{{.LOCAL_CERT_FILE}}"

  cert:check:
    desc: Check that the local development certificate exists
    preconditions:
      - sh: test -f "{{.LOCAL_CERT_FILE}}"
        msg: Create {{.LOCAL_CERT_FILE}} before starting HTTPS locally
    cmds:
      - echo "Local certificate is present"

This makes the intention visible.

The user-specific root is configurable. The rest of the path is constructed by the Taskfile.

For commands that need forward slashes, Task also provides path conversion helpers:

version: '3'

tasks:
  paths:normalize:
    desc: Show path conversions
    vars:
      RAW_PATH: '{{.RAW_PATH | default "C:\\Users\\name\\project"}}'
    cmds:
      - echo "Forward slashes {{.RAW_PATH | toSlash}}"
      - echo "OS-specific slashes {{.RAW_PATH | fromSlash}}"

Use this when a tool expects one path style, but your team uses multiple operating systems.

Keep personal overrides outside the shared Taskfile

A useful pattern is to support an optional local Taskfile.

Root Taskfile.yml:

version: '3'

includes:
  local:
    taskfile: ./Taskfile.local.yml
    optional: true
    internal: false

tasks:
  default:
    desc: Show available tasks
    cmds:
      - task --list
    silent: true

  dev:
    desc: Start the development server
    cmds:
      - npm run dev

Then add this to .gitignore:

Taskfile.local.yml

A developer can create their own local tasks:

version: '3'

tasks:
  tunnel:
    desc: Start my local tunnel
    cmds:
      - cloudflared tunnel run checkout-api-dev

  open-db:
    desc: Open my local database client
    cmds:
      - open -a TablePlus

The shared project interface remains clean.

The personal workflow is still automated.

No one else has to inherit one developer’s machine setup.

Use a global Taskfile for personal machine automation

Task also supports global Taskfiles.

When you run:

task -g some-task

Task looks for a Taskfile in your home directory.

That is useful for personal automation that is not project-specific.

For example, a developer could keep this at ~/Taskfile.yml:

version: '3'

tasks:
  projects:
    desc: Print the projects directory
    cmds:
      - echo "{{.HOME}}/projects"

  clean-docker:
    desc: Clean unused Docker resources
    prompt: Remove unused Docker resources?
    cmds:
      - docker system prune

There is one important detail.

When running a global Taskfile, tasks run from the home directory by default. If the task should operate on the directory where the command was called, use {{.USER_WORKING_DIR}}.

version: '3'

tasks:
  repo:status:
    desc: Show Git status for the directory where task was called
    dir: '{{.USER_WORKING_DIR}}'
    preconditions:
      - sh: test -d .git
        msg: This task must be run inside a Git repository
    cmds:
      - git status --short

Now this works from any repository:

task -g repo:status

This is excellent for personal workflows.

It should not replace project Taskfiles. The project should still expose its own shared interface.

Move Task’s internal cache when needed

Task stores checksum data in a local .task directory by default when using mechanisms such as sources and generates.

For most repositories, add this to .gitignore:

.task/

Some developers prefer to keep that state outside the project directory.

They can configure:

export TASK_TEMP_DIR='~/.task'

This is useful when you want repository directories to stay cleaner, or when tooling aggressively watches project files and you do not want .task to appear inside the working tree.

The Taskfile does not need to change.

This is a machine-level preference.

12. Secrets: what Task should and should not do

Task can help with secrets.

But Task should not become the secret store.

A Taskfile is normally committed to Git. That means this is wrong:

version: '3'

env:
  DB_PASSWORD: super-secret-password

tasks:
  dev:
    cmds:
      - npm run dev

It is also risky to commit a real .env file:

DB_USER=checkout
DB_PASSWORD=super-secret-password
STRIPE_SECRET_KEY=sk_live_real_value

The better rule is simple:

Commit examples, not secrets

For example, commit .env.example:

DB_USER=checkout
DB_PASSWORD=
STRIPE_SECRET_KEY=

Ignore real local files:

.env
.env.local
.env.*.local

Then let Task load local configuration if it exists:

version: '3'

dotenv:
  - .env.local
  - .env

tasks:
  dev:
    desc: Start the app with local environment
    preconditions:
      - sh: test -f .env.local
        msg: Create .env.local from .env.example before running the app
    cmds:
      - npm run dev

This is acceptable for low-risk local development secrets, but it is not enough for higher-risk credentials or shared team secrets.

For those, use a secret manager.

The boundary should be clear.

Task defines how secrets are loaded.

Task should not contain the secret values.

That distinction protects the project from a common failure mode: automation that makes the happy path convenient by making sensitive data too easy to leak.

Example 1: Running local development with 1Password CLI

A clean pattern is to store secret references in a local file, not raw secret values.

.env.1password:

DB_USER=op://checkout-api-dev/database/username
DB_PASSWORD=op://checkout-api-dev/database/password
STRIPE_SECRET_KEY=op://checkout-api-dev/stripe/secret-key

Then Task can run the app through op run:

version: '3'

tasks:
  dev:secure:
    desc: Start the app with secrets loaded from 1Password
    preconditions:
      - sh: command -v op
        msg: 1Password CLI is required
      - sh: test -f .env.1password
        msg: Create .env.1password with 1Password secret references
    cmds:
      - op run --env-file .env.1password -- npm run dev

This has a better shape than storing the real values in the repository.

The Taskfile contains the workflow.

The .env.1password file contains references.

1Password contains the actual secrets.

If the team wants to commit the reference file, check that the references do not expose sensitive naming conventions. In many teams, keeping .env.1password.example in Git and .env.1password ignored locally is a safer default.

Example .env.1password.example:

DB_USER=op://vault/item/username
DB_PASSWORD=op://vault/item/password
STRIPE_SECRET_KEY=op://vault/item/secret-key

Example .gitignore:

.env.1password

Example 2: Running tests with required secrets

Some integration tests require credentials.

The Taskfile can make that explicit and pass the values to the command environment:

version: '3'

tasks:
  test:integration:
    desc: Run integration tests that require database credentials
    requires:
      vars: [DB_USER, DB_PASSWORD]
    env:
      DB_USER: '{{.DB_USER}}'
      DB_PASSWORD: '{{.DB_PASSWORD}}'
    cmds:
      - npm run test:integration

Run it with variables:

task test:integration DB_USER=checkout DB_PASSWORD=secret

Or with 1Password:

version: '3'

tasks:
  test:integration:secure:
    desc: Run integration tests with secrets from 1Password
    preconditions:
      - sh: command -v op
        msg: 1Password CLI is required
      - sh: test -f .env.1password
        msg: Create .env.1password with secret references
    cmds:
      - op run --env-file .env.1password -- task test:integration

This keeps the public task stable.

The secure variant handles secret injection.

The important detail is that requires makes the required input explicit, while env ensures the executed command receives the variables it needs.

Example 3: Docker Compose secrets for local infrastructure

If the project uses Docker Compose, prefer mounting secrets as files when the application supports it.

compose.yml:

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: checkout
      POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
      POSTGRES_DB: checkout
    secrets:
      - postgres_password
    ports:
      - "5432:5432"

secrets:
  postgres_password:
    file: ./secrets/postgres_password.txt

.gitignore:

secrets/

Taskfile:

version: '3'

tasks:
  compose:up:
    desc: Start local infrastructure with Docker Compose secrets
    preconditions:
      - sh: command -v docker
        msg: Docker is required
      - sh: test -f secrets/postgres_password.txt
        msg: Create secrets/postgres_password.txt before starting Compose
    cmds:
      - docker compose up -d

This pattern avoids putting the secret value in the Compose file.

The secret is still local, so protect the file properly. But the repository no longer contains the secret.

For onboarding, provide a safe setup task:

version: '3'

tasks:
  secrets:init:
    desc: Create local secret files for development
    cmds:
      - mkdir -p secrets
      - test -f secrets/postgres_password.txt || printf "checkout-dev-password\n" > secrets/postgres_password.txt
      - cmd: chmod 600 secrets/postgres_password.txt
        platforms: [linux, darwin]

This is suitable only for local development credentials.

Do not use a generated shared password like this for production.

The chmod command is limited to Linux and macOS because it is not a native PowerShell command. This is an example of an important principle: Task is cross-platform, but every command inside a task still has its own platform behaviour.

Example 4: Docker build secrets

Sometimes the build needs access to a private package registry.

Do not bake the token into the image.

Bad:

ARG NPM_TOKEN
RUN npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN

Better pattern with Docker BuildKit secrets:

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci

Taskfile:

version: '3'

tasks:
  docker:build:
    desc: Build the image using a local npm secret
    preconditions:
      - sh: test -f "{{.HOME}}/.npmrc"
        msg: ~/.npmrc is required for private package installation
    cmds:
      - docker build --secret id=npmrc,src="{{.HOME}}/.npmrc" -t checkout-api:local .

The secret is available to the build step as a mounted secret.

It is not written into the Taskfile.

It is not passed as a normal build argument.

It is not intended to remain in the final image.

Example 5: Creating a Kubernetes Secret from local files

For Kubernetes, the Taskfile can create a Secret from local files.

First, keep the local secret file out of Git:

.local-secrets/

Local file:

.local-secrets/db-password

Taskfile:

version: '3'

vars:
  NAMESPACE: dev
  SECRET_NAME: checkout-api-secrets

tasks:
  k8s:secret:create:
    desc: Create or update the app Kubernetes Secret from local files
    preconditions:
      - sh: command -v kubectl
        msg: kubectl is required
      - sh: test -f .local-secrets/db-password
        msg: Create .local-secrets/db-password first
    cmds:
      - |
        kubectl create secret generic "{{.SECRET_NAME}}" \
          --namespace "{{.NAMESPACE}}" \
          --from-file=db-password=.local-secrets/db-password \
          --dry-run=client \
          -o yaml | kubectl apply -f -

Then the deployment can consume the secret.

Example Kubernetes fragment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkout-api
spec:
  template:
    spec:
      containers:
        - name: checkout-api
          image: checkout-api:local
          env:
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: checkout-api-secrets
                  key: db-password

This is a practical local development pattern.

For production, the better pattern usually involves a controlled secret delivery mechanism, such as a cloud secret manager, External Secrets Operator, Sealed Secrets, SOPS, Vault or your platform’s approved secret workflow.

A Kubernetes Secret is not automatically a complete secret-management strategy. By default, Kubernetes stores Secrets in the API server data store without encryption at rest unless encryption at rest and access control are configured properly.

Task can orchestrate the workflow, but it should not invent the security model.

Example 6: Creating a Kubernetes Secret from 1Password at runtime

You can combine Task, 1Password and kubectl.

.env.1password:

DB_PASSWORD=op://checkout-api-dev/database/password

Taskfile:

version: '3'

vars:
  NAMESPACE: dev
  SECRET_NAME: checkout-api-secrets

tasks:
  k8s:secret:create-from-1password:
    desc: Create or update the app Kubernetes Secret from 1Password
    preconditions:
      - sh: command -v op
        msg: 1Password CLI is required
      - sh: command -v kubectl
        msg: kubectl is required
      - sh: test -f .env.1password
        msg: Create .env.1password with secret references
    cmds:
      - |
        op run --env-file .env.1password -- sh -c '
          kubectl create secret generic "{{.SECRET_NAME}}" \
            --namespace "{{.NAMESPACE}}" \
            --from-literal=db-password="$DB_PASSWORD" \
            --dry-run=client \
            -o yaml | kubectl apply -f -
        '

This keeps the secret out of the repository and out of the Taskfile.

The secret exists in the subprocess environment while the command runs.

The resulting Kubernetes Secret exists in the cluster.

This is still sensitive. Access to the cluster and namespace now matters. Anyone with enough permission to read that Secret can access the value.

Task makes the workflow repeatable. It does not remove the need for proper access control.

Example 7: Validating that secrets exist without printing them

A common mistake is to debug by printing secrets.

Do not do this:

version: '3'

tasks:
  debug-secret:
    cmds:
      - echo "$DB_PASSWORD"

Instead, validate presence without revealing the value:

version: '3'

tasks:
  secrets:check:
    desc: Check required secret variables without printing values
    requires:
      vars: [DB_PASSWORD, STRIPE_SECRET_KEY]
    cmds:
      - echo "Required secret variables are present"

Or with shell checks:

version: '3'

tasks:
  secrets:check:
    desc: Check required secret variables without printing values
    cmds:
      - test -n "$DB_PASSWORD"
      - test -n "$STRIPE_SECRET_KEY"
      - echo "Required secret variables are present"

The task should prove readiness.

It should not leak values into the terminal, CI logs or shared screenshots.

13. Required inputs and interactive prompts

Some tasks should not run without explicit input.

A deployment task is a good example. Running it without ENV or VERSION should fail early with a clear message, not halfway through a script.

Task supports requires:

version: '3'

tasks:
  deploy:
    desc: Deploy a specific version
    requires:
      vars: [ENV, VERSION]
    cmds:
      - ./scripts/deploy.sh "{{.ENV}}" "{{.VERSION}}"

Run:

task deploy ENV=staging VERSION=1.4.2

You can restrict a variable to allowed values:

version: '3'

tasks:
  deploy:
    desc: Deploy a specific version to a known environment
    requires:
      vars:
        - name: ENV
          enum: [dev, staging, prod]
        - VERSION
    cmds:
      - ./scripts/deploy.sh "{{.ENV}}" "{{.VERSION}}"

You can also define allowed values once and reuse them:

version: '3'

vars:
  ALLOWED_ENVS: [dev, staging, prod]

tasks:
  deploy:
    desc: Deploy a specific version
    requires:
      vars:
        - name: ENV
          enum:
            ref: .ALLOWED_ENVS
        - VERSION
    cmds:
      - ./scripts/deploy.sh "{{.ENV}}" "{{.VERSION}}"

Interactive mode can prompt users for missing required variables when a terminal is available:

version: '3'

tasks:
  deploy:
    desc: Deploy a version interactively when inputs are missing
    requires:
      vars:
        - name: ENV
          enum: [dev, staging, prod]
        - VERSION
    cmds:
      - echo "Deploying {{.VERSION}} to {{.ENV}}"

Run:

task deploy --interactive

This is useful for local workflows, but CI should pass variables explicitly.

For dangerous tasks, use warning prompts:

version: '3'

tasks:
  prod:delete:
    desc: Delete production resources
    prompt:
      - This will delete production resources. Continue?
      - Are you completely sure?
    cmds:
      - ./scripts/delete-production-resources.sh

Prompts are not a security boundary. They are a friction point that helps avoid accidental execution.

For CI, avoid interactive assumptions. Pass values explicitly, use non-interactive configuration and be careful with prompt-skipping flags.

14. Dependencies and execution order

Task supports dependencies with deps.

version: '3'

tasks:
  build:
    desc: Build the application
    deps: [assets]
    cmds:
      - npm run build

  assets:
    desc: Build frontend assets
    cmds:
      - npm run build:assets

When you run:

task build

Task runs assets first.

The most important rule is this:

Dependencies run in parallel when there is more than one dependency

That is good for independent work:

version: '3'

tasks:
  assets:
    desc: Build all assets
    deps: [js, css]

  js:
    cmds:
      - npm run build:js

  css:
    cmds:
      - npm run build:css

But it is wrong for workflows that need strict order.

This can be wrong:

version: '3'

tasks:
  verify:
    deps: [lint, test, build]

If build depends on generated files from test or lint, this is not the right structure.

Use explicit task calls inside cmds when order matters:

version: '3'

tasks:
  verify:
    desc: Run checks in a deliberate order
    cmds:
      - task: lint
      - task: test
      - task: build

  lint:
    cmds:
      - npm run lint

  test:
    cmds:
      - npm test

  build:
    cmds:
      - npm run build

This is one of the most important design decisions in Taskfiles:

Use deps for independent prerequisites

Use cmds with task: for sequential workflows

15. Calling tasks from other tasks

A task can call another task:

version: '3'

tasks:
  verify:
    desc: Run all verification steps
    cmds:
      - task: lint
      - task: test
      - task: build

  lint:
    cmds:
      - npm run lint

  test:
    cmds:
      - npm test

  build:
    cmds:
      - npm run build

You can pass variables:

version: '3'

tasks:
  docker:build:
    desc: Build a Docker image
    vars:
      IMAGE: checkout-api:local
    cmds:
      - docker build -t "{{.IMAGE}}" .

  docker:build:prod:
    desc: Build the production Docker image
    cmds:
      - task: docker:build
        vars:
          IMAGE: checkout-api:prod

This keeps the public interface small while allowing reuse.

A useful pattern is to create internal tasks for shared implementation details.

version: '3'

tasks:
  docker:build:
    desc: Build the local Docker image
    cmds:
      - task: _docker-build
        vars:
          IMAGE: checkout-api:local

  docker:build:prod:
    desc: Build the production Docker image
    cmds:
      - task: _docker-build
        vars:
          IMAGE: checkout-api:prod

  _docker-build:
    internal: true
    requires:
      vars: [IMAGE]
    cmds:
      - docker build -t "{{.IMAGE}}" .

The public tasks express intent. The internal task holds the implementation.

That is good interface design.

16. Cross-platform workflows

Task is valuable because it helps a team avoid maintaining separate local workflows for macOS, Linux and Windows.

There are several practical rules.

First, prefer task names over shell aliases.

A shell alias is personal. A task is part of the repository.

Second, avoid putting too much shell logic directly in the Taskfile.

If logic becomes complex, move it to a script:

version: '3'

tasks:
  migrate:
    desc: Run database migrations
    cmds:
      - ./scripts/migrate.sh

Third, use platform filters when a command is genuinely platform-specific:

version: '3'

tasks:
  open:
    desc: Open the local app in a browser
    cmds:
      - cmd: open http://localhost:3000
        platforms: [darwin]
      - cmd: xdg-open http://localhost:3000
        platforms: [linux]
      - cmd: start http://localhost:3000
        platforms: [windows]

Fourth, use Task template functions for paths and executable extensions when needed:

version: '3'

tasks:
  build:
    desc: Build a binary with the right extension for the platform
    cmds:
      - go build -o "bin/app{{exeExt}}" ./cmd/app

Fifth, treat platform support as a design decision.

Task is cross-platform, but the commands you orchestrate may not be. If a workflow must work on native Windows, macOS and Linux, either use platform-specific commands with platforms, or move the logic to a script written in a cross-platform runtime already used by the project.

For example, if your project already uses Node.js, a script like this can be more portable than shell-specific file logic:

import { mkdirSync, existsSync, writeFileSync, chmodSync } from "node:fs";
import { join } from "node:path";

const secretsDir = ".local-secrets";
const passwordFile = join(secretsDir, "db-password");

mkdirSync(secretsDir, { recursive: true });

if (!existsSync(passwordFile)) {
  writeFileSync(passwordFile, "checkout-dev-password\n", { encoding: "utf8" });
}

try {
  chmodSync(passwordFile, 0o600);
} catch {
  // Some platforms or filesystems may not support POSIX permissions
}

Then Task can call the script:

version: '3'

tasks:
  secrets:init:
    desc: Create local development secret files
    cmds:
      - node scripts/init-local-secrets.js

That is often a better DevExp than filling the Taskfile with platform-specific shell branches.

17. Incremental work with sources, generates and status

Some tasks do expensive work.

Build assets. Generate code. Build an image. Compile binaries. Produce documentation. Validate many files.

Task can skip work when inputs have not changed.

Use sources to describe inputs and generates to describe outputs:

version: '3'

tasks:
  build:
    desc: Build only when source files changed
    sources:
      - package.json
      - package-lock.json
      - 'src/**/*.js'
    generates:
      - dist/server.js
    cmds:
      - npm run build

By default, Task uses checksums. You can use timestamps instead:

version: '3'

tasks:
  build:
    desc: Build using timestamp checks
    method: timestamp
    sources:
      - package.json
      - package-lock.json
      - 'src/**/*.js'
    generates:
      - dist/server.js
    cmds:
      - npm run build

You can configure the method globally:

version: '3'

method: timestamp

tasks:
  build:
    sources:
      - 'src/**/*.js'
    generates:
      - dist/server.js
    cmds:
      - npm run build

Use status when the task’s output is not a simple local file.

For example, a Docker image:

version: '3'

tasks:
  docker:build:
    desc: Build the Docker image if it is missing
    vars:
      IMAGE: checkout-api:local
    status:
      - docker image inspect "{{.IMAGE}}" > /dev/null 2>&1
    cmds:
      - docker build -t "{{.IMAGE}}" .

If the status command returns success, Task treats the task as up to date.

You can force execution:

task docker:build --force

You can check status without running the task:

task docker:build --status

This is useful in CI and local workflows because it makes expensive work conditional instead of habitual.

18. Preconditions, conditional execution and run policies

status answers this question:

Is this task already done?

preconditions answer a different question:

Is it valid to run this task now?

Example:

version: '3'

tasks:
  dev:
    desc: Start the development server
    preconditions:
      - sh: test -f package.json
        msg: Run this task from a project with package.json
      - sh: test -f .env.local
        msg: Create .env.local before starting the service
    cmds:
      - npm run dev

If a precondition fails, the task fails before running its commands.

Use this for required files, required tools, expected directories, local configuration and dangerous assumptions.

Task also supports if, which skips instead of failing:

version: '3'

tasks:
  verify:
    desc: Run optional checks when their configuration exists
    cmds:
      - cmd: npm run lint
        if: test -f package.json
      - cmd: yq --version
        if: command -v yq

Use if when skipping is acceptable.

Use preconditions when skipping would hide a real problem.

Task also supports run policies:

version: '3'

tasks:
  setup:
    run: once
    cmds:
      - npm ci

  generate:
    run: when_changed
    cmds:
      - echo "{{.TARGET}}"

The main options are:

• always to attempt the task every time

• once to run only once within a Task invocation

• when_changed to run once for each unique set of variables
  This becomes useful when one task is called multiple times by other tasks.

19. Includes and modular Taskfiles

A single Taskfile can become too large.

Task supports includes:

version: '3'

includes:
  docker: ./taskfiles/Docker.yml
  k8s: ./taskfiles/Kubernetes.yml
  docs: ./taskfiles/Docs.yml

tasks:
  verify:
    desc: Run project verification
    cmds:
      - task: docker:build
      - task: k8s:validate
      - task: docs:check

If taskfiles/Docker.yml contains:

version: '3'

tasks:
  build:
    desc: Build the Docker image
    cmds:
      - docker build -t checkout-api:local .

Then you run:

task docker:build

Includes are especially useful in monorepos:

version: '3'

includes:
  api:
    taskfile: ./services/api/Taskfile.yml
    dir: ./services/api

  web:
    taskfile: ./services/web/Taskfile.yml
    dir: ./services/web

Then:

task api:test
task web:test

You can pass variables to included Taskfiles:

version: '3'

includes:
  backend:
    taskfile: ./taskfiles/Docker.yml
    vars:
      DOCKER_IMAGE: backend_image

  frontend:
    taskfile: ./taskfiles/Docker.yml
    vars:
      DOCKER_IMAGE: frontend_image

You can also make includes optional:

version: '3'

includes:
  local:
    taskfile: ./Taskfile.local.yml
    optional: true

This is useful when each developer may have private local tasks that should not be required by the project.

Use includes when they improve navigation. Do not split a Taskfile just because it is possible. Split by responsibility:

• Docker tasks

• Kubernetes tasks

• Documentation tasks

• Code generation tasks

• Release tasks

• Service-specific tasks in a monorepo
  One important detail: root-level dotenv declarations cannot currently live inside included Taskfiles. Put shared dotenv loading in the main Taskfile, or use task-level dotenv where that is the right local choice.

20. Splitting Taskfiles by responsibility

At some point, a Taskfile stops feeling like a project interface and starts feeling like a long utility drawer.

That is the moment to split it.

Not before.

Splitting Taskfiles is useful when it makes the workflow easier to understand. It is harmful when it forces people to jump across files just to understand a simple project.

A good split keeps the main Taskfile.yml as the entrance to the project.

.
├── Taskfile.yml
├── taskfiles
│   ├── Dev.yml
│   ├── Quality.yml
│   ├── Docker.yml
│   ├── Kubernetes.yml
│   ├── Secrets.yml
│   └── Docs.yml
├── package.json
├── Dockerfile
├── compose.yml
└── k8s
    ├── deployment.yaml
    └── service.yaml

The root Taskfile should explain the project’s main operations:

version: '3'

vars:
  APP_NAME: checkout-api
  NAMESPACE: dev
  IMAGE: checkout-api:local

dotenv:
  - .env.local
  - .env

includes:
  dev:
    taskfile: ./taskfiles/Dev.yml
  quality:
    taskfile: ./taskfiles/Quality.yml
  docker:
    taskfile: ./taskfiles/Docker.yml
    vars:
      IMAGE: '{{.IMAGE}}'
  k8s:
    taskfile: ./taskfiles/Kubernetes.yml
    vars:
      APP_NAME: '{{.APP_NAME}}'
      NAMESPACE: '{{.NAMESPACE}}'
  secrets:
    taskfile: ./taskfiles/Secrets.yml
  docs:
    taskfile: ./taskfiles/Docs.yml

tasks:
  default:
    desc: Show available tasks
    cmds:
      - task --list
    silent: true

  setup:
    desc: Prepare the project for local development
    cmds:
      - task: dev:setup
      - task: secrets:init

  dev:
    desc: Start the local development environment
    cmds:
      - task: dev:start

  verify:
    desc: Run all checks before pushing
    cmds:
      - task: quality:lint
      - task: quality:test
      - task: quality:build
      - task: docker:build
      - task: k8s:validate

This root file gives the reader the story.

Setup.

Development.

Verification.

Everything else is delegated.

Dev.yml

version: '3'

tasks:
  setup:
    desc: Install project dependencies
    sources:
      - package.json
      - package-lock.json
    generates:
      - node_modules/.package-lock.json
    cmds:
      - npm ci

  start:
    desc: Start the development server
    deps: [setup]
    preconditions:
      - sh: test -f package.json
        msg: package.json is required
      - sh: test -f .env.local
        msg: Create .env.local from .env.example before starting the app
    cmds:
      - npm run dev

Quality.yml

version: '3'

tasks:
  lint:
    desc: Run linting
    cmds:
      - npm run lint

  test:
    desc: Run the test suite
    cmds:
      - npm test

  build:
    desc: Build the application
    sources:
      - package.json
      - package-lock.json
      - 'src/**/*.js'
    generates:
      - dist/server.js
    cmds:
      - npm run build

Docker.yml

version: '3'

vars:
  IMAGE: checkout-api:local

tasks:
  build:
    desc: Build the local Docker image
    sources:
      - Dockerfile
      - package.json
      - package-lock.json
      - 'src/**/*.js'
    cmds:
      - docker build -t "{{.IMAGE}}" .

  build-private:
    desc: Build the Docker image using a private npm configuration as a BuildKit secret
    preconditions:
      - sh: test -f "{{.HOME}}/.npmrc"
        msg: ~/.npmrc is required for private package installation
    cmds:
      - docker build --secret id=npmrc,src="{{.HOME}}/.npmrc" -t "{{.IMAGE}}" .

  run:
    desc: Run the Docker image locally
    deps: [build]
    cmds:
      - docker run --rm -p 3000:3000 "{{.IMAGE}}"

  compose-up:
    desc: Start local infrastructure
    cmds:
      - docker compose up -d

  compose-down:
    desc: Stop local infrastructure
    cmds:
      - docker compose down

Kubernetes.yml

version: '3'

vars:
  K8S_DIR: k8s
  NAMESPACE: dev
  APP_NAME: checkout-api

tasks:
  validate:
    desc: Validate Kubernetes manifests locally
    preconditions:
      - sh: command -v yq
        msg: yq is required
      - sh: command -v kubectl
        msg: kubectl is required
      - sh: test -d "{{.K8S_DIR}}"
        msg: Kubernetes directory not found
    cmds:
      - yq eval '.' "{{.K8S_DIR}}"/*.yaml > /dev/null
      - kubectl apply --dry-run=client -f "{{.K8S_DIR}}"

  apply:
    desc: Apply Kubernetes manifests to a namespace
    prompt:
      - Apply manifests to namespace {{.NAMESPACE}}?
    cmds:
      - kubectl create namespace "{{.NAMESPACE}}" --dry-run=client -o yaml | kubectl apply -f -
      - kubectl apply -n "{{.NAMESPACE}}" -f "{{.K8S_DIR}}"

  pods:
    desc: List pods using jq
    preconditions:
      - sh: command -v jq
        msg: jq is required
      - sh: command -v kubectl
        msg: kubectl is required
    cmds:
      - kubectl get pods -n "{{.NAMESPACE}}" -o json | jq '.items[] | {name: .metadata.name, phase: .status.phase}'

  logs:
    desc: Show logs for the app deployment
    cmds:
      - kubectl logs -n "{{.NAMESPACE}}" "deploy/{{.APP_NAME}}"

  delete:
    desc: Delete Kubernetes manifests from a namespace
    prompt:
      - Delete manifests from namespace {{.NAMESPACE}}?
    cmds:
      - kubectl delete -n "{{.NAMESPACE}}" -f "{{.K8S_DIR}}"

kubectl apply --dry-run=client is useful as a fast local check, but it does not replace server-side validation against the real cluster API.

Secrets.yml

version: '3'

vars:
  LOCAL_SECRETS_DIR: .local-secrets
  DB_PASSWORD_FILE: '{{joinPath .LOCAL_SECRETS_DIR "db-password"}}'

tasks:
  init:
    desc: Create local development secret files
    cmds:
      - mkdir -p "{{.LOCAL_SECRETS_DIR}}"
      - test -f "{{.DB_PASSWORD_FILE}}" || printf "checkout-dev-password\n" > "{{.DB_PASSWORD_FILE}}"
      - cmd: chmod 600 "{{.DB_PASSWORD_FILE}}"
        platforms: [linux, darwin]

  check:
    desc: Check required local secret files without printing values
    preconditions:
      - sh: test -f "{{.DB_PASSWORD_FILE}}"
        msg: Create {{.DB_PASSWORD_FILE}} first
    cmds:
      - echo "Required local secret files are present"

  dev-secure:
    desc: Run the app with secrets loaded from 1Password
    preconditions:
      - sh: command -v op
        msg: 1Password CLI is required
      - sh: test -f .env.1password
        msg: Create .env.1password with 1Password secret references
    cmds:
      - op run --env-file .env.1password -- npm run dev

Docs.yml

version: '3'

tasks:
  serve:
    desc: Serve documentation locally
    cmds:
      - npm run docs:serve

  check:
    desc: Check documentation quality
    cmds:
      - npm run docs:check

This structure creates a clean interface:

task setup
task dev
task verify
task docker:build
task docker:compose-up
task k8s:validate
task k8s:pods
task secrets:dev-secure
task docs:serve

The project feels like one interface, even though the implementation is split across several files.

That is the point.

A split Taskfile should still feel like one project interface. The goal is not to create many files. The goal is to keep each responsibility easy to find, easy to reason about and easy to change.

When not to split

Do not split a Taskfile just because you can.

A tiny project does not need this:

taskfiles/Build.yml
taskfiles/Test.yml
taskfiles/Dev.yml
taskfiles/Clean.yml

when the full Taskfile is only this:

version: '3'

tasks:
  dev:
    desc: Start development
    cmds:
      - npm run dev

  test:
    desc: Run tests
    cmds:
      - npm test

  build:
    desc: Build the app
    cmds:
      - npm run build

Splitting has a carrying cost.

It adds navigation. It adds indirection. It adds more places to look.

Split when the structure reduces cognitive load, not when it merely looks more architectural.

21. Loops, matrices and repeated work

Task supports loops.

A simple list:

version: '3'

tasks:
  print-services:
    desc: Print service names
    cmds:
      - for: [api, web, worker]
        cmd: echo "{{.ITEM}}"

A variable:

version: '3'

vars:
  SERVICES: [api, web, worker]

tasks:
  print-services:
    desc: Print service names from a variable
    cmds:
      - for:
          var: SERVICES
        cmd: echo "{{.ITEM}}"

A renamed iterator:

version: '3'

vars:
  SERVICES: [api, web, worker]

tasks:
  print-services:
    desc: Print service names with a clear variable name
    cmds:
      - for:
          var: SERVICES
          as: SERVICE
        cmd: echo "{{.SERVICE}}"

A matrix:

version: '3'

tasks:
  test:matrix:
    desc: Print a test matrix
    cmds:
      - for:
          matrix:
            NODE_VERSION: ['20', '22']
            TEST_TYPE: [unit, integration]
        cmd: echo "Run {{.ITEM.TEST_TYPE}} tests on Node {{.ITEM.NODE_VERSION}}"

Loops also work with dependencies:

version: '3'

tasks:
  build:all:
    desc: Build all services in parallel
    deps:
      - for: [api, web, worker]
        task: build
        vars:
          SERVICE: '{{.ITEM}}'

  build:
    internal: true
    requires:
      vars: [SERVICE]
    cmds:
      - echo "Building {{.SERVICE}}"

Remember the same rule as before:

Looping inside deps means parallel execution

That is great for independent service builds. It is not right for ordered deployment steps.

22. CLI arguments and wildcard tasks

Sometimes a task should forward arguments to another command.

Task supports -- and exposes the rest as .CLI_ARGS:

version: '3'

tasks:
  test:
    desc: Run tests and forward extra arguments
    cmds:
      - npm test -- {{.CLI_ARGS}}

Run:

task test -- --watch

For Kubernetes logs:

version: '3'

tasks:
  k8s:logs:
    desc: Forward arguments to kubectl logs
    cmds:
      - kubectl logs {{.CLI_ARGS}}

Run:

task k8s:logs -- deploy/checkout-api -n dev

Task also supports wildcard task names.

version: '3'

tasks:
  service:*:logs:
    desc: Show logs for a service
    vars:
      SERVICE: '{{index .MATCH 0}}'
    cmds:
      - kubectl logs "deploy/{{.SERVICE}}" -n dev

Run:

task service:checkout-api:logs

This can be elegant, but use it carefully. Wildcards are less discoverable than explicit task names. They are useful when the pattern is obvious and stable.

23. Cleanup with defer

Some tasks create temporary files, start services or create local state that should be cleaned up.

Task supports defer:

version: '3'

tasks:
  demo:
    desc: Create a temporary directory and clean it afterwards
    cmds:
      - mkdir -p tmp/task-demo
      - defer: rm -rf tmp/task-demo
      - echo "Doing work inside tmp/task-demo"

The deferred command runs when the task finishes, including when a later command fails.

You can also defer another task:

version: '3'

tasks:
  demo:
    cmds:
      - mkdir -p tmp/task-demo
      - defer:
          task: cleanup
      - echo "Doing work"

  cleanup:
    internal: true
    cmds:
      - rm -rf tmp/task-demo

This is useful for local integration tests, temporary fixtures and generated files.

24. Output, silence and CI-friendly logs

By default, Task prints command output in real time.

For simple local workflows, that is usually what you want.

For CI, parallel tasks can produce noisy logs. Task supports output modes:

• interleaved

• group

• prefixed
  Example with grouped output:

version: '3'

output:
  group:
    begin: '::group::{{.TASK}}'
    end: '::endgroup::'

tasks:
  verify:
    desc: Run checks with grouped logs
    cmds:
      - task: lint
      - task: test

  lint:
    cmds:
      - npm run lint

  test:
    cmds:
      - npm test

Example with prefixed output:

version: '3'

output: prefixed

tasks:
  verify:
    deps:
      - task: lint
      - task: test

  lint:
    cmds:
      - npm run lint

  test:
    cmds:
      - npm test

Silence controls whether Task echoes commands before running them.

At task level:

version: '3'

tasks:
  hello:
    silent: true
    cmds:
      - echo "Hello"

At command level:

version: '3'

tasks:
  hello:
    cmds:
      - cmd: echo "Hello"
        silent: true

At CLI level:

task hello --silent

Use silence with care. Hiding too much output can make debugging harder. A good default is to keep output visible for development tasks and tune CI output where logs become noisy.

25. Watch mode

Task can watch files and rerun a task when sources change.

version: '3'

interval: 500ms

tasks:
  build:
    desc: Build when source files change
    watch: true
    sources:
      - package.json
      - 'src/**/*.js'
    cmds:
      - npm run build

Run:

task build

or explicitly:

task build --watch

Watch mode requires sources, because Task needs to know what to observe.

Use watch mode for short, bounded tasks such as builds, generation and validation. Be cautious with long-running servers. For live-reload servers, a specialised tool may still be a better fit.

26. Taskfile style guide

A Taskfile should be pleasant to read.

The official style guide recommends simple conventions:

• Use the suggested section order

• Use two spaces for indentation

• Separate main sections with blank lines

• Separate tasks with blank lines

• Use uppercase variable names

• Avoid whitespace inside template expressions

• Use kebab case for task names

• Use colons for namespaces

• Prefer external scripts over complex multi-line commands
  A clean Taskfile looks like this:

version: '3'

vars:
  APP_NAME: checkout-api

tasks:
  test:
    desc: Run tests
    cmds:
      - npm test

  build:
    desc: Build the app
    cmds:
      - npm run build

A messy Taskfile grows like this:

version: '3'
tasks:
  test_everything_now:
    cmds:
      - npm test
  dockerBuild:
    cmds:
      - docker build -t app .

The second one may work, but it communicates less.

Names are part of the interface. Treat them with care.

Good task names:

• setup

• dev

• test

• test:unit

• test:integration

• verify

• build

• docker:build

• docker:run

• k8s:validate

• k8s:apply

• docs:serve

• docs:check
  Avoid names that encode implementation details too early:

• run-npm-script-for-development

• docker-build-new

• fix-stuff

• ci2

• tmp-command
  A task name should say what the developer wants, not expose every implementation step.

27. A complete practical single-file Taskfile

At this point, the examples can become more complete.

Imagine a small Node.js service, such as an Express API used in a containerisation or Kubernetes course.

The project uses:

• npm

• Docker

• Docker Compose

• Kubernetes manifests

• jq

• yq

• 1Password CLI for secure local development

• .env.local for local non-production configuration

• .local-secrets for local development secrets
  A single-file Taskfile could look like this:

version: '3'

output: prefixed

vars:
  APP_NAME: checkout-api
  IMAGE: checkout-api:local
  NAMESPACE: dev
  K8S_DIR: k8s
  LOCAL_SECRETS_DIR: .local-secrets
  DB_PASSWORD_FILE: '{{joinPath .LOCAL_SECRETS_DIR "db-password"}}'
  LOCAL_CERT_DIR: '{{joinPath .HOME ".certs" "checkout-api"}}'
  LOCAL_CERT_FILE: '{{joinPath .LOCAL_CERT_DIR "dev.crt"}}'

dotenv:
  - .env.local
  - .env
  - '{{.HOME}}/.checkout-api.env'

includes:
  local:
    taskfile: ./Taskfile.local.yml
    optional: true

tasks:
  default:
    desc: Show available tasks
    cmds:
      - task --list
    silent: true

  paths:info:
    desc: Print useful project and user paths
    cmds:
      - echo "Root directory {{.ROOT_DIR}}"
      - echo "Taskfile directory {{.TASKFILE_DIR}}"
      - echo "Task execution directory {{.TASK_DIR}}"
      - echo "User working directory {{.USER_WORKING_DIR}}"
      - echo "Local secrets directory {{.LOCAL_SECRETS_DIR}}"
      - echo "Local certificate file {{.LOCAL_CERT_FILE}}"

  setup:
    desc: Install project dependencies
    sources:
      - package.json
      - package-lock.json
    generates:
      - node_modules/.package-lock.json
    cmds:
      - npm ci

  dev:
    desc: Start the development server with local environment files
    deps: [setup]
    preconditions:
      - sh: test -f package.json
        msg: package.json is required
      - sh: test -f .env.local
        msg: Create .env.local from .env.example before running the app
    cmds:
      - npm run dev

  dev:secure:
    desc: Start the development server with secrets from 1Password
    deps: [setup]
    preconditions:
      - sh: command -v op
        msg: 1Password CLI is required
      - sh: test -f .env.1password
        msg: Create .env.1password with 1Password secret references
    cmds:
      - op run --env-file .env.1password -- npm run dev

  test:
    desc: Run the test suite
    deps: [setup]
    cmds:
      - npm test

  test:integration:
    desc: Run integration tests that require database credentials
    deps: [setup]
    requires:
      vars: [DB_USER, DB_PASSWORD]
    env:
      DB_USER: '{{.DB_USER}}'
      DB_PASSWORD: '{{.DB_PASSWORD}}'
    cmds:
      - npm run test:integration

  test:integration:secure:
    desc: Run integration tests with secrets from 1Password
    preconditions:
      - sh: command -v op
        msg: 1Password CLI is required
      - sh: test -f .env.1password
        msg: Create .env.1password with secret references
    cmds:
      - op run --env-file .env.1password -- task test:integration

  lint:
    desc: Run linting
    deps: [setup]
    cmds:
      - npm run lint

  build:
    desc: Build the service
    deps: [setup]
    sources:
      - package.json
      - package-lock.json
      - 'src/**/*.js'
    generates:
      - dist/server.js
    cmds:
      - npm run build

  verify:
    desc: Run local checks before pushing
    cmds:
      - task: lint
      - task: test
      - task: build
      - task: docker:build
      - task: k8s:validate

  secrets:init:
    desc: Create local development secret files
    cmds:
      - mkdir -p "{{.LOCAL_SECRETS_DIR}}"
      - test -f "{{.DB_PASSWORD_FILE}}" || printf "checkout-dev-password\n" > "{{.DB_PASSWORD_FILE}}"
      - cmd: chmod 600 "{{.DB_PASSWORD_FILE}}"
        platforms: [linux, darwin]

  secrets:check:
    desc: Check required local secret files without printing values
    preconditions:
      - sh: test -f "{{.DB_PASSWORD_FILE}}"
        msg: Create {{.DB_PASSWORD_FILE}} first
    cmds:
      - echo "Required local secret files are present"

  cert:check:
    desc: Check that the local development certificate exists
    preconditions:
      - sh: test -f "{{.LOCAL_CERT_FILE}}"
        msg: Create {{.LOCAL_CERT_FILE}} before starting HTTPS locally
    cmds:
      - echo "Local certificate is present"

  docker:build:
    desc: Build the local Docker image
    sources:
      - Dockerfile
      - package.json
      - package-lock.json
      - 'src/**/*.js'
    cmds:
      - docker build -t "{{.IMAGE}}" .

  docker:build-private:
    desc: Build the Docker image using a private npm configuration as a BuildKit secret
    preconditions:
      - sh: test -f "{{.HOME}}/.npmrc"
        msg: ~/.npmrc is required for private package installation
    cmds:
      - docker build --secret id=npmrc,src="{{.HOME}}/.npmrc" -t "{{.IMAGE}}" .

  docker:run:
    desc: Run the Docker image locally
    deps: [docker:build]
    cmds:
      - docker run --rm -p 3000:3000 "{{.IMAGE}}"

  compose:up:
    desc: Start local infrastructure with Docker Compose secrets
    deps: [secrets:check]
    preconditions:
      - sh: command -v docker
        msg: Docker is required
      - sh: test -f compose.yml
        msg: compose.yml is required
    cmds:
      - docker compose up -d

  compose:down:
    desc: Stop local infrastructure
    cmds:
      - docker compose down

  k8s:validate:
    desc: Validate Kubernetes YAML with yq and kubectl client dry run
    preconditions:
      - sh: command -v yq
        msg: yq is required
      - sh: command -v kubectl
        msg: kubectl is required
      - sh: test -d "{{.K8S_DIR}}"
        msg: Kubernetes directory not found
    cmds:
      - yq eval '.' "{{.K8S_DIR}}"/*.yaml > /dev/null
      - kubectl apply --dry-run=client -f "{{.K8S_DIR}}"

  k8s:validate-server:
    desc: Validate Kubernetes manifests against the current cluster API
    preconditions:
      - sh: command -v kubectl
        msg: kubectl is required
      - sh: test -d "{{.K8S_DIR}}"
        msg: Kubernetes directory not found
    cmds:
      - kubectl apply --dry-run=server -f "{{.K8S_DIR}}"

  k8s:secret:create:
    desc: Create or update the app Kubernetes Secret from local files
    deps: [secrets:check]
    preconditions:
      - sh: command -v kubectl
        msg: kubectl is required
    cmds:
      - |
        kubectl create secret generic "{{.APP_NAME}}-secrets" \
          --namespace "{{.NAMESPACE}}" \
          --from-file=db-password="{{.DB_PASSWORD_FILE}}" \
          --dry-run=client \
          -o yaml | kubectl apply -f -

  k8s:secret:create-from-1password:
    desc: Create or update the app Kubernetes Secret from 1Password
    preconditions:
      - sh: command -v op
        msg: 1Password CLI is required
      - sh: command -v kubectl
        msg: kubectl is required
      - sh: test -f .env.1password
        msg: Create .env.1password with secret references
    cmds:
      - |
        op run --env-file .env.1password -- sh -c '
          kubectl create secret generic "{{.APP_NAME}}-secrets" \
            --namespace "{{.NAMESPACE}}" \
            --from-literal=db-password="$DB_PASSWORD" \
            --dry-run=client \
            -o yaml | kubectl apply -f -
        '

  k8s:apply:
    desc: Apply Kubernetes manifests to a namespace
    requires:
      vars: [NAMESPACE]
    prompt:
      - Apply manifests to namespace {{.NAMESPACE}}?
    cmds:
      - kubectl create namespace "{{.NAMESPACE}}" --dry-run=client -o yaml | kubectl apply -f -
      - task: k8s:secret:create
      - kubectl apply -n "{{.NAMESPACE}}" -f "{{.K8S_DIR}}"

  k8s:pods:
    desc: List pods as JSON and extract useful fields with jq
    preconditions:
      - sh: command -v jq
        msg: jq is required
      - sh: command -v kubectl
        msg: kubectl is required
    cmds:
      - kubectl get pods -n "{{.NAMESPACE}}" -o json | jq '.items[] | {name: .metadata.name, phase: .status.phase}'

  k8s:logs:
    desc: Show logs for the app deployment
    cmds:
      - kubectl logs -n "{{.NAMESPACE}}" "deploy/{{.APP_NAME}}"

  k8s:delete:
    desc: Delete Kubernetes manifests from a namespace
    prompt:
      - Delete manifests from namespace {{.NAMESPACE}}?
    cmds:
      - kubectl delete -n "{{.NAMESPACE}}" -f "{{.K8S_DIR}}"

And these support files complete the example.

.gitignore:

.task/
.env
.env.local
.env.*.local
.env.1password
.local-secrets/
secrets/
Taskfile.local.yml

.env.example:

PORT=3000
DB_HOST=localhost
DB_PORT=5432
DB_USER=checkout
DB_PASSWORD=

.env.1password.example:

DB_PASSWORD=op://vault/item/password
STRIPE_SECRET_KEY=op://vault/item/secret-key

compose.yml:

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: checkout
      POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
      POSTGRES_DB: checkout
    secrets:
      - postgres_password
    ports:
      - "5432:5432"

secrets:
  postgres_password:
    file: ./.local-secrets/db-password

This Taskfile is useful because it gives the project a clear interface.

For onboarding:

task setup
task dev

For local verification:

task verify

For Docker:

task docker:build
task docker:run

For local infrastructure:

task secrets:init
task compose:up

For secure local development:

task dev:secure

For Kubernetes:

task k8s:validate
task k8s:validate-server
task k8s:apply NAMESPACE=dev
task k8s:pods
task k8s:logs

For user-specific paths:

task paths:info
task cert:check

For safety, dangerous tasks use prompts. Required tools are checked through preconditions. Repeated build work uses sources and generates. Kubernetes inspection uses jq. YAML validation uses yq. Secrets are loaded from local files or 1Password, not committed into the Taskfile.

This is the kind of Taskfile that improves DevExp because it reduces the number of things a developer must remember before they can be useful.

28. A complete modular Taskfile structure

The previous example is useful because everything is in one place.

But once a Taskfile grows, one place becomes too much place.

The next step is to split by responsibility.

.
├── Taskfile.yml
├── taskfiles
│   ├── Dev.yml
│   ├── Quality.yml
│   ├── Docker.yml
│   ├── Kubernetes.yml
│   ├── Secrets.yml
│   └── Docs.yml
├── scripts
│   └── init-local-secrets.js
├── package.json
├── package-lock.json
├── Dockerfile
├── compose.yml
├── .env.example
├── .env.1password.example
├── .gitignore
└── k8s
    ├── deployment.yaml
    └── service.yaml

The root Taskfile becomes the project’s front door.

Taskfile.yml

version: '3'

output: prefixed

vars:
  APP_NAME: checkout-api
  IMAGE: checkout-api:local
  NAMESPACE: dev
  K8S_DIR: k8s
  LOCAL_SECRETS_DIR: .local-secrets
  DB_PASSWORD_FILE: '{{joinPath .LOCAL_SECRETS_DIR "db-password"}}'

dotenv:
  - .env.local
  - .env
  - '{{.HOME}}/.checkout-api.env'

includes:
  dev:
    taskfile: ./taskfiles/Dev.yml
  quality:
    taskfile: ./taskfiles/Quality.yml
  docker:
    taskfile: ./taskfiles/Docker.yml
    vars:
      IMAGE: '{{.IMAGE}}'
  k8s:
    taskfile: ./taskfiles/Kubernetes.yml
    vars:
      APP_NAME: '{{.APP_NAME}}'
      NAMESPACE: '{{.NAMESPACE}}'
      K8S_DIR: '{{.K8S_DIR}}'
      DB_PASSWORD_FILE: '{{.DB_PASSWORD_FILE}}'
  secrets:
    taskfile: ./taskfiles/Secrets.yml
    vars:
      LOCAL_SECRETS_DIR: '{{.LOCAL_SECRETS_DIR}}'
      DB_PASSWORD_FILE: '{{.DB_PASSWORD_FILE}}'
  docs:
    taskfile: ./taskfiles/Docs.yml
  local:
    taskfile: ./Taskfile.local.yml
    optional: true

tasks:
  default:
    desc: Show available tasks
    cmds:
      - task --list
    silent: true

  setup:
    desc: Prepare the project for local development
    cmds:
      - task: dev:setup
      - task: secrets:init

  dev:
    desc: Start the local development environment
    cmds:
      - task: dev:start

  verify:
    desc: Run all local checks before pushing
    cmds:
      - task: quality:lint
      - task: quality:test
      - task: quality:build
      - task: docker:build
      - task: k8s:validate

  ci:
    desc: Run the verification workflow used by CI
    cmds:
      - task: verify

taskfiles/Dev.yml

version: '3'

tasks:
  setup:
    desc: Install project dependencies
    sources:
      - package.json
      - package-lock.json
    generates:
      - node_modules/.package-lock.json
    cmds:
      - npm ci

  start:
    desc: Start the development server
    deps: [setup]
    preconditions:
      - sh: test -f package.json
        msg: package.json is required
      - sh: test -f .env.local
        msg: Create .env.local from .env.example before starting the app
    cmds:
      - npm run dev

  secure:
    desc: Start the development server with secrets from 1Password
    deps: [setup]
    preconditions:
      - sh: command -v op
        msg: 1Password CLI is required
      - sh: test -f .env.1password
        msg: Create .env.1password with 1Password secret references
    cmds:
      - op run --env-file .env.1password -- npm run dev

taskfiles/Quality.yml

version: '3'

tasks:
  lint:
    desc: Run linting
    cmds:
      - npm run lint

  test:
    desc: Run the test suite
    cmds:
      - npm test

  test-integration:
    desc: Run integration tests that require database credentials
    requires:
      vars: [DB_USER, DB_PASSWORD]
    env:
      DB_USER: '{{.DB_USER}}'
      DB_PASSWORD: '{{.DB_PASSWORD}}'
    cmds:
      - npm run test:integration

  test-integration-secure:
    desc: Run integration tests with secrets from 1Password
    preconditions:
      - sh: command -v op
        msg: 1Password CLI is required
      - sh: test -f .env.1password
        msg: Create .env.1password with secret references
    cmds:
      - op run --env-file .env.1password -- task quality:test-integration

  build:
    desc: Build the application
    sources:
      - package.json
      - package-lock.json
      - 'src/**/*.js'
    generates:
      - dist/server.js
    cmds:
      - npm run build

taskfiles/Docker.yml

version: '3'

vars:
  IMAGE: checkout-api:local

tasks:
  build:
    desc: Build the local Docker image
    sources:
      - Dockerfile
      - package.json
      - package-lock.json
      - 'src/**/*.js'
    cmds:
      - docker build -t "{{.IMAGE}}" .

  build-private:
    desc: Build the Docker image using a private npm configuration as a BuildKit secret
    preconditions:
      - sh: test -f "{{.HOME}}/.npmrc"
        msg: ~/.npmrc is required for private package installation
    cmds:
      - docker build --secret id=npmrc,src="{{.HOME}}/.npmrc" -t "{{.IMAGE}}" .

  run:
    desc: Run the Docker image locally
    deps: [build]
    cmds:
      - docker run --rm -p 3000:3000 "{{.IMAGE}}"

  compose-up:
    desc: Start local infrastructure with Docker Compose
    cmds:
      - docker compose up -d

  compose-down:
    desc: Stop local infrastructure
    cmds:
      - docker compose down

taskfiles/Kubernetes.yml

version: '3'

vars:
  APP_NAME: checkout-api
  NAMESPACE: dev
  K8S_DIR: k8s
  DB_PASSWORD_FILE: .local-secrets/db-password

tasks:
  validate:
    desc: Validate Kubernetes manifests locally
    preconditions:
      - sh: command -v yq
        msg: yq is required
      - sh: command -v kubectl
        msg: kubectl is required
      - sh: test -d "{{.K8S_DIR}}"
        msg: Kubernetes directory not found
    cmds:
      - yq eval '.' "{{.K8S_DIR}}"/*.yaml > /dev/null
      - kubectl apply --dry-run=client -f "{{.K8S_DIR}}"

  validate-server:
    desc: Validate Kubernetes manifests against the current cluster API
    preconditions:
      - sh: command -v kubectl
        msg: kubectl is required
      - sh: test -d "{{.K8S_DIR}}"
        msg: Kubernetes directory not found
    cmds:
      - kubectl apply --dry-run=server -f "{{.K8S_DIR}}"

  secret-create:
    desc: Create or update the app Kubernetes Secret from local files
    preconditions:
      - sh: command -v kubectl
        msg: kubectl is required
      - sh: test -f "{{.DB_PASSWORD_FILE}}"
        msg: Create {{.DB_PASSWORD_FILE}} first
    cmds:
      - |
        kubectl create secret generic "{{.APP_NAME}}-secrets" \
          --namespace "{{.NAMESPACE}}" \
          --from-file=db-password="{{.DB_PASSWORD_FILE}}" \
          --dry-run=client \
          -o yaml | kubectl apply -f -

  secret-create-from-1password:
    desc: Create or update the app Kubernetes Secret from 1Password
    preconditions:
      - sh: command -v op
        msg: 1Password CLI is required
      - sh: command -v kubectl
        msg: kubectl is required
      - sh: test -f .env.1password
        msg: Create .env.1password with secret references
    cmds:
      - |
        op run --env-file .env.1password -- sh -c '
          kubectl create secret generic "{{.APP_NAME}}-secrets" \
            --namespace "{{.NAMESPACE}}" \
            --from-literal=db-password="$DB_PASSWORD" \
            --dry-run=client \
            -o yaml | kubectl apply -f -
        '

  apply:
    desc: Apply Kubernetes manifests to a namespace
    prompt:
      - Apply manifests to namespace {{.NAMESPACE}}?
    cmds:
      - kubectl create namespace "{{.NAMESPACE}}" --dry-run=client -o yaml | kubectl apply -f -
      - task: secret-create
      - kubectl apply -n "{{.NAMESPACE}}" -f "{{.K8S_DIR}}"

  pods:
    desc: List pods as JSON and extract useful fields with jq
    preconditions:
      - sh: command -v jq
        msg: jq is required
      - sh: command -v kubectl
        msg: kubectl is required
    cmds:
      - kubectl get pods -n "{{.NAMESPACE}}" -o json | jq '.items[] | {name: .metadata.name, phase: .status.phase}'

  logs:
    desc: Show logs for the app deployment
    cmds:
      - kubectl logs -n "{{.NAMESPACE}}" "deploy/{{.APP_NAME}}"

  delete:
    desc: Delete Kubernetes manifests from a namespace
    prompt:
      - Delete manifests from namespace {{.NAMESPACE}}?
    cmds:
      - kubectl delete -n "{{.NAMESPACE}}" -f "{{.K8S_DIR}}"

taskfiles/Secrets.yml

version: '3'

vars:
  LOCAL_SECRETS_DIR: .local-secrets
  DB_PASSWORD_FILE: '{{joinPath .LOCAL_SECRETS_DIR "db-password"}}'

tasks:
  init:
    desc: Create local development secret files
    cmds:
      - mkdir -p "{{.LOCAL_SECRETS_DIR}}"
      - test -f "{{.DB_PASSWORD_FILE}}" || printf "checkout-dev-password\n" > "{{.DB_PASSWORD_FILE}}"
      - cmd: chmod 600 "{{.DB_PASSWORD_FILE}}"
        platforms: [linux, darwin]

  init-portable:
    desc: Create local development secret files with Node.js
    cmds:
      - node scripts/init-local-secrets.js

  check:
    desc: Check required local secret files without printing values
    preconditions:
      - sh: test -f "{{.DB_PASSWORD_FILE}}"
        msg: Create {{.DB_PASSWORD_FILE}} first
    cmds:
      - echo "Required local secret files are present"

  check-env:
    desc: Check required secret variables without printing values
    cmds:
      - test -n "$DB_PASSWORD"
      - echo "Required secret variables are present"

taskfiles/Docs.yml

version: '3'

tasks:
  serve:
    desc: Serve documentation locally
    cmds:
      - npm run docs:serve

  check:
    desc: Check documentation quality
    cmds:
      - npm run docs:check

Taskfile.local.yml

This file is optional and ignored by Git.

version: '3'

tasks:
  tunnel:
    desc: Start my personal local tunnel
    cmds:
      - cloudflared tunnel run checkout-api-dev

  open-db:
    desc: Open my local database client
    cmds:
      - open -a TablePlus

Add it to .gitignore:

Taskfile.local.yml

This modular structure is more advanced, but it is also easier to scale.

The root file remains the narrative entry point.

The included files hold responsibility-specific detail.

The team still gets a single command interface:

task setup
task dev
task verify
task docker:build
task docker:compose-up
task k8s:validate
task k8s:validate-server
task k8s:apply
task secrets:check
task docs:serve

That is the balance to protect.

Do not turn the Taskfile structure into architecture theatre. Split when it helps people work with the project.

29. Common mistakes

Treating Task as a bag of aliases

A Taskfile should not be a random list of personal shortcuts.

Bad:

version: '3'

tasks:
  thing:
    cmds:
      - npm run x

  stuff:
    cmds:
      - docker ps

  magic:
    cmds:
      - ./scripts/do-everything.sh

Better:

version: '3'

tasks:
  setup:
    desc: Install dependencies
    cmds:
      - npm ci

  dev:
    desc: Start the development environment
    cmds:
      - npm run dev

  verify:
    desc: Run checks before pushing
    cmds:
      - task: test
      - task: build

The difference is intent.

Using deps for ordered workflows

This is a frequent mistake:

version: '3'

tasks:
  release:
    deps: [test, build, publish]

Those dependencies can run in parallel. If order matters, write the order:

version: '3'

tasks:
  release:
    cmds:
      - task: test
      - task: build
      - task: publish

Hiding important tasks without descriptions

If a task is part of the project interface, give it a description.

version: '3'

tasks:
  verify:
    desc: Run local checks before pushing
    cmds:
      - task: test
      - task: build

A task without a description may be fine for internal implementation detail. A public task should explain itself.

Putting too much logic in YAML

This is hard to maintain:

version: '3'

tasks:
  complex:
    cmds:
      - |
        for file in $(find . -name '*.yaml'); do
          echo "$file"
          yq eval '.' "$file" > /dev/null
        done

This is usually better:

version: '3'

tasks:
  yaml:validate:
    desc: Validate YAML files
    cmds:
      - ./scripts/validate-yaml.sh

Task should orchestrate. Scripts should hold complex logic.

Ignoring local and CI drift

If CI runs a different workflow from local development, Task loses part of its value.

A better pattern is:

version: '3'

tasks:
  ci:
    desc: Run the same verification used by CI
    cmds:
      - task: verify

  verify:
    desc: Run local verification
    cmds:
      - task: lint
      - task: test
      - task: build

Then CI calls:

task ci

The closer local and CI workflows are, the fewer surprises the team gets.

Hardcoding personal paths

This is a common DevExp smell:

version: '3'

tasks:
  config:
    cmds:
      - cat /Users/alice/dev/config.yml

Better:

version: '3'

vars:
  CONFIG_FILE: '{{joinPath .HOME ".config" "checkout-api" "config.yml"}}'

tasks:
  config:
    desc: Show the configured local file path
    cmds:
      - echo "{{.CONFIG_FILE}}"

Even better, fail clearly when the file matters:

version: '3'

vars:
  CONFIG_FILE: '{{joinPath .HOME ".config" "checkout-api" "config.yml"}}'

tasks:
  config:check:
    desc: Check that the local config file exists
    preconditions:
      - sh: test -f "{{.CONFIG_FILE}}"
        msg: Missing local config file at {{.CONFIG_FILE}}
    cmds:
      - echo "Local config file exists"

The task no longer assumes one developer’s machine.

Assuming cross-platform means every command is portable

Task can run on multiple platforms.

That does not make every shell command portable.

This is fragile if the team includes native Windows users:

version: '3'

tasks:
  clean:
    cmds:
      - rm -rf dist

A more honest version is this:

version: '3'

tasks:
  clean:
    cmds:
      - cmd: rm -rf dist
        platforms: [linux, darwin]
      - cmd: powershell -Command "Remove-Item -Recurse -Force dist"
        platforms: [windows]

Or move the operation to a cross-platform script if the project already has a runtime for it.

Printing secrets to debug tasks

This is not acceptable:

version: '3'

tasks:
  debug:
    cmds:
      - echo "$DB_PASSWORD"

Use presence checks instead:

version: '3'

tasks:
  secrets:check:
    desc: Check required secret variables without printing values
    cmds:
      - test -n "$DB_PASSWORD"
      - echo "DB_PASSWORD is present"

The difference is small in code and large in risk.

Treating Kubernetes Secrets as enough

A Kubernetes Secret is not a full security strategy by itself.

It is a Kubernetes object for holding sensitive values. You still need to think about encryption at rest, RBAC, namespace boundaries, auditability, rotation, backup exposure and how values reach the cluster in the first place.

Task can help you make the workflow repeatable.

It cannot decide your security model.

Splitting Taskfiles too early

This can look organised while making the project harder to understand:

taskfiles/Build.yml
taskfiles/Test.yml
taskfiles/Dev.yml
taskfiles/Clean.yml
taskfiles/Utils.yml

If each file contains one tiny task, the split probably adds more friction than value.

Start with one Taskfile.

Split when responsibilities become visible.

Do not use modularity to avoid naming things clearly.

30. How to adopt Task in an existing project

Start small.

Do not migrate every command on day one.

A good first Taskfile has only the core workflow:

version: '3'

tasks:
  default:
    desc: Show available tasks
    cmds:
      - task --list
    silent: true

  setup:
    desc: Install dependencies
    cmds:
      - npm ci

  dev:
    desc: Start development
    cmds:
      - npm run dev

  test:
    desc: Run tests
    cmds:
      - npm test

  verify:
    desc: Run checks before pushing
    cmds:
      - task: test

Then add tasks when the project feels friction.

Good candidates:

• A command people frequently ask about

• A command that differs across operating systems

• A command used both locally and in CI

• A command that requires several flags

• A command that has safety implications

• A command that validates generated files, Kubernetes manifests, JSON or YAML

• A command that new developers need during onboarding

• A command that needs user-specific configuration

• A command that needs secrets but should not expose them
  A practical adoption path:

1. Add task setup, task dev, task test and task verify

2. Add descriptions to make task --list useful

3. Move CI to call task verify or task ci

4. Add Docker and Kubernetes tasks if the project uses containers

5. Add preconditions for required tools and files

6. Add sources, generates or status for expensive repeated work

7. Add user-specific path handling where developers currently copy local paths into docs

8. Add explicit secret workflows using .env.example, ignored local files and approved secret managers

9. Review which commands are truly cross-platform and which ones need platforms or scripts

10. Split into included Taskfiles only when the root Taskfile becomes difficult to navigate

11. Review the Taskfile as part of project maintenance
    This last point matters. A Taskfile can rot like any other artifact. If it no longer reflects how the project works, it becomes another source of confusion.

Treat it as production DevExp.

31. Conclusions

Task is valuable because it gives a project a shared interface.

That sounds small. It is not.

A shared interface changes how developers experience the project. They no longer need to reconstruct workflows from scattered documentation, shell history, CI configuration and team memory. They can ask the project what it knows how to do.

That reduces onboarding cost. It reduces repeated explanations. It reduces local and CI drift. It makes cross-platform work more explicit. It makes dangerous tasks more visible. It makes common work easier to repeat.

The value becomes even clearer when paths and secrets enter the picture.

Hardcoded paths turn one developer’s machine into an invisible dependency. Secrets inside automation turn convenience into risk. A good Taskfile avoids both problems. It lets the project define the workflow while letting each developer provide their own local configuration safely.

The same is true for modularity.

A small Taskfile can be simple and useful. A larger Taskfile can be split by responsibility. But the goal is not to create more files. The goal is to preserve one coherent project interface as the workflow grows.

The same is also true for cross-platform work.

Task can give the team a portable entry point. It cannot magically make every command portable. That is why good Taskfiles are explicit about platform-specific commands, and why complex logic often belongs in scripts written in runtimes the project already uses.

Task is not magic. A bad Taskfile is just another messy file. But a good Taskfile becomes a compact map of how to work with the system.

The best Taskfiles are boring in the right way.

They have clear names. They have descriptions. They separate public tasks from internal tasks. They use dependencies only when parallelism makes sense. They use sequential task calls when order matters. They check preconditions. They make repeated work incremental. They keep complex logic in scripts. They make local workflows and CI workflows closer. They do not hardcode personal paths. They do not store secrets. They do not pretend Kubernetes Secrets solve the whole security problem. They split only when the split makes the project easier to understand.

That is why Task is a strong DevExp tool.

Not because it saves a few keystrokes.

Because it turns operational knowledge into something the whole team can run.

References

• Task Project. Task: The Modern Task Runner.

https://taskfile.dev/

• Task Project. Installation. https://taskfile.dev/docs/installation

• Task Project. Getting Started. https://taskfile.dev/docs/getting-started

• Task Project. Guide. https://taskfile.dev/docs/guide

• Task Project. Taskfile Schema Reference. https://taskfile.dev/docs/reference/schema

• Task Project. Command Line Interface Reference. https://taskfile.dev/docs/reference/cli

• Task Project. Environment Reference. https://taskfile.dev/docs/reference/environment

• Task Project. Configuration Reference. https://taskfile.dev/docs/reference/config

• Task Project. Templating Reference. https://taskfile.dev/docs/reference/templating

• Task Project. Taskfile Versions. https://taskfile.dev/docs/taskfile-versions

• Task Project. Style Guide. https://taskfile.dev/docs/styleguide

• 1Password. run. https://developer.1password.com/docs/cli/reference/commands/run/

• 1Password. Load secrets into the environment. https://developer.1password.com/docs/cli/secrets-environment-variables/

• Docker. Manage secrets securely in Docker Compose. https://docs.docker.com/compose/how-tos/use-secrets/

• Docker. Secrets. https://docs.docker.com/reference/compose-file/secrets/

• Docker. Build secrets. https://docs.docker.com/build/building/secrets/

• Kubernetes. Secrets. https://kubernetes.io/docs/concepts/configuration/secret/

• Kubernetes. kubectl create secret generic. https://kubernetes.io/docs/reference/kubectl/generated/kubectl_create/kubectl_create_secret_generic/

• Kubernetes. Managing Secrets using kubectl. https://kubernetes.io/docs/tasks/configmap-secret/managing-secret-using-kubectl/

Practise discovering responsibilities and collaborations while implementing a small scheduling workflow.

The exercise is intentionally manual. The organiser already knows which talk they want to schedule, which room they want to use, and which time they want. The system accepts or rejects that request according to the business rules.

This kata is not about finding an optimal schedule. It is about noticing how responsibility placement changes as more scheduling rules appear.

Business context

A one-day software conference needs a simple scheduling tool.

The organiser builds the public agenda by placing talks into rooms at specific times. Attendees use that agenda to know what happens, where it happens, and when it happens.

The system must protect the agenda from impossible schedules. A conference schedule is not valid just because talks have titles and times. It must also respect rooms, speakers, availability, and suitability.

Problem to solve

Build the behaviour needed to schedule talks into rooms and show the public agenda.

A talk has:

• A title

• A speaker

• An expected number of attendees

• Optional requirements, such as needing a projector

A room has:

• A name

• A capacity

• Optional capabilities, such as having a projector

A speaker may be unavailable at specific times.

Vocabulary

Use this vocabulary to describe the business problem. It is not a proposed implementation model.

• Conference

• Public agenda

• Talk

• Speaker

• Room

• Time

• Capacity

• Capability

• Scheduling request

• Move request

• Rejected request

Fixed rules

• The organiser schedules one talk at a time.

• Time is represented using fixed labels such as 09:00, 10:00, and 11:00.

• A room can host at most one talk at the same time.

• A speaker can give at most one talk at the same time.

• A room is suitable only when it has enough capacity and the required capabilities.

• A rejected scheduling request must not change the existing agenda.

• A rejected move request must not change the existing agenda.

Scenario map

Participant checklist

Before moving to the next scenario:

• Is the behaviour covered by a failing test first?

• Is the expected outcome observable from outside the implementation?

• Are previous scenarios still passing?

• Does the test describe business behaviour rather than internal structure?

• Did the last change introduce duplication worth refactoring?

• Can the current design be explained without mentioning a framework, database, or user interface?

Rule 1: The agenda reflects scheduled talks

What this rule means

The public agenda is the visible result of the scheduling work.

If nothing has been scheduled, the agenda is empty. If talks have been scheduled, the agenda shows those talks. The agenda should be useful for attendees, so talks must be shown in chronological order, regardless of the order in which the organiser scheduled them.

This rule does not say how the schedule is stored. It only says what the conference must be able to show.

Why this rule matters

This rule gives the kata its first observable behaviour.

Before rejecting invalid schedules, checking room conflicts, or moving talks, the system must be able to show what has already been accepted into the conference schedule.

The agenda is not a technical report. It is what attendees would read to know what happens during the day.

Example

The organiser schedules “Refactoring legacy code” at 09:00.

When the public agenda is requested, the talk appears at 09:00.

Counterexample

A new conference has no scheduled talks.

When the public agenda is requested, it should not invent placeholder talks, default sessions, or sample data. It should be empty.

What this rule adds to the kata

This rule starts with visibility. The first behaviour is not validation. The first behaviour is showing what the business has accepted so far.

Later rules will make it harder for something to become accepted into the agenda. For now, the goal is simply to make accepted talks visible.

Rule diagram

Scenario 1.1: Show an empty agenda

Business example

A conference has just been created and no talk has been placed yet.

Gherkin

Scenario: Show an empty agenda
  Given a conference with no scheduled talks
  When the public agenda is requested
  Then the agenda is empty

Diagram

Scenario 1.2: Schedule one talk

Business example

The organiser places one talk in a room that can host it.

Gherkin

Scenario: Schedule one talk
  Given Room A can host "Refactoring legacy code" at 09:00
  When the organiser schedules "Refactoring legacy code" in Room A at 09:00
  Then "Refactoring legacy code" appears in the public agenda at 09:00

Diagram

Scenario 1.3: Show several scheduled talks

Business example

The public agenda should show more than one scheduled talk.

Gherkin

Scenario: Show several scheduled talks
  Given 3 talks are scheduled
  When the public agenda is requested
  Then the agenda shows 3 talks

Diagram

Scenario 1.4: Show scheduled talks in chronological order

Business example

Talks may be scheduled in any order, but attendees need to read the agenda by time.

Gherkin

Scenario: Show scheduled talks in chronological order
  Given talks are scheduled at 11:00, 09:00, and 10:00
  When the public agenda is requested
  Then the talks are shown as 09:00, 10:00, and 11:00

Diagram

Rule 2: A room cannot host conflicting talks

What this rule means

A room can only host one talk at a given time.

Two talks may happen at the same time in the conference, but not in the same room. This is about protecting a physical constraint. A room cannot contain two independent sessions at the same time.

Why this rule matters

The agenda must be realistic.

A schedule that places two talks in Room A at 09:00 is not a valid conference schedule, even if both talks are otherwise valid.

This rule introduces the difference between:

A talk can exist.

and:

A talk can be placed in this room at this time.

Example

Room A hosts “Refactoring legacy code” at 09:00.

Room B hosts “Testing microservices” at 09:00.

This is allowed because the talks use different rooms.

Counterexample

Room A already hosts “Refactoring legacy code” at 09:00.

The organiser then tries to schedule “Testing microservices” in Room A at 09:00.

The request must be rejected.

What this rule adds to the kata

The system now has to preserve a valid agenda, not only record requested talks.

A rejected request must not replace or remove the talk that was already scheduled. Rejection is not just a return value or an error. It also means the previous valid schedule remains valid.

Rule diagram

Scenario 2.1: Schedule two talks in different rooms at the same time

Business example

Two different rooms can host two talks at the same time.

Gherkin

Scenario: Schedule two talks in different rooms at the same time
  Given Room A is available at 09:00
  And Room B is available at 09:00
  When two talks are scheduled at 09:00 in different rooms
  Then both talks appear in the public agenda

Diagram

Scenario 2.2: Reject two talks in the same room at the same time

Business example

A room already used at 09:00 cannot host another talk at 09:00.

Gherkin

Scenario: Reject two talks in the same room at the same time
  Given Room A already has a talk at 09:00
  When another talk is scheduled in Room A at 09:00
  Then the scheduling request is rejected

Diagram

Scenario 2.3: Keep the original talk after a room conflict

Business example

A rejected conflicting request must not remove or replace the original scheduled talk.

Gherkin

Scenario: Keep the original talk after a room conflict
  Given "Refactoring legacy code" is scheduled in Room A at 09:00
  When "Testing microservices" is scheduled in Room A at 09:00
  Then "Refactoring legacy code" remains scheduled in Room A at 09:00

Diagram

Rule 3: A speaker cannot give overlapping talks

What this rule means

A speaker can only give one talk at a given time.

Even if two different rooms are available, the same person cannot speak in both rooms at once.

This rule is different from room conflict. A room conflict is about a place. A speaker conflict is about a person.

Why this rule matters

A schedule can look valid from the room perspective and still be impossible for a speaker.

The conference needs a schedule that works for both attendees and speakers. A schedule that asks Alice to give two talks at 09:00 is not valid, even when those talks are in different rooms.

Example

Alice gives a talk at 09:00.

Bob gives another talk at 09:00.

This is allowed because they are different speakers.

Counterexample

Alice is already giving a talk at 09:00.

The organiser tries to schedule another talk by Alice at 09:00.

The request must be rejected.

What this rule adds to the kata

The system now has more than one kind of conflict.

A talk can be rejected because of the room, because of the speaker, or because the speaker is unavailable. The kata starts to move from simple storage toward business rules that interact.

Rule diagram

Scenario 3.1: Schedule two talks by different speakers at the same time

Business example

Different speakers can give different talks at the same time.

Gherkin

Scenario: Schedule two talks by different speakers at the same time
  Given Alice is available at 09:00
  And Bob is available at 09:00
  When their talks are scheduled at 09:00
  Then both talks appear in the public agenda

Diagram

Scenario 3.2: Reject two talks by the same speaker at the same time

Business example

Alice cannot give two talks at 09:00.

Gherkin

Scenario: Reject two talks by the same speaker at the same time
  Given Alice is already speaking at 09:00
  When another talk by Alice is scheduled at 09:00
  Then the scheduling request is rejected

Diagram

Scenario 3.3: Reject a talk when the speaker is unavailable

Business example

A speaker may be unavailable even when they are not already scheduled for another talk.

Gherkin

Scenario: Reject a talk when the speaker is unavailable
  Given Alice is unavailable at 09:00
  When Alice's talk is scheduled at 09:00
  Then the scheduling request is rejected

Diagram

Rule 4: A room must be suitable for the talk

What this rule means

A room being free is not enough. The room must also be appropriate for the talk.

A talk may need enough seats for expected attendees. A talk may also need a capability such as a projector. If the room does not satisfy those needs, the talk cannot be placed there.

Why this rule matters

A schedule should not only avoid conflicts. It should also make sense operationally.

A room with 30 seats cannot host a talk expecting 40 people. A talk that requires a projector cannot be placed in a room without one.

Example

A room has capacity 40.

A talk expects 40 attendees.

The room is suitable by capacity.

Counterexample

A room has capacity 39.

A talk expects 40 attendees.

The request must be rejected because the room is too small.

What this rule adds to the kata

The idea of “valid scheduling” becomes richer.

A request can now be rejected even when the room is free and the speaker is available. Availability and suitability are not the same thing.

Rule diagram

Scenario 4.1: Schedule a talk when the room has exactly enough capacity

Business example

A room with capacity 40 can host a talk expecting 40 attendees.

Gherkin

Scenario: Schedule a talk when the room has exactly enough capacity
  Given Room A has capacity 40
  When a talk for 40 attendees is scheduled in Room A
  Then the talk appears in the public agenda

Diagram

Scenario 4.2: Reject a talk when the room is too small

Business example

A room with capacity 39 cannot host a talk expecting 40 attendees.

** Keep in mind that this is not probably how you would implemented in real life, because you may reject the attendee if you instead of the talk or have other kind of solution for this, this is only for the kata purpose.

Gherkin

Scenario: Reject a talk when the room is too small
  Given Room A has capacity 39
  When a talk for 40 attendees is scheduled in Room A
  Then the scheduling request is rejected

Diagram

Scenario 4.3: Schedule a talk when the room has the required capability

Business example

A talk requiring a projector can be scheduled in a room with a projector.

Gherkin

Scenario: Schedule a talk when the room has the required capability
  Given Room A has a projector
  When a talk requiring a projector is scheduled in Room A
  Then the talk appears in the public agenda

Diagram

Scenario 4.4: Reject a talk when the room lacks the required capability

Business example

A talk requiring a projector cannot be scheduled in a room without one.

Gherkin

Scenario: Reject a talk when the room lacks the required capability
  Given Room A has no projector
  When a talk requiring a projector is scheduled in Room A
  Then the scheduling request is rejected

Diagram

Rule 5: Scheduled talks can be moved safely

What this rule means

The organiser can move an already scheduled talk to another room or time, but the move must obey the same business rules as a new scheduling request.

If the target room and time are valid, the talk moves. If the target is invalid, the move is rejected and the original schedule remains unchanged.

Why this rule matters

Real schedules change.

A speaker may request another time, a room may become unavailable, or the organiser may want to improve the agenda.

But changing a schedule is risky. A failed move should not leave the agenda half-changed. The system must protect the current valid agenda while trying to apply the requested change.

Example

“Refactoring legacy code” is scheduled at 09:00.

The organiser moves it to an available slot at 10:00.

The agenda now shows it at 10:00.

Counterexample

“Refactoring legacy code” is scheduled in Room A at 09:00.

The organiser tries to move it to Room B at 10:00, but Room B is already occupied at 10:00.

The move is rejected and the talk remains in Room A at 09:00.

What this rule adds to the kata

The kata now asks for safe change, not only initial scheduling.

The system must protect the current valid schedule when a requested change cannot be accepted.

Rule diagram

Scenario 5.1: Move a talk to an available slot

Business example

A scheduled talk can be moved to another valid time.

Gherkin

Scenario: Move a talk to an available slot
  Given "Refactoring legacy code" is scheduled at 09:00
  When the organiser moves it to 10:00
  Then "Refactoring legacy code" appears in the public agenda at 10:00

Diagram

Scenario 5.2: Release the original slot after moving a talk

Business example

After a successful move, another talk can use the original room and time.

Gherkin

Scenario: Release the original slot after moving a talk
  Given "Refactoring legacy code" is scheduled in Room A at 09:00
  When the organiser moves it to Room B at 10:00
  Then another talk can be scheduled in Room A at 09:00

Diagram

Scenario 5.3: Reject a move that creates a room conflict

Business example

A talk cannot be moved into a room and time that are already occupied.

Gherkin

Scenario: Reject a move that creates a room conflict
  Given Room A already has a talk at 10:00
  When another talk is moved to Room A at 10:00
  Then the move request is rejected

Diagram

Scenario 5.4: Keep the original schedule after a rejected move

Business example

A rejected move must not remove the original scheduled talk.

Gherkin

Scenario: Keep the original schedule after a rejected move
  Given "Refactoring legacy code" is scheduled in Room A at 09:00
  When it is moved to an occupied room at 10:00
  Then "Refactoring legacy code" remains scheduled in Room A at 09:00

Diagram

Resume

Strategy conversations often fail in the same way. The language sounds confident, but the landscape is missing. A team may have a roadmap, quarterly objectives, product bets, architecture diagrams, and budget commitments, yet still struggle to explain why one move makes sense now and another does not.

This is the problem Wardley Mapping tries to solve. It gives teams a way to make strategic context visible. Instead of debating from opinions, status, vendor pressure, or fashionable practices, the team can discuss users, needs, dependencies, maturity, constraints, and movement.

A Wardley map does not make the decision for you. It does something more practical: it improves the conversation before the decision is made.

TL;DR

• Wardley Mapping is a way to visualize strategic context by starting with users and their needs.

• A map shows the value chain required to satisfy those needs, from visible user-facing capabilities to hidden enabling components.

• Each component is placed on an evolution axis: genesis, custom built, product, and commodity or utility.

• The same management approach should not be used for every component. Novel work needs learning, custom work needs close collaboration, product-like work needs evaluation, and commodity work needs standardization.

• Wardley Mapping helps with product strategy, platform strategy, build versus buy, legacy modernization, cloud migration, outsourcing, team boundaries, and prioritization.

• The goal is not to create a perfect drawing. The goal is to expose assumptions, find mismatches, and make better strategic moves.

• A useful first map can be created around one real decision, one user, one need, and one value chain.

• The article includes a complete worked example for an e-commerce self-service returns portal.

Index

1. Why strategy needs a map

2. What Wardley Mapping is

3. The two whys: purpose and movement

4. How a Wardley map works

5. The four stages of evolution

6. How to create your first map

7. Complete worked example: self-service returns portal

8. How to read map patterns

9. Real uses at work

10. Common mistakes

11. How to run a 90-minute mapping session

12. Conclusions

13. References

1. Why strategy needs a map

Most teams do not fail because they lack ambition. They fail because they lack position. They know what they want to achieve, but they cannot clearly explain where they are, what the landscape looks like, which constraints matter, and why this move is better than another.

This is why strategy documents can be dangerous. They often contain familiar words that make people feel safe: innovation, efficiency, alignment, customer-centricity, transformation, platform, ecosystem, Artificial Intelligence, cloud, modernization. These words may be useful, but they are not strategy by themselves. They do not show the user need, the dependencies, the maturity of each capability, the likely direction of change, or the cost of choosing one move over another.

A team can say, “We need a platform,” without showing which repeated needs the platform will serve. A company can say, “We need to modernize,” without identifying which part of the legacy system blocks valuable change. A product organization can say, “We need this feature,” without proving whether it addresses a real user need or merely satisfies a stakeholder request.

Wardley Mapping introduces discipline into this conversation. It asks the team to stop treating strategy as a polished story and start treating it as situated judgment. Before deciding what to do, the team must describe the landscape in which the decision lives.

That shift matters because software and product work are economic work. Every product decision, architecture decision, vendor decision, platform decision, and modernization decision spends money, time, attention, and organizational capacity. When the landscape is unclear, the investment is exposed to avoidable waste and risk.

2. What Wardley Mapping is

Wardley Mapping is a practice for visualizing a strategic landscape. It begins with users and their needs, then maps the chain of components required to satisfy those needs. Each component is positioned according to two dimensions: how visible it is to the user, and how evolved it is.

The vertical dimension is the value chain. Components near the top are more visible to the user. Components lower down are less visible, although they may still be essential. For example, a customer using an e-commerce returns portal cares about whether they can return an item easily, track the process, and receive a refund. They do not usually care whether the company hand-built its address validation service, hosting layer, or email delivery mechanism.

The horizontal dimension is evolution. Components move from uncertain and novel to more common, standardized, and expected. A new business capability may begin as exploration. Over time it may become custom built, then available as a product, and eventually treated as a commodity or utility.

This second dimension is what makes Wardley Mapping more than a dependency diagram. A dependency diagram may show that a returns portal needs payment integration, carrier integration, order history, and customer notifications. A Wardley map also asks whether those components are novel, custom, product-like, or commodity-like.

That question changes the strategy. If a component is commodity-like, handcrafting it may be wasteful. If a component is novel, treating it as predictable delivery may be naive. If a component is custom and strategically important, outsourcing it too early may move learning outside the organization. If a component is mature but critical, the right concern may be resilience, ownership, and operational quality rather than differentiation.

Wardley Mapping is not about making prettier diagrams. It is about making better decisions under uncertainty.

3. The two whys: purpose and movement

A useful distinction in Wardley Mapping is the difference between the why of purpose and the why of movement. The why of purpose explains what we are trying to achieve. The why of movement explains why this move makes sense from our current position.

Most organizations are more comfortable with purpose than movement. They can say they want better customer experience, faster delivery, lower cost, higher reliability, stronger product differentiation, or improved operational efficiency. Those goals may be valid, but they do not explain which move should happen next.

Consider a company that says, “We want to improve customer experience by making returns easier.” That is purpose. It matters, but it is not enough. The movement question is more specific: should the company build a custom returns portal, buy a returns management product, extend its commerce platform, improve customer support scripts, change return policy rules, or fix warehouse processing first?

Each of those moves may support the purpose. They are not equally good. Their value depends on the landscape: user needs, current capabilities, existing systems, operational constraints, component maturity, cost, risk, and timing.

This is where Wardley Mapping becomes useful. It helps the team connect purpose to movement. It does not stop at “we want better returns.” It asks what the customer needs, what capabilities satisfy that need, what those capabilities depend on, how evolved each dependency is, and which move improves the situation.

The practical consequence is simple. A strategy should not only explain what the organization wants. It should explain why this move is appropriate in this context.

4. How a Wardley map works

A Wardley map has a simple structure. It starts with a user. The user has needs. Those needs require capabilities. Those capabilities depend on other components. The map places those components vertically by visibility and horizontally by evolution.

The first anchor is the user. This prevents the conversation from starting with internal preferences. A team may want to sell a product, reduce cost, reuse a platform, adopt a vendor, or remove a legacy system. Those may be legitimate business concerns, but the map begins with the person or group receiving value.

The second element is the user need. This should be expressed as an outcome, not as a solution. “A returns portal” is not a user need. “The customer needs to know whether an item can be returned, start the process easily, and understand when the refund will arrive” is closer to a need.

The third element is the value chain. Once the need is clear, the team identifies what must exist to satisfy it. In an e-commerce returns flow, visible capabilities might include eligibility checking, return request creation, label generation, tracking, refund status, and customer notifications. Underneath those visible capabilities sit less visible components such as order history, product catalog, return policy rules, carrier integration, warehouse status, payment refund integration, fraud checks, authentication, address validation, monitoring, and hosting.

The fourth element is evolution. Each component is placed from left to right according to how mature and industrialized it is. The team asks whether the component is novel and uncertain, custom to the organization, available as a product, or commodity-like.

The map is useful because it combines these ideas in one shared view. It shows what the user values, what the organization must provide, what sits underneath the visible experience, and which components should be treated differently because they are at different stages of evolution.

A first map will not be perfect. That is acceptable. The value is not in producing a final artifact. The value is in making assumptions visible enough for the team to challenge them.

5. The four stages of evolution

The evolution axis is central to Wardley Mapping because it changes how work should be treated. The same delivery model, funding model, governance model, and team structure should not be applied to every component.

Genesis

Genesis is the uncertain beginning. The component is novel, rare, unstable, and poorly understood. The team does not yet know exactly what shape it should take, whether users will value it, or which constraints will matter most.

Work in genesis needs learning. It should be approached through discovery, experiments, prototypes, fast feedback, and careful reduction of uncertainty. A fixed delivery promise can be dangerous here because the team may not yet understand what it is building.

In a returns example, a new predictive model for detecting return abuse in a highly specific market might be genesis if the organization has never tested it and does not know whether the signals are useful.

Custom built

Custom built means the component is understood enough to build, but it remains specific to the context. It may change often, depend on local knowledge, or reflect business-specific rules.

Work in this stage needs close collaboration. It often requires product, engineering, operations, legal, support, and domain experts to work together because the component encodes how the business actually works.

In a returns portal, return policy rules may be custom built. They may depend on country, product category, customer segment, promotional conditions, delivery date, item condition, fraud risk, and commercial strategy.

Product

A product-like component is more mature. Vendors exist. Patterns are known. Comparison is possible. The organization can evaluate options instead of inventing everything from scratch.

Work in this stage needs selection, integration, lifecycle management, and vendor understanding. The economic risk is excessive customization. A product can reduce cost and time, but only if the organization avoids bending it into a poor copy of its old process.

In a returns portal, carrier integration or customer notification tooling may be product-like. Many services already exist, and the team should be careful before building these capabilities from scratch.

Commodity or utility

Commodity or utility components are standardized, widespread, expected, and often invisible to the user. The user does not reward the company for handcrafting them, but failure may still be painful.

Work in this stage needs standardization, automation, operational discipline, cost awareness, and resilience. The goal is usually not differentiation. The goal is reliable, low-friction consumption.

In a returns portal, authentication, hosting, address validation, and basic logging are likely to be commodity-like or close to it. They may still require security and operational care, but they are rarely the strategic reason customers choose the company.

The important lesson is that evolution changes the economics of work. A component can begin as a source of differentiation and later become an expected utility. When that happens, the organization must change how it manages the component. Continuing to treat commodity work as bespoke craft consumes attention that could be used where learning or differentiation matter more.

6. How to create your first map

The easiest way to start is to map one real decision. Do not map the entire company. Do not start with an abstract transformation theme. Pick one product, one service, one user journey, one platform question, or one painful decision that people are already debating.

A good first question might be: should we build or buy this capability? Which part of this legacy system should we modernize first? Should we create a platform team for this area? Why is delivery slow in this workflow? Which parts of this service are differentiating and which are merely necessary?

Once the question is selected, identify the primary user. Be specific. “Customer” may be too broad. “Customer trying to return an item without contacting support” is better. “Developer deploying a service safely without waiting for another team” is better. “Finance analyst reconciling refunds at month end” is better.

After the user is clear, write the user need as an outcome. Avoid naming the solution too early. The user does not need “a dashboard” in the abstract. They may need to detect operational issues before customers complain. The user does not need “a portal” in the abstract. They may need to complete a return without uncertainty, delay, or avoidable support contact.

Next, build the value chain. Start with the visible capabilities that satisfy the need, then ask what each capability depends on. Continue downward until further decomposition stops being useful for the decision at hand. The goal is not to describe every technical detail. The goal is to reveal the components that influence the strategic choice.

Then place each component on the evolution axis. Ask whether it is novel, custom, product-like, or commodity-like. Be careful not to confuse how you currently treat the component with how evolved it is in the market. A company may handcraft something that is already available as a mature product. That does not make the component strategically custom. It may indicate waste, inertia, or historical accident.

Finally, discuss mismatches. Look for commodity components receiving custom investment, uncertain components being given fixed commitments, product-like components being over-customized, and strategically important knowledge being moved outside the organization too early.

At the end of this process, the team should be able to state what the map changes about the decision. If the map changes nothing, either the decision was already obvious or the map is too shallow.

7. Complete worked example: self-service returns portal

Let us walk through a complete example. The situation is an e-commerce company that wants to reduce support volume and improve customer experience around product returns. Several people in the company are arguing about whether to build a custom self-service returns portal or buy a returns management product.

Step 1: define the strategic question

Question: should we build, buy, or delay a self-service returns portal for customers?

Answer: we should not decide at the level of “returns portal” because that phrase hides many components with different maturity, cost, risk, and user value. Some parts may be standard product capabilities. Some may be commodity infrastructure. Some may be business-specific and worth custom investment. We need to map the capability before choosing a build or buy answer.

This reframes the conversation. The team is no longer asking whether the whole thing should be built or bought. It is asking which parts of the capability deserve custom work, which should be consumed from the market, which should reuse existing internal capabilities, and which should be delayed.

Step 2: identify the user

Question: who is the primary user?

Answer: the primary user is the customer who wants to return a product without contacting support. Secondary users include support agents, warehouse teams, finance, operations, and fraud teams, but the first map should be anchored on the customer.

This matters because different users produce different maps. A customer-anchored map focuses on clarity, eligibility, instructions, tracking, and refund confidence. A warehouse-anchored map would focus more on intake processing, inspection, restocking, exception handling, and inventory accuracy. Both may be useful, but they are not the same map.

Step 3: identify the user need

Question: what does the customer need?

Answer: the customer needs to know whether the item can be returned, start the return easily, receive clear instructions, track the return status, and understand when the refund or exchange will happen. The customer does not primarily need “a portal”. The portal is one possible solution to the need.

This distinction prevents solution bias. If the team starts with “build a portal”, it may miss simpler improvements such as clearer order pages, better notifications, improved return policy wording, or tighter support automation. Starting with the need keeps the map honest.

Step 4: identify visible capabilities

Question: what capabilities directly satisfy the customer need?

Answer: the visible capabilities are return eligibility result, return request flow, return instructions, return label generation, return tracking, refund or exchange status, and customer notifications.

These are visible because the customer interacts with them directly or experiences their output. If they fail, the customer notices immediately. A confusing eligibility message, missing label, unclear instruction, or delayed refund status will generate support contact and reduce trust.

Step 5: identify hidden dependencies

Question: what does each visible capability depend on?

Answer: return eligibility depends on order history, product category, delivery date, return policy rules, item condition rules, customer history, and fraud checks. Label generation depends on carrier integration, address validation, country rules, shipping service selection, and packaging constraints. Refund or exchange status depends on payment provider integration, warehouse confirmation, finance rules, inventory status, and customer notifications.

This is where the idea starts becoming a map. The returns portal is not one thing. It is a visible customer experience sitting on top of policy, data, logistics, payments, warehouse operations, identity, communication, monitoring, and exception handling.

Step 6: place components on the evolution axis

The team now estimates where each component sits on the evolution axis. These placements are not universal truths. They are working assumptions for this company and this decision.

The table is useful, but it is not yet the map. The map needs a visual arrangement where visibility and evolution can be seen together. A textual approximation can help in the article, but a final published version should include a proper image or SVG.

Visibility

High
  Customer
|
| needs
v
  Return eligibility result   [Custom built]
  Return request flow [Product -> Custom built]
  Return instructions [Custom built]
  Return label generation [Product]
  Return tracking [Product]
  Refund or exchange status   [Product -> Custom built]

Medium
  Return policy rules [Custom built]
  Fraud and abuse checks  [Custom built]
  Customer notifications  [Product]
  Carrier integration [Product]
  Payment refund integration  [Product -> Commodity]
  Inventory and warehouse update  [Custom built]

Low
  Order history   [Product -> Custom built]
  Address validation  [Product -> Commodity]
  Authentication  [Commodity]
  Monitoring and audit log[Product -> Commodity]
  Hosting [Commodity -> Utility]

Evolution
Genesis | Custom built | Product | Commodity / Utility

This approximation shows the reasoning, but a true Wardley map would place each component spatially on two axes. The vertical position would show visibility to the customer, and the horizontal position would show evolution. Lines would show dependencies. Annotations could mark inertia, risk, movement, or disagreement.

Step 7: interpret the map

Question: what does the map reveal?

Answer: the strategic investment is not generic hosting, authentication, address validation, basic carrier integration, or email infrastructure. Those components are mature enough that the company should usually reuse internal standards, buy products, or consume existing services. The more strategic areas are return policy rules, eligibility logic, fraud checks, warehouse integration, refund orchestration, and the customer-facing experience around uncertainty.

This immediately changes the build versus buy conversation. A full custom build would waste effort on mature components. A full product purchase might fail if the product cannot represent the company’s policy, warehouse process, fraud rules, and customer promise. The better answer is likely a mixed strategy.

Question: where is the main risk?

Answer: the main risk is not whether the company can display a form. The main risk is whether the eligibility decision is correct, whether refund timing matches the customer promise, whether warehouse operations can support the process, whether fraud controls are proportionate, and whether customers understand what is happening without contacting support.

This is a practical insight. If the team had started with user interface screens, it might have underestimated the operational and policy work underneath the visible portal. The map shows that a beautiful flow can still fail if the eligibility logic, warehouse events, refund rules, and notifications are unreliable.

Question: what should not be built from scratch?

Answer: the team should not build custom authentication, custom address validation, custom carrier integration, custom email infrastructure, or custom hosting unless there are strong constraints. Those components are not the differentiating parts of the landscape. Building them would increase cost and delay without improving the customer’s return experience in a meaningful way.

Question: what should the company learn before scaling?

Answer: the company should learn which return reasons are most common, which product categories create exceptions, where customers currently contact support, how often fraud checks are needed, how quickly the warehouse can process returns, and whether customers understand the return status messages. The first release should test these assumptions before the company commits to a broader platform.

Step 8: derive a concrete strategy

The map suggests that the team should not start by building a complete custom returns platform. It also suggests that buying a product and forcing every business rule into it may create problems if the company’s return policy and warehouse operations are specific.

A better strategy is to reuse or buy mature components while custom-building the policy and orchestration parts that reflect the company’s actual business. The team should use existing authentication, hosting, monitoring, address validation, notification infrastructure, and carrier services where possible. It should invest custom effort in eligibility rules, fraud checks, warehouse integration, refund orchestration, exception handling, and the customer-facing flow.

The first release should be deliberately narrow. For example, it could support one country, refund-only returns, a limited set of product categories, and customers with standard completed orders. It should exclude international returns, exchanges, damaged items, marketplace sellers, high-value fraud-risk items, and complex exceptions until the team has learned enough from the first slice.

The strategic decision is no longer “build or buy the returns portal”. The decision becomes more precise: buy or reuse mature components, build the business-specific logic, release a narrow slice, learn from real usage, and expand only after the risky assumptions have been tested.

That is the value of the map. It turns an abstract strategic argument into a concrete set of choices.

8. How to read map patterns

Once a map exists, the team needs to interpret it. The goal is not to admire the drawing. The goal is to find patterns that change the decision.

These patterns help move the article from beginner explanation to practical judgment. A reader should not only know what the axes mean. They should begin to understand what certain positions imply.

For example, custom work in commodity space does not automatically mean the team is wrong. There may be regulatory or operational constraints. But the map changes the burden of proof. If the market provides mature address validation, the team needs a strong reason to build and operate its own.

The same applies in the opposite direction. If a component is still uncertain, forcing it through a fixed delivery plan may create false confidence. In that case, the responsible move may be to reduce scope, run an experiment, and learn before scaling.

9. Real uses at work

Wardley Mapping is useful because many organizational decisions are really questions about user needs, dependencies, maturity, and movement. The map gives different functions a shared surface for discussing those questions.

Product strategy

Product teams can use Wardley Mapping to separate user needs from feature requests. A stakeholder may ask for a dashboard, export, workflow, or portal, but the map asks what the user actually needs and what capabilities are required to satisfy that need.

In the returns example, “build a portal” was too broad. The map revealed several separate capabilities: eligibility, instructions, tracking, refund status, notifications, policy, fraud checks, and warehouse integration. That decomposition helps the product team prioritize the first useful slice.

Platform strategy

Platform teams can use Wardley Mapping to avoid building platforms from internal enthusiasm alone. A platform should serve repeated user needs, usually for internal users such as developers, product teams, analysts, or operations teams.

The map helps identify which components are mature enough to standardize and which are still too unstable. Standardizing authentication, deployment templates, observability, or service ownership may improve flow. Standardizing a business workflow that is still changing may freeze learning too early.

Build versus buy

Wardley Mapping improves build versus buy decisions because it shows that most capabilities are not one thing. A returns portal includes commodity components, product components, custom business rules, operational integrations, and user-facing experience.

The decision is rarely “build everything” or “buy everything”. A better decision may be to buy mature components, build the business-specific differentiators, and delay uncertain parts until the team has learned enough.

Legacy modernization

Modernization is often framed too broadly. A system is old, painful, or unpopular, so the organization decides to replace it. This can become expensive if the team does not know which parts of the system are actually blocking valuable change.

A Wardley map helps identify which components are still strategically important, which are commodity but trapped, which are risky, and which can be left alone for now. It also helps distinguish technical discomfort from economic urgency.

Cloud migration

Cloud migration should not be treated as a strategy by itself. It is usually a change in how underlying components are provided and operated. The map helps ask which components should move, why they should move, and what practices must change around them.

Moving infrastructure without changing ownership, deployment, observability, cost management, resilience, and operating model may produce a more expensive version of the old system. Mapping helps make those dependencies visible before the migration becomes a large commitment.

Team boundaries

Team boundaries should support the flow of change. A map helps discuss whether teams should align around user needs, product areas, platforms, capabilities, or shared services.

A component in genesis may need a small exploratory team. A custom business capability may need close collaboration between product, engineering, operations, and domain experts. A commodity capability may belong in a platform, shared service, or external provider. The map helps avoid applying one team model to every kind of work.

10. Common mistakes

The first common mistake is starting with technology instead of the user. If the conversation begins with Kubernetes, microservices, Artificial Intelligence, cloud, data mesh, or platform engineering, the team is already at risk of anchoring on a solution. Technology belongs on the map as a component, not as the starting point.

The second mistake is mapping the organization chart instead of the value chain. The fact that a team owns something does not explain whether it is visible to the user, strategically important, commodity-like, duplicated, risky, or evolving. Sometimes the map reveals that the current organization structure is part of the problem.

The third mistake is treating the map as objective truth. A Wardley map is a model. Its value comes from making assumptions visible, not from pretending the drawing is reality. The right phrase is not “the map says”. The better phrase is “our current understanding is”.

The fourth mistake is trying to make the perfect map. A useful map is good enough to improve the conversation. The first map should create challenge, reveal assumptions, and guide the next question. It does not need to describe every system, dependency, or exception.

The fifth mistake is confusing low visibility with low importance. Hosting, authentication, backups, observability, payment integrity, and audit logs may sit low on the map, but failure in these components can damage the entire user experience. Low visibility means the user does not usually value custom craftsmanship there. It does not mean the component can be neglected.

The sixth mistake is assuming commodity means outsource. A commodity component may still remain internal for regulatory, security, latency, resilience, cost, or control reasons. The point is not automatic outsourcing. The point is appropriate treatment: standardization, automation, operational discipline, and clear ownership.

The seventh mistake is assuming custom means strategic. Custom may mean valuable differentiation. It may also mean historical accident, unnecessary variation, local preference, or unresolved complexity. The map asks for evidence rather than accepting custom work as important by default.

The eighth mistake is drawing once and never updating the map. User needs change, components evolve, vendors mature, regulation appears, and inertia grows. A map should be revisited when the landscape changes or when the decision becomes important again.

11. How to run a 90-minute mapping session

A first mapping session does not need to be complicated. The goal is to create a useful first map around a real decision, not to teach the entire theory of Wardley Mapping.

Invite a small cross-functional group. For a product or software decision, that might include product, engineering, operations, support, security, architecture, and someone close to the customer or user. The group should be small enough to have a real conversation and diverse enough to challenge assumptions.

Start with a decision statement. For example: “Should we build or buy a self-service returns capability?” Write the statement where everyone can see it. Then ask the group to identify the primary user and the user need. Spend enough time here, because a weak user need will distort the rest of the map.

Next, identify visible capabilities. Ask what the user experiences directly. In the returns example, this included eligibility, request creation, instructions, tracking, refund status, and notifications. Then move downward into dependencies. Ask what each capability needs in order to work.

Once the value chain is visible, place each component on the evolution axis. Do not let the group hide disagreement. If one person thinks return policy rules are custom and another thinks they are product-like, mark the disagreement. Disagreement is useful because it shows where assumptions differ.

After placement, look for mismatches. Ask where the organization is handcrafting mature components, where it is forcing certainty onto uncertain work, where it is over-customizing products, and where hidden dependencies create visible risk.

End the session with decisions and open questions. The output should not be only a map. It should include what the map changed, what the team now believes, what remains uncertain, what should be tested, and what move should happen next.

A simple 90-minute agenda could look like this:

The facilitator’s job is not to defend the map. The facilitator’s job is to keep the conversation anchored on user needs, dependency, evolution, and decision quality.

12. Conclusions

Wardley Mapping is useful because it changes the quality of strategic conversation. It helps teams move from broad intention to situated judgment. Instead of asking only what the organization wants, the team asks who the user is, what the user needs, what components are required, how evolved those components are, and what move fits the landscape.

The most important lesson is not that every team needs a beautiful map. The important lesson is that strategy needs position. Without position, teams copy practices, overbuild commodity capabilities, standardize unstable work, outsource learning, and call internal preferences strategic.

In software and product work, this has a direct economic consequence. Poor strategic visibility can waste money, time, attention, and delivery capacity. It can also increase risk by hiding critical dependencies under user-facing plans. A Wardley map helps expose those commitments before they become expensive.

The practical next step is small. Pick one decision your team is already debating. Choose one user and one need. Draw the value chain. Place each component on the evolution axis. Discuss where the map changes the decision. If nothing changes, the map may be too shallow or the decision may already be obvious. If something changes, you have found the value of the practice.

References

• Wardley, Simon. Wardley Maps. https://learnwardleymapping.com/book/

• Wardley, Simon. On being lost. https://medium.com/wardleymaps/on-being-lost-2ef5f05eb1ec

• Wardley, Simon. Finding a path. https://medium.com/wardleymaps/finding-a-path-cdb1249078c0

• Wardley, Simon. Exploring the map. https://medium.com/wardleymaps/exploring-the-map-ad0266fad59b

• Wardley, Simon. Doctrine. https://medium.com/wardleymaps/doctrine-8bb0015688e5

• Wardley, Simon. The play and a decision to act. https://medium.com/wardleymaps/the-play-and-a-decision-to-act-8eb796b1dff1

• Wardley, Simon. Getting started yourself. https://medium.com/wardleymaps/getting-started-yourself-e1a359b785a2

• Wardley, Simon. Finding a new purpose. https://medium.com/wardleymaps/finding-a-new-purpose-8c60c9484d3b

• Wardley, Simon. Keeping the wolves at bay. https://medium.com/wardleymaps/keeping-the-wolves-at-bay-93de21b6b2f8

• Wardley, Simon. Charting the future. https://medium.com/wardleymaps/anticipation-89692e9b0ced

• Wardley, Simon. I wasn’t expecting that. https://medium.com/wardleymaps/i-wasnt-expecting-that-dcfe122a2234

• Wardley, Simon. The scenario. https://medium.com/wardleymaps/the-scenario-8bc05feee81

• Wardley, Simon. Something wicked this way comes. https://medium.com/wardleymaps/something-wicked-this-way-comes-b028d5c607bf

• Wardley, Simon. On the practice of scenario planning. https://medium.com/wardleymaps/on-the-practice-of-scenario-planning-49eed8279e90

• Wardley, Simon. Super Looper. https://medium.com/wardleymaps/round-round-get-around-i-loop-around-d88e865d4337

• Wardley, Simon. To infinity and beyond. https://medium.com/wardleymaps/to-infinity-and-beyond-c7a53ccd2a07

• Wardley, Simon. Better for Less. https://medium.com/wardleymaps/better-for-less-58fe8c0a3aaa

• Wardley, Simon. On playing chess. https://medium.com/wardleymaps/on-playing-chess-2634b825dbac

• Sun Tzu. The Art of War.

The code has classes. The classes have methods. The methods call other methods. There may even be interfaces, diagrams, and patterns. At first glance, everything appears to be in the right place.

But when you try to understand the behaviour, the design starts to resist.

One object asks too many questions. Another object holds data but makes no decisions. A service coordinates everything. A domain object is reduced to a container. A collaborator exists, but nobody can explain what role it plays. A method works, but it reads like a script that happens to be written inside a class.

This is one of the traps of Object-Oriented Programming (OOP): it is possible to use classes without really thinking in objects.

Responsibility-Driven Design (RDD) starts from a different place.

It does not begin by asking, “what classes do we need?”

It begins by asking, “what behaviour needs to happen, and who should be responsible for it?”

That question changes the design conversation.

Not because it gives us a mechanical recipe. It does not. But because it moves our attention from structure to responsibility, from data to behaviour, and from isolated classes to collaborating objects.

This article is about that shift.

TL;DR

Responsibility-Driven Design (RDD) is a way of designing Object-Oriented Programming (OOP) systems by starting from responsibilities, roles, and collaborations.

Its core idea is simple:

Objects should not be treated as mere data containers. They should be responsible participants in a collaborating system.

A responsibility is something an object is expected to know, do, decide, coordinate, translate, protect, or delegate. A role is the position an object plays in a scenario. A collaboration happens when one object asks another object for help by sending a message. A contract describes what that message means: what the receiver expects, what it promises, and what the caller should not need to know.

The point of Responsibility-Driven Design (RDD) is not to create more classes. It is to distribute behaviour well.

A good object-oriented design is not a pile of named things. It is a community of objects that know what they are responsible for and know when to ask one another for help.

Index

1. Why classes are not enough

2. Object thinking before object design

3. What Responsibility-Driven Design (RDD) is really about

4. Responsibilities before structure

5. Doing and knowing responsibilities

6. Roles and role stereotypes

7. Finding candidate objects

8. Assigning responsibilities

9. Collaborations, messages, and contracts

10. Class, Responsibility, Collaborator (CRC) cards

11. Control style: centralized, dispersed, delegated

12. A practical example in Kotlin

13. Trust boundaries and reliable collaborations

14. Flexibility and variation points

15. Patterns as responsibility arrangements

16. Conclusion

17. References

1. Why classes are not enough

A common mistake in Object-Oriented Programming (OOP) is to think that object-oriented design is mainly about finding classes.

It is understandable. Requirements often contain nouns, and nouns often look like objects. A library has members, books, loans, reservations, librarians, fines, and notifications. It is tempting to turn those words into classes and feel that the design has begun.

Sometimes that is useful. Some of those concepts may deserve representation in code.

But a list of nouns is not a design.

The problem is not noticing candidate objects. The problem is treating those candidates as if they already explain the behaviour of the system.

A class called Loan does not tell us who is responsible for creating a loan. A class called Member does not tell us who decides whether that member may borrow another book. A class called Notification does not tell us who should be told, when, or why. The class name gives us a possible concept, but not yet a distribution of responsibilities.

That is where many object-oriented designs become weak. They have objects, but the objects do not carry enough behaviour. They hold data, expose state, and wait for a central service to do the real work.

The design is object-shaped, but the thinking is still procedural.

Responsibility-Driven Design (RDD) pushes against that. It asks us to begin with behaviour.

Not “what entities exist?”
But “what work must be done?”

Not “what data does this object have?”
But “what is this object responsible for?”

Not “which class should hold this field?”
But “who should know this, decide this, or do this?”

That is the first important shift:

A class becomes useful when it gives a responsibility a good home.

flowchart LR
    Requirement[Requirement] --> CandidateNouns[Candidate nouns]
    CandidateNouns --> Classes[Classes]
    Classes --> Data[Fields and data]
    Data --> CentralService[Central service makes decisions]

    Requirement --> Behaviour[Behaviour that must happen]
    Behaviour --> Responsibilities[Responsibilities]
    Responsibilities --> Roles[Roles]
    Roles --> Collaborations[Collaborations]
    Collaborations --> ResponsibleObjects[Responsible objects]

The second path does not reject classes. It simply refuses to let classes lead the design before responsibilities are understood.

2. Object thinking before object design

Before Responsibility-Driven Design (RDD) becomes a technique, it rests on a way of seeing software.

Object thinking asks us to stop seeing software as procedures operating over data. Instead, we see a system as a community of objects that know things, do things, make decisions, and collaborate.

The important shift is not syntax. A programming language can support classes and still allow procedural design. The deeper shift is cognitive.

A procedural instinct asks:

What sequence of steps should I write?

An object thinking instinct asks:

Which responsible participants should collaborate to make this behaviour happen?

That difference matters because it changes what we notice.

If we think procedurally, we tend to look for the flow first. We ask where the process starts, which data is needed, which functions transform it, and where the result goes. This can be useful for understanding an algorithm, but it often creates designs where objects become passive containers passed through a central process.

If we think in objects, we look for participants. We ask what each participant is responsible for, what it can do for others, what it should hide, and when it needs help.

The system is no longer just a sequence of steps.

It becomes a network of responsibilities.

This does not mean every algorithm disappears. It means the design is no longer organized around one controlling procedure that interrogates everything else.

A good object-oriented design gives behaviour to objects that can own it.

flowchart TD
    ObjectThinking[Object thinking] --> Behaviour[Behaviour first]
    ObjectThinking --> Responsibilities[Responsibilities]
    ObjectThinking --> Collaboration[Collaboration]
    ObjectThinking --> Encapsulation[Encapsulation]
    ObjectThinking --> DistributedControl[Distributed control]

    Behaviour --> WhatHappens[What must happen?]
    Responsibilities --> WhoOwnsIt[Who should own it?]
    Collaboration --> WhoHelps[Who needs to help?]
    Encapsulation --> WhatIsHidden[What should stay hidden?]
    DistributedControl --> WhereControlLives[Where should control live?]

Responsibility-Driven Design (RDD) gives this way of thinking a practical vocabulary.

3. What Responsibility-Driven Design (RDD) is really about

Responsibility-Driven Design (RDD) is a way of designing object-oriented systems by focusing on responsibilities, roles, and collaborations.

A responsibility is an obligation.

An object may be responsible for knowing something. It may be responsible for doing something. It may be responsible for deciding something. It may be responsible for coordinating a process. It may be responsible for translating between the system and an external boundary. It may be responsible for protecting an invariant. It may be responsible for delegating part of its work to another object.

The important part is that responsibility is behavioural language.

It tells us what an object contributes to the system.

That is why Responsibility-Driven Design (RDD) is not just a technique for finding classes. It is a way to reason about how behaviour should be distributed.

The practical questions are:

• What responsibilities exist?

• Which roles are needed?

• Which object should carry each responsibility?

• Which objects must collaborate?

• What contract does each collaboration imply?

• Where should control live?

• Which details should be hidden?

• Which boundaries are trustworthy?

• Where is flexibility actually valuable?

These questions are not theoretical decoration. They are the questions we need when code starts to feel wrong.

flowchart LR
    Scenario[Scenario] --> Responsibilities[Responsibilities]
    Responsibilities --> Roles[Roles]
    Roles --> Candidates[Candidate objects]
    Candidates --> Collaborations[Collaborations]
    Collaborations --> Contracts[Contracts]
    Contracts --> Protocols[Protocols]
    Collaborations --> ControlStyle[Control style]
    Collaborations --> Trust[Trust boundaries]

The diagram is not a process that must be followed mechanically. It is a map of design concerns. In real work, we move back and forth between them.

4. Responsibilities before structure

The phrase “responsibilities before structure” is easy to say, but it changes the design conversation.

Imagine we are designing a library lending system.

A structure-first approach might begin with:

• Member

• Book

• BookCopy

• Loan

• Reservation

• Fine

• Notification

That list may contain useful candidates. But it does not yet tell us how the system behaves.

A responsibility-first approach asks different questions:

• Who decides whether a member may borrow a book copy?

• Who records that a book copy is now on loan?

• Who knows when the loan is due?

• Who decides whether the loan is overdue?

• Who notifies the member?

• Who coordinates the lending process?

• Who talks to persistence?

• Who talks to the notification channel?

Now we are no longer just naming concepts. We are distributing work.

That distribution is the heart of design.

A responsibility map might begin like this:

This table is not the final design. It is a way to make the work visible.

That is one of the first things Responsibility-Driven Design (RDD) gives us: it makes responsibility visible before structure becomes fixed.

5. Doing and knowing responsibilities

Responsibilities are not all the same kind.

A useful distinction in Responsibility-Driven Design (RDD) is the difference between doing responsibilities and knowing responsibilities.

A doing responsibility is about behaviour. It is the responsibility to calculate, validate, reserve, lend, notify, coordinate, translate, decide, or delegate.

A knowing responsibility is about information. It is the responsibility to know the member identifier, know the book copy identifier, know the due date, know whether a loan is active, or know which rules apply to a member.

This distinction is useful, but it should not be made too simplistic. Objects often do both.

For example, an ActiveLoan may know its due date, but it may also answer whether it is overdue on a given date. A LoanPeriod may know a start date and due date, but it may also calculate whether a date is within the period.

The point is not to force objects into boxes.

The point is to notice what kind of responsibility we are assigning.

This matters because different responsibilities lead to different design pressures. A coordinator should not absorb every rule. A value should not be forced to know external systems. A boundary object should not leak external vocabulary into the domain.

Responsibility type helps us ask better questions.

6. Roles and role stereotypes

A common weak definition of an object is this: an object is data plus methods.

That definition is not completely wrong, but it is not strong enough for design.

It keeps our attention on the wrong thing. It makes us think of objects as containers that happen to have functions attached. That is how we end up with data holders, getters, setters, and one large service making decisions from the outside.

A better design definition is this:

An object is a responsible participant that plays a role in a collaboration.

A role is not the same thing as a class. A class is a code structure. A role is a behavioural position in a scenario.

Role stereotypes help us describe that position. They are not rigid categories. They are thinking tools.

A controller is not automatically a design mistake. It becomes dangerous when close direction turns into centralized intelligence and the rest of the model becomes passive.

An information holder is not automatically weak either. Some objects legitimately hold information. The problem appears when information holding becomes the whole model and behaviour migrates elsewhere.

The value of the stereotypes is that they help us see emphasis.

They let us ask:

Is this object’s role clear?

That is more useful than asking whether the object has enough methods.

7. Finding candidate objects

If we do not simply underline nouns, how do we find candidate objects?

The answer is not to ignore domain language. Domain language matters. The problem is treating every noun as if it automatically deserves a class.

Candidate objects can come from many signals:

flowchart TD
    Scenario[Usage scenario] --> Responsibilities
    DomainLanguage[Domain language] --> CandidateConcepts[Candidate concepts]
    BusinessRules[Business rules] --> PolicyObjects[Policy objects]
    ExternalSystems[External systems] --> BoundaryObjects[Boundary objects]
    Relationships[Complex relationships] --> Structurers
    Events[Domain events] --> EventObjects

    Responsibilities --> Candidates[Candidate objects]
    CandidateConcepts --> Candidates
    PolicyObjects --> Candidates
    BoundaryObjects --> Candidates
    Structurers --> Candidates
    EventObjects --> Candidates

    Candidates --> Keep[Keep]
    Candidates --> Rename[Clarify]
    Candidates --> Merge[Merge]
    Candidates --> Reject[Reject]

Finding candidates is only half the work.

The other half is rejecting weak ones.

A candidate object should be questioned if it only exists because a noun appeared in a requirement, if it only holds data and exposes getters, if its responsibility is vague, if it duplicates another object’s responsibility, or if it creates a boundary before the design needs one.

That does not mean small objects are bad. It means an object must earn its place by carrying meaning, behaviour, or collaboration value.

A useful question is:

Would removing this object make the design less clear, or only shorter?

If the design becomes clearer without it, the object may not be real yet.

8. Assigning responsibilities

Assigning responsibilities is the difficult part of object design.

It is easy to say that objects should have responsibilities. It is harder to decide where a responsibility belongs.

Responsibility-Driven Design (RDD) does not remove judgment, but it gives judgment better questions.

One useful heuristic is “keep behaviour near the knowledge it needs”. But it must not be applied mechanically.

For example, we may try to put borrowing eligibility directly on Member:

val borrowingDecision = member.canBorrow(
    activeLoans = activeLoans,
    requestedBookCopy = requestedBookCopy,
    today = today
)

That may be reasonable if the decision is mostly about member state. But if eligibility depends on loan limits, membership type, book category, library branch policy, and temporary suspension rules, then Member may become overloaded.

A clearer responsibility home may be BorrowingPolicy:

val borrowingDecision = borrowingPolicy.assess(
    member = member,
    activeLoans = activeLoans,
    requestedBookCopy = requestedBookCopy,
    today = today
)

This is not about extracting for the sake of extracting. It is about asking where the decision belongs.

The better heuristic is:

Keep behaviour near the knowledge it needs, unless doing so gives the object responsibilities that do not belong to its role.

That sentence is one of the most useful parts of Responsibility-Driven Design (RDD). It protects us from both extremes: passive data objects on one side and bloated domain objects on the other.

9. Collaborations, messages, and contracts

Responsibilities do not live in isolation.

An object fulfils a responsibility by doing its own work or by collaborating with others.

In Object-Oriented Programming (OOP), collaboration happens through messages. In most mainstream languages, that usually means method calls. But the design idea is larger than the syntax.

A message says:

I need you to do something you are responsible for.

A contract says:

This is what you can expect when you ask me to do it.

A protocol is the set of messages an object offers to its collaborators.

For example:

interface BorrowingPolicy {
    fun assess(
        member: LibraryMember,
        activeLoans: MemberLoans,
        requestedBookCopy: BookCopy,
        today: LocalDate
    ): BorrowingDecision
}

For this example, we might read the contract like this:

The name BorrowingDecision matters because it says what the object represents. It is not a generic response. It is the result of assessing whether borrowing is allowed.

A contract should avoid leaking implementation details into the client. LendBookService should not need to know the internal order of policy checks. It should ask for a decision and act on it.

That is encapsulation as design language.

Not just private fields.

A responsibility becomes concrete through a protocol. But the protocol should not be invented too early. First the role must be real. Then the contract must be meaningful. Then the interface can earn its place.

sequenceDiagram
    participant LendBookService
    participant BorrowingPolicy
    participant LoanRepository
    participant LoanNotificationSender

    LendBookService->>BorrowingPolicy: assess(member, activeLoans, bookCopy, today)
    BorrowingPolicy-->>LendBookService: BorrowingDecision
    LendBookService->>LoanRepository: save(activeLoan)
    LendBookService->>LoanNotificationSender: sendBookLentNotification(activeLoan)

A sequence like this helps because it shows behaviour over time. It reveals who asks, who answers, and who is responsible for each part of the scenario.

10. Class, Responsibility, Collaborator (CRC) cards

Class, Responsibility, Collaborator (CRC) cards are useful because they force a simple but important conversation:

• What is this candidate responsible for?

• What does it know?

• What does it do?

• Who does it collaborate with?

They are not useful because the card is magical. They are useful because they make the design conversation visible.

A weak card might look like this:

A better responsibility-driven version might look like this:

This is still not a production ritual. It is a thinking tool.

The point is not to fill a card perfectly. The point is to ask whether an object has a real responsibility or whether we only gave a name to a thing.

https://emmanuelvalverderamos.substack.com/p/crc-cards-class-responsibility-collaborator

11. Control style: centralized, dispersed, delegated

Responsibility distribution affects the control style of the system.

There are three useful styles to think about:

1. Centralized control

2. Dispersed control

3. Delegated control

A system can centralize control too much. In that style, one object knows the process, makes the decisions, tells everyone else what to do, and treats other objects mostly as data sources or technical endpoints. This may be easy to follow at first, but it often creates an object with centralized control, the kind of object many teams would casually call a God object.

A system can also disperse control too much. In that style, behaviour is spread everywhere, but without a clear sense of ownership. It becomes hard to know who is responsible for what. You avoid one dominant object, but you get a fog of tiny interactions where nobody can explain the flow.

The more useful middle is delegated control. A coordinator may still exist, but it does not do all the work. It delegates meaningful responsibilities to objects that are better homes for those responsibilities.

flowchart TD
    subgraph CentralizedControl[Centralized control]
        LendingServiceA[LendBookService] --> MemberA[LibraryMember]
        LendingServiceA --> LoansA[MemberLoans]
        LendingServiceA --> BookCopyA[BookCopy]
        LendingServiceA --> RepositoryA[LoanRepository]
        LendingServiceA --> SenderA[LoanNotificationSender]
        LendingServiceA --> CalendarA[Calendar]
    end

    subgraph DelegatedControl[Delegated control]
        LendingServiceB[LendBookService] --> BorrowingPolicyB[BorrowingPolicy]
        BorrowingPolicyB --> LoansB[MemberLoans]
        BorrowingPolicyB --> BookCopyB[BookCopy]
        BorrowingPolicyB --> MemberB[LibraryMember]
        LendingServiceB --> RepositoryB[LoanRepository]
        LendingServiceB --> SenderB[LoanNotificationSender]
        LendingServiceB --> CalendarB[Calendar]
    end

The difference is not that delegated control has more classes. The difference is that the work has a clearer shape.

LendBookService coordinates.
BorrowingPolicy decides.
ActiveLoan represents the loan.
LoanRepository persists.
LoanNotificationSender notifies.

That is the goal: not maximum distribution, but meaningful distribution.

12. A practical example in Kotlin

Let us bring the ideas together in code.

Suppose we begin with this:

class LendBookService(
    private val loanRepository: LoanRepository,
    private val loanNotificationSender: LoanNotificationSender,
    private val calendar: Calendar
) {
    fun lendBook(
        member: LibraryMember,
        activeLoans: MemberLoans,
        requestedBookCopy: BookCopy
    ): ActiveLoan {
        val today = calendar.today()

        require(member.canBorrowBooks()) {
            "Member cannot borrow books."
        }

        require(activeLoans.count() < member.maximumActiveLoans()) {
            "Member has reached the active loan limit."
        }

        require(requestedBookCopy.isAvailable()) {
            "Book copy is not available."
        }

        val loanPeriod = LoanPeriod.startingOn(today)
        val activeLoan = ActiveLoan.create(
            memberId = member.id,
            bookCopyId = requestedBookCopy.id,
            loanPeriod = loanPeriod
        )

        loanRepository.save(activeLoan)
        loanNotificationSender.sendBookLentNotification(activeLoan)

        return activeLoan
    }
}

This code is not absurd. It may even be a reasonable first version.

But it has pressure.

LendBookService coordinates the use case, checks member eligibility, checks loan limits, checks book availability, creates the loan period, saves the loan, and sends the notification. Some of that may belong there. Some of it may not.

A responsibility-driven question is:

Is lending responsible for deciding borrowing eligibility, or is lending responsible for asking whether borrowing is allowed?

That question lets us introduce a clearer responsibility:

assess whether a member may borrow a requested book copy

One possible home is BorrowingPolicy:

class BorrowingPolicy(
    private val maximumActiveLoans: MaximumActiveLoans
) {
    fun assess(
        member: LibraryMember,
        activeLoans: MemberLoans,
        requestedBookCopy: BookCopy,
        today: LocalDate
    ): BorrowingDecision {
        if (!member.canBorrowBooks()) {
            return BorrowingDecision.rejected(
                reason = BorrowingRejectionReason.MemberCannotBorrow
            )
        }

        if (activeLoans.hasReached(maximumActiveLoans.forMember(member))) {
            return BorrowingDecision.rejected(
                reason = BorrowingRejectionReason.ActiveLoanLimitReached
            )
        }

        if (!requestedBookCopy.isAvailableOn(today)) {
            return BorrowingDecision.rejected(
                reason = BorrowingRejectionReason.BookCopyNotAvailable
            )
        }

        return BorrowingDecision.accepted()
    }
}

Now LendBookService can coordinate at a higher level:

class LendBookService(
    private val borrowingPolicy: BorrowingPolicy,
    private val loanRepository: LoanRepository,
    private val loanNotificationSender: LoanNotificationSender,
    private val calendar: Calendar
) {
    fun lendBook(
        member: LibraryMember,
        activeLoans: MemberLoans,
        requestedBookCopy: BookCopy
    ): LendingOutcome {
        val today = calendar.today()

        val borrowingDecision = borrowingPolicy.assess(
            member = member,
            activeLoans = activeLoans,
            requestedBookCopy = requestedBookCopy,
            today = today
        )

        if (borrowingDecision.isRejected()) {
            return LendingOutcome.rejected(borrowingDecision.rejectionReason())
        }

        val activeLoan = ActiveLoan.create(
            memberId = member.id,
            bookCopyId = requestedBookCopy.id,
            loanPeriod = LoanPeriod.startingOn(today)
        )

        loanRepository.save(activeLoan)
        loanNotificationSender.sendBookLentNotification(activeLoan)

        return LendingOutcome.accepted(activeLoan)
    }
}

This is not a general rule that every condition must become a policy object. That would be another form of mechanical design.

The point is that a responsibility became visible. Once it became visible, we could ask where it belonged.

A responsibility-driven reading of the example might look like this:

flowchart TD
    LendBookService --> Calendar
    LendBookService --> BorrowingPolicy
    BorrowingPolicy --> LibraryMember
    BorrowingPolicy --> MemberLoans
    BorrowingPolicy --> BookCopy
    LendBookService --> ActiveLoan
    ActiveLoan --> LoanPeriod
    LendBookService --> LoanRepository
    LendBookService --> LoanNotificationSender

The design now says something clearer.

The service coordinates the lending scenario. The policy decides whether the loan is allowed. The repository persists. The sender notifies. The values and information holders carry domain meaning.

That is Responsibility-Driven Design (RDD) in practice.

Not “make more classes”.

Not “hide everything behind interfaces”.

Not “avoid coordination”.

The lesson is simpler:

Give behaviour a responsible home.

13. Trust boundaries and reliable collaborations

Not all collaborations are equal.

Some collaborations happen inside a trusted part of the model. Others cross boundaries where failure is normal.

This distinction matters because object-oriented design is not only about who talks to whom. It is also about how much trust is reasonable in that conversation.

In this simplified example, a collaboration between LendBookService and BorrowingPolicy can be designed with higher trust because both objects live inside the application model. If the domain values are valid, BorrowingPolicy can focus on the borrowing decision.

A collaboration between LendBookService and LoanRepository is different. Persistence can fail. A database may be unavailable. A write may conflict. A transaction may be interrupted.

A collaboration with notification is also different. An email provider can fail. A message can be delayed. A downstream consumer may be unavailable.

flowchart LR
    subgraph ApplicationModel[Application model]
        LendBookService
        BorrowingPolicy
        ActiveLoan
        LoanPeriod
    end

    subgraph ExternalBoundaries[External boundaries]
        Database[(Database)]
        NotificationChannel[Notification channel]
    end

    LendBookService --> BorrowingPolicy
    LendBookService --> LoanRepository --> Database
    LendBookService --> LoanNotificationSender --> NotificationChannel

A table makes the difference visible:

Reliability is responsibility allocation under uncertainty.

It is not enough to say that persistence can fail. We need to decide who notices the failure, who translates it, who decides what it means, and who takes recovery action.

The point is not to make every object defensive against everything. That creates duplication and noise.

The point is to decide where trust is reasonable and where failure deserves explicit responsibility.

14. Flexibility and variation points

Flexibility is valuable, but it is not free.

Many object-oriented designs become over-engineered because every collaborator receives an interface, every rule becomes a strategy, and every small calculation becomes an object with a name. The design looks flexible, but the flexibility is speculative. The cost is paid immediately. The benefit may not arrive.

Responsibility-Driven Design (RDD) gives us a better question:

Where is variation real enough to deserve a design boundary?

In the library example, some variation points are plausible.

Borrowing rules may vary by membership type. Loan periods may vary by book category. Notification channels may vary. Persistence mechanisms may vary. Holiday calendars may affect due dates.

Other things may not deserve flexibility yet.

A method that calculates whether one date is after another probably does not need an interface. A small value like BookCopyId is not a variation point. A simple LoanPeriod may not need a hierarchy.

flowchart TD
    VariationPoint[Potential variation point] --> ConcreteExamples{Do we have concrete variations?}
    ConcreteExamples -->|No| KeepSimple[Keep the design simple]
    ConcreteExamples -->|Yes| Impact{Does variation affect many clients?}
    Impact -->|No| Localize[Keep variation local]
    Impact -->|Yes| Boundary[Introduce explicit boundary]
    Boundary --> Contract[Define contract]

Patterns fit here, but not as decoration.

A pattern is useful when it expresses a better distribution of responsibilities.

The pattern is justified only when the responsibility movement is justified.

Good design is not maximum abstraction. Good design is abstraction where it pays rent.

15. Patterns as responsibility arrangements

Patterns deserve their own short reflection because they are often taught badly.

Many developers learn patterns as shapes. They recognize a class diagram, remember a name, and then look for a place to apply it. That is backwards.

From a Responsibility-Driven Design (RDD) perspective, a pattern is more useful when read as an arrangement of responsibilities.

Strategy is not “an interface with implementations”. It is a way to give a varying decision to interchangeable collaborators.

Observer is not “a list of subscribers”. It is a way to separate the fact that something happened from the objects that react to it.

Adapter is not “a wrapper”. It is a way to protect the model from a collaborator whose protocol does not fit the design we want.

State is not “classes for states”. It is a way to move state-dependent behaviour into the objects that represent those states.

That perspective is important because it prevents pattern worship. The pattern is not the goal. The responsibility movement is the goal.

In the library example, BorrowingPolicy might evolve into a strategy if borrowing rules vary by member type, branch, or material type. LoanNotificationSender might evolve toward an observer-like design if many parts of the system need to react to a BookLent event. LoanRepository may use an adapter internally to protect the application from a persistence framework.

But none of those choices should be automatic.

First understand the responsibility. Then understand the collaboration. Then choose the structure that expresses them well.

16. Conclusion

Responsibility-Driven Design (RDD) is not about collecting classes.

It is a way of thinking about object-oriented software as a community of responsible collaborators.

That changes the starting point. We do not begin with data and then attach behaviour. We begin with behaviour and ask where responsibility belongs. We do not reduce objects to containers. We treat them as participants. We do not centralize every decision in one smart service. We distribute intelligence across objects that know how to do their work.

We do not use Class, Responsibility, Collaborator (CRC) cards because cards are magic. We use them because they make responsibilities and collaborations visible. We do not delegate because indirection is good. We delegate because another object is a better home for the work.

We do not add flexibility everywhere. We add it where variation is real. We do not add interfaces because classes exist. We add boundaries when a role, a contract, or a trust boundary earns one. We do not use patterns to decorate code. We use patterns when they express a better distribution of responsibilities.

Good Object-Oriented Programming (OOP) is not about having more classes, more interfaces, or more pattern vocabulary. It is about making the system easier to understand because responsibilities are named, behaviour has a home, collaboration has a shape, and control lives where it belongs.

The best object designs do not feel like a pile of classes.

They feel like a community of objects that know what they are responsible for and know when to ask each other for help.

References

Books, papers, and talks

• Beck, Kent; Cunningham, Ward. A Laboratory for Teaching Object-Oriented Thinking.
  https://c2.com/doc/oopsla89/paper.html

• Cooper, Ian. Responsibility Driven Design Revisited.

• Freeman, Steve; Pryce, Nat. Growing Object-Oriented Software, Guided by Tests.

  https://www.growing-object-oriented-software.com/

• West, David. Object Thinking.
  https://www.microsoftpressstore.com/store/object-thinking-9780735619654

• Wirfs-Brock, Rebecca. Object Technology: Basic Concepts.
  https://www.informit.com/articles/article.aspx?p=3109983

• Wirfs-Brock, Rebecca. Responsibility-Driven Design.
  https://www.wirfs-brock.com/Design.html

• Wirfs-Brock, Rebecca; McKean, Alan. Object Design: Roles, Responsibilities, and Collaborations.
  https://www.informit.com/store/object-design-roles-responsibilities-and-collaborations-9780201379433

• Wirfs-Brock, Rebecca; Wilkerson, Brian; Wiener, Lauren. Designing Object-Oriented Software.
  https://archive.org/details/designingobjecto00wirf

This article is a continuation or extension of the article

Following these two points of clarification:

• Role testing is not contract testing: In the previous article, Javi López mentioned to me that he does not view role testing as contract testing.

• My friend Adrían Muñoz Gamez gave me feedback that in the previous article Tests should fail for only one reason, for the sake of simplicity, I wrote a test that called `save` and then `findById`, which is not a good or consistent test, since it should fail for only one reason, and that test had two reasons to fail.

Therefore, to clarify these questions and delve deeper into the topic, I have written this article.

Introduction

Interfaces often give us confidence earlier than they should.

At first, everything looks fine. The interface is clean. One implementation passes its tests. Another is convenient for local development. A third might be useful in tests or in a different runtime context. The compiler is satisfied, the test suite is green, and the boundary appears well designed.

None of those facts proves that every implementation means the same thing by save and findById.

Consider these two implementations:

class InMemoryCustomerRepository : CustomerRepository {
    private val customers = mutableMapOf<CustomerId, Customer>()

    override fun save(customer: Customer) {
        customers[customer.id] = customer
    }

    // ...
}

class PostgresCustomerRepository(
    private val rows: CustomerRows
) : CustomerRepository {

    override fun save(customer: Customer) {
        rows.insert(
            CustomerRow(
                id = customer.id.value,
                name = customer.name
            )
        )
    }

    // ...
}

CustomerRows is a small table gateway used to keep the example focused on repository behaviour rather than database driver calls. Its shape appears later.

Both implement the same method:

fun save(customer: Customer)

A basic test that saves one customer and finds it later can pass for both. But save the same customer id twice and their meanings separate.

The in-memory implementation replaces the previous value. Assuming id is a primary key, the PostgreSQL implementation shown above rejects the second insert. One interprets save as an upsert. The other interprets it as an insert.

The interface did not prevent the disagreement:

interface CustomerRepository {
    fun findById(id: CustomerId): CustomerLookup
    fun save(customer: Customer)
}

The same structural interface can therefore hide incompatible observable behaviour:

It defines which messages clients can send. It does not define enough of the behaviour clients can rely on.

That is the problem role tests help us examine.

A role test is a reusable suite of behavioural examples for a role. It does not primarily ask whether the in-memory repository behaves like PostgreSQL, or whether a new implementation reproduces every observable detail of an old one.

A role contract asks:

What must every implementation make true so that clients can safely depend on this role?

Each implementation is checked against the same behavioural specification.

The contract boundary is:

A role test does not compare implementations with one another. It checks each implementation against the client-visible behavioural contract of the role.

This makes role tests useful in several situations:

• Keeping an in-memory fake aligned with a production adapter

• Checking several production adapters that claim the same role

• Introducing a new Strategy implementation

• Replacing a library, database adapter, algorithm, or external dependency during a refactor

• Running an old and a new implementation side by side while clients migrate

There is also an important limit. Passing a finite test suite does not prove complete substitutability. It provides executable evidence for the behaviours represented by those examples. Untested concurrency, durability, performance, security, and failure properties do not become guaranteed merely because the suite is green.

Role tests are therefore both a testing technique and a design technique. They protect known behaviour, expose semantic disagreements, keep test doubles honest, and force vague abstractions to become more precise.

TL;DR

• An interface defines shape, while a role test defines expected behaviour. A signature can say save(customer), but it cannot fully say what must be true after saving

• Role tests do not primarily compare implementations. They run the same behavioural specification against each implementation

• In object-oriented literature, role tests are a form of contract or polymorphic testing. The name emphasizes that one behavioural contract is reused against every implementation of a role

• The role is the reference, not the fake, the database, or the legacy implementation. When implementations disagree, the team must clarify the contract

• Roles are often discovered from the client side. A client’s needs reveal the messages and responsibilities required from a collaborator

• Role tests are valuable during refactors. An old dependency and its replacement can both be adapted to the same role and checked with the same suite before clients migrate

• Role tests keep fakes aligned with real adapters. A lightweight in-memory implementation should satisfy the same client-visible promises, even though it does not reproduce infrastructure details

• Strategy implementations can also have role tests. The shared suite protects properties common to every valid strategy, or the complete behaviour when a new strategy is intended as a drop-in replacement

• Passing the suite is evidence, not a formal proof. The suite protects only the part of the contract it encodes

• Implementation-specific tests still matter. SQL, filesystem, HTTP, security, performance, and operational concerns need their own tests

Table of contents

• The problem with interfaces

• What a role test is

• Are role tests contract tests?

• What a role test is not

• Roles are discovered from the client side

• A small example in Kotlin

• The first testing smell: using one role method to arrange another

• A precise role-test fixture

• Testing two implementations with the same role test

• The missing save contract

• Keeping test doubles aligned with real adapters

• Using role tests to replace a dependency safely

• Replacing an OpenAPI-generated client without breaking local clients

• A Strategy example during a refactor

• Role tests, characterization tests, and differential tests

• What should go into a role test?

• What should not go into a role test?

• Role tests and object-oriented design

• Common mistakes

• When role tests are worth the cost

• Conclusion

• References

The problem with interfaces

Interfaces are useful because they let us name a role without committing every client to one concrete implementation.

They appear around persistence, clocks, payment gateways, event publishers, file systems, external APIs, pricing policies, routing algorithms, feature flags, and other boundaries where substitution matters.

But an interface is incomplete.

It defines what can be called, not everything those calls are expected to mean.

Take the repository again:

interface CustomerRepository {
    fun findById(id: CustomerId): CustomerLookup
    fun save(customer: Customer)
}

The type signature answers some questions:

• Which messages can a client send?

• Which arguments are required?

• Which result type is returned?

• Which implementations can be supplied where CustomerRepository is expected?

It leaves other questions unanswered:

• What should be true after a customer is saved?

• Which customer fields must be preserved?

• What happens when no customer has the requested id?

• Should customers with different ids remain independent?

• What happens when the same id is saved twice?

• Which failures can clients observe?

• Is saved data immediately visible to a later lookup?

• Does the role promise durable storage, or only retrieval during the life of the object?

• Is the implementation expected to be safe under concurrent access?

A repository contract does not need to answer every possible question. It must state the behaviours clients are allowed to rely on instead of relying on a familiar method name.

The word save feels meaningful because developers bring conventions to it. One reads it as insert. Another reads it as upsert. Another expects optimistic concurrency. Another assumes the call returns only after durable persistence.

The compiler cannot resolve those interpretations. It verifies structural compatibility, not the full meaning of the abstraction.

A behavioural contract can include:

• Preconditions: what must be true before a call

• Postconditions: what the implementation guarantees after a call

• Invariants: what remains true across operations

• Failure semantics: which failures clients may observe and how they are represented

• History properties: how sequences of calls affect later observations

Barbara Liskov and Jeannette Wing’s work on behavioural subtyping makes the underlying point precise: syntactic compatibility is not sufficient. An implementation must preserve the properties that clients are entitled to assume from the abstraction’s specification.

A repository contract might contain this property:

Given a valid customer,
when the client saves it,
then a later lookup by the same id returns that customer.

It might also contain:

Given no saved customer with an id,
when the client looks up that id,
then the repository reports that the customer is missing.

If clients rely on replacement semantics, it might additionally contain:

Given a previously saved customer,
when the client saves another customer with the same id,
then a later lookup returns the most recently saved customer.

These statements describe relationships between calls. The interface alone cannot express them.

The first shift is:

An interface is not the whole contract. It is the typed surface through which the contract is exercised.

The role test gives part of that contract an executable form.

What a role test is

A role test is a reusable suite of behavioural examples that states what every valid implementation of a role must make true for its clients.

In responsibility-driven design, a role is a coherent set of related responsibilities within a collaboration. An object can play one or more roles. A responsibility is an obligation to perform work, make a decision, or know information. A collaboration is an interaction between objects or roles.

CustomerRepository can be understood as a role with responsibilities such as:

• Remember a customer presented by a client

• Find a remembered customer by identity

• Represent absence using the agreed domain language

The role can be played by several objects:

• InMemoryCustomerRepository

• PostgresCustomerRepository

• FileCustomerRepository

• RemoteCustomerRepository

The role is not any one of those classes. It is the set of responsibilities they claim to fulfil for their clients.

A role test says:

Any implementation that claims to be a CustomerRepository should satisfy these examples.

Conceptually:

The role test normally contains:

1. Shared examples that describe the role

2. A factory or fixture hook supplied by each concrete implementation test

This makes the suite executable documentation. A future reader can inspect it to understand what the abstraction means in this codebase, not only which methods it exposes.

That matters because weak abstractions rarely announce themselves with invalid method signatures. They appear when:

• Different implementations interpret the same method differently

• A fake becomes more permissive than production

• A replacement dependency preserves API shape but changes behaviour

• Clients begin to rely on behaviour that was never made explicit

• A shared interface is hiding several incompatible roles

A role test gives those behaviours a home.

Are role tests contract tests?

In the broad object-oriented sense, a role test is a form of contract test.

The older contract idea comes from Bertrand Meyer’s Design by Contract (DbC). In that model, a call is an agreement between a client and a supplier. The client must satisfy the preconditions for using the operation. The supplier must guarantee the promised postconditions and preserve the relevant invariants.

Role tests do not require a DbC language or runtime assertion mechanism. They borrow the same discipline: make the client-supplier promise explicit enough that it can be checked.

For a repository role, the agreement might say:

• Precondition: the customer has a valid identity.

• Postcondition: a later lookup by that identity returns the saved customer.

• Invariant: different customer identities remain independent.

The role test turns those promises into examples that every implementation must satisfy.

Manuel Rivero calls them “role or contract tests.” His definition starts from the contract clients establish with a role and then tests every adapter to check that it respects that contract. He prefers the name role test because contract test has become overloaded.

Jason Gorman describes the same reusable-suite pattern as “polymorphic/contract testing”: test methods live in a base suite, while concrete test subclasses provide different implementations. Rivero also relates role tests to the contract tests in J. B. Rainsberger’s collaboration-and-contract testing model.

That vocabulary connects several older ideas. Mock Roles, not Objects explains how client tests discover outgoing interfaces from the services a collaboration needs. Liskov and Wing’s behavioural subtyping work explains why substitutability requires preserving specified properties, not merely matching method signatures. Fowler’s writing on contract tests uses the same broad contract language for a different risk: compatibility between independently changing services. The overlap is useful, but the testing target is different.

The resulting definition is:

A role test is an object-oriented contract test expressed as a reusable behavioural suite and applied to every implementation that claims the same role.

The distinctive move is to execute one contract against two or more alternatives that must be substitutable.

The word interfaces can mislead here.

The sources describe testing different implementations or adapters of a role, not testing a contract against several unrelated interfaces. Usually there is one role interface:

CustomerRepository

and several implementations:

InMemoryCustomerRepository
PostgresCustomerRepository
ServiceCustomerRepository

In a dynamic language, there may be no formal interface construct at all. The role can be a duck type documented by shared examples. This is one reason “two or more interfaces” cannot be the general definition.

When two external dependencies expose different interfaces, adapters translate both into one stable role interface. The role suite runs against the adapters:

Legacy API -> Legacy adapter -> CustomerRepository contract
New API    -> New adapter    -> CustomerRepository contract

A second implementation is not logically required to write the suite. The suite can document a role before another implementation exists. Its substitutability value becomes visible when a fake, replacement, alternative strategy, or second adapter is added.

The terminology becomes confusing because contract testing also has a narrower and now widespread meaning in distributed systems. Martin Fowler uses the term for tests that check whether an external service continues to satisfy the behaviour expected by a client. Consumer-driven contract-testing literature develops that idea further around consumers, providers, published interactions, and independent deployment.

The two usages protect different risks:

Object-oriented role or contract test Distributed contract test Protects substitutability between implementations Protects compatibility between independently changing participants Runs one behavioural suite against every implementation Verifies requests, responses, messages, schemas, and interaction semantics Common examples are fake versus real repository or old versus new strategy Common examples are mobile client versus HTTP API or event consumer versus producer The contract is usually owned inside one design The contract crosses a deployment, team, or service boundary

An HTTP-backed repository may need both. Its role suite checks that the adapter presents the expected CustomerRepository semantics to local clients. Its distributed contract tests check that the remote provider still accepts and returns the agreed protocol.

Here, role test names the object-oriented, polymorphic use: one behavioural suite, one role, every implementation that claims it. Distributed contract testing remains a separate compatibility concern at service or deployment boundaries.

What a role test is not

It is not a direct implementation comparison

It is tempting to describe role testing as “testing two implementations of the same interface against each other.”

That wording is understandable but imprecise.

If we frame the technique that way, one implementation can accidentally become the reference and the other becomes a copy.

The flow should not be:

PostgreSQL behaviour -> copy into the in-memory fake

It should be:

client needs -> role contract -> shared examples -> implementations

The wrong oracle is:

InMemoryCustomerRepository behaves like PostgresCustomerRepository.

The role oracle is:

InMemoryCustomerRepository satisfies CustomerRepositoryRoleShould.
PostgresCustomerRepository satisfies CustomerRepositoryRoleShould.

The role is the reference, not one implementation.

If the implementations disagree, the answer is not automatically “make the fake match PostgreSQL” or “make PostgreSQL match the fake.”

Possible explanations include:

• The fake is wrong

• The production adapter is wrong

• The old implementation contains accidental behaviour

• The role test is missing a client-visible rule

• The abstraction promises something one implementation cannot provide

• Two different roles are hiding behind one interface

It is not differential testing

Differential testing runs the same inputs through two implementations and compares their outputs.

That can be valuable when replacing a legacy algorithm, database query, parser, or library. It can reveal disagreements over a large input set.

But it uses one implementation, or agreement between implementations, as an oracle. If the old implementation contains a bug, differential testing can encourage the new implementation to reproduce it.

A role test uses an intentional behavioural specification as the oracle.

It is not only a way to remove duplicated test code

Test reuse is useful. If several implementations must satisfy the same examples, copying those tests would create maintenance risk.

The deeper value is semantic:

• The team states the shared behaviour once

• Every implementation is held to the same meaning

• A disagreement becomes a design decision

• A new implementation tests the abstraction itself

It is not a complete proof of substitutability

A finite suite protects the examples and properties it encodes.

It does not automatically establish:

• Every possible input

• Every operation sequence

• Thread safety

• Durability

• Performance

• Security

• Availability

• Untested failures

Passing the suite is evidence that an implementation satisfies the represented portion of the contract. It is not a formal proof that every client-visible property is preserved.

It is not a replacement for implementation-specific tests

A PostgreSQL repository still needs tests for migrations, constraints, transactions, mapping, and database integration. A filesystem adapter may need tests for paths, permissions, atomic writes, and serialization. An HTTP adapter may need tests for authentication, timeouts, status-code translation, and retry behaviour.

Those tests protect implementation-specific responsibilities.

The role test protects shared behaviour.

It is not a particular test inheritance mechanism

A reusable role suite can use:

• A Kotlin or Java test interface

• An abstract test class

• Parameterized tests

• Dynamic tests

• RSpec shared examples

• Composition through functions or fixtures

The mechanism is secondary. The reusable behavioural specification is the technique.

Roles are discovered from the client side

A role does not usually appear because we invented an interface in isolation.

It often appears because a client needs help.

A use case needs somewhere to save a customer. A workflow needs a way to publish an event. A policy needs a source of time. A checkout process needs a pricing strategy. A migration needs an abstraction around a library that is being replaced.

In each case, the client is not asking for a concrete class. It is asking for a collaborator that can play a useful role in a larger behaviour.

Imagine we are developing RegisterCustomer:

class RegisterCustomer(
    private val customers: CustomerRepository
) {
    fun register(command: RegisterCustomerCommand) {
        val customer = Customer(
            id = command.customerId,
            name = command.name
        )

        customers.save(customer)
    }
}

At first, the test does not need a database. It needs to express that successful registration asks something to remember the customer.

@Test
fun `register a customer`() {
    val customers = RecordingCustomerRepository()
    val useCase = RegisterCustomer(customers)

    useCase.register(
        RegisterCustomerCommand(
            customerId = CustomerId("customer-1"),
            name = "Alice"
        )
    )

    assertThat(customers.savedCustomers).containsExactly(
        Customer(
            id = CustomerId("customer-1"),
            name = "Alice"
        )
    )
}

The recording repository is a client-test double. It records the outgoing collaboration that this client needs and refuses unrelated messages:

class RecordingCustomerRepository : CustomerRepository {
    val savedCustomers = mutableListOf<Customer>()

    override fun save(customer: Customer) {
        savedCustomers += customer
    }

    override fun findById(id: CustomerId): CustomerLookup {
        error("RegisterCustomer does not need lookup.")
    }
}

The messages sent by the client begin to reveal a required role.

Later, another client needs lookup. Another needs replacement semantics. Another needs to distinguish missing data from infrastructure failure. The role becomes more precise as real client needs appear.

The discovery path moves from a client’s behaviour to a role and then to the implementations that must satisfy it:

Role tests fit naturally with Test-Driven Development (TDD) and need-driven design.

The paper Mock Roles, not Objects explains how tests for a client can discover outgoing interfaces based on services the client requires. The interface is pulled into existence by demand rather than pushed outward from all the features a provider happens to offer.

Two testing activities follow:

1. Client tests protect how the client collaborates with the role

2. Role tests protect whether concrete implementations honour that role

The client test does not prove that PostgreSQL works. The PostgreSQL role test does not prove that RegisterCustomer sends the correct message. Together they protect both sides of the collaboration.

Client needs change how interfaces are designed.

A good role interface is not a list of everything an implementation can do. It is a description of what a client needs from a collaborator.

Consider a provider-oriented interface:

interface CustomerStore {
    fun save(customer: Customer)
    fun findById(id: CustomerId): CustomerLookup
    fun deleteAll()
    fun rebuildIndex()
    fun exportCsv(): String
    fun compactStorage()
}

Those operations may exist in one infrastructure component, but they do not form one coherent client role.

Application clients may need:

interface CustomerRepository {
    fun save(customer: Customer)
    fun findById(id: CustomerId): CustomerLookup
}

Operational tooling may need:

interface CustomerStorageMaintenance {
    fun rebuildIndex()
    fun compactStorage()
}

Narrow roles are easier to understand, substitute, adapt, and role-test.

A small example in Kotlin

The repository example is familiar, but role tests are not mainly about repositories.

Role tests also apply to clocks, payment gateways, event publishers, file adapters, HTTP clients, caches, notification senders, search adapters, and Strategy implementations.

Start with a small domain:

data class CustomerId(val value: String) {
    init {
        require(value.isNotBlank()) {
            "Customer id must not be blank."
        }
    }
}

data class Customer(
    val id: CustomerId,
    val name: String
) {
    init {
        require(name.isNotBlank()) {
            "Customer name must not be blank."
        }
    }
}

Now decide how lookup absence appears in the role’s language.

A nullable result would be concise:

fun findById(id: CustomerId): Customer?

An explicit result makes the contract easier to see:

sealed interface CustomerLookup {
    data class Found(val customer: Customer) : CustomerLookup
    data class Missing(val requestedId: CustomerId) : CustomerLookup
}

The repository becomes:

interface CustomerRepository {
    fun findById(id: CustomerId): CustomerLookup
    fun save(customer: Customer)
}

The result type already communicates one decision: absence is a normal lookup outcome represented as Missing, not null or an exception.

It still does not define the relationship between calls. The role suite will do that.

JUnit Jupiter allows test methods to be declared in interfaces. A concrete test class can implement the interface, supply a factory method, and inherit the shared examples.

The snippets below are complete for the design point they teach. Database, service, or sandbox harnesses are shown only where their shape affects the role-test contract.

import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test

interface CustomerRepositoryRoleShould {

    fun createEmptyRepository(): CustomerRepository

    @Test
    fun `find saved customer by id`() {
        // Arrange
        val repository = createEmptyRepository()
        val customer = Customer(
            id = CustomerId("customer-1"),
            name = "Alice"
        )

        // Act
        repository.save(customer)
        val result = repository.findById(customer.id)

        // Assert
        assertThat(result)
            .isEqualTo(CustomerLookup.Found(customer))
    }

    @Test
    fun `return missing when customer does not exist`() {
        // Arrange
        val repository = createEmptyRepository()
        val unknownId = CustomerId("unknown")

        // Act
        val result = repository.findById(unknownId)

        // Assert
        assertThat(result)
            .isEqualTo(CustomerLookup.Missing(unknownId))
    }

    @Test
    fun `keep saved customers separated by id`() {
        // Arrange
        val repository = createEmptyRepository()
        val alice = Customer(
            id = CustomerId("customer-1"),
            name = "Alice"
        )
        val bob = Customer(
            id = CustomerId("customer-2"),
            name = "Bob"
        )

        // Act
        repository.save(alice)
        repository.save(bob)

        val foundAlice = repository.findById(alice.id)
        val foundBob = repository.findById(bob.id)

        // Assert
        assertThat(foundAlice)
            .isEqualTo(CustomerLookup.Found(alice))
        assertThat(foundBob)
            .isEqualTo(CustomerLookup.Found(bob))
    }

    @Test
    fun `preserve relevant customer data`() {
        // Arrange
        val repository = createEmptyRepository()
        val customer = Customer(
            id = CustomerId("customer-1"),
            name = "Zoë 李"
        )

        // Act
        repository.save(customer)
        val result = repository.findById(customer.id)

        // Assert
        assertThat(result)
            .isEqualTo(CustomerLookup.Found(customer))
    }
}

The tests use Arrange, Act, Assert because it makes each expectation explicit. This structure is not part of role testing itself. It is simply a readable way to express each behavioural example.

The suite observes the repository only through its public role. It says nothing about maps, SQL, transactions, files, HTTP requests, JSON, or connection pools.

That is intentional.

The factory name also states a fixture precondition:

fun createEmptyRepository(): CustomerRepository

Every implementation-specific test must provide a clean repository. Without isolation, shared examples can leak state into one another and stop being reliable specifications.

The naming convention is deliberate. CustomerRepositoryRoleShould makes the role the subject of the specification:

CustomerRepositoryRoleShould find saved customer by id.
CustomerRepositoryRoleShould return missing when customer does not exist.
CustomerRepositoryRoleShould keep saved customers separated by id.

The individual method names remain short while the complete test name communicates the behavioural subject.

The first testing smell: using one role method to arrange another

The first suite is good enough to introduce the idea, but it also hides a testing smell.

The example named find saved customer by id uses save to create the precondition and findById to make the observation. If it fails, the failure might be in saving, lookup, mapping, equality, fixture isolation, or the relationship between two calls.

Some role examples genuinely need a sequence of role messages. If the contract is about a conversation, the test should show the conversation. The problem is accidental sequencing caused by weak fixture support.

A useful rule is:

If a test is about lookup, do not use save to create the precondition. If a test is about saving, do not use findById to observe the result.

The test should fail for the behaviour it is trying to specify.

For lookup behaviour, the repository should already contain the customer. For saving behaviour, the test should observe stored state without going back through lookup.

That does not mean exposing implementation details to production code. It means giving the test suite implementation-specific fixture hooks that can prepare and inspect state outside the role method currently under test.

A precise role-test fixture

A sharper role suite separates the production role from test infrastructure:

interface CustomerRepositoryFixture {
    val repository: CustomerRepository

    fun givenStored(vararg customers: Customer)

    fun storedCustomerById(id: CustomerId): CustomerLookup
}

Now the shared examples can say exactly which behaviour they exercise:

interface CustomerRepositoryRoleShould {

    fun createFixture(): CustomerRepositoryFixture

    @Test
    fun `find stored customer by id`() {
        // Arrange
        val fixture = createFixture()
        val customer = Customer(
            id = CustomerId("customer-1"),
            name = "Alice"
        )

        fixture.givenStored(customer)

        // Act
        val result = fixture.repository.findById(customer.id)

        // Assert
        assertThat(result)
            .isEqualTo(CustomerLookup.Found(customer))
    }

    @Test
    fun `store a new customer`() {
        // Arrange
        val fixture = createFixture()
        val customer = Customer(
            id = CustomerId("customer-1"),
            name = "Alice"
        )

        // Act
        fixture.repository.save(customer)

        // Assert
        assertThat(fixture.storedCustomerById(customer.id))
            .isEqualTo(CustomerLookup.Found(customer))
    }

    @Test
    fun `return missing when customer does not exist`() {
        // Arrange
        val fixture = createFixture()
        val unknownId = CustomerId("unknown")

        // Act
        val result = fixture.repository.findById(unknownId)

        // Assert
        assertThat(result)
            .isEqualTo(CustomerLookup.Missing(unknownId))
    }

    @Test
    fun `keep stored customers separated by id`() {
        // Arrange
        val fixture = createFixture()
        val alice = Customer(
            id = CustomerId("customer-1"),
            name = "Alice"
        )
        val bob = Customer(
            id = CustomerId("customer-2"),
            name = "Bob"
        )

        fixture.givenStored(alice, bob)

        // Act
        val foundAlice = fixture.repository.findById(alice.id)
        val foundBob = fixture.repository.findById(bob.id)

        // Assert
        assertThat(foundAlice)
            .isEqualTo(CustomerLookup.Found(alice))
        assertThat(foundBob)
            .isEqualTo(CustomerLookup.Found(bob))
    }

    @Test
    fun `preserve relevant customer data`() {
        // Arrange
        val fixture = createFixture()
        val customer = Customer(
            id = CustomerId("customer-1"),
            name = "Zoë 李"
        )

        // Act
        fixture.repository.save(customer)

        // Assert
        assertThat(fixture.storedCustomerById(customer.id))
            .isEqualTo(CustomerLookup.Found(customer))
    }
}

The lookup example arranges state through givenStored and exercises only findById. The save example exercises only save and observes state through storedCustomerById.

The fixture is not part of the production role. The in-memory fixture can write directly to the backing map. The PostgreSQL fixture can prepare and inspect rows through the table gateway. The shared suite stays focused on client-visible behaviour, while each concrete fixture owns the mechanics needed to make the examples precise.

That precision matters because role tests often become design evidence. A noisy test that can fail for five reasons is a weak witness. A role test should make the missing or broken contract visible.

The change in test shape is small but important.

Before, a lookup example arranged state through the role method save:

val repository = createEmptyRepository()

repository.save(customer)

assertThat(repository.findById(customer.id))
    .isEqualTo(CustomerLookup.Found(customer))

After, the same lookup example uses fixture infrastructure for the precondition and reserves the role call for the behaviour under test:

val fixture = createFixture()

fixture.givenStored(customer)

assertThat(fixture.repository.findById(customer.id))
    .isEqualTo(CustomerLookup.Found(customer))

The same separation works in the other direction. A save example should not need findById to observe the result:

val fixture = createFixture()

fixture.repository.save(customer)

assertThat(fixture.storedCustomerById(customer.id))
    .isEqualTo(CustomerLookup.Found(customer))

Testing two implementations with the same role test

The in-memory implementation is small:

class InMemoryCustomerRepository(
    private val customers: MutableMap<CustomerId, Customer> = mutableMapOf()
) : CustomerRepository {

    override fun findById(id: CustomerId): CustomerLookup {
        val customer = customers[id]
            ?: return CustomerLookup.Missing(id)

        return CustomerLookup.Found(customer)
    }

    override fun save(customer: Customer) {
        customers[customer.id] = customer
    }
}

Its concrete test declares that it must satisfy the role:

class InMemoryCustomerRepositoryShould :
    CustomerRepositoryRoleShould {

    override fun createFixture(): CustomerRepositoryFixture =
        InMemoryCustomerRepositoryFixture()
}

private class InMemoryCustomerRepositoryFixture :
    CustomerRepositoryFixture {

    private val stored = mutableMapOf<CustomerId, Customer>()

    override val repository: CustomerRepository =
        InMemoryCustomerRepository(stored)

    override fun givenStored(vararg customers: Customer) {
        customers.forEach { customer ->
            stored[customer.id] = customer
        }
    }

    override fun storedCustomerById(id: CustomerId): CustomerLookup {
        val customer = stored[id]
            ?: return CustomerLookup.Missing(id)

        return CustomerLookup.Found(customer)
    }
}

Now add a PostgreSQL implementation:

data class CustomerRow(
    val id: String,
    val name: String
)

interface CustomerRows {
    fun findById(id: String): CustomerRow?
    fun insert(row: CustomerRow)
    fun upsert(row: CustomerRow)
}

class PostgresCustomerRepository(
    private val rows: CustomerRows
) : CustomerRepository {

    override fun findById(id: CustomerId): CustomerLookup {
        val row = rows.findById(id.value)
            ?: return CustomerLookup.Missing(id)

        return PostgresCustomerLookupMapper.toCustomerLookup(row)
    }

    override fun save(customer: Customer) {
        rows.insert(
            CustomerRow(
                id = customer.id.value,
                name = customer.name
            )
        )
    }
}

private object PostgresCustomerLookupMapper {

    fun toCustomerLookup(row: CustomerRow): CustomerLookup =
        CustomerLookup.Found(
            Customer(
                id = CustomerId(row.id),
                name = row.name
            )
        )
}

PostgresCustomerLookupMapper is deliberately not injected into the repository.

It is an internal implementation detail of the PostgreSQL adapter, not a peer of the CustomerRepository role. Extracting a collaborator does not automatically mean promoting it to the constructor boundary.

The role test protects the shared behaviour of CustomerRepository.

The mapper supports one implementation. As shown here, it is private and exercised through the repository. If it grows enough to deserve direct tests, that would be a reason to revisit its visibility and responsibilities, not a reason to place it in the shared role.

The PostgreSQL test uses the same suite:

class PostgresCustomerRepositoryShould :
    CustomerRepositoryRoleShould {

    override fun createFixture(): CustomerRepositoryFixture {
        val rows = TestDatabase.freshCustomerRows()
        return PostgresCustomerRepositoryFixture(rows)
    }
}

private class PostgresCustomerRepositoryFixture(
    private val rows: CustomerRows
) : CustomerRepositoryFixture {

    override val repository: CustomerRepository =
        PostgresCustomerRepository(rows)

    override fun givenStored(vararg customers: Customer) {
        customers.forEach { customer ->
            rows.upsert(
                CustomerRow(
                    id = customer.id.value,
                    name = customer.name
                )
            )
        }
    }

    override fun storedCustomerById(id: CustomerId): CustomerLookup {
        val row = rows.findById(id.value)
            ?: return CustomerLookup.Missing(id)

        return CustomerLookup.Found(
            Customer(
                id = CustomerId(row.id),
                name = row.name
            )
        )
    }
}

The concrete database harness is intentionally represented by TestDatabase.freshCustomerRows(). In a real test suite it must provide:

• A migrated schema

• An empty customers table

• Isolation between tests

• The same database dialect used by the production adapter

Possible implementations include a rolled-back transaction, table truncation, a fresh schema, a database sandbox, or a disposable container.

The minimal table needed by these examples is:

CREATE TABLE customers (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL
);

PostgresCustomerRepositoryFixture deliberately uses the table gateway directly. It prepares and inspects state at the adapter boundary without calling the role method currently under test.

That gives each role example a sharper failure signal:

givenStored(...) -> repository.findById(...)
repository.save(...) -> storedCustomerById(...)

If the lookup test fails, the failure points at lookup behaviour. If the save test fails, the failure points at save behaviour.

The shared suite should not know which isolation strategy is used. Fixture construction belongs to the concrete adapter test.

Both implementations now satisfy the same known behaviours.

The in-memory adapter can use a map. PostgreSQL can use a table gateway and an internal mapper. The suite does not care because those are implementation decisions, not role-level promises.

The behavioural specification is written once and run against every implementation that claims the abstraction.

The missing save contract

The current role suite still has a weakness.

It does not define what happens when the same customer id is saved twice.

That omission allows the in-memory and PostgreSQL implementations to pass while disagreeing about save.

Suppose a client renames a customer by saving a new representation with the same identity. Replacement semantics then become part of the role.

Add one example:

@Test
fun `replace previously stored customer with the same id`() {
    // Arrange
    val fixture = createFixture()
    val original = Customer(
        id = CustomerId("customer-1"),
        name = "Alice"
    )
    val renamed = original.copy(name = "Alicia")

    fixture.givenStored(original)

    // Act
    fixture.repository.save(renamed)

    // Assert
    assertThat(fixture.storedCustomerById(original.id))
        .isEqualTo(CustomerLookup.Found(renamed))
}

This is the same before-and-after lesson applied to a new contract decision. The old shape would have been noisier:

repository.save(original)
repository.save(renamed)

assertThat(repository.findById(original.id))
    .isEqualTo(CustomerLookup.Found(renamed))

That test checks an important history property, but it can still fail through lookup. The fixture-based version keeps the observed behaviour focused on what save must do when the identity already exists.

The in-memory implementation passes. The PostgreSQL implementation fails because the second insert violates the unique key.

The failed test reveals a missing contract decision.

Possible responses include:

1. Define save as an upsert and change PostgreSQL

2. Define duplicate identity as an error and change the in-memory fake

3. Rename save to add if creation is the real responsibility

4. Separate add and replace

5. Introduce optimistic concurrency if silent replacement would lose changes

6. Admit that the implementations do not satisfy the same role

The role test should not invent the answer merely to make implementations equal. The decision comes from client needs and domain rules.

If last-write-wins replacement is the intended contract, PostgreSQL can implement an upsert:

override fun save(customer: Customer) {
    rows.upsert(
        CustomerRow(
            id = customer.id.value,
            name = customer.name
        )
    )
}

The production adapter now satisfies the chosen role.

This does not make the fake the source of truth. The client requirement and the resulting specification are the source of truth. The fake happened to implement the selected behaviour first.

The example also demonstrates the limit of role testing:

A shared suite is only as complete as the client-visible behaviours it expresses.

Green tests meant that both implementations satisfied the initial examples. They did not mean that every semantic question had already been answered.

Keeping test doubles aligned with real adapters

An in-memory repository is a fake: a working but simplified implementation of a dependency.

Fakes are useful because they are fast, deterministic, and easy to construct:

val customers = InMemoryCustomerRepository()

Those strengths also make them dangerous. A fake can become a fantasy object that behaves conveniently in tests but cannot be substituted by production.

Common divergences include:

• A map overwrites duplicate keys while SQL rejects them

• A fake accepts values rejected by database constraints

• A fake returns the exact stored instance while production reconstructs data

• A fake ignores serialization and representation loss

• A fake offers immediate consistency while a remote store is eventually consistent

• A fake never fails

• A fake is not thread-safe while production use is concurrent

• A fake claims persistence but loses everything when the process ends

A role suite reduces drift for the behaviours included in the contract.

The fake should not be judged by this rule:

Make the fake reproduce PostgreSQL.

The role contract asks for this:

Make the fake and PostgreSQL honour the same promises made by CustomerRepository.

Everything outside those promises may differ.

That separation prevents two opposite mistakes.

The first is an unrealistically weak fake:

class AlwaysSuccessfulCustomerRepository :
    CustomerRepository {

    override fun findById(id: CustomerId): CustomerLookup =
        CustomerLookup.Missing(id)

    override fun save(customer: Customer) {
        // Pretend the operation succeeded.
    }
}

Client tests using this fake can pass even though saved data can never be found.

The second mistake is recreating the infrastructure inside the fake. If the in-memory repository implements SQL locking, database transactions, network retries, connection pools, and persistence formats, it is no longer lightweight.

Role tests identify the middle ground:

• Reproduce the shared semantics

• Omit implementation-specific mechanics

• Test the real adapter separately

The resulting test strategy has different suites protecting different risks:

Fakes are a common use case, but not the whole technique. A filesystem repository and a PostgreSQL repository can both be production adapters. A sandbox payment gateway and a live gateway may both be production-like environments. Kafka and another broker may coexist during migration.

The relevant fact is that each implementation claims the same role.

Using role tests to replace a dependency safely

Role tests become especially useful when a dependency must be replaced.

Imagine a system coupled to a legacy customer library:

data class LegacyCustomerRecord(
    val customerNumber: String,
    val displayName: String
)

interface LegacyCustomerStore {
    fun put(record: LegacyCustomerRecord)
    fun fetch(customerNumber: String): LegacyCustomerRecord?
}

The team wants to migrate to a new service:

data class CustomerRequest(
    val id: String,
    val fullName: String
)

data class CustomerResponse(
    val id: String,
    val fullName: String
)

interface CustomerServiceClient {
    fun upsert(request: CustomerRequest)
    fun get(customerId: String): CustomerResponse?
}

The APIs differ. Directly changing every client would mix several concerns:

• Understanding what clients actually need

• Translating between data models

• Implementing the new integration

• Updating every use site

• Deciding which legacy behaviours must be preserved

A safer refactor introduces a stable role:

interface CustomerRepository {
    fun findById(id: CustomerId): CustomerLookup
    fun save(customer: Customer)
}

The old dependency receives an adapter:

class LegacyCustomerRepository(
    private val legacyStore: LegacyCustomerStore
) : CustomerRepository {

    override fun findById(id: CustomerId): CustomerLookup {
        val record = legacyStore.fetch(id.value)
            ?: return CustomerLookup.Missing(id)

        return CustomerLookup.Found(
            Customer(
                id = CustomerId(record.customerNumber),
                name = record.displayName
            )
        )
    }

    override fun save(customer: Customer) {
        legacyStore.put(
            LegacyCustomerRecord(
                customerNumber = customer.id.value,
                displayName = customer.name
            )
        )
    }
}

The new dependency receives another adapter:

class ServiceCustomerRepository(
    private val client: CustomerServiceClient
) : CustomerRepository {

    override fun findById(id: CustomerId): CustomerLookup {
        val response = client.get(id.value)
            ?: return CustomerLookup.Missing(id)

        return CustomerLookup.Found(
            Customer(
                id = CustomerId(response.id),
                name = response.fullName
            )
        )
    }

    override fun save(customer: Customer) {
        client.upsert(
            CustomerRequest(
                id = customer.id.value,
                fullName = customer.name
            )
        )
    }
}

Both adapters run the same role suite:

class LegacyCustomerRepositoryShould :
    CustomerRepositoryRoleShould {

    override fun createFixture(): CustomerRepositoryFixture =
        LegacyCustomerRepositoryFixture(
            legacyStore = LegacyTestEnvironment.emptyStore()
        )
}

class ServiceCustomerRepositoryShould :
    CustomerRepositoryRoleShould {

    override fun createFixture(): CustomerRepositoryFixture =
        ServiceCustomerRepositoryFixture(
            client = CustomerServiceSandbox.emptyClient()
        )
}

The following fixtures show the contract shape. Each real project supplies the backing test environment.

LegacyCustomerRepositoryFixture and ServiceCustomerRepositoryFixture follow the same pattern as the PostgreSQL fixture: they expose the adapter through repository, prepare state through the real dependency’s test environment, and inspect state without calling the role method currently under test.

These fixture names represent production-compatible test environments: an isolated instance of the legacy store and a sandbox, emulator, disposable service, or controlled integration environment for the replacement.

Using another hand-written fake underneath each adapter may make the suite faster, but it would not prove that the adapter translates the real dependency correctly. If a provider cannot run in the role suite, retain provider-specific integration or distributed contract tests beside it.

A gradual migration can then proceed in small steps:

1. Identify the behaviour clients need from the old dependency

2. Introduce a role interface around those needs

3. Adapt the old dependency to the role

4. Write the shared role suite

5. Make the old adapter satisfy the suite

6. Implement the new adapter

7. Make the new adapter satisfy the same suite

8. Switch clients incrementally

9. Remove the old dependency when no clients remain

This is closely related to Branch by Abstraction. Martin Fowler describes that technique as introducing an abstraction so an old and a new supplier can coexist while clients migrate gradually.

Role tests strengthen the technique by making the abstraction’s expected behaviour executable.

The role suite does not compare the two external APIs. It checks that both adapters present the same CustomerRepository behaviour to local clients.

Role testing does not usually verify a contract against two unrelated interfaces. It verifies one role contract against the implementations or adapters that claim that role.

If the old and new dependencies expose different APIs, adapters translate both into the stable role.

During migration, the system may also run both implementations against production-like traffic and compare selected observations. That is useful, but it is differential testing or shadow traffic, not the role test itself.

The techniques complement one another:

• The role suite states what must remain true

• Characterization tests reveal what the old dependency currently does

• Differential tests find disagreements between old and new implementations

• Integration tests prove that each real dependency is wired correctly

• Feature flags or controlled routing migrate clients gradually

Role tests are valuable because they prevent “the old dependency did it” from becoming the only definition of correctness.

Replacing an OpenAPI-generated client without breaking local clients

Generated clients are useful. An OpenAPI Specification (OAS) document describes provider-facing details: paths, operations, schemas, parameters, responses, and protocol errors.

The risk appears when application code starts speaking generated-client language directly.

Imagine checkout code coupled to a generated shipping client:

interface GeneratedShippingQuotesApi {
    fun quote(request: GeneratedShippingQuoteRequest): GeneratedShippingQuoteResponse
}

data class GeneratedShippingQuoteRequest(
    val destinationCountry: String,
    val weightInGrams: Int
)

data class GeneratedShippingQuoteResponse(
    val available: Boolean,
    val carrier: String?,
    val priceInCents: Long?
)

class CheckoutShippingOptions(
    private val shippingApi: GeneratedShippingQuotesApi
) {
    fun quoteFor(
        destinationCountry: String,
        weightInGrams: Int
    ): String {
        val response = shippingApi.quote(
            GeneratedShippingQuoteRequest(
                destinationCountry = destinationCountry,
                weightInGrams = weightInGrams
            )
        )

        if (!response.available) {
            return "No shipping available"
        }

        return "${requireNotNull(response.carrier)}: ${requireNotNull(response.priceInCents)} cents"
    }
}

The generator is not the problem. The transport contract has become the local application role.

Checkout needs a smaller role:

data class CountryCode(val value: String) {
    init {
        require(value.matches(Regex("[A-Z]{2}"))) {
            "Country code must use two uppercase letters."
        }
    }
}

data class ShippingRequest(
    val destinationCountry: CountryCode,
    val weightInGrams: Int
) {
    init {
        require(weightInGrams > 0) {
            "Weight must be greater than zero."
        }
    }
}

data class ShippingQuote(
    val carrier: String,
    val priceInCents: Long
)

sealed interface ShippingQuoteResult {
    data class Quoted(val quote: ShippingQuote) : ShippingQuoteResult
    data class UnsupportedDestination(val country: CountryCode) : ShippingQuoteResult
}

interface ShippingQuotes {
    fun quoteFor(request: ShippingRequest): ShippingQuoteResult
}

The shared role suite protects local behaviour, not OpenAPI protocol details:

interface ShippingQuotesFixture {
    val shippingQuotes: ShippingQuotes

    fun givenAvailableQuote(
        request: ShippingRequest,
        quote: ShippingQuote
    )

    fun givenUnsupportedDestination(country: CountryCode)
}

interface ShippingQuotesRoleShould {

    fun createFixture(): ShippingQuotesFixture

    @Test
    fun `return a quote for a supported destination and weight`() {
        val fixture = createFixture()
        val request = ShippingRequest(
            destinationCountry = CountryCode("DE"),
            weightInGrams = 1200
        )
        val quote = ShippingQuote(
            carrier = "DHL",
            priceInCents = 899
        )

        fixture.givenAvailableQuote(request, quote)

        val result = fixture.shippingQuotes.quoteFor(request)

        assertThat(result)
            .isEqualTo(ShippingQuoteResult.Quoted(quote))
    }

    @Test
    fun `report unsupported destination in local domain language`() {
        val fixture = createFixture()
        val country = CountryCode("AQ")
        val request = ShippingRequest(
            destinationCountry = country,
            weightInGrams = 1200
        )

        fixture.givenUnsupportedDestination(country)

        val result = fixture.shippingQuotes.quoteFor(request)

        assertThat(result)
            .isEqualTo(ShippingQuoteResult.UnsupportedDestination(country))
    }
}

The old adapter can wrap the generated client:

class GeneratedClientShippingQuotes(
    private val api: GeneratedShippingQuotesApi
) : ShippingQuotes {

    override fun quoteFor(request: ShippingRequest): ShippingQuoteResult {
        val response = api.quote(
            GeneratedShippingQuoteRequest(
                destinationCountry = request.destinationCountry.value,
                weightInGrams = request.weightInGrams
            )
        )

        if (!response.available) {
            return ShippingQuoteResult.UnsupportedDestination(
                request.destinationCountry
            )
        }

        return ShippingQuoteResult.Quoted(
            ShippingQuote(
                carrier = requireNotNull(response.carrier),
                priceInCents = requireNotNull(response.priceInCents)
            )
        )
    }
}

The replacement can be a handwritten adapter:

interface ShippingQuoteTransport {
    fun fetchQuote(request: ShippingRequest): ShippingQuoteResult
}

class ValidatedHttpShippingQuotes(
    private val transport: ShippingQuoteTransport
) : ShippingQuotes {

    override fun quoteFor(request: ShippingRequest): ShippingQuoteResult {
        return transport.fetchQuote(request)
    }
}

Both adapters run the same ShippingQuotesRoleShould suite.

• The OAS contract describes the provider API

• The role test describes the local application role

• The generated client and the handwritten adapter are implementation choices behind that role

The role suite does not replace provider contract tests, schema checks, authentication tests, retry tests, timeout tests, or real integration tests. It protects the meaning promised to application code while provider protocol concerns stay at the provider boundary.

A Strategy example during a refactor

The Strategy pattern defines a family of algorithms behind a common interface so a client can select or replace the algorithm without owning its implementation details.

That makes Strategy a natural place for role tests, but it introduces an important distinction.

Sometimes strategies are intentionally different:

RoadRouteStrategy and WalkingRouteStrategy

They receive the same origin and destination but should produce different routes. A shared role suite can protect common properties, such as returning a connected route with the requested endpoints. It should not require equal routes.

In other cases, a new Strategy is intended as a behavioural replacement for an old one. Then the role suite can protect the complete business behaviour that must survive the refactor.

Consider a checkout that delegates pricing:

interface PriceCalculationStrategy {
    fun calculatePrice(order: Order): Money
}

The example uses a deliberately small, single-currency Money value so that the pricing rules remain visible:

data class Money private constructor(
    private val cents: Long
) : Comparable<Money> {

    init {
        require(cents >= 0) {
            "Money cannot be negative."
        }
    }

    fun discountBy(percentage: Int): Money {
        require(percentage in 0..100) {
            "Discount percentage must be between 0 and 100."
        }

        val discountInCents = cents * percentage / 100
        return Money(cents - discountInCents)
    }

    override fun compareTo(other: Money): Int =
        cents.compareTo(other.cents)

    companion object {
        fun euros(amount: String): Money {
            val decimal = amount.toBigDecimal()
                .setScale(2)

            return Money(
                decimal.movePointRight(2)
                    .longValueExact()
            )
        }

        fun zero(): Money = Money(0)
    }
}

enum class CustomerType {
    REGULAR,
    PREFERRED
}

data class Order(
    val customerType: CustomerType,
    val subtotal: Money
)

Production money handling may require several currencies, explicit rounding rules, overflow protection, and auditability. The pricing role below only needs enough money behaviour to make the strategy rules visible.

class Checkout(
    private val priceCalculation: PriceCalculationStrategy
) {
    fun totalFor(order: Order): Money =
        priceCalculation.calculatePrice(order)
}

The current strategy contains legacy conditionals:

class LegacyPriceCalculationStrategy :
    PriceCalculationStrategy {

    override fun calculatePrice(order: Order): Money {
        if (order.customerType == CustomerType.PREFERRED) {
            return order.subtotal.discountBy(10)
        }

        return order.subtotal
    }
}

The team wants to replace it with a rule-based design:

interface PricingRule {
    fun appliesTo(order: Order): Boolean
    fun priceFor(order: Order): Money
}

class PreferredCustomerPricingRule : PricingRule {

    override fun appliesTo(order: Order): Boolean =
        order.customerType == CustomerType.PREFERRED

    override fun priceFor(order: Order): Money =
        order.subtotal.discountBy(10)
}

class RuleBasedPriceCalculationStrategy(
    private val rules: List<PricingRule>
) : PriceCalculationStrategy {

    override fun calculatePrice(order: Order): Money {
        val applicableRule = rules.firstOrNull {
            it.appliesTo(order)
        }

        return applicableRule?.priceFor(order)
            ?: order.subtotal
    }
}

The role suite expresses the rules clients rely on:

import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test

interface PriceCalculationStrategyRoleShould {

    fun createStrategy(): PriceCalculationStrategy

    @Test
    fun `charge subtotal to a regular customer`() {
        val strategy = createStrategy()
        val order = Order(
            customerType = CustomerType.REGULAR,
            subtotal = Money.euros("100.00")
        )

        val total = strategy.calculatePrice(order)

        assertThat(total)
            .isEqualTo(Money.euros("100.00"))
    }

    @Test
    fun `apply ten percent discount to a preferred customer`() {
        val strategy = createStrategy()
        val order = Order(
            customerType = CustomerType.PREFERRED,
            subtotal = Money.euros("100.00")
        )

        val total = strategy.calculatePrice(order)

        assertThat(total)
            .isEqualTo(Money.euros("90.00"))
    }

    @Test
    fun `keep a zero subtotal at zero`() {
        val strategy = createStrategy()
        val order = Order(
            customerType = CustomerType.PREFERRED,
            subtotal = Money.zero()
        )

        val total = strategy.calculatePrice(order)

        assertThat(total)
            .isEqualTo(Money.zero())
    }
}

Both strategies claim the role:

class LegacyPriceCalculationStrategyShould :
    PriceCalculationStrategyRoleShould {

    override fun createStrategy(): PriceCalculationStrategy =
        LegacyPriceCalculationStrategy()
}

class RuleBasedPriceCalculationStrategyShould :
    PriceCalculationStrategyRoleShould {

    override fun createStrategy(): PriceCalculationStrategy =
        RuleBasedPriceCalculationStrategy(
            rules = listOf(
                PreferredCustomerPricingRule()
            )
        )
}

The static structure is simple: Checkout depends on the role, while the role suite verifies both strategy implementations independently.

Now the team can refactor the internal design without changing what Checkout is allowed to assume.

The suite protects business meaning:

• Regular customers pay the subtotal

• Preferred customers receive the agreed discount

• A zero subtotal remains zero

It does not protect implementation details:

• if statements

• Rule ordering internals not visible to clients

• The number of rule objects

• Whether percentages are calculated through one method or another

The suite protects business meaning without turning the old implementation into the oracle.

If the legacy strategy contains an accidental bug for one unusual order, the team must decide whether that behaviour is contractual. A characterization or differential test may expose the disagreement. The role suite contains the decision about what should survive.

Strategies are interchangeable only relative to the properties promised by their shared role.

If RoadRouteStrategy and WalkingRouteStrategy intentionally optimize different outcomes, their role test should express common route validity, not equal paths. If RuleBasedPriceCalculationStrategy is a drop-in replacement for the legacy pricing strategy, its suite can express the complete pricing rules that clients require.

Role tests, characterization tests, and differential tests

During a replacement, teams often need three related activities. They should not collapse into one another.

Observed legacy behaviour can inform the role contract. It should not become the role contract automatically.

Characterization tests

Michael Feathers describes characterization tests as tests that document actual current behaviour so code can be changed more deterministically.

When a team does not yet understand a legacy implementation, a characterization test records what happens today:

@Test
fun `characterize current preferred customer pricing`() {
    val legacy = LegacyPriceCalculationStrategy()
    val order = Order(
        customerType = CustomerType.PREFERRED,
        subtotal = Money.euros("100.00")
    )

    val observedTotal = legacy.calculatePrice(order)

    assertThat(observedTotal)
        .isEqualTo(Money.euros("90.00"))
}

Before the refactor, the test creates a concrete observation:

It does not yet say:

That second statement requires a decision. The team may confirm that the behaviour is an intentional business rule, discover that it is an accidental bug, or decide that the rule should change.

Characterization tests are useful but dangerous as a source of truth. They capture what exists, including accidental behaviour.

Differential tests

Differential tests run the same examples through old and new implementations:

val oldResult = legacyStrategy.calculatePrice(order)
val newResult = ruleBasedStrategy.calculatePrice(order)

assertThat(newResult).isEqualTo(oldResult)

Differential tests reveal disagreement across many generated or recorded inputs.

They are less useful for deciding which result is correct.

Role tests

Role tests encode the behaviour clients are allowed to require. If the team decides that the preferred-customer discount is contractual, the observation moves into the shared role suite:

@Test
fun `apply ten percent discount to a preferred customer`() {
    val strategy = createStrategy()
    val order = Order(
        customerType = CustomerType.PREFERRED,
        subtotal = Money.euros("100.00")
    )

    val total = strategy.calculatePrice(order)

    assertThat(total)
        .isEqualTo(Money.euros("90.00"))
}

The expected value is the same as in the characterization test, but the oracle is different.

The characterization-test oracle:

The role-test oracle:

Characterization tests can feed a role test, but they should not become the role test automatically.

During a dependency replacement, a strong workflow can use all three:

1. Characterize the legacy implementation

2. Identify which observed behaviours are intentional

3. Place intentional shared behaviour in the role suite

4. Run the role suite against old and new adapters

5. Use differential testing on a wider dataset to find unexpected disagreements

6. Decide each disagreement using domain rules and client needs

The workflow avoids two failure modes:

• Blindly copying every legacy behaviour

• Rewriting the dependency without understanding what clients rely on

What should go into a role test?

A shared-suite behaviour must be promised by every valid implementation.

A practical filter is:

Could a client written only against this role reasonably depend on this behaviour?

For CustomerRepository, that may include:

• A saved customer can be found by id

• An unknown id produces Missing

• Customers with different ids remain independent

• Relevant customer data survives persistence and reconstruction

• Saving the same id has defined semantics

• Invalid input is handled consistently, if input validation belongs to the role

• Failures use a stable domain language, if clients are expected to react to them

For PriceCalculationStrategy, it may include:

• Business rules that every drop-in pricing implementation must preserve

• Boundary behaviour such as preserving a zero subtotal

• Boundary behaviour around zero or discount limits

Role tests often describe operation sequences rather than isolated methods:

save customer
find customer

save original
save replacement
find identity

calculate regular order
calculate preferred order
preserve a zero subtotal

The term behavioural contract matters because the suite describes interactions, not only isolated method returns.

Use preconditions, postconditions, invariants, failures, and history as prompts:

• Does one implementation reject an input the role accepts?

• Does it return an outcome the role does not permit?

• Does it throw an exception clients cannot handle?

• Can it break an invariant?

• Can a sequence of calls create an observation forbidden by the role?

Do not add every conceivable case. Add behaviours clients are allowed to rely on and risks likely to cause semantic drift.

The suite should grow when the role becomes better understood.

What should not go into a role test?

A role test should not become a dump of every behaviour of every implementation.

These do not belong in a generic CustomerRepositoryRoleShould:

• Creating the customers table

• Using a specific SQL index

• Opening exactly one database connection

• Retrying a PostgreSQL deadlock three times

• Calling PostgresCustomerLookupMapper

• Serializing customers as JSON

• Storing files under a particular directory

• Using a mutable map internally

• Calling an HTTP endpoint with a specific library

Some of these behaviours need tests. They belong to the concrete adapter.

The same separation applies to Strategy:

• The role suite can protect pricing outcomes

• It should not require RuleBasedPriceCalculationStrategy to evaluate rules through a particular collection operation

• It should not require the legacy strategy to contain an if

The shared suite should also avoid accidental behaviour.

Suppose PostgreSQL returns rows in insertion order for a query without ORDER BY. If no client is promised that order, do not add it to the role suite merely because it happened in one test run.

Every shared assertion increases the contract surface. Once clients depend on it, changing it becomes more expensive.

The suite should capture intentional guarantees, not everything implementations happen to share.

There is another warning sign: implementation-specific branching inside the suite.

fun expectedDuplicateBehaviour(): DuplicateBehaviour
fun expectedOrdering(): Ordering
fun expectedFailureType(): FailureType

If every assertion changes according to the implementation, the suite no longer describes one role. It describes a family of incompatible behaviours.

The right response may be:

• Narrow the shared contract

• Split the interface

• Introduce separate roles

• Accept that one implementation is not substitutable

Role tests and object-oriented design

Role tests are not only a testing technique. They create design pressure.

They force a question that class-oriented designs can avoid:

What role is this object playing for its clients?

That question is stronger than:

What class is this?

A class is a code construct. A role is a responsibility in a collaboration.

Role tests fit naturally with object-oriented design. Objects collaborate through messages and make promises to their neighbours. A role test captures part of those promises.

Role tests can reveal weak abstractions:

• If the interface is hard to role-test, the role may be unclear

• If each implementation needs exceptions to the shared suite, the interface may hide several concepts

• If the suite needs implementation internals, the abstraction may be leaking

• If the suite becomes enormous, the role may own too many responsibilities

• If a fake cannot satisfy production semantics, the fake may be misleading

• If production cannot satisfy the role promised to clients, the abstraction may be unrealistic

The PostgresCustomerLookupMapper example illustrates a smaller boundary decision.

The mapper improves one adapter’s internal design. It is not part of the shared repository role. Clients should not know it exists, so the role suite ignores it.

The Strategy example illustrates another boundary.

Checkout knows only PriceCalculationStrategy. It should not know whether pricing is implemented through conditionals, a rule collection, a decision table, or an external engine. The role test protects the result that Checkout can rely on.

Role tests also support evolvability.

When a new adapter or strategy is introduced, the suite provides immediate feedback about whether the existing abstraction is strong enough. When a dependency is replaced, the suite separates client promises from supplier details. When a test fake is used, the suite reduces the risk that tests execute against an easier but semantically false world.

Role tests do not magically produce good design. They make vague contracts harder to ignore.

Common mistakes

Wrong oracle

The production adapter is not automatically the truth. The fake is not automatically the truth. The legacy dependency is not automatically the truth.

The intentional role specification is the reference.

Characterization and differential tests can reveal legacy behaviour. They do not decide which behaviour deserves to become contractual.

Overclaiming substitutability

Passing examples is evidence for represented behaviour, not exhaustive proof.

State the boundary of the suite honestly.

Implementation-detail assertions

Tests such as “store the customer in a map,” “execute this SQL,” or “evaluate exactly three pricing rules” may be valid implementation tests. They are not role tests.

Overgrown or inconsistent roles

Persistence, search, exporting, reporting, and notification rarely form one coherent repository role.

Test friction can be design feedback.

If the suite expects replacement from one repository and duplicate rejection from another, it is not protecting one role.

Role tests are useful when a meaningful role and substitution pressure already exist. They are not a reason to create interfaces everywhere.

Replacing other test types

A PostgreSQL adapter can pass its role suite and still fail because of migrations, permissions, configuration, connection pools, or deployment.

An HTTP adapter can pass and still fail against the real provider.

Role tests are object-oriented contract tests for substitutability. Distributed contract tests use the same broad language for compatibility across an independently changing boundary. State which meaning is intended instead of treating either vocabulary as universal.

Weak or over-realistic fakes

A fake that ignores calls, always succeeds, or stores less information than the role promises can make client tests misleading.

A fake should reproduce shared semantics, not database engines, networks, or operational failure systems.

Strategy equality

Alternative strategies can intentionally produce different outputs.

The shared suite should protect the common role. Equal output is required only when one strategy is intended as a behavioural replacement for another.

Fragile test mechanics

Each implementation fixture must create a clean and known state. Shared tests are unreliable if state leaks between examples.

A test interface, abstract class, or shared-example feature is only the delivery mechanism.

Most mistakes come from choosing the wrong oracle, widening the role beyond client needs, or confusing shared semantics with implementation mechanics.

When role tests are worth the cost

Role tests add work:

• A shared suite must be named and maintained

• Every implementation needs an isolated fixture

• The team must decide which behaviours are genuinely shared

• Real adapters can make the suite slower

They are especially valuable when:

• A fake is used heavily in client tests

• Several implementations already exist

• A new Strategy is intended as a drop-in replacement

• A database, library, framework, or external service is being replaced

• Old and new adapters must coexist during migration

• Different deployments choose different adapters

• Semantic drift would be expensive

• The abstraction is important enough to deserve explicit behavioural documentation

They may add little value when:

• There is one implementation and no realistic substitution pressure

• The interface exists only because a framework requires it

• The abstraction has almost no meaningful behaviour

• The implementations intentionally promise different semantics

• The role suite would repeat behaviour already protected more clearly through a stable public boundary

Sometimes the difficulty of writing a role test is evidence that the interface itself is not carrying enough design value.

Removing, narrowing, or splitting the interface may be better than surrounding it with more test architecture.

Conclusion

A role test is a small idea with a large design consequence.

It says that an abstraction means something.

An interface tells the compiler which messages an object accepts. It does not fully describe what clients may assume after sending those messages.

That is how an in-memory repository and a PostgreSQL repository can both implement:

fun save(customer: Customer)

while disagreeing about duplicate identity.

A role test turns the client-visible promises of that abstraction into shared executable examples.