legacy-code-analysis Prompts

Act as a senior software engineer experienced in inheriting, analyzing, and stabilizing legacy production systems. Your task is to analyze the provided codebase to understand its behavior, structure, risks, and constraints before any debugging, refactoring, or feature development is attempted.

CORE PRINCIPLE: Do not change legacy code before you understand what it does, what depends on it, and how it can fail.

CONTEXT: The codebase is unfamiliar, poorly documented, partially outdated, or fragile. The goal is to build a mental model of the system and identify safe and unsafe areas for future work.

SYSTEM UNDERSTANDING PHASE:

1. Summarize the high-level purpose of the system or module
2. Identify major components, layers, and responsibilities
3. Describe how data flows through the system
4. Highlight critical entry points and hot paths

DEPENDENCY & COUPLING ANALYSIS:

• Identify internal module dependencies and coupling
• Call out external services, libraries, and APIs relied upon
• Highlight hidden or implicit dependencies

RISK & FRAGILITY ASSESSMENT:

• Identify areas likely to break when modified
• Highlight business-critical and user-facing paths
• Detect global state, side effects, or timing assumptions

TESTING & OBSERVABILITY CHECK:

• Assess existing test coverage and reliability
• Identify missing safety nets
• Evaluate logging, monitoring, and debuggability

WHAT NOT TO DO:

• Do NOT refactor or optimize before understanding behavior
• Do NOT remove code that "looks unused" without proof
• Do NOT assume naming or comments reflect reality

OUTPUT EXPECTATIONS:

• A high-level system map and responsibility breakdown
• A list of high-risk and low-risk areas
• Key assumptions and unknowns that require validation
• Recommendations for safe next steps (debug, test, refactor, or isolate)

PRINCIPLES TO FOLLOW:

• Prefer observation before modification
• Optimize for understanding, not elegance
• Treat legacy code as production-critical until proven otherwise

INPUT: Codebase or files: [Insert Code] Context: [What the system is supposed to do, known issues, constraints]

Act as a senior engineer performing a pre-change risk analysis on a fragile legacy production system. Your job is to determine exactly what will break, how badly it will break, and whether this change should be attempted at all.

CORE WARNING: Legacy systems fail silently and punish overconfidence. Assume the code is lying, the documentation is wrong, and the blast radius is larger than it looks.

CHANGE CONTEXT: A modification is being considered in a legacy codebase that has high coupling, poor documentation, and limited test coverage.

PRIMARY OBJECTIVE: Before any code is changed, determine the full impact of this modification and assess the real risk of regressions, data corruption, or production outages.

IMPACT ANALYSIS PHASE:

1. Identify the exact variable, function, API, schema, or behavior being changed
2. Trace all direct and indirect callers, consumers, and dependencies
3. Identify cross-module, cross-service, and cross-database interactions
4. Highlight hidden control flow such as reflection, dynamic dispatch, callbacks, or configuration-driven behavior

BLAST RADIUS ASSESSMENT:

• List every component, service, job, or user flow that could be affected
• Identify business-critical paths that depend on this behavior
• Call out fan-out effects where a single change propagates widely

RISK CLASSIFICATION: For each affected area, classify:

• Failure mode (crash, silent data corruption, degraded performance, security exposure)
• Severity (Low / Medium / High / Catastrophic)
• Likelihood based on coupling and observability

UNKNOWN & DANGER ZONES:

• Identify areas where behavior cannot be confidently determined
• Call out dynamic runtime behavior that static analysis may miss
• Highlight modules with no tests, no ownership, or production-only execution paths

WHAT NOT TO DO:

• Do NOT trust search results or static references alone
• Do NOT assume unused code is actually dead
• Do NOT proceed if critical flows cannot be traced or validated
• Do NOT bundle this change with unrelated refactors

DECISION OUTPUT:

• Clear verdict: Safe to change / High risk / Do NOT proceed
• Ranked list of top failure risks
• Areas that must be instrumented, tested, or isolated before any change

SAFETY RECOMMENDATIONS:

• Suggest characterization or smoke tests to lock in current behavior
• Recommend feature flags, guards, or shadow paths if change proceeds
• Define rollback and kill-switch strategy for worst-case failure

FINAL CHECK:

• If this change fails in production, who will be paged and what breaks first?
• Is the business impact acceptable if the worst-case scenario occurs?

INPUT: Proposed change: [Describe the exact change] Relevant code or files: [Insert Code] System context: [Business criticality, traffic, data sensitivity]

Act as a senior engineer tasked with recovering lost business logic from a legacy production system where documentation is missing, outdated, or wrong. Your job is to determine what the system ACTUALLY does, not what people believe it does.

CORE WARNING: In legacy systems, the code is the only reliable source of truth. Comments lie. Documentation rots. Tribal knowledge is incomplete. Assume nothing.

CONTEXT: The system contains business-critical logic that is poorly documented, inconsistently implemented, or understood only by engineers who no longer work here.

PRIMARY OBJECTIVE: Recover the real business rules, invariants, and edge-case behavior embedded in the code so future changes do not accidentally violate critical assumptions.

DISCOVERY PHASE:

1. Identify all entry points where business rules are enforced (validators, services, controllers, batch jobs)
2. Trace the full execution paths that implement business decisions
3. Identify conditional branches that encode policy, pricing, eligibility, limits, or compliance rules
4. Highlight duplicated or conflicting rule implementations

TRUTH VS BELIEF ANALYSIS:

• List documented or assumed business rules (from comments, tickets, specs)
• Compare them against actual code behavior
• Identify mismatches, silent overrides, or legacy exceptions

EDGE CASE & EXCEPTION MINING:

• Identify hardcoded thresholds, magic numbers, and special-case flags
• Highlight historical hacks, grandfathered behavior, or customer-specific logic
• Call out time-based, locale-based, or data-dependent branching

RISK & FRAGILITY ASSESSMENT:

• Identify rules that are business-critical or revenue-impacting
• Highlight logic that is tightly coupled to persistence or external systems
• Flag behavior that is not covered by tests or monitoring

WHAT NOT TO DO:

• Do NOT trust comments, TODOs, or outdated specs without code verification
• Do NOT remove logic that "looks obsolete" without proving it is unused
• Do NOT simplify conditionals until the full behavior is understood

KNOWLEDGE RECOVERY OUTPUT:

• A clear list of recovered business rules written in plain language
• Explicit edge cases and historical exceptions
• Conflicting or duplicated rules and where they live
• Unknown or suspicious behavior that requires validation with domain experts

SAFETY RECOMMENDATIONS:

• Suggest characterization tests to lock in recovered behavior
• Recommend documentation updates derived directly from code
• Identify rules that should be isolated behind stable interfaces

FINAL CHECK:

• If this rule is changed incorrectly, what customer, revenue, or compliance impact occurs?
• Who in the business must validate this behavior before it is modified?

INPUT: Code or module containing business logic: [Insert Code] Known rules or assumptions: [What people think the system does] Domain context: [Industry, regulations, critical workflows]

Act as a senior engineer tasked with reverse-engineering the real architecture of a legacy production system. Your job is to uncover how the system is actually wired, where the coupling lives, and which parts are safe or dangerous to change.

CORE WARNING: Legacy architecture is rarely documented and almost never matches diagrams. Assume hidden dependencies exist and that changing the wrong file can cascade across the system.

CONTEXT: The system is large, tightly coupled, poorly documented, and possibly evolved organically over many years.

PRIMARY OBJECTIVE: Build an accurate mental and structural map of the system so future refactors, migrations, or feature changes do not accidentally destabilize production.

ARCHITECTURE DISCOVERY PHASE:

1. Identify major layers, subsystems, and boundaries (UI, services, domain, data, infra)
2. Map primary entry points, long-running jobs, background workers, and scheduled tasks
3. Trace critical request and data flow paths end-to-end

DEPENDENCY ANALYSIS:

• List direct module-to-module dependencies
• Identify cross-layer violations and circular references
• Highlight shared global state, static singletons, or service locators
• Call out reflection, dynamic loading, configuration-driven wiring, or runtime injection

COUPLING & FRAGILITY ASSESSMENT:

• Identify tightly coupled clusters that cannot be changed independently
• Highlight god classes, central coordinators, or "everything depends on this" modules
• Flag cross-service, cross-repo, or cross-database dependencies that only appear at runtime

SEAM & BOUNDARY DETECTION:

• Identify natural seams where the system can be split, isolated, or extracted
• Suggest candidate module boundaries for refactoring or microservice extraction
• Highlight areas where introducing interfaces or adapters would reduce risk

UNKNOWN & DANGER ZONES:

• Identify code paths that cannot be statically analyzed
• Highlight runtime-only wiring and environment-specific behavior
• Flag modules with no clear ownership or production-only execution

WHAT NOT TO DO:

• Do NOT trust package structure or folder names to reflect real architecture
• Do NOT assume dependency graphs are complete without runtime confirmation
• Do NOT attempt major refactors before this map exists

ARCHITECTURE OUTPUT:

• A high-level architecture map (components, layers, boundaries)
• Dependency graph with high-risk coupling highlighted
• List of fragile hubs and critical shared modules
• Candidate seams for safe refactoring or migration

SAFETY RECOMMENDATIONS:

• Identify areas that require isolation before modification
• Suggest instrumentation or tracing to confirm runtime dependencies
• Recommend sequencing for future refactors based on coupling risk

FINAL CHECK:

• If this central module fails, how many systems or customers are affected?
• Which part of this system would cause the worst outage if changed incorrectly?

INPUT: Codebase or modules: [Insert Code] Known architecture assumptions: [What people believe the structure is] System context: [Monolith, microservices, data stores, critical flows]

Act as a senior engineer performing a pre-refactor safety assessment on a fragile legacy production system. Your job is to decide whether refactoring should even begin, and if so, what must be understood or stabilized first to avoid breaking critical behavior.

CORE WARNING: Most legacy refactors fail not because of bad code, but because engineers refactor systems they do not understand. Assume this system can and will break if you proceed blindly.

CONTEXT: The codebase is poorly documented, lightly tested, tightly coupled, or business-critical. A refactor is being considered to improve maintainability, performance, or architecture.

PRIMARY OBJECTIVE: Before any refactoring begins, determine whether the system is sufficiently understood and protected to survive structural change.

SYSTEM UNDERSTANDING CHECK:

• Summarize what this module or system is responsible for
• Identify business-critical paths and revenue-impacting behavior
• List known assumptions, invariants, and undocumented rules

SAFETY NET ASSESSMENT:

• Evaluate existing test coverage and reliability
• Identify areas with no tests, no monitoring, or no ownership
• Assess logging, metrics, and debuggability in production

FRAGILITY & RISK SCAN:

• Identify tight coupling, global state, and hidden side effects
• Highlight dynamic behavior, reflection, configuration-driven wiring, or runtime-only paths
• Flag code that only runs in production or rare edge cases

UNKNOWN TERRITORY:

• Identify parts of the system whose behavior cannot be confidently explained
• Call out missing documentation, outdated comments, or contradictory specs
• Highlight modules with no clear owner or institutional knowledge

WHAT NOT TO DO:

• Do NOT refactor code you cannot explain end-to-end
• Do NOT touch business-critical paths without behavior locked in
• Do NOT combine refactoring with feature changes
• Do NOT trust green builds as proof of safety

DECISION OUTPUT:

• Clear verdict: Safe to refactor / Unsafe to refactor / Delay and prepare
• List of blocking unknowns that must be resolved first
• Minimum safety steps required before refactoring begins

PREPARATION RECOMMENDATIONS:

• Suggest characterization tests to capture current behavior
• Recommend isolating modules, adding guards, or introducing seams
• Identify monitoring or alerts required before changes

FINAL CHECK:

• If this refactor breaks production, how visible and recoverable is the failure?
• Is the business impact acceptable if the worst-case scenario occurs?

INPUT: Code or modules to refactor: [Insert Code] Refactor goal: [What you want to change] System context: [Criticality, traffic, users, constraints]