Harness Engineering: Why We Document Everything Before Handoff

4 out of 5 agency projects we've inherited had zero documentation. No architecture decisions. No deployment guide. No environment variable map. Just code and a Slack channel that went quiet 6 months ago.

We call our approach harness engineering. Every project gets documentation woven into the build process, not bolted on at the end. The goal is simple: when we hand off, your team should never need to call us again.

Key Takeaways > - Documentation written after a project ships is always incomplete. We write it during development. > - Our handoff package includes 7 documents covering architecture, deployment, runbooks, and more. > - Clients who receive proper docs reduce onboarding time for new developers by 60-70%.

What Harness Engineering Actually Means

Most agencies treat documentation as an afterthought. Ship the code, write a README, move on. The client gets a working product and a 200-word file that says "run npm install."

Harness engineering flips this. Documentation is a first-class deliverable, scoped and budgeted like any feature. We write architectural decision records (ADRs) as we make decisions, not weeks later when we've forgotten the tradeoffs. We document deployment steps the first time we deploy, not during a frantic handoff meeting.

The name comes from the idea that documentation is the harness that keeps the project controllable after the people who built it leave. Code without docs is a horse without reins. It runs, but nobody can steer it.

Our Exact Documentation Template

Every RalphNex project ships with these 7 documents. No exceptions.

1. Architecture Overview (ARCHITECTURE.md) System diagram, tech stack rationale, service boundaries, data flow. This answers "why is it built this way?" not just "what does it do?" We include the options we rejected and why. When your future CTO asks "why didn't they use microservices?" the answer is in the doc.

2. Environment and Setup Guide (SETUP.md) Every environment variable explained. Local development setup that works on a clean machine. Required services, API keys, and how to obtain them. We test this by having someone outside the project follow it. If they get stuck, the doc is wrong.

3. Deployment Runbook (DEPLOY.md) Step-by-step deployment for every environment: staging, production, and any intermediaries. Rollback procedures. DNS configuration. SSL certificates. CI/CD pipeline explanation. This is the doc you read at 2 AM when something breaks.

4. API Documentation (API.md) Every endpoint, every request/response schema, every error code. We generate this from code where possible, but we annotate it with context that auto-generated docs miss - like "this endpoint is slow because it queries three external APIs" or "this returns paginated results, max 100 per page."

5. Database Schema and Migrations (DATABASE.md) Entity relationship diagrams. Migration history. Indexing strategy. Seed data for local development. Common queries and their performance characteristics. We include the queries that are slow and why we left them that way (usually because optimizing wasn't worth it at current scale).

6. Third-Party Integration Map (INTEGRATIONS.md) Every external service: what it does, which credentials it needs, rate limits, fallback behavior, and who to contact when it breaks. When Stripe changes their webhook format or an API provider deprecates an endpoint, this doc tells your team exactly what's affected.

7. Architectural Decision Records (decisions/) A folder of short docs, one per significant decision. "Why PostgreSQL over MongoDB." "Why server-side rendering." "Why we chose Vercel over AWS." Each one follows the same format: context, decision, consequences, alternatives considered.

Why Most Post-Project Docs Are Useless

Here's the contrarian take: documentation written after a project is finished is barely better than no documentation at all.

When you write docs after shipping, you're reconstructing decisions from memory. You forget the edge cases. You skip the "obvious" things that aren't obvious to someone who wasn't there. You write what the code does today, not why it was built that way.

We've seen this pattern repeatedly. An agency delivers a "comprehensive" doc package on the last day. It looks impressive - 40 pages, nice formatting, table of contents. But when the client's new developer tries to set up the project, half the steps are wrong because the docs were written against an older version of the codebase.

Our docs are written in the same pull requests as the code they describe. Architecture decision? The ADR is in the same PR as the implementation. New deployment step? The runbook update ships with the infrastructure change. This means docs are always current because they're reviewed alongside the code.

The Real Reason We Do This

We write docs so clients can fire us. That sounds self-destructive, but it's the opposite.

When a client knows they can leave at any time, they stay because they want to - not because they're locked in. Morta CRM came back for a second engagement 4 months after handoff. Equipment Rentalz hired us for phase two after their in-house team successfully maintained phase one for 6 months using our docs.

Lock-in is a short-term revenue strategy. Clean handoffs are a referral strategy. Referrals have driven more revenue for us than any locked-in client ever would.

The docs also protect us. When a client's new developer introduces a bug and blames our code, the architecture docs and ADRs show exactly what we built and why. No ambiguity, no finger-pointing.

How We Budget Documentation Time

Documentation takes 15-20% of total project time. On a EUR 60k SaaS build, that's EUR 9k-12k worth of engineering time spent on docs. Most agencies would call that margin they could pocket.

We break it down by sprint:

- Sprint 1-2: Architecture overview, setup guide, initial ADRs. Heavy documentation period because foundational decisions are being made. - Mid-project sprints: ADRs for new decisions, API docs for new endpoints, integration maps as we add services. Lighter but consistent. - Final sprint: Deployment runbook finalization, database schema doc, full review of all docs against current codebase.

The review step matters. We do a "docs audit" in the final sprint where we check every document against the actual state of the code. Commands that changed, environment variables that were added, endpoints that were deprecated. This is the step most agencies skip, and it's the step that makes docs actually useful.

What Happens Without Documentation

We inherited a project last year where the previous agency had shipped a EUR 80k platform with a single README that said "Contact [name] for setup instructions." That person had left the agency.

The client's new developer spent 3 weeks reverse-engineering the deployment process. Three weeks of senior developer salary burned on something that a 2-page runbook would have solved. They spent another 2 weeks figuring out why certain API endpoints existed and what business logic they encoded.

Total cost of missing documentation: roughly EUR 15k in developer time, plus 5 weeks of delayed feature development. That's more than what proper docs would have cost during the original build.

We've seen this story five or six times now. The "savings" from skipping documentation always cost more in the first 6 months after handoff.

Our Handoff Process

Documentation alone isn't enough. The handoff itself needs structure.

Week 1: Async doc review. We share the full documentation package. The client's team reads it and sends questions. We update the docs based on those questions - if they had to ask, the doc wasn't clear enough.

Week 2: Live walkthrough. A 2-hour recorded session where we walk through architecture, deployment, and the trickiest parts of the codebase. The recording becomes part of the documentation package.

Week 3-4: Shadowed support. We're available for questions but we don't touch the code. The client's team makes their first changes, deploys to staging, and handles their first bug. We're on standby, not in the driver's seat.

Day 30: Clean break. Support period ends. The client has working docs, a recorded walkthrough, and 2 weeks of experience running the project themselves. They're self-sufficient.

If they're not self-sufficient by day 30, that's our failure, not theirs. It means our docs missed something.

Documentation as a Competitive Advantage

Most agencies compete on price, speed, or design quality. We compete on handoff quality.

When a founder is evaluating agencies, they're thinking about the build. They should be thinking about what happens after the build. The cheapest agency delivers code you can't maintain. The most expensive agency delivers code with golden handcuffs - everything works, but only they know how.

We aim for the middle: production-quality code with documentation that makes us replaceable. It's a weird pitch. "Hire us because you'll never be stuck with us." But it's the pitch that wins repeat business.

The founders who've been burned by bad handoffs before understand this immediately. The ones who haven't been burned yet learn eventually. We'd rather they learn from our blog post than from a EUR 15k lesson.

Frequently Asked Questions

What format do you use for documentation?

All documentation ships as Markdown files in the project repository. No external wikis, no Notion links that expire, no Google Docs with broken permissions. Markdown lives with the code, gets version-controlled with the code, and stays accessible as long as the repository exists. We use Mermaid diagrams for architecture visuals so they render directly in GitHub.

How do you keep documentation updated during development?

Documentation updates are required in pull requests that change the relevant system. If a PR adds a new API endpoint, the API docs must be updated in the same PR. If a PR changes the deployment process, the runbook gets updated. Code reviewers check for doc updates as part of the review. It's a process rule, not a suggestion.

Do you provide documentation for smaller projects like marketing sites?

Yes, but scaled down. A EUR 5k marketing site doesn't need 7 documents. It gets a setup guide, deployment runbook, and CMS usage guide (if applicable). The principle is the same: anyone should be able to maintain it without calling us. The depth scales with project complexity.

Can we hire you just for documentation of an existing project?

We've done this twice. It's harder than documenting a project we built because we're reverse-engineering decisions instead of recording them in real-time. Budget roughly EUR 5k-10k depending on codebase size. The output is the same 7-document package, but the ADRs will say "likely reasoning" instead of "actual reasoning" for decisions we weren't part of.

*Want to see what a proper handoff looks like? Book a 30-minute call and we'll walk you through a real documentation package from a recent project. Or explore our services to see how harness engineering fits into every engagement.*