AGENTS.md — Safe refactoring

Restructure code in small steps that never change behaviour, each one checked by tests, so the design improves without new bugs.

How to do it

1. Name the goal — Write one sentence on the structure you want and why, for example 'move pricing rules out of the controller so the new tax rule has one home'.
2. Secure a safety net — Run the tests that cover the code. If coverage is thin, add characterisation tests that pin current behaviour, including odd behaviour, before changing anything.
3. Separate refactoring from behaviour change — Do the refactor on its own branch or in its own commits. Feature or bug-fix changes come after, in separate commits.
4. Take one small step — Apply one named move: rename, extract function, inline, move module, introduce parameter. Prefer the editor's automated refactorings where they exist.
5. Run tests after every step — Run the relevant tests and the type checker. If anything fails, undo the step rather than debugging forward.
6. Commit each green step — Commit after each working step with a message naming the move. Small commits make bisecting and review simple.
7. Keep public interfaces stable — When a widely used function or API must change, add the new form, migrate callers, then remove the old form in a later step.
8. Review the diff as pure structure — Before the pull request, read the diff and confirm no logic, output or test expectation changed. Note any deliberate exception.

Checklist (before a pull request)

• Tests covering the touched code passed before and after the refactor
• No test expectations were changed except renames that follow the code
• Refactoring commits contain no feature or bug-fix changes
• Each commit builds and passes tests on its own
• Old interfaces kept during migration are marked deprecated with a removal plan
• Type checker and linter report no new errors

Rules

• Never refactor code that has no tests covering it; add characterisation tests first. (Without a safety net you cannot tell a refactor from a rewrite.)
• Keep each refactoring pull request focused on one structural goal. (Reviewers can verify behaviour is unchanged only when the diff has one purpose.)
• Benchmark before and after when refactoring a hot path. (Cleaner code can still be slower, and that is a behaviour change users notice.)
• Preserve error types, messages and status codes callers rely on. (Callers often branch on errors, so changing them breaks contracts silently.)

Checks

Generated from the Celestial engineering practice “Safe refactoring”.