AI Agents Files: Context, Build Specs, Markdown
This is just an open thought/notes post — using agents specifications files in an AI development environment.
These kind of files are written in Markdown, and can do some of these kind of things:
- Project documentation
- Anything from testing, code narration, code structure, dependencies that an AI tool can read to assist in code generation or help.
- Structured input to LLMs
- Agent guidance — i.e. infor and context about your development environment, project settings
There’s an emerging standard, open source, called AGENTS.md. Here’s their first page sample:
# AGENTS.md ## Setup commands - Install deps: `pnpm install` - Start dev server: `pnpm dev` - Run tests: `pnpm test` ## Code style - TypeScript strict mode - Single quotes, no semicolons - Use functional patterns where possible
These can become very complicated. I’ve ran some tests developing a desktop image environment for VM Ware, and have specified a ton of applications, OS, etc. in these files.
Here is some of my experiment. It’s quite easy to generate such a file, and I was asking it to create a packer instance for VMWare”
# DVM Virtual Dev Environment ## Project Overview This project creates a Ubuntu 24.04.3 desktop virtual machine using HashiCorp Packer and VMware. The VM is pre-configured with development tools including Visual Studio Code and IntelliJ IDEA Community Edition. ## Purpose - Build standardized development environments - Automate VM provisioning with consistent tooling - Provide reproducible Ubuntu desktop environments for development work ## Key Components ### Packer Configuration (`ubuntu-desktop.pkr.hcl`) - **Base Image**: Ubuntu 24.04.3 Desktop AMD64 ISO - **Platform**: VMware (vmware-iso builder) - **Resources**: 4GB RAM, 2 CPUs, 40GB disk - **Authentication**: SSH with ubuntu/ubuntu credentials ### Provisioning The build process installs: **Development Tools:** - Microsoft Visual Studio Code - IntelliJ IDEA Community Edition - Docker Desktop - Postman - MySQL Workbench Community
But also — this remembers a lot of context.
Amazon has the same ides — rules for their “spec driven development” approach. Will probably discuss later as I have questioned them about the lifecycle of biz rules in a development cycle, but, generally stores all the info of your dev environment for your project. Generally, is stored in .amazonq/rules, though can be in a file like amazonq.rules.
Also Anthropic has the CLAUDE.md file, which is like AGENTS. It’s loaded at startup to give your agent context, among other things. There is also use of a json file for settings.
From CLAUDE site:
Key points about the configuration system
- Memory files (CLAUDE.md): Contain instructions and context that Claude loads at startup
- Settings files (JSON): Configure permissions, environment variables, and tool behavior
- Slash commands: Custom commands that can be invoked during a session with
/command-name- MCP servers: Extend Claude Code with additional tools and integrations
- Precedence: Higher-level configurations (Enterprise) override lower-level ones (User/Project)
- Inheritance: Settings are merged, with more specific settings adding to or overriding broader ones
Note that these other AI agents will in fact read AGENTS.md, even if they put up a fight against you. Also, be aware that in general you’ll eventually be checking in and maintaining these files for your projects.
Thoughts. Well, after working with these, it’s nice to have a context on loadup mechanism. It would be nice to share among other developers. That said, I wonder how this is going to play into the specs in maven, ivy, ant, gradle etc. files. Why not just read those files, instead of in some cases having a double entry?
And since this is now emerging, there are several standards — am guessing if you ever switch AI providers it could convert the standards (from say Q rules to CLAUDE) with no fuss. It had better, being that conversions seems to be one of the AI strongpoints.
Another really nice related mechism is experimenting with saving chat contexts from the IDE. Amazon has something like this, and Claude can remember as well — but you could technically store prompt history offline, even incorporate the best answers into the md files.
Best thing is to try all of this out.
References:
Further Reading:
There are mentions of Jupyter notebooks in much of the MD config documentation. I didn’t discuss this here, but you can of course explore it more.