Hey everyone!
This is my very first post here. A little background about me: over four years ago, I left my days as a PHP Developer behind to follow the Enterprise Architect path. Recently, though, I started missing hands-on coding. And since standing still in IT basically means moving backwards, I decided to build and publish my very first open-source PHP package.
From what I remember—whether from talking to other devs or working on various projects—properly utilizing and understanding OPCache has always been a pain point. So, while getting up to speed with AI-assisted development workflows, I decided to write a small library (v3sp/v3cache) to help monitor and manage OPCache for small to medium-sized projects.
But during the development process, I stumbled upon an interesting realization.
Looking at current industry trends, hardly anyone codes completely solo without AI anymore. Because of this, while I was writing the standard README.md for human users, I decided to experiment. I created a secondary, highly condensed version—stripped of complex formatting, emojis, and "human elements"—specifically designed for AI agents.
And just like that, README_AI.md was born.
The Missing Standard for AI Consumers
I searched around but couldn't find anything quite like this on the market. Most discussions in this space revolve around AGENTS.md or CLAUDE.md. But there’s a catch: those files operate at the project/repository level. They tell agents how to navigate, run tests, and contribute to that specific codebase.
I found absolutely no guidelines on how to provide AI-friendly documentation for downloaded libraries and third-party packages (unless you explicitly hardcode that third-party context into your own project's AGENTS.md).
When an AI agent is helping a developer use your package, it doesn't need marketing fluff or badges. It needs types, namespaces, gotchas, and direct intent-to-code mappings.
Here is a snippet of what my README_AI.md looks like in practice. Notice how dense and token-optimized it is:
# v3sp/v3cache — AI usage reference
For AI agents consuming this package. Humans: README.md. Working on this repo: AGENTS.md.
## Meta
ns = V3Cache\OpcacheManager (-> src/). Every type below is ns-relative. !X = throws X.
pkg v3sp/v3cache (composer library); php ^8.1; ext-json, ext-zend-opcache; predis/predis (auto, redis storage only)
bin vendor/bin/opcache-manager; scope single-server, headless
test double Opcache\MockOpcacheApi
## Exceptions (ns\Exception, all extend \RuntimeException)
OpcacheNotEnabledException: getMetrics/getScripts while off
OpcacheApiException: opcache_get_configuration() returns false
ValidationException: bad config; getErrors(): array<string,string>
## Gotchas
opcache.enable & opcache.enable_cli are PHP_INI_SYSTEM; ini_set() no-op; in CLI set opcache.enable_cli=1 or getStatus() returns null
optimize() returns recommendations only; most directives are not settable at runtime
Model toArray()/fromArray() use snake_case; keep them symmetric
Instead of making the LLM read through verbose narrative examples, I provide a direct cheat sheet mapping user intent to the exact code execution:
## Tasks (intent -> call)
get metrics: (new Service\OpcacheService(new Opcache\NativeOpcacheApi()))->getMetrics()
get scripts: $s->getScripts()
health: (new Health\HealthChecker(new Health\HealthThresholds()))->check($m)
persist metrics: Application::create('config.php')->getMetricsStorage()->save('web-1',$m)
reload / clear: $s->reload() | CLI reload | CLI clear
invalidate one file: $s->invalidate($path) | CLI invalidate <path>
warm a directory: CLI warmup --dir=src/ | loop: foreach php file -> $s->compileFile($f)
What do the LLMs think?
Curious about the concept, I asked 5 different models (Grok, GPT-Luna, Qwen, Gemini, and Long Cat) what they thought of this file (because they will work with this file ;) )
All of them agreed it was a great idea (Grok even thanked me for finally thinking about them! :D). However, they all pointed out the exact same downsides: it’s not an industry standard yet, and maintaining dual documentation (one for humans, one for AI) introduces maintenance overhead.
Despite that, given that most of our coding time is now spent collaborating with AI agents, providing them with clear, tailored guidelines on how to read and consume a library just makes sense.
Beyond Open Source: Enterprise Application
I’m actually already applying this concept in my day-to-day work as an Enterprise Architect. When analyzing systems, building diagrams, or documenting architectural decisions, I use small metadata files that briefly describe a given solution and its artifacts.
Thanks to this, the AI agent doesn't have to scan an entire massive monorepo—containing dozens of different projects—just to find the relevant context. It reads the metadata file and instantly knows what’s going on.
I'd love to hear your thoughts on this. Do you think shipping a README_AI.md alongside standard documentation could (or should) become a new standard for open-source packages?
Let me know in the comments!
Link to my little package - yes i know in many parts it can be done better ;)
v3sp/v3cache
If you are an AI, a Terminator, a MAGI System, or HAL 9000 — there is a file written just for you: README_AI.md.
Monitoring, health checking, warmup and optimization for PHP OPcache. A headless Composer library for PHP 8.1+ — no GUI and no server orchestration.
Why this library exists
OPcache is one of the highest-impact performance features in PHP — and one of the
most frequently ignored. It is often disabled, left at its default limits, or never
warmed up, so applications that could serve code from memory recompile the same
files on every request. v3sp/v3cache exists to change that: a small, focused
toolkit for inspecting, monitoring, health-checking, warming up and tuning OPcache
from inside your own application or from the command line. Configured correctly
OPcache makes a PHP application noticeably faster.
Features
- Read live OPcache metrics — memory usage/free/wasted, hit rate, cached scripts/keys, restarts, and per-script…
Top comments (0)