For developers: your first week on an inherited codebase

The first week on an inherited project sets the tone for everything after it. Rush in with changes and you risk breaking things you do not yet understand. Spend the week only reading and the owner wonders what they are paying for. The plan below balances both: protect the project first, learn how it works, add safety nets, deliver a couple of small visible fixes, and finish with a clear written report.

Adjust the days to fit your hours. The order matters more than the exact timing.

Day 1: access and backups

Before you change anything, make sure you can undo anything.

Get access the right way. Ask the owner to invite you as a collaborator or team member on each service: the repository host, hosting platform, database, and any other dashboards you need. Avoid shared logins. Invites give you your own credentials, leave an audit trail and can be removed cleanly when the work ends. If the owner is unsure how, the TakeoverWork guide on giving a developer access without sharing passwords walks them through it.

Take backups. At minimum:

• A full clone of the repository, including all branches and tags (git clone --mirror is a good choice).
• A database export. For PostgreSQL, a pg_dump of both schema and data. For managed platforms, use their backup or export feature and confirm the file is not empty.
• Copies of uploaded files from object storage, if the app stores user uploads.
• A record of current environment variable names (not values) from the hosting dashboard.

Store backups where the owner can reach them, not only on your laptop.

Write an access log. List every service, whether you have access, at what level, and who owns the account. Gaps go straight into your report.

Day 2: reproduce locally

Aim to run the app on your machine against a non-production database.

1. Match the runtime version. Check .nvmrc, .tool-versions, engines in package.json, or the hosting platform's build settings.
2. Install with the package manager the lockfile belongs to.
3. Create a local environment file with development or test keys. Never point local development at the production database.
4. Load the schema into a local or staging database. If migrations exist, run them in order. If not, build the schema from your Day 1 export and note that migrations are missing.
5. Start the app and walk through the main user journeys.

Write down every step that was not documented. Those notes become the first real README for the project, which is a quick win in itself.

Day 3: map the architecture

Now build a mental model and write it down. A one-page map is enough:

• Entry points. Web routes, API endpoints, background jobs, scheduled tasks, webhooks.
• Data stores. Databases, caches, file storage, and which parts of the code read or write each one.
• External services. Auth provider, payments, email, analytics, AI APIs, with where each is called from.
• Deployment path. How code gets from the repository to production, including any manual steps.

Follow one complete user action end to end, such as sign-up or checkout, through every layer. This exposes hidden coupling faster than reading files at random. Note anything surprising, such as business logic inside UI components or database calls made directly from the browser.

For Supabase projects, review row level security now. Paste the policy SQL into the Supabase RLS Checker and look for tables with RLS off or policies that allow everything. The Supabase auth or RLS broken page covers common patterns.

Day 4: secrets, rotation and error tracking

Find exposed secrets. Search the code and full git history for keys. Paste config files and suspicious snippets into the Secret Leak Scanner, which runs in your browser. Check client-side bundles too: any key shipped to the browser is public, whatever the variable is called.

Plan rotation with the owner. Once control changes hands, rotate keys for payment providers, email services, AI APIs, database passwords and any service-role or admin keys. Rotate one at a time:

1. Create the new key in the provider dashboard.
2. Update it in the hosting environment variables.
3. Redeploy and confirm the feature still works.
4. Revoke the old key.

Never send new keys through chat. The owner should enter them directly in the dashboard, or grant you access to do so. The AI-generated app security issues page lists other risks worth checking at this stage.

Set up error tracking. If the project has none, add an error tracking service with the owner's agreement, under an account the owner controls. From now on you will see real failures instead of relying on user reports. Check that it captures both server and client errors and does not send personal data you do not need.

Day 5: characterisation tests

Characterisation tests record what the code does today, right or wrong, so you notice when a change alters behaviour. They are especially useful when no tests exist.

• Pick the riskiest paths: login, payment, the main create-and-save action.
• Write tests that call these paths and assert on current outputs.
• Where current behaviour is clearly a bug, keep the test but mark it, so fixing the bug becomes a deliberate change.
• Run the tests in CI if possible, so every future push is checked.

A handful of focused tests on critical paths beats a large suite of shallow ones. Use the Dependency Freshness Check to see whether any upgrade is urgent, but hold off on large upgrades until these tests exist.

Day 6: quick wins

With backups, monitoring and some tests in place, make two or three small, low-risk improvements the owner will notice:

• A clear error message where users currently see a blank screen
• A broken link, typo or layout bug on a key page
• A missing loading state on a slow action
• The README you drafted on Day 2

Keep each change in its own commit with a clear message. Stay away from auth, payments and schema changes for now; those belong in planned milestones.

Day 7: written status report

End the week with a written report the owner can read in a few minutes. Suggested sections:

1. Summary. Two or three sentences on the overall state.
2. Access. What you have, what is missing, and who must act.
3. Backups. What was backed up, when, and where it is stored.
4. What works. Confirmed by you, not assumed.
5. What is broken. With severity and likely cause.
6. Security. Secrets found, keys rotated, keys still to rotate, access rule issues.
7. Quick wins delivered.
8. Recommended next steps. In priority order, with effort ranges.

Write about the code, never about the previous developer. Neutral language keeps the focus on solutions and is fair to someone who is not there to explain their choices. The Production Readiness Checklist is a handy structure for the "next steps" section.

First-week checklist

• Collaborator access granted on every reachable service
• Repository mirrored, database exported, file storage copied
• Access log written, with gaps noted
• App running locally against a non-production database
• Setup steps documented in a README
• One-page architecture map written
• Access rules reviewed for every table holding user data
• Secrets scanned in code and history; rotation plan agreed
• Error tracking running under an owner-controlled account
• Characterisation tests covering critical paths
• Two or three low-risk quick wins shipped
• Written status report sent to the owner

Find more provider resources on /for-developers.