Use AI agents on a legacy codebase by starting with discovery and behavioral protection, not a broad rewrite. Ask the agent to map entry points, dependencies, data flows, build commands, and known failure areas. Treat current behavior as a contract until a human explicitly approves changing it.
Begin with read-only tasks: explain one request path, identify callers of a risky interface, and document how to reproduce the build. Add characterization tests around behavior that must survive, including odd cases that users may depend on. Choose one small change with a clear rollback. Require the agent to show its plan, affected files, assumptions, and validation commands before editing. Keep dependency upgrades, formatting, refactoring, and behavior changes separate so reviewers can understand cause and effect. When documentation conflicts with code, record the conflict instead of silently choosing one.
Judge progress by reduced uncertainty. Useful outcomes include a reproducible environment, a dependency map, a passing regression test, or a smaller unsafe area. Large diffs and modern-looking abstractions are not evidence of a safer system.
Give the agent only the permissions needed for the current stage and keep work isolated. Review every behavior change with maintainers who know the system. Once the codebase has executable tests and explicit boundaries, agents can help modernize it incrementally without erasing the knowledge embedded in existing behavior.
