Write effective tasks

A good task tells the Agent four things: what result to produce, where it may act, what it must not do, and how to prove completion.

Recommended structure

Objective: Describe the final result in one sentence.

Background: Provide only the context that affects decisions.

Scope: Specify the directories, modules, files, or data that may be inspected or modified.

Constraints: List prohibited actions, compatibility requirements, and security requirements.

Acceptance criteria: Define behavior or output the user can observe.

Verification: Specify the smallest tests to run, sources to cite, or files to deliver.

For example:

Objective: Fix the Settings search so clearing the query no longer leaves a filtered result.

Scope: Modify only Settings navigation and the corresponding tests.
Constraints: Do not install dependencies, refactor the search algorithm, or change the design system.
Acceptance criteria: Selecting Clear or pressing Escape shows all settings and leaves focus in the input.
Verification: Run the smallest relevant tests and provide the final diff and anything not verified.

Inspect the current state and propose a plan first. Make changes only after confirming the scope.

Replace adjectives with evidence

Words such as “good,” “comprehensive,” and “professional” are difficult to verify. Replace them with statements such as:

• “Analyze comprehensively” → “Cover entry points, data flow, error paths, and tests, and cite key files.”
• “Write professionally” → “Write for a new user, put steps before reasons, and define each term on first use.”
• “Guarantee correctness” → “Run the specified tests and distinguish verified from unverified claims.”
• “Find the latest information” → “Verify publication dates, use the specified cutoff date, and prefer official sources.”

Separate investigation from modification

For a high-risk task, have the Agent perform a read-only investigation before approving implementation:

1. Confirm the current state and affected surface.
2. Propose a small plan.
3. Make the change.
4. Run validation.
5. Self-review against the actual diff.

This lets you correct direction while the cost is still low.

Do not overspecify implementation

If the result matters more than the implementation, describe the interface and acceptance criteria. If a specific implementation is a hard constraint, state it explicitly. Locking down every detail in advance may prevent the Agent from following patterns that already exist in the repository.

Define failure behavior

You can state in advance that the Agent must:

• stop and list gaps when evidence cannot be found;
• explain the reason before expanding directory access or permissions;
• verify an unknown external outcome instead of retrying automatically;
• distinguish existing failures from regressions introduced by the task;
• never substitute a written claim for file or test evidence.

When to split work into several tasks

Split a task when it includes several independent deliverables, requires different permissions, produces a large amount of context, or contains an important decision point partway through. Independent investigations can use Multi-Agent; dependent implementation should proceed sequentially by milestone.

For a larger-scale organization method, read Manage large projects.