Chapter 1. Defining tasks and instructing agents

Learning objectives

• Rewrite a vague feature request as a task with an observable definition of done.
• Split a large feature into small tasks that can each be run, verified and reverted.
• Decide whether to get a plan first or delegate directly, based on uncertainty and the extent of the impact.
• Review an agent's plan, remove unnecessary steps and adjust its scope.
• Distinguish what belongs in repository instruction files (AGENTS.md, CLAUDE.md, GEMINI.md) from what belongs in other mechanisms.

Introduction

One Friday evening, a solo founder asked a coding agent to "make sign-up smoother" and went out for dinner. On returning, the founder found a report saying "Task complete" and changes to the form design, password rules and package list. With no criteria for judging what had improved or broken, the founder eventually reverted everything.

This was not a failure of the agent's ability. The agent worked diligently within the instructions it received and stopped when the result looked done. The instructions had never defined where the work ended, what it could touch or how it should prove the result.

This chapter covers the skill of delegating work. You first learn about definitions of done and the structure of a good task instruction, then how to split large features into smaller tasks and follow existing code patterns. You then learn when to get a plan first, how to review it and how to put repeated instructions in repository files. Going deeper covers features whose business rules are undecided and work that runs without human supervision.

Key concepts

What it means to delegate work

Even when a coding agent does the work, a person remains responsible for the result. The person giving instructions has four responsibilities.

1. Define the goal: decide what to build, why and where the task ends.
2. Review the plan: check whether the approach fits the goal and scope.
3. Check the result: judge by evidence rather than a report (Chapter 2).
4. Decide whether to release it: record changes (Chapter 3), check risks (Chapter 4) and decide whether to put them in front of users (Chapter 5).

Claude Code's best practices explain this relationship simply: an agent stops when work looks done; if it has no checks to run on its own, appearances are its only signal. A person then has to become the verifier and find every mistake. If you tell an interior designer only "Make the living room look nice," you have no grounds to question a result you dislike. If you say "White walls, two warm-colored lights, keep the existing built-in closet," you can check each item when the work is done.

Definition of done: deciding where "finished" is in advance

A definition of done is a set of conditions written in advance so that anyone checking the work reaches the same conclusion about whether it is finished. A good definition of done can be judged true or false by looking at a screen or running a command. Adjectives such as "better," "cleaner" and "faster" mean different things to different people and cannot serve as completion criteria on their own.

Writing completion criteria in two categories helps reduce omissions. Functional criteria state what must work ("Pressing 4 stars shows only reviews with a rating of 4"). Quality criteria state the conditions the implementation must meet ("All existing tests pass," "Do not add any new packages," "The layout does not break even on a narrow screen").

Claude Code's best practices recommend giving completion criteria as checks the agent can run. Provide a few example inputs and expected results and say "Run the tests after implementing this," and the agent can keep fixing until the checks pass.

Four elements of a good task instruction

A good task instruction usually contains four elements. Think of it as a small contract.

1. Goal: what you are building and what the user will be able to do.
2. Definition of done: what must be confirmed for the task to count as finished.
3. Scope and limits: how far the agent may go and what it must not touch.
4. Verification method: which commands or checks prove completion and what evidence to show.

Goal: Add a filter to the order history screen to show only orders that are 'In transit'.
Definition of done:
- Selecting 'In transit' shows only orders with that status.
- Selecting 'All' restores the original list.
- Add tests for both cases, and all tests run by npm test pass.
Scope and limits:
- Change only files inside src/pages/orders/.
- Do not change the order data structure or payment code. Do not install new packages.
Verification method:
- Show the test commands run, their complete output and a screenshot at 360px width.

An instruction can be short if it contains all four elements. Conversely, ten lines of adjectives still leave you unable to judge a result without completion criteria and scope.

Define states beyond the ideal screen

When describing a feature, people usually imagine one screen where everything has gone well. A real app passes through several states before reaching that screen. Unless the instructions specify those states, the agent will decide for itself or omit them altogether.

To find all the states, first map the user flow. Write the sequence of where users enter, what they click and where they finish. At each step ask, "What if there is no data? What if it is slow? What if it fails? What if the user leaves partway through?" The answers become completion criteria.

Breaking work down: vertical slices

The bigger the job you delegate, the more files change, the harder the review and the harder it is to identify which change caused a problem. Split large features into small tasks. The direction of the split matters.

Think of a cake. Separate it into layers—sponge, cream and fruit—and nobody can taste a complete piece until all the layers are ready. Cut it vertically and each slice contains every layer, so the first slice is ready to taste. Tasks work the same way.

Each vertical slice can be run, verified and reverted independently. Judge its size with two questions: can you describe the change in one sentence, and can you finish reviewing it in one sitting? Just as you label each moving box with its contents, "one task = one purpose" makes checking and reverting easier.

Anthropic's experiments with long-running agents also found it crucial to assign just one feature per session and commit each feature so that a problem could be undone by returning to an earlier state.

Point to an existing pattern

An agent knows several ways to build the same feature. If the instructions say nothing about which to use, it chooses one of those approaches, which may differ from the way this repository works. When error formats, methods of validating input and component structures vary from one file to the next, the app gradually becomes harder to modify.

The solution is to point directly to an example the agent should follow. Claude Code's best practices also recommend identifying an existing file as a good example, instructing the agent to follow its approach and setting a limit that prohibits libraries other than those already in use. This is more effective than a lengthy explanation because the agent takes the actual code in this repository as its reference.

First read how src/api/products.ts validates input and returns errors.
Build a coupon lookup API in src/api/coupons.ts using the same pattern.
Use only packages already in package.json.

Getting a plan first

When adding a feature that involves several files in code you are seeing for the first time, it is safer to ask the agent for a plan before letting it immediately start writing code. At the planning stage, you can check and adjust in advance which files will change, the order of the work and the areas that must not be touched. Revising a plan costs far less than undoing code changes.

Claude Code's best practices recommend four stages: explore, plan, implement and commit. Exploration and planning happen in plan mode, which reads files and gathers context using read-only commands without modifying source files. Press Shift+Tab until the status bar shows plan mode, or start a session with claude --permission-mode plan. Use Ctrl+G to edit the proposed plan directly in a text editor before proceeding. Approving the plan or changing modes again with Shift+Tab moves on to implementation.

Other tools offer similar controls. Gemini CLI accepts plan for --approval-mode. With a tool that lacks plan mode, you can ask "Only make a plan first; do not edit files," but those words do not change permissions and therefore do not actually prevent editing. Use plan mode or read-only permissions when editing must be blocked.

Five questions for reviewing a plan

A plausible list of steps is not necessarily a good plan. Ask these five questions in order.

1. Does it connect to a requirement? Can you match every step to a requirement? An unmatched step is likely outside the scope.
2. Does it exceed the scope? Does it touch forbidden files or include unrelated cleanup such as "tidy the shared components while we are here"?
3. Is anything difficult to undo? Are there steps that modify existing data in bulk, change the database structure or send emails outside the organization? If there are, separate those particular steps from the rest and review them.
4. Is verification included? Does the end of the plan say which checks will confirm what?
5. Is it the right size? Is the plan too large for a small request? Does it hide major unrequested decisions such as adding a library or reorganizing folders?

Give the agent specific feedback on the review. Include both the step number and your reason, as in "Remove step 3. We are not changing existing member data" or "Add a step for writing tests before step 5." This lets the agent revise the plan accurately.

Repository instruction files: how each tool reads them

A repository is a folder containing a project's files and change history. An instruction file in the repository is a guidance memo that the agent reads at the start of a session, saving the team from repeating itself. It is like the work handbook given to a new employee.

Teams that use several tools together often want to manage their instructions in a single file. Claude Code's documentation explains that if both CLAUDE.md and AGENTS.md exist, it reads only CLAUDE.md by default. To share a single file, it advises writing @AGENTS.md at the very top of CLAUDE.md to import it. You can also choose a value in your personal settings (claude-md-and-agents-md) that makes it read both files. @path is Claude Code's syntax for importing a file, and Gemini CLI also supports @file imports inside GEMINI.md. In Codex, you can use project_doc_fallback_filenames in ~/.codex/config.toml to make it recognize instruction files with other names.

@AGENTS.md

## Claude Code only
- Before changing anything under src/billing/, show a plan in plan mode.

You can verify whether the instructions were actually read. In Claude Code, use /context to see which files were loaded; Gemini CLI uses /memory show to display their combined content. Codex's documentation describes a way to check the order in which the instructions were read by asking the agent to summarize them.

What belongs in an instruction file

Use one rule: include only things that cannot be learned by reading the code but cause mistakes if the agent does not know them. Claude Code's best practices suggest asking of each line, "Would removing this cause a mistake?" If not, remove it. Long instructions can obscure the rules that matter and lead to them being ignored.

Manage length too. Claude Code's documentation recommends keeping a single CLAUDE.md below 200 lines. Move longer material elsewhere according to its purpose.

@path imports help organize long files, but imported files also load at session start, so imports do not reduce the amount of content. To create your first instruction file, start with a draft-generation command such as Claude Code's /init, which analyzes the codebase to draft instructions or suggests improvements if instructions already exist. A person then adds information that cannot be learned from the code.

Going deeper

Features without settled rules: interviews and specifications

Sometimes you cannot write completion criteria because business rules remain undecided: how long a waitlisted customer gets priority when a booking opens, or whether to move to the next person if they do not respond. If you ask the agent to implement immediately, it fills the gaps with plausible guesses that spread throughout the code.

Claude Code's best practices recommend having the agent interview the person first for larger features. Give a brief description and ask it to use AskUserQuestion for detailed questions. Skip obvious questions and explore difficult issues the person may not have considered: implementation, screens, edge cases, concerns and trade-offs. Once the questions are answered, have it write the result to a specification such as SPEC.md.

A good specification is self-contained. It names relevant files and interfaces, states exclusions and ends with an end-to-end check proving the whole feature works. Once it is ready, start implementation in a new session. This gives the agent clean context based on the specification alone, without the long interview conversation. The documentation also says time refining a specification is more valuable than time supervising implementation.

Interviews reveal human blind spots too. Questions such as "What if two people accept almost simultaneously?" and "What if the lesson is canceled during the priority period?" expose cases the operator missed. A person still decides the rules.

Context as a budget

Everything an agent refers to in one conversation—messages, files read and command output—is called context. Context is limited. Claude Code's documentation calls it the most important resource to manage, warning that as it fills up, agents may forget earlier instructions or make more mistakes.

Keep instruction files short, because they load with every session, and clear the context with /clear between unrelated tasks. The most common waste is a mixed-purpose session: you interrupt one task to ask an unrelated question and then return to the original work. Delegate investigations that scan dozens of files to a subagent. A subagent reads the files in its own separate context and returns only a summary, preserving the context of the conversation where implementation is taking place.

Unattended execution

For overnight work, bulk changes across hundreds of files or work delegated to a cloud agent, nobody is available to answer questions partway through. Instructions must be especially complete.

Order matters for bulk work. Claude Code's best practices suggest first writing the target list to a file, then creating a script that calls non-interactive execution (claude -p "instructions") for each target. Try two or three before running the full batch, and adjust the instructions to address problems found. Pre-allow the necessary tools with --allowedTools, and use --permission-mode dontAsk so calls that would normally ask for approval are denied without asking. Actions requiring no approval, such as reading files within the working folder, still run. Limit turns with --max-turns so a run stuck on one target stops. Catching mistakes in a small trial prevents repeating them across every target.

Cloud agents follow the same principle. Codex's cloud environment settings include dependency setup scripts, environment variables and secrets, and controls for internet access and allowed domains. Prepare what tests need while granting only the necessary access.

At work

Alley Books: after reverting eleven files

Yunseo, who owns a neighborhood bookshop called "Alley Books," wanted a star-rating filter for the reader review board. Initially, "Improve the review page a bit" led the agent to change eleven files, covering design, sorting and even the review form. Unable to judge what was correct, Yunseo reverted everything.

The second time, she rewrote the task with all four elements.

1. Goal: put star-rating (1–5) filter buttons above the review list.
2. Definition of done: pressing 4 stars shows only 4-star reviews; pressing "All" shows all reviews. When no reviews have the selected rating, show "No reviews with this rating yet." Add tests for all three cases; npm test must pass.
3. Scope and limits: change only the review list screen. Do not change the review form or database structure.
4. Verification: show test output and browser screenshots.

Yunseo initially missed the empty state but added it when mapping the user flow. Some customers would press 2 stars; without any 2-star reviews, they would otherwise see a blank screen.

Because several files seemed likely to change, she first requested a plan in plan mode. It included "Add a star-rating index to the reviews table." Yunseo reviewed it with the five questions. The step matched no requirement (question 1), touched the forbidden database scope (question 2), and was unnecessary with only about 200 reviews that could be filtered on screen (question 5). She removed the step and chose filtering on screen.

The agent showed test output and screenshots. Yunseo clicked through the app herself before accepting it. The difference between attempts was the instruction structure, not the agent's ability. Completion criteria defined the stopping point, and scope filtered out an unnecessary plan step.

Wave Sound Surf School: slicing a large feature vertically

Doyun, who runs the lesson-booking app for "Wave Sound Surf School," wanted a feature that notified customers and handled refunds when dangerous waves canceled a lesson. It spanned the admin screen, booking data, text messages and payment refunds.

Doyun initially considered three approaches.

• Delegate everything at once: one instruction seemed sufficient, but more than twenty files would change. A wrong refund would be difficult to trace to a particular change. Rejected.
• Split by layer: delegate data structures, server and screen in sequence. Nothing would work until all three were finished, preventing intermediate checks. Rejected.
• Slice vertically: split into results that users could use. Selected.

First, Doyun realized the rules were incomplete. He had not decided whether cancellation two hours before a lesson meant a full refund or whether customers could select an alternative lesson. He asked the agent to interview him, answered questions such as "Do customers who already chose a replacement lesson still receive the text?" and recorded the decisions in SPEC.md.

He then split the feature into three tasks.

1. When an administrator marks a lesson "Canceled due to weather," show that status in the customer booking list. No texts or refunds yet.
2. Send each customer one notification text when weather cancels a lesson. Tests record messages instead of sending them.
3. When a customer selects "Refund" through the notification link, request payment cancellation and change the booking status to "Refund complete."

He delegated each task in a new session using SPEC.md. Only the third task, which touched payments, needed a plan in plan mode. He removed an out-of-scope step to "tidy shared error handling in the payment module." Administrators could use the cancellation indicator from the day task one finished. When task three revealed a refund calculation error, the preceding tasks were already verified, so only task three's changes needed investigation.

Common mistakes

1. "The longer and more detailed the instruction, the better." It is easy to feel that length makes an instruction accurate. But even ten lines of adjectives give you no way to judge the result if there are no conditions you can check. A shorter instruction is better when its completion criteria, scope and verification method are clear.
2. "If it is in the instruction file, the agent will always follow it." A rule written in a file looks like a rule that will be obeyed. However, instructions are only reference material for the agent's decisions, so it may overlook lines when the content is long or inconsistent. Use enforcement mechanisms such as permission rules or hooks for behavior that must be blocked.
3. "Being careful means getting a plan for every task." Caution is a virtue, but planning is effective for work that is large and uncertain. Asking for a plan even for a change you can describe in one sentence merely consumes time.
4. "Assigning more at once is efficient because it reduces round trips." This seems true if you count only the instructions given. But increased review and reversal costs exceed the saved round trips. A problem may require discarding the whole batch.
5. "The standard way to split a feature is into data, server and screen tasks, in that order." Splitting work along the technical structure may look tidy. However, you cannot check how it works until the final layer is complete. Divide the work vertically into things a user can actually do.
6. "The agent made a plan, so I can trust the plan." A plausible list of steps can be persuasive. However, it may include cleanup that was never requested, data changes that are difficult to undo or missing verification steps. Use the five questions to review it before approving.

Summary at a glance

Check the official docs

• Claude Code: Best practices — giving the agent a means of verification, the explore→plan→implement→commit sequence, when to skip planning, interviews and specifications, and executing work in bulk
• Claude Code: How Claude remembers your project — where CLAUDE.md files are located and the order in which they are loaded, @ imports, .claude/rules/, and how AGENTS.md is handled
• Claude Code: Skills — skill file locations and disable-model-invocation
• Codex: Custom instructions with AGENTS.md — AGENTS.md discovery order, size limits, alternative file names
• Gemini CLI: GEMINI.md — instruction file hierarchy, @ imports, /memory, context.fileName
• Anthropic: Effective harnesses for long-running agents — assigning one feature at a time and keeping a record of progress

Self-check

1-1. Consider two requests: (a) "Make the notification settings screen easier to use" and (b) "Turning notifications off prevents the next morning's summary email, and the setting remains off after refreshing the settings screen." Which has a definition of done? How would you rewrite the other?

1-2. You are delegating a list screen showing customers' past bookings. Name four states to specify beyond the screen where everything goes well, and write one completion criterion for each.

1-3. Add a "Group booking inquiry" feature to a workshop booking app. It needs an inquiry form, an administrator view and an acknowledgment email. Divide it into three vertical slices, each with one completion criterion.

1-4. You want to edit the wording of one step in a plan received in Claude Code's plan mode before proceeding. Which key combination do you use? Also give one example of a task that can be delegated directly without plan mode.

1-5. A plan for adding a "Notify me when back in stock" button to a product detail screen contains: ① add a request button and confirmation text ② add an API to save requests ③ tidy the colors and spacing of button components throughout the app ④ report completion. Using the five questions, identify its problems and give specific revision instructions.

1-6. A repository contains only the team's AGENTS.md, which Claude Code has been reading successfully. One member creates CLAUDE.local.md at the root with personal notes, after which only that member's sessions stop following team rules. Explain why and how to resolve it.

1-7. A team decides to manage its agent instructions in one TEAM_GUIDE.md. Which settings make Codex and Gemini CLI read it as their instruction file?

Hands-on tasks