How to write an effective agent role for Codex

An agent role should own a coherent piece of work that can be reviewed independently: research current documentation, inspect a defined code path, evaluate a skill, or verify a set of routes. Describe the intended result rather than a personality or vague expertise label.

Keep the scope bounded enough that the role can finish without rediscovering the whole project. Include relevant project instructions and preserve the authorization limits of the original task.

List the minimum raw inputs the role needs and the observations that support its conclusion. A documentation researcher needs primary pages and check dates. A code reviewer needs the diff, repository guidance, and affected runtime path. A visual reviewer needs rendered pages at representative widths.

Do not send the intended answer or a suspected finding to an independent evaluator unless the task genuinely requires it. That avoids steering the review toward the conclusion you hope to receive.

State which tools are relevant and which external changes require separate approval. Read-only inspection can usually proceed independently; publishing, sending messages, merging, or changing another system must remain within the user’s authorization.

A role description does not grant account access. Connected tools still apply their own authentication, permissions, and approval policies.

Specify the shape of the handoff: findings with evidence, a structured brief, a patch plus validation, or a decision memo with unresolved questions. Ask for concise source links and file locations when they help the next person inspect the result.

Avoid rigid headings when the task is exploratory. Require the information that changes the decision, not ornamental structure.

A role is complete when its bounded objective is met and the evidence is available. It is blocked when a concrete missing input or permission prevents meaningful progress. It should not expand into implementation merely because the research revealed an opportunity unless the original task authorizes that change.

A practical sequence might use one role to research official documentation, one to implement a focused change, and one to independently evaluate the result. Use parallel roles only when the tasks are independent and the shared workspace will not create conflicting edits.

• Write better repository instructions
• Create a project brief
• Use the change handoff skill

A useful agent role owns a distinct decision or artifact. Examples include gathering primary sources, reproducing a failure, checking a patch, or validating a rendered page. Labels such as researcher or reviewer add little unless they also define inputs, boundaries, evidence, and a completion condition.

Keep the handoff small. The next stage should receive the artifact, decisive observations, and unresolved questions, not a transcript of every action. When one agent can complete a tightly coupled task with less coordination risk, a multi-role design adds ceremony without improving the result.

• Build a clearer AGENTS.md
• Open the workflow handbook

Test the playbook with a bounded task whose correct result can be observed. Confirm that each role receives enough context, stays within its permission boundary, and produces the promised output. Check that later stages use the actual artifact rather than relying on an earlier summary.

Failures often appear at handoffs: a researcher omits the source date, an implementer works from an outdated brief, or a verifier repeats the implementation claim without rerunning the behavior. Design the output contract around those risks and keep a human decision point for irreversible or externally visible actions.