Preparing the Codebase for Other Humans

The First Pull Request Never Starts

Continue with the property-management product from the previous chapter. The founder has separated onboarding work from product judgment and has a bounded engineering task ready: reject duplicate vendor identifiers during import preview without disturbing the legacy mapping used by early customers.

The new developer clones the repository and stops almost immediately. The README names an old runtime. The sample environment file contains a storage setting nobody can explain. Seed data creates a user but no building, vendor, or maintenance request. Once the app runs, the developer finds two import paths and cannot tell which one customers use.

None of these problems is visible while the founder is writing the code. Memory completes the system: which command still works, why two paths exist, which warning is harmless, and what an import must preserve. The repository contains the executable parts; the founder supplies the rest on demand.

That arrangement was reasonable while the product was changing quickly and one person carried the entire feedback loop. It fails as soon as work must travel. The developer can interrupt the founder repeatedly, guess at the missing context, or avoid the risky code. All three choices consume the leverage the hire was meant to create.

The goal is not a polished repository. It is a joinable one.

Use One Change to Find the Missing System

“Document the codebase” has no useful finish line. It encourages either a few cosmetic README edits or a documentation sabbatical. Begin with the first real assignment instead.

Ask what the developer must know to take the duplicate-identifier change from a clean checkout to production. They need to understand why imports matter, create a representative local account, trace the preview path, distinguish current behavior from legacy behavior, verify the result, release it, and recognize a failed release. Each interruption along that route reveals a specific piece of private knowledge.

The resulting standard is practical. Without live founder narration, a competent collaborator should be able to:

• explain the customer promise and the boundaries the change must protect;
• run a representative version of the product;
• trace the affected workflow through code, data, jobs, and integrations;
• make and verify a bounded change;
• ship it through the supported path or stop safely;
• locate the known hazards before discovering them by accident.

This is narrower than documenting everything and more demanding than producing a folder called docs. Legibility is behavior: another person can form a correct model and act with it.

Put the Customer Promise Next to the Code

The developer’s first plausible solution is to merge vendor rows that share an identifier. Technically, it makes the input cleaner. Product context reveals the danger: a regional property manager may use the same vendor identifier for separate local branches, while an early customer’s mapping file treats each branch as a distinct notification destination. Silent merging could send a maintenance request to the wrong crew.

Commands cannot teach that. The repository needs a short product-context note that says who the product serves now, which workflow creates value, what customers trust it to preserve, and which behavior is deliberately outside scope. It should also name assumptions still under test and legacy paths whose odd shape protects a real customer.

For this product, the useful context is compact. Property managers need a maintenance request to reach an appropriate vendor and remain visible until somebody resolves it. Building, resident, vendor, and access data cross a trust boundary. The product supports repeatable maintenance operations; it does not promise to become a general property-management suite. The old vendor mapping remains because several retained accounts still import that format.

That note changes the implementation. Duplicate identifiers should be exposed during preview for a human decision, not silently normalized. The developer can now evaluate a technically tidy idea against the product promise.

Product context belongs near architecture and release guidance because it constrains both. It is not a pitch deck. Its job is to prevent a collaborator from improving the code while damaging the product.

Make a Clean Checkout Tell the Truth

The founder next watches the developer set up the repository without taking over the keyboard. When a step fails, they repair the supported path or write down the obstacle. A spoken workaround preserves the defect for the next person.

The README should lead from a clean checkout to a meaningful local state. That includes exact runtime and package-manager versions, install and database commands, migrations, seed data, the development server, and the commands used for tests, linting, formatting, and builds. Environment variables need a safe example shape, a sentence about their purpose, and a source of truth. Real secrets do not belong in the repository; an authorized developer still needs to know which secrets exist, whether local work requires them, and how access is granted.

Representative data matters as much as a running process. A blank dashboard proves very little about an import change. The property-management seed creates a demo account with two buildings, vendors with shared and distinct identifiers, an early-format mapping, and maintenance requests in several states. Fake notification and storage adapters keep local work from reaching customers or production services.

Honesty is more useful than apparent maturity. If one operating system is supported, say so. If a service must run in a container, provide that path. If a test is flaky, name it rather than training a newcomer to ignore red output. The setup guide is trustworthy when it describes the system that exists today.

Trace the Workflow, Not the Directory Tree

A list of folders rarely explains architecture. For the assigned change, the developer needs to follow an import as the product follows it: upload, storage, preview job, parsing, validation, mapping, preview display, commit, and any downstream notifications. The architecture note should make that route visible and point to its entry points in the code.

The working map also names ownership and boundaries:

• which application accepts the request and authorizes access;
• which worker parses the file, how it retries, and whether the job is idempotent;
• where the original file and preview result live;
• which records become durable only after confirmation;
• which external services are involved;
• where errors, metrics, and alerts appear;
• which behavior differs between development, staging, and production.

Data names need product meaning. account might mean a login, paying company, billing record, or workspace. property, building, and the legacy site may look interchangeable while representing different customer concepts. A collaborator should not have to reconstruct those meanings from foreign keys and old migrations.

Keep the map close to the code’s level of change. Stable boundaries and core flows deserve prose and a small diagram if spatial relationships are hard to hold. Volatile internals are better linked through entry points than copied into a document that will immediately drift. Mess is survivable when the map admits where it is.

Build an Honest Safety Path

The developer can now reach the validation code and understand its purpose. The next question is how to know the change is safe.

The repository should distinguish protections that exist from protections the founder hopes to add. For duplicate identifiers, a focused test can prove that preview reports the conflict without committing records. Another can preserve the legacy mapping behavior. Broader integration tests may cover upload, preview, confirmation, and job retry. If notification behavior lacks reliable automation, the release path should require a manual check with fake destinations.

Thin automation is not a reason to pretend. A concise manual QA path for account creation, import preview, import commit, permissions, notification routing, and export is safer than a green test command that misses the customer workflow. The collaborator needs to know which checks carry real confidence, which are slow or flaky, and which risks still depend on review.

Conventions matter where they affect safe work. Explain how errors are represented, where authorization belongs, how migrations and backfills are reviewed, and when a decision record is expected. A long style guide is less urgent than one clear rule preventing a background job from bypassing tenant checks.

The review brief should connect code to consequence: duplicate identifiers are visible before commit; the original file remains recoverable; no row is guessed into a vendor; the early-format mapping still works; notification behavior does not change. Review becomes an inspection of a product promise, not a search for the founder’s unstated preferences.

Rehearse Release and Recovery

A change is not handed off if only the founder can ship it.

Release guidance should identify who can deploy, how access is granted, what the deployment changes, and what success looks like afterward. It must say when migrations run relative to application and worker processes, how feature flags and configuration move, where logs and metrics live, and which post-deploy action proves the customer path still works.

Recovery deserves the same precision. “Rollback” is incomplete when a migration has transformed data or a job has produced external effects. The guide should distinguish a safe application rollback from a forward repair, explain how to pause workers or disable a feature, and identify the person who can approve a destructive recovery step.

For the import change, the developer deploys to staging, uploads the representative file, confirms that the duplicate appears in preview, commits an unambiguous file, and checks that the expected job and notification events appear. In production, the initial release is observed through preview failures and import-job metrics. If conflicts spike unexpectedly, the validation can be disabled without undoing committed customer data.

The boring details create independence: the command, credential boundary, migration order, normal signals, failure signals, and first safe response. A runbook earns its place when it lets somebody act during pressure rather than merely describing the component.

Name the Places Where Tidying Is Dangerous

Known debt becomes expensive when a collaborator encounters it as a surprise. Record debt in operational terms: who or what still depends on it, how failure appears, how to inspect it, what currently reduces the risk, and what would make removal safe.

The legacy import path is a useful example. “Old parser” expresses regret but offers no guidance. A useful note says that retained accounts still upload the early vendor format, that the path is selected by mapping version, that preview and commit must agree, and that it can be removed only after those accounts migrate and historical files can still be interpreted. Missing test coverage, provider limits, data inconsistencies, permission concerns, slow queries, and rollback hazards deserve the same treatment when they can harm customers or stop delivery.

Do not catalog every inelegant line. Prioritize by blast radius and interruption cost. Setup, deployment, data ownership, trust boundaries, and core-workflow verification usually come before naming preferences or a complete API inventory.

Some explanations belong in short decision records rather than a debt list. The import design can be preserved without ceremony:

# Keep customer imports asynchronous

Decision: Customer imports stay in the background job system.
Reason: Files vary in size and quality; preview and retry must not hold an HTTP request open.
Consequence: Import status stays visible, jobs must be safe to retry, and support needs a recovery runbook.
Revisit when: The import contract or infrastructure changes enough to remove those constraints.

The record protects reasoning a future collaborator might otherwise “simplify” away.

Leave a Small Handoff Surface

The finished handoff does not need an internal encyclopedia. A strong repository usually points from its README to a small set of maintained artifacts: product context; the working architecture and data model; verification and release guidance; runbooks for consequential failures; decision records; known debt; and an onboarding path built around the first useful change.

Where these artifacts live matters less than whether the repository makes them findable. Ownership matters more than polish. Update the architecture map when a boundary changes, release guidance when the process changes, and the debt note when a hazard appears or disappears. If nobody can name the event that should update a document, the document is likely to decay.

Documentation should also lose to a durable fix when the fix is cheaper. Repair a broken setup script instead of explaining its workaround forever. Add an admin action if a common incident requires a twelve-step database ritual. Remove a dead path rather than teaching every newcomer to ignore it.

Test the Handoff with Real Work

The duplicate-identifier assignment is now the onboarding test. The founder gives the developer the repository, the task boundary, and normal access, then records every moment when progress requires private explanation. Each interruption has one of three destinations: make the code or tooling clearer, put stable knowledge in the right document, or define an escalation because the decision still belongs with the founder.

The codebase is ready for another human when the developer can explain the product constraint, run representative data, trace the import, change it, verify it, release it through the supported path, and identify the legacy hazard before touching it. Perfect coverage and elegant architecture are not required. A truthful route through the work is.

Delay delegation when setup still needs live narration, product context is missing, release and recovery are founder rituals, or dangerous areas are hidden. Proceed when the first assignment carries context, boundaries, acceptance criteria, verification, and a safe way to stop.

To test a codebase before the collaborator arrives, choose one product-critical workflow and attempt the same journey from a clean checkout. Write down the first ten questions private memory answers. Fix or document the five that would most affect customer trust, production safety, or the ability to complete the change.

When that journey no longer depends on a running founder commentary, engineering work can travel. The next challenge is larger than the repository: allowing decisions to travel without turning the founder into the approval queue.