The Documentation We Never Wrote

LLMs require explicit instructions. They can't read your mind, interpret social cues, or adapt to unspoken team conventions. Every architectural decision needs to be documented. Every coding standard must be spelled out. Every business rule requires clear articulation.

This isn't an LLM limitation – it's good engineering practice we've often been too lazy to implement. (And I've been using the em dash since years in manual typing, it's Alt-Gr+- on Linux.)

For my current MVP, I've essentially condensed the best parts of the Qafoo blog about object-oriented PHP principles into a single document. I've written down patterns that I'd normally communicate through code reviews and conversations.

The result? The clearest technical direction I've ever provided to any "team member."

The Coaching We Should Always Do

Here's my current LLM primer: "Be critical about suggestions and don't just agree with me. Really evaluate ideas. Be optimistic, critical and solution oriented."

Sound familiar? That's exactly what I should tell every developer I hire, and basically also in every meeting before we start talking. But I don't (always), because I assume they'll figure it out through context and experience.

With humans, I rely on:

• Osmosis through pair programming

• Formal feedbacks in 1:1s and training sessions

• Learning from failed pull requests

• Picking up patterns from senior team members

• Informal feedback during coffee chats

LLMs force me to be explicit about expectations I've always held but never articulated (while we even blogged about them). The result is better guidance for artificial intelligence – and probably better guidance for human intelligence too.

The Standards We Compromise On

Working with LLMs makes errors immediately obvious. A 30-60% failure rate forces you to invest in clear specifications, comprehensive testing, and robust review processes.

With human teams, mistakes are subtler and less frequent. Good developers self-correct. Senior engineers catch issues before they ship. The system works well enough that we don't invest in the infrastructure to make it work excellently.

But what if we applied LLM-level discipline to human teams?

• Explicit architectural decision records for every major choice

• Written coding standards instead of a document updated every two years

• Clear business requirements documents instead of Jira conversations

Human developers are better at filling gaps and working around unclear requirements. This is usually helpful, but it can mask underlying problems with product definition or technical communication and even lead to more subtile bugs.

Scaling Through Documentation

Twenty years of team leadership has taught me that knowledge transfer is the one of the hardest part of scaling engineering organizations. Tribal knowledge lives in senior developers' heads. Context gets lost when people leave. New team members struggle to understand unwritten conventions.

LLMs can't rely on institutional knowledge or social context. They need everything written down clearly. This constraint forces you to create the documentation infrastructure that makes human teams scale better too.

The Uncomfortable Truth

Most engineering teams operate on shared understanding, implicit knowledge, and good intentions. This works until it doesn't – usually around 15-20 people, when informal communication breaks down.

LLMs require the explicit processes that high-performing large teams eventually develop anyway. They just force you to develop them upfront instead of retrofitting them during a scaling crisis.

Maybe the real value of coding with LLMs isn't the code generation. Maybe it's finally building the engineering practices we should have had all along.

The technology is temporary. The discipline is permanent.