Writing Issues for Agentic AI
An agentic AI picks up an issue, reads the repository, writes the code, and opens a pull request on its own. It cannot tap you on the shoulder halfway through to ask what you meant, so the issue is the whole brief. This guide covers how to write issues an agent can finish correctly the first time, and ends with a template you can copy into your tracker.
Step 1: Lead with the Outcome
Title the issue with the result you want, not the activity. "Improve the contact form" invites the agent to guess what "improve" means; a title that names the end state tells it when it is done. Follow the title with one or two sentences describing what a user will see or be able to do once the issue is closed.
Vague:
Fix the guide page on mobileClear:
Guide code blocks scroll horizontally instead of overflowing the page below 480pxStep 2: Give the Context It Cannot Infer
The agent can read every file in the repository, but it cannot read your mind, your meetings, or your chat history. Write down what lives only in your head.
- Why the change matters: the bug report, the customer request, or the goal behind it. Knowing the purpose lets the agent make sensible calls on details you did not specify.
- Where to start: name the files, components, or pages involved, e.g.
assets/css/guide.css. This saves the agent from searching and keeps it from editing look-alike code elsewhere. - What you already know: steps to reproduce, error messages pasted verbatim, screenshots, and approaches that were tried and failed.
- Links to related issues, pull requests, or design references the work should match.
Step 3: Draw the Boundaries
Agents are eager to help, and an issue with no edges tends to grow: a fix to one page turns into a refactor of the whole stylesheet. State what is in scope and, just as importantly, what is out of scope.
A short "Non-goals" list ("Do not change the nav markup", "Leave the error pages alone") is often the single most effective line in an agentic issue.
Step 4: Write Checkable Acceptance Criteria
Acceptance criteria are the agent's definition of done. Write each one so that anyone, human or AI, could look at the result and answer yes or no. Avoid words like "better", "cleaner", or "nicer" unless you say what they mean.
- Describe observable behavior: "At 375px wide, no element extends past the right edge of the viewport."
- Cover the edge cases you care about: empty states, long text, keyboard navigation, JavaScript disabled.
- Keep each criterion small and independent, so a reviewer can tick them off one by one.
Step 5: Point to the Rules, Don't Repeat Them
Project-wide rules (coding style, architecture constraints, branching and pull request workflow) belong in files the agent reads every time, such as CLAUDE.md, AGENTS.md, or ARCHITECTURE.md. Keep them there, and use the issue only for what is specific to this task.
If an issue needs to break a standing rule, say so explicitly and explain why. Otherwise the agent will, correctly, follow the rule.
Step 6: Size It to One Pull Request
An issue should produce one pull request that a person can review in one sitting. If you find yourself writing "and also" more than once, split the issue. Smaller issues are easier for the agent to get right, easier for you to review, and cheaper to throw away if the approach turns out to be wrong.
Step 7: Say How to Verify It
Tell the agent how to prove the work is finished: the test command to run, the page to open and the width to check it at, or the output to expect. An agent that can verify its own work will catch most of its mistakes before you ever see them.
Example verification step for a static site:
python3 -m http.server 8000Then: "Open localhost:8000/guide/ at 375px, 768px, and 1280px wide and confirm every criterion above."
Step 8: Gate It with a Label and a Review
Not every issue is ready for an agent. Mark the ones that are with a dedicated label, such as agentic, and instruct the agent to work only on labeled issues. An agent treats issue text as instructions, so keep that label in the hands of maintainers.
- Apply the label only after the issue meets the checklist in this guide.
- Never put secrets, credentials, or customer data in an issue body.
- Have the agent open a pull request rather than merge, and review it as you would a teammate's.
- When the result misses, improve the issue (or the rules file) before re-running, so the next one lands.
Step 9: Use a Template
A template turns this guide into a habit. Copy the block below into a new issue, or save it as .github/ISSUE_TEMPLATE/agentic.md so it appears in GitHub's "New issue" picker.
## Goal
<!-- One or two sentences: what is true once this is done? -->
## Context
<!-- Why it matters, where to start (files/pages), what you already know. -->
## Scope
In scope:
-
Non-goals:
-
## Acceptance criteria
- [ ]
- [ ]
## How to verify
<!-- Commands to run, pages to open, widths or inputs to check. -->
## Notes
<!-- Exceptions to standing rules, links, screenshots. Never secrets. -->