Inherited Codebase Checklist for Freelancers and Agencies

#webdev #codequality #freelance #programming

Taking over a client codebase is risky because the first problems are usually invisible: missing environment variables, hidden coupling, weak tests, expired dependencies, and business logic nobody can explain.

Use this checklist before you quote the work, commit to a timeline, or promise a cleanup plan.

1. Confirm the repo can be understood

Start with the boring facts:

Languages, frameworks, package managers, and lockfiles
App entry points, routes, jobs, webhooks, and scheduled tasks
Database models, migrations, and external services
Deployment target and CI/CD configuration
Environment variables and secret handling

If you cannot describe how the system starts, stores state, and talks to the outside world, you are not ready to estimate it.

2. Find operational hazards first

Before style issues, look for things that can break production:

Committed secrets or private keys
Missing auth checks on API routes
Unpinned dependencies or missing lockfiles
No backup or migration story
No tests around billing, auth, permissions, or payments
Manual deployment steps that live in someone's head

These findings change the quote because they are not cleanup. They are risk containment.

3. Separate noise from roadmap

An inherited repo can produce hundreds of complaints. Most are not worth showing a client.

Group findings into a short roadmap:

Bucket	What belongs here
Critical	Security, data loss, broken deploys, auth and billing risk
High	Coupled modules, missing tests around core flows, outdated vulnerable dependencies
Medium	Duplication, oversized files, weak docs, stale TODOs
Low	Naming, style, low-impact cleanup