The basics / Develop with agents
中文

Develop with agents

Frame the problem. Let the agent investigate, recommend and prove the result.

Updated 2 Nov 2026View as markdown
On this page

Give the outcome, not the fix

  • Supply the outcome, constraints, repository instructions and relevant examples; let the agent find the code and recommend one sound approach.
  • For anything beyond a small, clear edit, ask for a plan first, agree it, then let the agent implement. Correcting a plan costs one message; correcting code costs a rework.

Scenario: a profile photo uploads successfully, but reopening the mobile app shows the old one.

Bad prompt
Clear the image cache in the profile screen after upload and reload it on every app launch. That should stop the old photo coming back.
Better prompt
After a successful upload, reopening app [version] shows the old profile photo. Reproduction steps and a synthetic account: [details]. Trace one upload and the next read: the stored image version, the profile's saved reference, what the image service returns and the app's cache key. Find where they first differ, report the evidence, and propose a check that separates a stale display from a failed save. Do not edit code or purge caches.

Why: a successful upload doesn’t prove the profile points to the new image, and clearing caches first erases the evidence. See Understand the ticket.

Scenario: the approved English label on the order-export button changes from “Download” to “Export CSV”.

Bad prompt
Replace every Download string in the app with Export CSV so the wording is consistent.
Better prompt
Change the English order-export button label from Download to Export CSV. Check the rendered button and accessible name, and report the diff and check result. Leave unrelated download labels alone; do not commit or push yet.

Why: the bad prompt turns a one-button change into a sweep of every “Download” string. For a small, clear change, name exactly what changes and the check that proves it, and implement directly; no plan is needed. See Implement the change.

Keep the change to its ticket

  • Agents fix what they notice. Ask for the ticket’s change only, and have the agent list other problems in the PR description; you ticket each one.

Scenario: while implementing ENG-123, you notice the order-export code is messy.

Bad prompt
Implement the CSV export, and while you're at it, refactor the order-export module and rename its helpers so it's cleaner.
Better prompt
Implement the CSV export for ENG-123 only. Note the refactoring you'd recommend in the PR description as a follow-up, with the reason. Don't change unrelated code. Report the diff and the checks you ran.

Why: a PR that mixes a feature and a refactor is harder to review and to roll back. Keep the PR to one purpose.

Ask for evidence before accepting the result

  • Check output, tests or the running flow against the agreed outcome. “Done” and “all tests pass” are claims; ask for the commands and their output.
  • Correct drift early by naming the mismatch.
  • When the agent keeps getting something wrong, don’t fix the code by hand. Add the missing context, sharpen the instruction or write a failing test, then let the agent correct it. A hand edit hides the cause, and the agent repeats the mistake next time; a recurring one belongs in a regression check or the repository’s instructions.
  • Independent review and human approval happen in Code review.

Scenario: the agent has tried four fixes for a failing test, and each one breaks something else.

Bad prompt
Still failing. Try again.
Better prompt
Stop editing. List what you've tried, what each attempt showed, your current hypothesis and the one check that would confirm or rule it out. Don't change code until we agree the next step.

Why: another attempt without new evidence repeats the same guess. Naming a hypothesis and a check turns guessing back into investigation.

Follow one session, start to finish

ExampleENG-123 · One session, start to finish
  1. You send the Deliver a change opening prompt with ENG-123.
    The agent reads the ticket and proposes a plan: an export job that takes merchant_id from the request and reuses the list filters.
    Check: the merchant must come from the signed-in user, or anyone can request another merchant’s orders.
  2. You reply: “Take the merchant from the signed-in user, not the request. Otherwise the plan is agreed; implement it with tests.”
    The agent implements it and reports that all tests pass.
    Check: nothing yet. A pass is a claim, not evidence.
  3. You send the verify prompt.
    The agent reports evidence for each acceptance criterion, and one failure: an empty result returns an error instead of headers only.
    Check: each item names a command, its output and the commit.
  4. You reply: “Fix the empty case, and show the new test failing before the fix and passing after.”
    The agent shows both runs.
    Check: read the diff yourself; you will have to explain it in review.
  5. You ask the agent to check its diff for unexpected files and open the PR with the description template.
    Check: the description gives the why, the evidence and the remaining gap.

Review still matters: in Code review, a fresh session finds a gap this one missed.

Decide what the agent may do without asking

  • Let it read, search, run tests and edit files in the repository freely. Require your approval for anything that reaches outside it: pushing, deploying, writing to a shared or production database, sending messages, installing tools.
  • Don’t switch to approving everything to save time. The approval prompt is your last chance to stop a command aimed at the wrong place; see Access, secrets and data.

Keep each session focused

  • Continue the conversation for the same outcome; start a new one for unrelated work.
  • Before a handoff, have the agent save the ticket, branch, decisions, changed files, checks and next action. The next agent confirms them against the repository.
  • Give parallel agents distinct tasks and files, in separate worktrees, then verify the combined result. Separate chats do not isolate files.

Run a skill by name

  • A skill is a saved procedure the agent follows for a recurring task, so the steps don’t have to be rewritten in every prompt.
  • The handbook uses five: project-discovery when you start on a project, pr-review in code review, release-check before a deploy, release-closeout after each release, and ssat-review before go-live or a major release.
  • Install them once, for yourself, so they work in any repository, client ones included. Paste this into Claude Code or Codex; install and update has the commands if you’d rather run them yourself.
Prompt
Install Neutron's agent skills from the public GitHub repository neutronsg/neutron-agent-skills, for my user only.
- If you are Claude Code, run: claude plugin marketplace add neutronsg/neutron-agent-skills, then: claude plugin install neutron@neutron
- If you are Codex, run: codex plugin marketplace add neutronsg/neutron-agent-skills, then: codex plugin add neutron@neutron
If Claude Code's marketplace step fails because there is no GitHub SSH key, set CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 for that command and retry.
Then list the installed plugins to confirm neutron is there, and tell me how to load it (a new session, or /reload-plugins in Claude Code).
Don't change any other settings.
  • Start it by typing its name before your request: /project-discovery in Claude Code, $neutron:project-discovery in Codex. Prompt cards that use a skill show the command for the agent you pick.

Keep the repository’s AGENTS.md useful

  • Agents read AGENTS.md at the start of each session; Claude Code reads it through CLAUDE.md, below. Put in it what an agent can’t guess: the exact commands to install, run and test; the conventions the code follows; where the docs live (the docs index); and gotchas that have caught agents before.
  • Leave out changelogs, plans and ticket notes, and any rule a linter or test can enforce; put that in the check instead.
  • Keep it short and true. A stale line misleads every session; release closeout keeps it aligned.
  • Make CLAUDE.md a single line, @AGENTS.md, so Claude Code and Codex read the same instructions.

Choose the model and thinking level for the task

  • Start at each vendor’s general model (Opus 5.5, GPT-6.1 Sol) and its default thinking level. Step down for focused work that is easy to check; step up when a mistake would be hard to spot or costly.
  • Raise the thinking level before switching to the strongest model; both vendors advise this order. More thinking cannot recover a log the agent cannot read, so fix missing context first.
  • Judge the choice by the verified result, including retries and rework, not by the cost or speed of one response.
Task For example Model (Claude / OpenAI, Oct 2026) Thinking level
Focused and easy to check A label change, extracting fields, a search run by a subagent Haiku 5.5 / GPT-6 Luna low
Everyday ticket work ENG-123 from clear acceptance criteria; a bug with a reproduction Opus 5.5, or Sonnet 5.5 when speed matters / GPT-6.1 Sol Default (medium)
Hard to verify or costly to get wrong Unfamiliar code, cross-system investigation, migrations, concurrency, value movement, code and security review Opus 5.5 / GPT-6.1 Sol high; xhigh for reviews
Long autonomous runs, or still unsolved at high A multi-hour refactor; an incident cause not found at high Fable 5.1 / GPT-6 Astra xhigh or max

Sources: Claude models and effort; OpenAI Codex models and reasoning effort.