iCode Agent · Guide · Workflow

Refactor a module.

Refactoring is mostly understanding: what calls this, what it calls, and what has to stay true while the shape changes. iCode Agent does that mapping against the real code before it edits anything.

The task

Name the module and the change you want, then let it map the blast radius first:

Refactor src/report/builder.ts. Extract the formatting into a
separate module, update all callers, and make sure the tests still pass.

Naming the file bounds the work. If you are unsure where the change belongs, describe the goal and let the agent find the boundary — but a named target keeps the change focused.

What happens

1. Map it. grep and find locate the module's callers; read shows the code with line numbers so the agent can see structure, not guess at it.
2. Plan the change. It identifies what moves, what stays, and every caller that must be updated.
3. Edit in small steps. edit replaces one exact span at a time and shows the diff, so a review sees the change, not a rewritten file.
4. Keep the tests green. It runs your suite — the safety net that makes a refactor safe rather than risky.

Nothing is rewritten wholesale: edit changes a target span and write is used only for genuinely new files. The diff is always visible before you accept it.

Reviewing the diff

This is where you earn the value: the agent proposes, you decide. A good prompt for a refactor asks for reasoning you can check, not just a result:

Refactor the auth module. Show me the callers you found first,
then make the smallest change that removes the duplication.
Run the tests after each file you touch.

If a change is wrong, steer mid-task rather than reverting afterward — the agent has not committed anything, so a redirect is cheap.

Good prompts for this workflow

Find every caller of parseConfig() before changing its signature.
Extract the duplicated retry logic into one helper and update both call sites.
Explain what this module does, then suggest a refactor — but make no edits yet.

The last one is deliberately read-only: ask for the analysis, read it, and then ask for the change. For a large refactor that is often the better shape.