legacy-code-understanding
Analyze old, messy, undocumented, inherited, fragile, or difficult-to-maintain codebases before changing them. Use when Codex needs to take over a client project, understand legacy web/mobile/backend
SKILL.mdskills/legacy-code-understanding/SKILL.md
GitHubLegacy Code Understanding
Use this skill before fixing, refactoring, modernizing, rewriting, or taking over an inherited system where the behavior, risks, or business rules are not fully understood.
Core Rule
Understand before changing. Legacy code may be messy, but it can encode real business rules, production data assumptions, and fragile integrations. Map the system, identify risks, and recommend staged improvements before editing.
Workflow
- Identify legacy context:
- project/client, business purpose, current pain points, production status, real users, real data, existing docs, and whether the goal is maintenance, bug fixing, modernization, migration, rescue, quote, or rewrite evaluation
- Map repository structure:
- frontend, backend, mobile, database, public/static files, config, deployment, tests, docs, scripts, vendor code, archived folders, and multiple apps
- Identify the stack:
- languages, frameworks, runtime versions, package managers, database, ORM/query method, auth, deployment, external services, testing tools, and unsupported/outdated technology
- Locate entry points:
- app/server startup, router, pages/screens, API client, middleware, service initialization, database connection, jobs, scripts, Docker/Compose, proxy config, and CI/CD
- Map important user and business flows:
- login, registration, booking/order/payment, approvals, admin actions, staff workflows, reports, file uploads, notifications, exports, and integrations
- Map data flow:
- where data is created, validated, transformed, stored, displayed, exported, and permission-checked
- Inspect database structure:
- schemas, migrations, models, raw SQL, seed data, stored procedures, views, triggers, backups, main entities, relationships, status fields, ownership fields, constraints, and legacy fields
- Review authentication and authorization:
- password handling, sessions/tokens, roles, middleware, frontend guards, backend checks, hardcoded admins, tenant/shop scoping, and route-level access control
- Identify external dependencies and integrations:
- payments, email, SMS, file storage, maps, courier APIs, social login, analytics, AI APIs, webhooks, credentials, error handling, fallbacks, and active/inactive status
- Identify dependency and platform risks:
- old runtimes, unsupported frameworks, abandoned packages, missing lockfiles, multiple package managers, deprecated APIs, manual vendor code, and unsafe upgrade paths
- Identify maintainability risks:
- large files, long functions, duplicate logic, hardcoded values, mixed concerns, raw SQL, dead/commented code, inconsistent formatting, global state, hidden side effects, missing error handling, and unclear ownership
- Identify security risks:
- hardcoded secrets, weak password handling, missing backend authorization, SQL injection, unsafe uploads, open CORS, debug mode, exposed errors, unsafe token storage, sensitive logs, and cross-user data access
- Review testing coverage:
- existing tests, test scripts, CI coverage, unreliable tests, manual QA notes, critical untested flows, and characterization tests needed before refactor
- Review deployment and runtime setup:
- Docker, server scripts, proxy config, CI/CD, platform config, env docs, cron/jobs, workers, logs, health checks, backups, and one-person deployment knowledge
- Look for hidden business rules:
- special-case conditions, hardcoded IDs, manual status transitions, pricing/discount formulas, date/time exceptions, region rules, report calculations, payment rules, and approval rules
- Identify safe quick wins:
- setup docs,
.env.example, health check, basic logging, characterization tests, API notes, missing permission checks, backup steps, Docker Compose, and workflow documentation
- Identify high-risk areas:
- auth, payments, pricing, status transitions, migrations, reports, uploads, integrations, deployment scripts, admin roles, cron jobs, and import/export scripts
- Recommend modernization strategy:
- stabilize first, refactor gradually, use a strangler pattern, or rewrite only if justified by evidence and business value
- Recommend next steps ordered by safety and value.
- Produce a legacy code assessment with scope, stack, repo map, flows, data/database notes, auth, integrations, risks, tests, deployment, quick wins, high-risk areas, modernization strategy, and next steps.
Read references/legacy-assessment-checklist.md for inspection targets, risk categories, modernization options, and the final assessment format.
Non-Negotiable Rules
- Do not rewrite, refactor, upgrade, or delete legacy code before understanding its behavior and risks.
- Do not assume messy or duplicated code is useless.
- Do not remove strange logic without checking whether it is a hidden business rule.
- Do not recommend a full rewrite by default.
- Do not change production data without explicit backup and approval.
- Do not upgrade many dependencies at once without a staged plan.
- Do not expose secrets found in code, config, logs, or docs.
- Do not ignore security, missing tests, database risk, or deployment knowledge gaps.
- Do not invent architecture, commands, data models, or business flows.
- Keep recommendations practical, staged, risk-aware, and tied to business value.
Output Contract
When using this skill, provide:
- Assessment scope and legacy context.
- Project overview and technology stack.
- Repository structure map and entry points.
- Main user/business flows and data flow.
- Database notes.
- Authentication/authorization notes.
- External integrations and dependency risks.
- Maintainability and security risks.
- Testing and deployment status.
- Hidden business rules or unknowns.
- Quick wins and high-risk areas.
- Modernization recommendation.
- Ordered next steps.