A useful AI coding-agent task names the outcome, relevant starting context, exact targets, constraints, authority, success criteria, and evidence to report. It also states what should remain unchanged and what ambiguity should stop the work.
The task does not need to prescribe every keystroke. It needs a boundary strong enough for you to decide whether the result belongs.
Why vague requests expand risk
Consider this request:
Clean up this project and improve the README.
The agent must infer what “clean up” means. It might reformat code, update dependencies, delete files, rewrite documentation, change repository settings, or make a commit. Even a technically competent result may solve a different problem than the one the student intended.
A bounded task turns those hidden choices into visible decisions.
Write six parts
1. Outcome
State the observable result, not the activity:
Add the verified test command to the Testing section of README.md so a new
reader can run the existing test suite.
“Improve documentation” is an activity category. “Add the verified test command to a named section” is an outcome.
If the project itself lacks completion criteria, begin with Define “Done” Before You Start.
2. Relevant starting context
Provide only facts that change the task:
The repository contains README.md and an existing tests/ directory. The current
test command is documented in pyproject.toml and should be verified locally.
Do not paste the whole repository description into every prompt. Durable project facts, supported commands, and conventions belong in maintained documentation or AGENTS.md.
3. Exact scope
Name the target and expected unchanged state:
Allowed change: README.md only.
Expected unchanged: source code, tests, dependencies, configuration, assets,
repository settings, and Git history.
The unchanged list matters when nearby files would be easy to modify but are not part of the request.
4. Constraints
Record conditions that determine an acceptable result:
Preserve the existing README structure and tone. Do not invent a command.
Use the repository's current test configuration and report if it is ambiguous.
Do not add a dependency or create generated output inside the repository.
Constraints should come from the assignment, repository, platform, or real user need. Avoid a long list of preferences that do not affect acceptance.
5. Authority and stop conditions
Tell the agent which safe actions are authorized and which actions require a pause:
You may inspect repository files, run the existing focused test command, edit
README.md, and inspect the final diff.
Do not commit, push, deploy, change accounts, install software, delete files,
or modify another file. Stop and report if the test command is missing, requires
a new dependency, or changes persistent data.
Official OpenAI model guidance recommends providing domain context, hard constraints, approval boundaries, and success criteria, and defining which actions require confirmation. That guidance describes current OpenAI models; other agents and interfaces may expose different controls.
A prompt is not an enforcement mechanism. Use the selected surface’s sandbox, permissions, checkpoints, and review features where available.
6. Success evidence
Name what the final report must prove:
Success means:
- README.md contains the verified command in the Testing section.
- The command completes successfully in the current environment.
- The final diff changes README.md only.
Report the command and result, summarize the diff, and name any limitation or
unresolved condition. Do not claim checks you did not run.
This makes the report testable. “Done” without a command result or diff is not enough evidence for this task.
Put the parts together
Goal
Add the verified test command to the Testing section of README.md so a new
reader can run the existing test suite.
Context
The repository contains README.md and tests/. The current test command should
be derived from and checked against the existing project configuration.
Scope
Edit README.md only. Keep source code, tests, dependencies, configuration,
assets, repository settings, and Git history unchanged.
Constraints
Preserve the existing structure and tone. Do not invent a command or add a
dependency. Report ambiguity instead of choosing silently.
Authority
You may inspect files, run the existing focused test command, edit README.md,
and inspect the final diff. Do not commit, push, deploy, install software,
delete files, or modify another file. Stop if the command is absent, unsafe,
or requires broader changes.
Success and report
Verify that the command completes in the current environment and that the diff
changes README.md only. Report the command result, diff summary, limitations,
and unresolved work. Do not claim checks you did not run.
This task is longer than “improve the README,” but each sentence changes the acceptance decision. Remove a sentence only when its boundary exists reliably elsewhere.
Ask for inspection before change
An agent should establish the starting state before editing. For this example, it should locate the README, inspect the current Testing section, find the project configuration, identify the existing test command, and check the working tree for unrelated changes.
This follows the general inspect–change–verify workflow. Inspection can reveal a material ambiguity: perhaps two test commands exist for different environments. The right response is to report that distinction, not choose whichever command looks familiar.
Review the result against the contract
After the agent finishes:
- Read the final diff yourself.
- Confirm that only allowed targets changed.
- Match each changed line to the stated outcome.
- Inspect the actual validation output.
- Check that prohibited actions did not occur.
- Decide to accept, revise, reverse, or investigate.
If generated code is part of a different task, use the full AI-generated code review before acceptance.
Common mistakes
- Writing a broad role instead of a result. “Act as a senior engineer” does not define what should change.
- Naming targets but not unchanged state. Nearby files remain easy to alter.
- Saying “ask before anything.” Name the safe local work that is already authorized and the material actions that require confirmation.
- Moving durable facts into every prompt. Maintain repository guidance once.
- Listing tests without acceptance criteria. Explain what each check establishes.
- Treating the final report as proof. Inspect the diff and command output.
- Implicitly authorizing Git or external actions. State commit, push, deployment, and account boundaries directly when they matter.
Do this now
Rewrite one vague request using the six-part task contract. Use a disposable or low-risk project and require a one-file expected diff. Run the task only after you can explain what must remain unchanged.
Log what you learned
The task contract and final diff form the learning record. Add the validation result and your accept, revise, reverse, or investigate decision. If the same repository facts keep appearing in later tasks, move those durable facts into AGENTS.md rather than making each prompt longer.