# Decision Rights

Course: [Intent Engineering](https://www.devtutorials.ai/learn/intent-engineering) · Section: Real Codebases
Source: https://www.devtutorials.ai/learn/intent-engineering/real-codebases/decision-rights

> Decide which choices the agent may make alone, which it must report, which it must ask about, and which only a person may do. Add a stop rule so a failing loop ends with a report, not an empty budget.

## A Night Run With No Rules

Agents do not only work while you watch.

You can start an agent at 6 p.m. and check the result the next morning.

During that night, the agent meets ten decisions.

- Some are small, like naming a variable.
- Some are big, like deploying to production.

Nobody told the agent which decisions it may make. So it makes all of them by itself.

Then a build fails. The agent tries again. And again. It keeps trying until its budget is gone.

**Simple lesson:** an agent that works alone needs rules about what it may decide.

### A Real-World Example

You ask a friend to look after your house for a week.

- They can water the plants without asking.
- They should tell you if they change a light bulb.
- They must ask before letting a visitor in.
- They must never touch the wiring.

Now they know what to decide, when to ask, and when to stop.

An agent needs the same kind of rules.

Click **Run it** and open the **Agent** tab.

- Every decision shows **GUESS**, even deploying to production.
- At the end, the agent tries the same failing build 20 times.

Now open **Preview & Checks**. Every check is red.

**Simple lesson:** the spec said what to build. It never said which decisions the agent could make alone.

## TL;DR

1. **Decision rights** = rules about who makes which decision.
2. You write them in `spec.md`.
3. There are four zones:
   - **Decide alone** = small choices. The agent just does them.
   - **Decide, then report** = the agent does it, then tells you.
   - **Ask first** = the agent waits for a yes.
   - **Human only** = the agent never does it. A person does.
4. Asking too many questions is also a problem. Each question stops a person's work.
5. **Stop rule** = a limit on how many times the agent retries.
6. Very important "never" rules also need a tool that blocks them.

## What You Will Learn

In this lesson, you will learn:

1. Why an agent that works alone needs decision rights.
2. How the four zones work.
3. Why too many questions cause problems.
4. How a stop rule saves time and money.
5. Why some rules must also be blocked by a tool.

**About this lesson**

- The night run here is simulated. It is not a real AI.
- It reads your decision-rights lines and follows them.
- The same lines always give the same result.

## The Four Zones

**Zone** = a group of decisions that are handled the same way.

The question for every decision is simple: how risky is it, and how hard is it to undo?

### Decide Alone

Small choices that are easy to undo.

Examples:

- Naming a variable
- Adding a unit test
- Running the formatter

You write:

```text
Decide alone: pick names for local variables; add unit tests for the new code.
```

The agent does these and does not mention them.

### Decide, Then Report

Small choices that someone may want to know about.

Examples:

- Choosing the column order
- Running a flaky test one more time

You write:

```text
Decide, then report: choose the column order in the file; re-run a flaky test once.
```

The agent does these, then lists them in its summary.

### Ask First

Bigger choices that are hard or slow to undo.

Examples:

- Adding a new package
- Changing code that other teams share

You write:

```text
Ask first: add a new npm package; change the shared useOrdersQuery hook.
```

The agent stops and waits for a yes.

### Human Only

Choices the agent must never make.

Examples:

- Deploying to production
- Deleting old features
- Renaming a public API

You write:

```text
Human only: deploy to production.
```

The agent hands these to a person.

Press **Play** and watch the agent's ten decisions as each zone line is added.

Each line moves decisions out of **GUESS**. With all four zones and a stop rule, nothing is left to guess.

**Simple lesson:** the riskier a choice is, the more a person should be involved.

## The Cost of Asking

### Too Many Questions

It may feel safe to make the agent ask about everything.

But every question stops a person.

At night, nobody is there to answer. So the work stops too.

**Interruption budget** = the most questions the agent may ask in one run.

In this lesson, the budget is 6 questions.

The right zones ask only 5:

- 2 Ask first decisions
- 3 Human only decisions

Everything else goes ahead without a question.

Click the button and run it.

- Every decision becomes a question.
- The budget check fails.

Now compare the two specs side by side:

The right zones fit the budget. Asking about everything does not.

**Simple lesson:** too careful is as bad as too free. Ask only about the risky choices.

## Stop Rules

### When the Same Fix Keeps Failing

Agents do not give up easily.

When something fails, they try again. Then they try something else.

With no limit, this goes on until the budget is gone.

The result may be:

- No finished work
- No report
- Wasted time and money

A **stop rule** tells the agent when to stop trying.

Example:

```text
Stop after 3 failed attempts at the same fix, and report what you tried.
```

Now, the next morning, you get a report:

- What failed
- How many times it tried
- What it tried

That report helps a person fix the problem fast.

**Important:** keep the number small.

"Stop after 50 tries" does not help. By then, most of the budget is already gone.

### Lab Exercise: Sort Ten Decisions Into Zones

The tech lead sends you a note.

It says:

- Which decisions go in each zone
- When to stop if the build keeps failing

Write one line for each zone and one line for the stop rule. Then press **Check my spec**.

A correct spec:

- Asks before the Ask first decisions
- Hands the Human only decisions to a person
- Stays within the budget of 6 questions
- Stops after a few failed tries

You can list several decisions on one line. Put a semicolon between them:

`Human only: rename the public exportOrders function; delete the old CSV export; deploy to production.`

## Steer in the Spec, Block in the Tool

A spec line guides the agent. It does not physically stop it.

So for things that must never happen, also block them with a tool.

**Harness** = the tools and settings around the agent that allow or block actions.

Examples:

- Permission settings
- Approval rules
- Branch protection
- Hooks that block a command

The spec explains the rule. The harness makes sure it holds.

For example, "Human only: deploy to production" should also be blocked by a permission rule.

**Simple lesson:** if something must never happen, write it in the spec and block it in the tool.

To learn how blocking works, see [Hooks and Permissions](/learn/harness-engineering/foundations/hooks-and-permissions) in the Harness Engineering course.

## What Changes per Tool

| Tool | Decision rights in the spec | Hard enforcement |
|---|---|---|
| Claude Code | `docs/specs/<feature>/spec.md` | permissions and hooks |
| Codex | `docs/specs/<feature>/spec.md` | approval policies and sandbox settings |
| Cursor | `docs/specs/<feature>/spec.md` | approval settings and hooks |
| Spec Kit | constitution files | agent configuration |
| Kiro | steering files | Kiro agent settings |

The autonomy zones stay the same across tools. Only the enforcement mechanism changes.

## Common Mistakes

| Mistake | Wrong idea | Correct idea | What goes wrong |
|---|---|---|---|
| No decision rights | "It will ask when it is not sure." | Write the four zones. | It deploys to production at 3 a.m. |
| Asking about everything | "More questions are safer." | Ask only about Ask first and Human only. | Ten questions, and nothing is done by morning. |
| No stop rule | "It will figure it out." | Stop after 3 tries, with a report. | The whole budget goes on one bug. |
| A huge stop limit | "Stop after 50 tries is fine." | Keep the number small. | The budget is gone before it stops. |
| Only a spec line for "never" | "I wrote Human only, so it is safe." | Also block it with a permission or hook. | One bad run ignores the line. |
| Mixing up report and ask | "Reporting is the same as asking." | Report = decide, then tell. Ask = wait for a yes. | The agent waits for an answer nobody gives. |

## Exercises

These exercises help you practise decision rights.

Press **Check** when you are ready. Use **Show Hint** if you get stuck.

## What to Remember

- Decision rights = who decides what.
- An agent that works alone needs them most.
- There are four zones: Decide alone, Decide then report, Ask first, Human only.
- Ask only about risky choices.
- Too many questions stop the work.
- A stop rule ends a retry loop early, with a report.
- "Never" rules also need a tool that blocks them.

## Further Reading

- [Intent Engineering Framework for AI Agents, by Product Compass](https://www.productcompass.pm/p/intent-engineering-framework-for-ai-agents): a product manager's view of goals, limits and decision rights for agents.
- [Harness engineering, by OpenAI](https://openai.com/index/harness-engineering/): humans steer, agents execute, and checks enforce.
- [Effective harnesses for long-running agents, by Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents): keeping long agent runs on track.
- [Kiro steering](https://kiro.dev/docs/steering/): repo-wide rules for agents.

Next: **Non-Functional Requirements**. You will turn words like "fast" and "easy to use" into clear numbers the agent can check.