Stop Fighting Your AGENTS.md File: A Better Way to Scale AI Agent Documentation

Ivan Wang — Mon, 15 Sep 2025 14:39:31 +0000

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.md automatically
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