At Qred, we use vibe / agentic coding for small & medium complex tasks, we do agentic coding to improve our compliance work within the development space. It may sound contradictory when we talk about how AI will improve our compliance work, normally AI is a compliance issue, this is not the case if you think it through and do implement it in a systematic way.
We want to share how we solved it as our initial approach was somewhat unstructured due to some technical limitations but also a inconsistent structure made it hard for me as the CTO to centrally influence agentic behaviors or tasks. This made me rethink and to not rely on a specific agentic development product.
As of that, we want to share our experience on how we have implemented agentic coding in a systematic way, where agents.md is one part of it.
We have ~50 engineers, over 400 repositories, around 100 of them actively being worked on and 800+ serverless functions and 50 containers running in production supporting our business.
Agents.md is the new standard of agentic development instructions, a way to give context and set behaviours. When we started with the rollout, we had central instructions in copilot, but it had limitations on 1k chars, now extended to 4k as of the date of the article. Besides that you can add knowledge bases, it is very unclear on how they are used in practice but you also have the repo specific instructions in .github/copilot-instructions.md. As of the char limitations, we had a hard time to get this to work well, so we asked our teams to take the latest copy of the instructions and evolve it to their needs.
We knew already from the beginning that this will not scale but we will start here, most of the teams did not even add the instruction files in their repo. We thought of a way to build a script that would deploy and edit the local files of each repo but reality is more complicated with all different corner cases. We decided to leave copilot, where this was one of the reasons.
So, we switched to Claude code that only supported claude.md and we needed to think this through. Then we bumped over Agents.md, the new standard that is compatible across most of the agentic ide / cli tools besides Claude code, there is a feature request on it but it looks like anthropic have ghosted that need.
So, regardless, we want to be compatible with the standard but at the same time use the Claude. Both agents.md and claude.md format is compatible so we decided to make use of the file reference, so our claude.md files only states @agents.md. This makes us future proof and very easy to switch or mix and match between different agentic development IDE / CLI ass agents.md is the single source of truth.
Now to the tricky part, to get consistency in a systematic way across all repositories but at the same time have some flexibility as we use Javascript, Java and Python for different use cases and competences in different repositories. That means we need to have some central general instructions with principles and guidance, one for each language and the possibility to give instructions per repository.
With that requirement we then came up with the following structure,
A central repository named ai-development-instructions with general instructions (e.g. tech stack, security principles, API structure etc) and language specific instructions. Then for each local repository we use git submodules that allow us to include / link another repository as a sub-folder. Besides that we also have a file named agents-repo-specific.md to be able to give the local context of the repository such as how to run tests, how the specific folder/file structure looks like and some other logic.
So to sum it up, our agents.md in all repositories looks something like this:
# AI Instructions Manifest
To perform your task, you must follow the instructions synthesized from the following files.
## Latest version of ai-development-instructions git submodule
In each session start, run `git submodule update --remote --merge`to make sure you have latest version
## Central Instructions (linked in via git submodules)
@ai-development-instructions/organization-instructions.md
@ai-development-instructions/secure-development-instructions.md
@ai-development-instructions/java-v25-instructions.md
## Repository-Specific Instructions
@agents-repo-specific.md
And the ai-development-instructions folder is a separate repository in our organization (https://github.com/$orgname/ai-development-instructions) that is part of all repositories as a git submodule, so a change in the ai-development-instructions repository gets out to all other repositories when a git pull operation is done.
So this is now part of our blueprints when we setup new repositories and this gives me as the CTO powerful flexibility to change behaviours of how we now develop and ship code to production, something that gets harder when you have a bunch of repositories and engineers with different backgrounds and experiences.
Oh, by the way, this article was crafted by hand and not by AI.
Top comments (0)