I was sitting in a demo from the head of architecture when the problem clicked into focus. He was showing how his team had moved everything out of Confluence and into Markdown files. Not because they loved Markdown. Because their AI couldn't read Confluence.
The room went quiet ... Forty pages of style guides, conventions, architectural decisions ... all sitting in a system the AI couldn't parse. The documentation wasn't missing. It was invisible.
That was the moment I understood why my early AI output had been so sloppy.
The Slop Problem
When I first started using AI coding assistants, I was frustrated by the inconsistency. One function would use camelCase, the next would snake_case. Error handling patterns I thought were established appeared nowhere. Imports from packages we'd explicitly banned showed up without comment.
I blamed the AI. Poor training. Alignment issues. The usual suspects.
What I didn't see ... what took that demo to reveal ... was that the AI wasn't ignoring our standards. It couldn't see them. We had documented everything. Written it all down. Formatted it beautifully. But we'd written it in a language the AI didn't speak.
The documentation wasn't missing ... It was invisible.
Confluence Is Where Standards Go to Die
The architecture head explained the migration: move standards from Confluence into Markdown files in the repo. Not because Markdown is better for humans. Because Markdown is readable by Claude, by Cursor, by the constellation of AI tools his team was now using.
Think about what this means ... We spent years building documentation systems designed for human consumption. Formatted pages. Organized hierarchies. Approval workflows. And we told ourselves these were standards.
They weren't. They were wish lists.
A standard isn't what you write down ... It's what your systems can enforce. What your tools can reference. What actually shapes the code that gets written. If your AI can't read it, it's not a standard. It's decoration.
The Persona Solution
What the architecture team did next was instructive. They didn't just move documents. They redesigned how standards lived in their system.
First, they made sure their standards were actually documented. Sounds obvious, but plenty of teams skip this step. The tribal knowledge exists in heads, in Slack threads, in "that's not how we do it here" comments on PRs. You can't encode what you haven't written.
Then ... and this is where it gets interesting ... they brought those standards into the AI's context. Skills, rules, agents, hooks. The AI needed to learn the house style, so they built a curriculum and fed it into the system.
The metaphor clicked: throwing an engineer onto a team without giving them the style guide is unfair. Giving an AI access to your codebase without giving it your standards is the same mistake. You're asking it to succeed blind.
What Gets Referenced
This shift changes what documentation means. Before, you needed standards in Confluence because that's where humans looked things up. Now you need them in Markdown files because that's what Claude, Cursor, and the rest can reference.
The format isn't arbitrary ... Markdown is parseable. It's structured without being rigid. It's the intersection of human-readable and machine-readable, and that intersection is where modern standards have to live.
But there's a trap here: moving documents isn't the same as maintaining them.
The Drift Problem
Two failure modes I see constantly:
Style guides that exist but don't evolve
The team wrote them once, celebrated the effort, and never updated them again. Standards changed. Patterns emerged. The documentation fossilized. Now when your AI references the Markdown files, it's reading history, not guidance.
Confluence pages that became graveyards
Standards at one point, ignored for years. The URL still works ... The page still loads ... Nobody's looked at it since 2022. If you migrate these to Markdown without audit, you're just giving your AI a bigger cemetery to reference.
If you migrate standards without audit, you're just giving your AI a bigger cemetery to reference.
The Choice
The architecture demo ended with a simple observation: AI is going to output something ... You can get slop, or you can get coherence. The difference isn't the model. It's the context you give it.
Forty pages of style guide in Confluence is context that doesn't exist. Forty pages of Markdown in your repo is context the AI can learn from. Same content ... Different accessibility ... Completely different outcomes.
I think about my early frustration with AI slop differently now. It wasn't the AI's fault. It was mine. I'd documented standards the AI couldn't read, then blamed the AI for not following them.
The documentation was there. The standard wasn't.
One email a week from The Builder's Leader. The frameworks, the blind spots, and the conversations most leaders avoid. Subscribe for free.
Top comments (0)