Legacy Code Modernization Planner for AI Coding Agents

Create a safe modernization plan and AI coding agent prompt for an old PHP website. It has many duplicated files, no automated tests, direct database queries, fragile templates, and very little documentation. The site is already in production, so the plan must avoid risky rewrites. Include a risk map, what not to touch yet, phased roadmap, testing strategy, documentation plan, rollback plan, verification checklist, and first safe Cursor prompt.

=== LEGACY CODE MODERNIZATION PLAN ===

Project/system: Old production PHP website with duplicated files, direct database queries, fragile templates, no automated tests, and little documentation.

Modernization goal: Improve maintainability, reliability, and developer confidence while preserving existing URLs, page behavior, forms, sessions, database behavior, and production stability.

System type: Legacy server-rendered PHP website

Confirmed facts:

• The site uses PHP.
• The site is already in production.
• The codebase has many duplicated files.
• There are no automated tests.
• The site uses direct database queries.
• Templates are fragile.
• Documentation is minimal.

Assumptions:

• Existing URLs may matter for SEO.
• The site may use shared includes, global variables, and direct form handlers.
• Database queries may contain hidden business rules.
• Deployment and rollback procedures may be informal.

Unknowns to clarify:

• PHP version
• database type and version
• hosting environment
• routing structure
• whether Composer is used
• whether authentication exists
• whether payments or personal data are involved
• how deployments are performed
• whether staging exists

Current system diagnosis: The codebase should not be rewritten immediately. The absence of tests and documentation makes broad modernization risky. The safest approach is to first document the current system, capture critical behavior with smoke tests, identify high-risk workflows, and then refactor duplicated code in small reversible steps.

Risk map:

1. Production stability — Critical Any broad rewrite could break live pages.

2. SEO-sensitive URLs — High Changing file names, routing, or .htaccess behavior may damage indexing and traffic.

3. Direct database queries — High Queries may contain business-critical assumptions and may be vulnerable or fragile.

4. Forms and session handling — High Legacy form logic may depend on implicit state.

5. Fragile templates — Medium to high Shared visual changes may affect many pages unexpectedly.

6. Lack of tests — High There is no safety net for refactoring.

Do not touch yet:

• production database schema
• authentication/session logic
• payment logic if present
• .htaccess/rewrite rules
• public URLs
• high-traffic pages
• form handlers
• direct database queries in critical workflows
• deployment configuration
• environment variable values

Modernization inventory:

• Documentation: urgent, low risk, high value
• Smoke tests: urgent, medium difficulty, high value
• Duplicated templates: high value, medium risk
• Database query safety: high value, high risk
• Dependency/runtime upgrades: medium value, medium to high risk
• Architecture cleanup: high value, medium risk
• Framework migration: future phase only, high risk

Recommended modernization strategy: Use an incremental stabilization-first strategy. Do not migrate to a framework yet. Create a reliable baseline, document the system, add smoke tests, then consolidate duplicated templates and utilities gradually.

Phased roadmap: Phase 0 — Discovery and safety baseline:

• Map all public PHP entry files and routes.
• Document shared includes, templates, and configuration files.
• Identify top production pages by importance.
• Document database connection points.
• Create backup and rollback notes.
• Record current PHP version and hosting constraints.

Phase 1 — Stabilization:

• Create local setup instructions.
• Add smoke tests for homepage, key content pages, search, contact forms, login if present, and admin if present.
• Add a simple manual QA checklist.
• Add safe error logging if missing.
• Document deployment steps.

Phase 2 — Low-risk cleanup:

• Identify duplicated header, footer, navigation, and layout sections.
• Extract shared templates carefully.
• Remove dead files only after confirming they are unused.
• Centralize repeated helper functions.
• Keep URLs and output behavior unchanged.

Phase 3 — Database safety:

• Inventory direct SQL queries.
• Identify queries used by critical pages.
• Add tests or manual verification for critical query outputs.
• Convert high-risk queries to prepared statements gradually.
• Avoid schema changes unless separately planned.

Phase 4 — Architecture modernization:

• Separate page controllers, templates, helpers, and database access.
• Introduce Composer/autoloading if compatible.
• Create module boundaries for major features.
• Add documentation for data flows.

Phase 5 — Dependency/runtime upgrades:

• Check PHP version compatibility.
• Upgrade libraries one at a time.
• Test after each upgrade.
• Avoid mixing dependency upgrades with refactors.

Phase 6 — Hardening:

• Review input validation and output escaping.
• Improve security headers if appropriate.
• Review file permissions.
• Add monitoring for server errors.
• Improve performance on high-traffic pages.

Phase 7 — Documentation and handoff:

• Create README.
• Create architecture overview.
• Create setup guide.
• Create deployment guide.
• Create database query map.
• Create modernization backlog.

Testing strategy:

• Smoke tests for critical public pages
• Characterization tests for helper functions
• Manual QA checklist for forms and sessions
• Regression checks for URLs and page output
• Database query verification for critical pages
• Accessibility checks for template changes

Documentation plan:

• README with setup instructions
• Route map
• Template/include map
• Database access map
• Deployment guide
• Known risks document
• Modernization backlog

Rollout and rollback plan:

• Work in small branches.
• Deploy only one modernization category at a time.
• Back up files and database before risky changes.
• Keep previous templates until new shared templates are verified.
• Define rollback trigger: broken critical page, form failure, database errors, or unexpected SEO URL changes.
• Verify after deployment using smoke tests.

AI coding agent prompt: Inspect this legacy production PHP website and create a modernization baseline. Do not rewrite the app or migrate it to a framework. First map public entry files, routes, includes, templates, configuration files, database access points, form handlers, and deployment assumptions. Identify duplicated code and high-risk areas. Preserve existing URLs, page behavior, sessions, forms, and database behavior. Do not change production database schema, authentication, payments, .htaccess rules, environment variable values, or deployment configuration unless explicitly requested. Add or recommend smoke tests for the most important pages. Return an architecture map, risk map, do-not-touch list, safe first refactor tasks, testing plan, documentation plan, and rollback notes.

Verification checklist:

• Existing public pages still load.
• Existing URLs remain unchanged.
• Forms still submit correctly.
• No database schema changes were made.
• No secrets were exposed.
• Smoke tests pass.
• Shared templates render consistently.
• Server logs show no new errors.
• Rollback path is clear.

Risks and safety notes: Because the site is in production and has no tests, modernization must be incremental. Framework migration should be postponed until routes, templates, database behavior, and critical workflows are documented and protected by tests.