AGENTS.md

Understanding the primary output file.

What is AGENTS.md?

AGENTS.md is a single markdown file that teaches AI coding assistants how to work safely in your codebase. It's the primary output of Aspect Code.

Every major AI coding tool — GitHub Copilot, Cursor, Claude Code, Windsurf, Cline, Gemini, Aider — reads AGENTS.md automatically when it's present in your project root.

What's inside

AGENTS.md contains sections generated from static analysis of your codebase:

Section	What it captures
Project Overview	Languages, framework, directory structure
Architecture Rules	Hub modules with blast radius, entry points, layer boundaries
Conventions	Naming patterns, import rules, file organization
Co-edit Clusters	Files that change together and should be updated as a group
Do/Don't Rules	Specific guardrails — what to avoid, what to always do

The file also includes any custom instructions you've written, and complements (without duplicating) any existing AI config files in your project.

How it works with existing AI config

If your project already has AI instruction files like .cursorrules, CLAUDE.md, .windsurfrules, GEMINI.md, or CONVENTIONS.md, Aspect Code reads them and ensures AGENTS.md complements rather than duplicates what's already there.

This means you can adopt Aspect Code without losing your existing customizations.

Editing AGENTS.md

AGENTS.md is plain markdown. You can:

Read it to understand what your AI assistants are seeing

Edit it to add project-specific rules or override generated sections

Diff it to see how your project's architecture has evolved

Commit it so your whole team benefits

When Aspect Code regenerates (in watch mode or manually), it preserves your manual edits in clearly marked custom sections.