You’ve spent hours polishing that README. Diagrams. API references. The perfect ‘onboarding guide’ for any developer. Then you watch your AI coding assistant generate code that completely contradicts every rule you carefully documented. Sound familiar?
It’s not your writing. It’s your assumption. You thought AI agents would want to read your docs. They don’t. They skip them. They treat your documentation like a billboard on a highway — existing, but irrelevant.
I found this out the hard way. I maintain a tool called trigger-tree, an open-source plugin for Claude Code that logs exactly which project files the AI agent actually opens. No cloud, no tokens, just raw truth. And the truth stung: most of my carefully written docs were never even glanced at by the agent.
Let that sink in. You’re writing documentation for a reader that doesn’t exist. The AI isn’t a human. It doesn’t get bored, curious, or motivated. It only reads what it’s required to read.
If an AI doesn’t read your docs, they are effectively dead code.
That’s the realization that changed everything. We write tests for our application logic to ensure it’s executed. Why wouldn’t we do the same for our documentation? If an AI agent is supposed to follow a style guide, a database schema convention, or a deployment checklist, how do we know it actually consumed that information?
Until now, we didn’t. We just hoped. And hope is not a deployment strategy.
So I built a CI gate. Today, trigger-tree is available as a GitHub Action. It runs during your pipeline, checks which documentation files the AI agent has opened in the last N commits, and fails the build if the coverage is below a threshold. You get a red X if the AI ignored your latest docs update. Simple. Brutal. Effective.
Think of it like a test coverage report — but for context. You’re not testing code; you’re testing comprehension. Did the AI agent actually read the STYLE_GUIDE.md before generating that PR? The CI gate knows.
This is not about punishing the AI. It’s about aligning incentives. Right now, AI agents optimize for speed and token efficiency. They’ll skip reading documentation because it’s cheaper. Your job is to make skipping expensive.
One developer I know told me, ‘I spent two weeks writing a migration guide. The AI kept generating old syntax. I thought it was a model issue. Turns out, it never opened the file.’ That’s the kind of frustration that drives this. We’re not fighting the AI. We’re fighting our own assumptions about how AI consumes information.
The golden rule of documentation for AI: Write it. Then enforce it. If you can’t verify that the agent read it, you might as well have written it in invisible ink.
This isn’t just about a GitHub Action. It’s a new category of developer tooling: AI-readiness verification. As AI coding assistants become the default way to write software, the doc that isn’t enforced is the doc that doesn’t exist. Your CI pipeline should ask: ‘Did the agent see the context it needs?’ If the answer is no, stop the build.
I’m not saying every doc needs a gate. But the critical ones — the ones that define architecture, security rules, and standards — those need teeth. A CI gate is the simplest way to give them bite.
Documentation without verification is just a wish.
Try trigger-tree. Add the GitHub Action. Set a minimum coverage threshold. Watch your AI agent finally start reading the docs you worked so hard to write. Because the best documentation is the one that’s actually consumed.
FAQ
Q: Isn't this overkill? Can't the AI just infer documentation from the codebase?
A: No. AI models are not omniscient. They rely on context windows, and if a style guide or architectural decision is not in the active context, the model will default to its training data — which may be outdated or wrong. Forcing the agent to open the doc ensures the right context is actually loaded.
Q: How do I practically implement this CI gate?
A: Add the trigger-tree GitHub Action to your workflow. It scans logs from the agent (e.g., Claude Code) to see which files were opened. Set a threshold — e.g., 80% of your docs must be opened per session. If the agent missed the critical doc, the build fails. You can also configure it to only gate on specific files like STYLE_GUIDE.md or SECURITY.md.
Q: Won't this just make the AI open the file without reading it?
A: Opening the file is the first step. The AI will read at least part of it to process the token count. If you want deeper verification, you can chain this with a check that the agent's output references specific rules from the doc. But as a baseline, requiring the file to be opened is a massive improvement over the current 'hoping it reads it' approach.