tychofreeman/go-refactor-mcp

How to work

Work test first:

• Write the tests we need next first.
• Then make the tests pass with the minimal amount of code.
• Rerun the tests.

Make every change in two phases: “make the change easy, then make the easy change”.

1. Make the change easy. Before changing any behaviour, refactor: change the design of the code, without changing what it does, until the change you need is small and local. Typical refactorings: rename something to what it will mean, extract the code you will change into its own function, add the parameter or field the new behaviour will need, move a declaration to where the change belongs. The tests keep passing after every refactoring.
2. Make the easy change. Then make the behaviour change itself, which should now touch little code.

Do the refactorings in phase 1 with the gorefactor MCP tools (rename, extract_function, add_parameter, introduce_parameter, move_declaration, …). Make the change in phase 2 with the gorefactor edit tools (replace_statements, insert_statements, add_declaration, create_file, …).

Read Go code with the gorefactor inspect tool, not with Read, cat or sed: every result stays in the conversation and is sent again on each later turn, so read only what you need. Inspect a file first: it shows the file without its function bodies, with line numbers, for a third to a half of the whole file. Then inspect only the functions or line ranges you will change, several at once with targets, e.g. {“targets”: [{“file”: “a.go”, “function”: “F”}, {“file”: “b.go”, “start_line”: 10, “end_line”: 30}]}. Use Grep or Bash for files that are not Go (test fixtures, JSON) and to find where a name is used.

Lessons from earlier sessions

Earlier sessions with the same tools, on other Go code, found these. Each derivation reached its goal with at most one distinct line of Go written by hand for each change the task makes (one per field that moves, say), and was found by two or more sessions. Write as little Go by hand as you can: when a step seems to need code, look for operations that produce it, and call them (a refusal costs one call and changes nothing; undo reverts a step).

Derivations:

• A new field or type a test needs costs no code: write the test first with a keyed literal that uses it; the field or the type is declared for you, typed from the literal (a “chose:” line).
• A behavior change inside a nested loop: extract_function the inner loop with the declaration of what it builds (whole statements); it takes the locals and returns the result. The change is one guard line, insert_statements with where: "before" on the loop body’s first statement. Put a guard before any call with side effects, and re-read line numbers after the extraction: a guard one line too late type-checks, and only the test catches it.