MyAiConfiguration/shared/rules/refactoring.md

Refactoring Guidelines

Core Rule

• Refactor only when it improves readability, maintainability, correctness, performance, safety, or architecture.
• Do not refactor unrelated code without a concrete reason.
• Do not change behavior unless the refactoring explicitly requires it.
• Preserve existing functionality by default.
• Keep refactorings focused and minimal.
• Prefer simple improvements over large rewrites.

Scope

• Limit changes to the smallest reasonable scope.
• Do not mix unrelated refactorings.
• Do not combine feature work, bug fixes, formatting changes, and broad refactoring unless necessary.
• Avoid repository-wide changes unless explicitly required.
• Do not rename, move, split, or merge files unnecessarily.
• Do not introduce new abstractions without a clear benefit.

Behavior Preservation

• Existing public behavior must remain unchanged unless explicitly requested.
• Preserve API contracts unless a breaking change is explicitly intended.
• Preserve serialization formats, database contracts, configuration keys, routes, and external integrations unless explicitly required.
• Preserve exception behavior where it is part of an existing contract.
• Preserve thread-safety and concurrency behavior.
• Preserve performance characteristics unless the refactoring intentionally improves them.

Code Quality

• Prefer modern, readable C# syntax.
• Reduce unnecessary complexity.
• Remove duplication where doing so improves clarity.
• Prefer clear control flow over clever code.
• Reduce nesting where practical.
• Improve naming when current names are misleading or unclear.
• Prefer strongly typed code.
• Avoid unnecessary interfaces and abstractions.
• Avoid unnecessary wrapper classes and indirection.
• Prefer composition over inheritance.
• Remove dead code when it is clearly unused.
• Remove obsolete comments and commented-out code.
• Keep methods and classes focused.

Architecture

• Respect existing architectural boundaries.
• Do not introduce new layers without a concrete need.
• Avoid circular dependencies.
• Reduce coupling where practical.
• Keep dependencies explicit.
• Do not move business logic into infrastructure or presentation layers.
• Do not weaken encapsulation for convenience.
• Avoid global or static mutable state.

Performance

• Do not trade significant readability for theoretical micro-optimizations.
• Avoid introducing unnecessary allocations in hot paths.
• Avoid unnecessary collection copies.
• Avoid unnecessary LINQ in performance-critical code.
• Preserve or improve algorithmic complexity.
• Measure performance-sensitive refactorings when relevant.
• Do not assume a refactoring is faster without evidence.

Safety

• Do not weaken validation, authorization, authentication, encryption, null-safety, or input handling.
• Preserve or improve error handling.
• Preserve cancellation behavior.
• Preserve disposal and resource lifetime semantics.
• Avoid introducing race conditions.
• Avoid exposing mutable internal state.
• Treat external input as untrusted.
• Do not introduce unsafe code unless explicitly required.

Dependencies

• Do not add new dependencies unless they provide a clear and necessary benefit.
• Prefer existing project dependencies and the .NET BCL.
• Do not replace stable dependencies without a concrete reason.
• Avoid refactorings that increase long-term maintenance cost.

Tests

• Existing relevant tests must continue to pass.
• Update tests when internal structure changes make it necessary.
• Do not delete valid tests merely because they fail after a refactoring.
• Add tests when the refactoring exposes previously untested critical behavior.
• Prefer behavior-based tests over implementation-detail tests.

Validation

After a refactoring:

• Build the affected project or solution.
• Run relevant tests.
• Check for new warnings.
• Verify affected code paths.
• Review the diff for accidental behavior changes.
• Check that unrelated files were not modified unnecessarily.
• Confirm that the result is simpler or clearer than before.

Large Refactorings

• Break large refactorings into small, understandable steps.
• Avoid big-bang rewrites when incremental changes are practical.
• Keep intermediate states buildable where possible.
• Do not perform broad architectural rewrites without explicit user intent.
• If multiple valid architectural directions exist, ask the user before choosing one.

Decision Rule

• If a refactoring may change externally visible behavior, data contracts, architecture, public APIs, persistence, security, or deployment behavior, ask the user first.
• If the benefit is unclear or the change introduces significant complexity, do not proceed autonomously.
• When uncertain, prefer the smaller and safer refactoring.