A typical editing workflow
Explore, plan, edit, verify: the loop that keeps an agent session short, reviewable and cheap.
Explore and plan before editing
The most expensive sessions are the ones where the agent starts editing before it understands the code. Ask for an explanation first, read it, correct it, and only then ask for changes. Understanding it built up in the conversation carries into the edit.
> /init
reads the repository and writes a starter CLAUDE.md you can edit
> how does the auth middleware attach a user to the request? cite the files.
< explanation with file:line references
> that is wrong about the refresh path - it re-reads the cookie at line 42.
now propose a plan to return 401 when the token is expired, and change nothing yet
> proceed, then run the tests. keep the change to src/auth/ and its test file.- Use
@to reference a specific file or directory instead of describing it in prose. - Use
!to run a shell command in the session and put its output in context. - Ask for file and line references. A claim you cannot check is a claim you cannot trust.
- Correct the agent's model of the code early; every later instruction is interpreted through it.
Edit, verify, commit
git status --short # clean before the agent starts
git switch -c agent/expiry-401
# ... one focused request, then review
git diff # read the whole patch
npm test # run the gate yourself
git add -p && git commit -m "Return 401 for expired tokens in auth middleware"
# clear context between unrelated tasks so old noise stops influencing edits
# (inside the session: /clear)| Command | What it does | Use it when |
|---|---|---|
| /init | Generate a starter instruction file | First session in a new repository |
| /clear | Drop the conversation, keep the session | Switching to an unrelated task |
| /compact | Summarise history to free context | A long session that is still on one task |
| /permissions | Inspect and edit allow, ask and deny rules | The agent keeps asking for the same command |
| /review | Ask for a review of the current diff | Before you commit, as a second pair of eyes |
| /mcp | Manage external tool servers | Connecting a database, issue tracker or docs source |
💡
One task per session, and commit between tasks. Long sessions mix context, so an instruction for task three is interpreted with everything from tasks one and two still in the window - a common cause of edits that look random but are perfectly consistent with a stale goal.
FAQ
Should I commit before or after the agent works?
Before. A clean commit is your undo button: if the diff is wrong you can discard it entirely without losing unrelated work, and you can see exactly which files the session touched.
The agent keeps asking for permission to run the tests.
Add the exact command to
allow in settings, using the same form the prompt shows. Allowing a narrow command such as Bash(npm test) is much safer than enabling a mode that approves everything.Related
Installing and configuring Claude Code Permissions and safety with agents
Last refreshed 2026-09-18.