I Stopped Writing Onboarding Docs.

I Built an Agent That Reads Live Code Instead.

Engineering · AI Tools · Developer Experience

In 10 years of building software, I’ve seen the same problem repeat on every team.
A new engineer joined our team on a Monday.

By Thursday, they were deep in a debugging session tracing a flow through a service that had been renamed and restructured three months earlier.

The onboarding document they were following had no idea.

It described a version of the codebase that no longer existed.

Nobody had updated it not because anyone was careless, but because the sprint had not stopped for documentation. It never does.

That engineer lost two days.
A senior engineer lost half a day helping them reorient.

I had seen this pattern enough times to stop treating it as an execution problem.

It was a structural one.

So I stopped trying to fix documentation and started engineering around it.

Documentation Is Fighting Physics

The usual fixes are predictable:

• Assign documentation owners
• Add doc updates to the definition of done
• Schedule periodic reviews

Every team tries some version of this.

And every team eventually fails.

Because this isn’t a discipline problem. It’s a physics problem.

Code moves faster than prose.

In a team shipping weekly:

• Services get refactored
• APIs evolve
• Flows change

And every document that references them begins to decay.

Not all at once.

Just enough to become dangerous.

A sentence here.
A diagram there.
A flow that’s almost correct.

That’s worse than no documentation because it creates false confidence.

The Real Problem

Documentation is static.

Code is dynamic.

We’ve been trying to use a static artifact to represent a constantly changing system.

That model doesn’t work.

No amount of process improvement will fix it.

The Shift: Prompts, Not Documents

Watch how a senior engineer actually explains a system:

They don’t open a wiki.

They:

• Open the code
• Trace execution paths
• Follow data flow
• Explain what exists right now

The knowledge transfer is live.

That’s the key insight:

The source of truth is not the documentation.
The source of truth is the code.

So the question becomes:

What if an AI could do that on demand?

Not from memory.
Not from outdated docs.

But by reading the live codebase every time.

The System: An Onboarding Agent

I built an onboarding agent using Windsurf IDE workflows.

Each workflow is just a markdown file stored in the repo.

When an engineer runs:

/onboarding

The agent activates and begins executing structured missions:

• Scans the codebase
• Maps architecture
• Traces feature flows
• Builds diagrams
• Verifies understanding

Everything is generated from live code.

Nothing is hardcoded.

The Design Principle That Makes It Work

Every instruction follows one rule:

Use discovery language. Never assumptions.

Good:

• “Scan the solution and map dependencies”
• “Trace the flow from entry point to data store”

Bad:

• “Open this file”
• “Check this service”

Why it matters:

• Hardcoded paths decay
• Discovery adapts

The agent always finds what exists today.

The Architecture: 5 Layers of Understanding

The onboarding is structured as a progressive journey.

Layer 1- Orient

Before opening a single file:

• Project inventory
• Architecture diagram
• Dependency graph
• Middleware execution flow

The engineer builds a mental map first.

Layer 2- Understand

The agent maps:

• Data sources
• Database schema
• API contracts
• External integrations

For large UI systems:

• Components are grouped by domain
• Each domain is explored separately

No overload. Just structured discovery.

Layer 3- Trace (Most Valuable)

This is where onboarding becomes real.

The agent generates:

• End-to-end sequence diagrams
• Method-level flow tracing
• Data movement across services
• Error paths

Not from documentation.

From actual code execution paths.

Layer 4- Own

Before writing code, the engineer learns:

• Change impact analysis
• Dependency mapping
• Risk identification

They answer:

“If I change this, what breaks?”

This is where junior engineers start thinking like seniors.

Layer 5- Master

Covers what code doesn’t explain:

• Architectural decisions
• Extension patterns
• Known pitfalls (“gotchas”)

This is the tribal knowledge layer captured once, reused forever.

What the Team Maintains vs What Generates Itself

This is where the model becomes scalable.

Maintained by Humans

• Project context
• Feature flow names
• Decision logs
• Gotchas

Generated Automatically

• Architecture diagrams
• Dependency graphs
• API inventories
• Sequence flows
• Impact analysis

The result:

Less than 1 hour/month of maintenance.

Everything else stays accurate because it regenerates from code.

The Voice Layer (Practical, Not Fancy)

One useful addition:

The agent can speak summaries aloud.

Why?

Because engineers often:

• Look at diagrams
• Read explanations

Splitting attention slows comprehension.

Voice removes that split.

Implementation (No Paid APIs)

• Uses Microsoft Edge TTS
• Installed via pip install edge-tts
• Triggered directly from workflow

No API keys.
No cost.
No external dependencies.

What Actually Changed

Before:

• Engineers trusted docs
• Docs were outdated
• Confusion → escalation → wasted time

After:

Questions changed.

From:

“I don’t understand where this starts”

To:

“I traced this flow and expected X, but I’m seeing Y why?”

That shift matters.

It means:

• Engineers arrive with context
• Discussions become deeper
• Onboarding becomes faster

The Bigger Shift

This isn’t just about onboarding.

It’s about redefining documentation.

We’ve been trying to:

• Write better docs
• Enforce better processes

But the real solution is simpler:

Stop writing documentation that can go stale.

Let the code remain the source of truth.

Let AI interpret it on demand.

The Outcome

• No outdated onboarding docs
• No silent misinformation
• No repeated orientation cycles

Just:

• Live understanding
• Generated in real time
• Always aligned with current code

One Honest Caveat

This implementation uses Windsurf IDE workflows.

The concept is portable.

But the execution especially slash-command activation is Windsurf-native.

Final Thought

Documentation didn’t fail because engineers didn’t try hard enough.

It failed because we were solving the wrong problem.

The fix isn’t better documentation.

It’s eliminating the need for it.