AGENTS.md emerged as a way to share the same instructions with various AI agents and tools.
A lot of the major players like Cursor, VS code, Codex, Gemini cli, Windsurf are supporting it. Claude code has its own CLAUDE.md but is likely to join the rest of the industry given the increasing adoption of AGENTS.md - which will be great!
But even working with a single AGENTS.md, you soon realize there are 2 major challenges:
1- Maintainability
As models evolve and new versions come out, their coding styles change too and so should best practices and instructions to continually guide them understand our project needs. Meaning the best practices will constantly need to evolve alongside the code if they are to remain useful.
As a result, these static .md files grow larger and larger and become a maintenance nightmare.
2- Human-AI collaboration
AI is perhaps writing the majority of the code now and this trend will code now and this trend will more likely to continue but human engineers in the loop in the form of reviewers and approvers to deploy reliable and safe code is essential.
This makes it vital for both Human engineers and AI agents to share the same best practices to collaborate effectively.
But how "dev-friendly" are these .md files? 🤔
- It's hard to look for something in a .md file with 100+ lines
- They are inefficient to add context rich information e.g. code examples, illustrations etc to better guide AI agents in complex scenarios
Here comes Credos to the rescue 😀
Allowing us to:
1- Centralize our best practices - single source of truth for everyone in our team (including our AI agents)
2- Cut context bloat by providing the agent with relevant best practices only
3- Super easy to maintain and update instantly without any code deployments
And most importantly, it's agnostic to tools/AI agents giving us the freedom to explore and switch to different tools if need be.
Try it out for yourself: https://credos.dev