Workflow tips and limits
How to get useful multi-file changes out of a terminal agent, and the failure modes worth planning for.
A workflow that holds up
Treat the agent as a fast, tireless contributor with no memory of your intent. Output quality tracks two things: how precisely you state the task, and how small the requested change is.
# AGENTS.md
## Commands
- Test: npm test -- --runInBand
- Lint: npm run lint
- Build: npm run build
## Rules
- Never edit files under generated/ - they are rebuilt.
- Use the project logger, not console.log.
- Add or update a test with every behaviour change.- One task per session: a bug, a feature, a migration. Mixed goals produce mixed diffs.
- State the acceptance criteria and the command that proves them.
- Make the agent run the tests, and paste the failure back if it claims success without running them.
- Commit between tasks so a bad session is one reset away.
- Anything you repeat in every prompt belongs in the rules file.
Where it breaks down
| Limit | What you see | Mitigation |
|---|---|---|
| Context window | It forgets an earlier file, or ignores a constraint you stated | Keep tasks small and point it at the few files that matter |
| Hallucinated APIs | Confident calls to methods that do not exist | Require a test or a build after every change |
| Stale assumptions | It copies a pattern you already replaced | Keep the rules file current and review the diff, not the summary |
| Silent scope creep | Unrelated files are touched | Read the diff file by file before committing |
| Cost and rate limits | Long sessions get slow or expensive | Cap the task, and use a cheaper model for search and summarising |
💡
The agent is strongest where feedback is mechanical - a failing test, a type error, a compiler message. Give it something it can measure and it converges; give it taste and it guesses.
FAQ
Should I let the agent commit?
Let it propose and you decide. Autocommit removes the diff review that keeps mistakes out of history.
How large a task is reasonable?
Aim for a change you can review in a few minutes. If the diff needs a walkthrough, split the task before you start.
Related
Install and first session When it works and when it fails
Last refreshed 2026-09-18.