DEV Community

Ivan Wang
Ivan Wang

Posted on

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

#ai #agents #documentation #cli

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

One command builds everything:

npx agents-md compose
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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!

Top comments (0)