Agiled Docs

Instructions tell the worker what to do every time it runs.

Clear instructions make worker output easier to review and make tool access safer.

Good Instructions Include

The worker's role.
The type of records it should review.
The output format.
What it should avoid.
When it should ask for human review.
Which details matter most.

Good instructions also say what the worker should not do. If the worker should never email customers, update records, use old notes, or make pricing promises, write that limit directly.

Include the evidence the worker should use. For example, tell it to rely on the current task description, linked project, latest customer message, or invoice balance instead of general workspace context.

Example Structure

Review the task and related project context.
Summarize the current blocker in 3-5 bullets.
List missing information separately.
Do not change records.
Write the final output as a task comment for the assignee.

Keep Scope Narrow

Do not ask a worker to perform broad, vague work such as "handle all customer operations." Narrow instructions make output easier to review and reduce tool access risk.

Give the worker one job. If you need analysis, customer messaging, and record updates, split those responsibilities or require human review before write actions.

Add Review Boundaries

Tell the worker when to stop. Examples:

stop if customer identity is unclear
stop if the invoice balance does not match the request
stop if required project context is missing
stop if a reply would include legal, billing, or security commitments

Clear stop rules are more reliable than broad instructions such as "be careful."

For customer, finance, legal, security, or HRM topics, require human review before any output is reused outside the team.

Review Before Activation

Before setting a worker active, read the instructions alongside the selected context sources and tools. The three should match the same job.

Run the worker on one safe record first. Review whether it used the right context, ignored unrelated records, followed the requested format, and avoided actions it should not take.

Improve Bad Output

If output is vague, add the exact fields, time period, record type, and response format. If output is too broad, remove context sources or tools before making the instruction longer.

If output uses the wrong tone, add a short example response. If output misses important facts, add the specific context source instead of telling the worker to "look harder."

If output is overconfident, add stop rules and ask the worker to list missing information separately. This makes uncertainty visible to the reviewer.

Useful Output Formats

Common formats include summary plus risks, checklist plus missing information, customer-ready draft plus internal notes, or recommendation plus evidence. Pick one format so reviewers know where to look every time.

Instruction Review Checklist

Before saving:

remove vague verbs such as handle, manage, or fix unless the action is defined
state which record type and status the worker should consider
define the output format
say what information should be ignored
say when the worker should stop and ask for review
confirm write tools are necessary before allowing them

Keep the instruction short enough that a teammate can review it. If it needs a long policy, link the worker to a knowledge source and keep the run instruction focused on the job.

Write Worker Instructions