This content originally appeared on DEV Community and was authored by Ivan Wang
GitHub: https://github.com/ivawzh/agents-md
Your AGENTS.md started innocent enough—maybe 50 lines of clean context. Six months later? It's a 5,000-line beast that nobody wants to touch.
The Problem Every AI Team Hits
project/
├── AGENTS.md ← 5000+ lines, merge conflicts, stale info
├── docs/ ← team avoids updating the monster
└── api/ ← context scattered everywhere
Reality check: Massive single files don't scale. Your team gets merge conflicts, information goes stale, and agents get overwhelmed with irrelevant context.
The Solution: Composable Agent Context
What if you could organize agent context like code? With modules, clear boundaries, and automatic composition?
agents-md lets you split context into focused fragments, then auto-composes them into clean AGENTS.md files wherever you need them.
project/
├── AGENTS.md ← auto-generated, always fresh
├── docs/overview.agents.md ← team docs agents can read
├── api/
│ ├── AGENTS.md ← API-specific context
│ └── endpoints.agents.md ← focused fragments
└── agents-md/epics/
├── epic-one.md ← feature-specific context
└── epic-two.md ← easy to maintain
One command builds everything:
npx agents-md compose
Key Features
-
Smart targeting: Fragments route to nearest
AGENTS.mdautomatically - Zero config: Works out of the box, customize only what you need
- Flexible organization: Use any file structure that makes sense
- Priority ordering: Control what appears first with simple directives
Get Started in 60 Seconds
# Install and initialize
npm install -D agents-md && npx agents-md init
# Create a fragment
echo "# API Guidelines..." > docs/api.agents.md
# Compose everything
npx agents-md compose
Done! Your AGENTS.md now includes content from fragments and stays in sync automatically.
Why This Matters Now
Every AI team hits this scaling problem. We're seeing explosive growth in agent projects, but tooling hasn't caught up. This is infrastructure every AI company will need.
Try It Today
Fighting with unwieldy documentation? Give it a shot:
npm i -D agents-md && npx agents-md init
GitHub: https://github.com/ivawzh/agents-md
What agent documentation pain points are you dealing with? Let me know in the comments or on GitHub!
This content originally appeared on DEV Community and was authored by Ivan Wang
Ivan Wang | Sciencx (2025-09-15T14:39:31+00:00) Stop Fighting Your AGENTS.md File: A Better Way to Scale AI Agent Documentation. Retrieved from https://www.scien.cx/2025/09/15/stop-fighting-your-agents-md-file-a-better-way-to-scale-ai-agent-documentation/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.