One Rule in AGENTS.md to Surface Claude Code Action Items at the Top of Long Reports
A practical developer tip for Claude Code and Codex: add the 'Lead with what you need from me' rule to AGENTS.md to prevent critical user actions from getting b
AI developer Vox (@Voxyz_ai) shared a concise AGENTS.md rule on October 6, 2026, designed to solve a common friction point in autonomous coding agents like Claude Code and Codex: critical human action items getting buried inside walls of text after completing long tasks.
Image source: @Voxyz_ai (X)
When autonomous coding agents execute complex refactoring cycles, multi-step builds, or automated test debugging runs, they often produce extensive reports filled with command outputs, file diffs, and intermediate diagnostic traces. In this massive stream of prose, essential items that require immediate developer intervention—such as logging into an administrative dashboard, providing API credentials, or placing a newly exported CSV file—frequently get lost in the middle or bottom of the screen, creating unnecessary workflow delays while developers scroll through the response.
1. The 'Lead with What You Need from Me' Section in AGENTS.md
The proposed fix is to include the following self-contained section directly in your repository's root AGENTS.md file:
## 7. Lead with what you need from me
When a long task is done, or you're stuck and need me to do something, list what you need from me at the very top of your reply. One thing per item, numbered. Spell out what I should do, where, and what to send back to you when I'm done, e.g. "Log into Stripe, export the September refunds CSV, put it in inbox/". Whatever's blocking you most goes first. If you don't need anything from me, just say so.
This instruction establishes strict behavioral constraints on how the agent structures its handoff:
- Immediate top-of-reply reporting: Whenever an extensive task finishes or execution is blocked by a missing prerequisite, the agent must output required human actions at the very top before presenting its detailed summary.
- Single-action numbered items: Every discrete request must be formatted as its own numbered item, making the list easy to digest at a glance.
- Three essential action details: The agent must explicitly detail what the developer needs to do, where the action should take place, and what artifacts must be returned to the agent once completed (e.g., "Log into Stripe, export the September refunds CSV, put it in inbox/").
- Blockers take top priority: The item causing the greatest operational blockage must be placed first in the list.
- Explicit confirmation when unblocked: If the task completed smoothly and requires no human action, the agent must explicitly state that nothing is needed before delivering the rest of the report.
2. Integration with Core Agent Working Principles
This prompt addition serves as the seventh principle building upon an established six-part AGENTS.md framework:
- Plan before you touch code: Formulate and align on architectural plans prior to editing source files.
- Smallest change that works: Implement the minimal viable diff that satisfies requirements.
- Split work across subagents: Decompose complex workflows across isolated worker scopes.
- Own the bug: Take full end-to-end responsibility for reproducing and resolving defects.
- Verify before you say done: Rigorously test and validate changes before reporting completion.
- Write down every correction: Document edge cases and capture operator corrections.
- Lead with what you need from me: Surface required human actions upfront.
While the original six sections govern the internal execution and engineering discipline of the agent, the seventh rule streamlines the human-agent interaction boundary, cutting context-switching overhead when the agent hands control back to the operator.
3. Practical Considerations and Community Feedback
Developer discussions around the rule highlight several operational insights:
- Prioritizing blockers over cosmetic formatting: Community members noted that explicitly instructing the model that "whatever's blocking you most goes first" provides far greater practical value than generic output-formatting requests.
- Alignment with task understanding: If an agent lacks genuine understanding of an underlying failure, it may surface superficial requirements while the real architectural defect remains obscured in the logs below. High-quality task framing remains critical to ensure the surfaced blockers are meaningful.
- Multi-agent portability across Claude Code and Codex: Since Claude Code version 2.1.277 natively reads
AGENTS.md(or can import it via@AGENTS.mdwithinCLAUDE.md), maintaining this rule inAGENTS.mdallows teams to enforce consistent reporting standards across Claude Code, Codex, and other coding harnesses from a single source of truth.