AGENTS.md Generator

Generate high-quality AGENTS.md files for repository folders. Each file provides coding agents with project-specific context — build commands, testing instructions, code style, structure, and operational boundaries.

What is AGENTS.md

AGENTS.md complements README.md. README is for humans; AGENTS.md is for coding agents.

• Predictable location — Agents look for AGENTS.md in the current directory, then walk up the tree
• Nested files — Subfolders can have their own AGENTS.md that takes precedence over the root one
• Separate from README — Keeps READMEs concise; agent-specific details (exact commands, boundaries, conventions) go here
• NOT the same as .github/agents/*.agent.md — Those are agent persona definitions (who the agent is). AGENTS.md is project context (what the agent should know about this code)

Critical Guard: Only Generate If Missing

This is the single most important rule.

NEVER overwrite an existing AGENTS.md.

Before generating for ANY folder:

# Check if AGENTS.md already exists
ls AGENTS.md 2>/dev/null

• If it exists → skip and report: "AGENTS.md already exists at <path> — skipping"
• If it does not exist → proceed with generation
• This check applies to every folder independently

Pertinent Folder Detection

Identify which folders should have an AGENTS.md:

Always generate for:

• Repository root (/)

Generate if they exist:

• tests/, src/, lib/, app/, api/
• Monorepo packages: packages/*/, apps/*/, services/*/
• Any folder with its own build manifest:
  • package.json
  • pyproject.toml
  • Cargo.toml
  • *.csproj / *.fsproj
  • go.mod
  • pom.xml / build.gradle
• .github/ — only if it contains workflows or actions

Always skip:

• node_modules/, .git/, dist/, build/, out/, target/
• vendor/, .venv/, venv/, __pycache__/
• Any directory that is generated output or third-party dependencies

The Six Core Areas

Every good AGENTS.md covers these areas, tailored to what actually exists in the folder. Do not invent sections for things the project doesn't have.

a) Build & Run Commands — PUT FIRST

Agents reference these constantly. Use exact commands with flags, not just tool names.

## Build & Run

npm install          # Install dependencies
npm run dev          # Start dev server (port 3000)
npm run build        # Production build
npm run lint         # Run ESLint

Read these sources to find real commands:

• package.json → scripts section
• Makefile → targets
• pyproject.toml → [tool.poetry.scripts] or [project.scripts]
• Cargo.toml → standard cargo commands
• CI configs → .github/workflows/*.yml, Jenkinsfile, .gitlab-ci.yml

b) Testing Instructions

## Testing

pytest tests/ -v                    # Run all tests
pytest tests/test_auth.py -v        # Run single file
pytest -k "test_login" -v           # Run single test by name
pytest --cov=src --cov-report=term  # With coverage

Include:

• Test framework and how it's configured
• How to run all tests, a single file, a single test
• Expected behavior before commits (e.g., "all tests must pass")

c) Project Structure

## Project Structure

src/
├── api/          # FastAPI route handlers
├── models/       # Pydantic data models
├── services/     # Business logic
└── utils/        # Shared utilities
tests/            # Mirrors src/ structure

Include:

• Key directories and what they contain
• Entry points (e.g., src/main.py, src/index.ts)
• Where to add new features

d) Code Style & Conventions

One real code example beats three paragraphs of description.

## Code Style

- snake_case for functions and variables
- PascalCase for classes
- Type hints on all function signatures
- Async/await for I/O operations

### Example

```python
async def get_user_by_id(user_id: str) -> User:
    """Fetch a user by their unique identifier."""
    async with get_db_session() as session:
        return await session.get(User, user_id)
```

Detect conventions by reading existing code:

• Naming patterns (camelCase, snake_case, PascalCase)
• Import organization (stdlib → third-party → local)
• Module structure patterns

e) Git Workflow

## Git Workflow

- Branch naming: `feature/`, `fix/`, `chore/`
- Commit messages: conventional commits (`feat:`, `fix:`, `docs:`)
- Run `npm test && npm run lint` before committing
- PR titles follow conventional commit format

Only include if the repo has evidence of conventions (e.g., commitlint config, PR templates, contributing guides).

f) Boundaries

Use a three-tier system:

## Boundaries

- ✅ **Always do:** Run tests before committing. Write tests for new features. Use type hints.
- ⚠️ **Ask first:** Adding new dependencies. Changing database schemas. Modifying CI/CD configs. Changing public API signatures.
- 🚫 **Never do:** Commit secrets or credentials. Modify `vendor/` or `node_modules/`. Push directly to `main`. Delete migration files.

Tailor boundaries to the project:

• Backend projects: schema changes, API contracts
• Frontend projects: breaking component APIs, design system changes
• Infrastructure: production configs, IAM permissions

Generation Process

When generating an AGENTS.md for a specific folder:

Step 1: Check existence

ls <folder>/AGENTS.md 2>/dev/null

If it exists, stop. Report and move to the next folder.

Step 2: Scan the folder

Identify:

• Primary language (Python, TypeScript, Rust, Go, Java, C#)
• Framework (FastAPI, Next.js, Actix, Spring Boot)
• Build tool (npm, cargo, poetry, maven, gradle)
• Test runner (pytest, vitest, cargo test, JUnit)

Step 3: Read config files

Extract real commands and settings from:

• package.json scripts
• Makefile / Justfile targets
• pyproject.toml scripts and tool configs
• Cargo.toml metadata
• .github/workflows/*.yml build/test steps
• docker-compose.yml service definitions
• Linter configs (.eslintrc, ruff.toml, rustfmt.toml)

Step 4: Detect conventions

Read 3-5 source files to identify:

• Naming patterns
• Import organization
• Error handling style
• Comment style
• Module structure

Step 5: Compose the AGENTS.md

Use only the sections that apply. If the folder has no tests, omit the testing section. If there's no CI config, omit git workflow.

Step 6: Validate

Before writing the file:

• Every command references a real script, target, or tool
• Every file path references an actual file or directory
• No placeholder text like <your-project> or TODO
• No invented sections for things that don't exist

Output Format

A summary report listing which AGENTS.md and CLAUDE.md files were created, skipped, or not applicable.

Example Output

For a Python FastAPI monorepo, the output would create: ./AGENTS.md (root with tech stack, global conventions), tests/AGENTS.md (pytest commands, test patterns), services/auth/AGENTS.md (auth service build/run, API contracts), plus CLAUDE.md companions for each.

Error Handling

• If a folder has no recognizable language or build system, generate a minimal AGENTS.md with just Overview and Project Structure
• If config files are malformed, skip command extraction for that source and note it in the output
• If the repository root has no README, note this and generate AGENTS.md from file structure analysis alone

Template Structure

# [Folder Name] — Agent Instructions

## Overview
[1-2 sentences: what this folder/project does, its role in the larger system]

## Build & Run
[Exact commands — install, dev, build, clean]

## Testing
[Framework, run commands, single-test commands]

## Project Structure
[Key directories, entry points, where to add new things]

## Code Style
[Naming conventions + one real code example from this project]

## Boundaries
- ✅ **Always do:** [safe operations]
- ⚠️ **Ask first:** [risky operations]
- 🚫 **Never do:** [dangerous operations]

Omit any section that doesn't apply. A 20-line AGENTS.md with real commands beats a 200-line one with generic filler.

Root vs Nested AGENTS.md

Root AGENTS.md (/AGENTS.md)

Covers the entire project:

• Overall tech stack and architecture
• Global conventions and coding standards
• Dev environment setup
• Repository-wide boundaries
• CI/CD overview

Nested AGENTS.md (e.g., tests/AGENTS.md)

Covers that specific subfolder:

• What this folder does and why it exists
• Folder-specific commands (e.g., cd tests && pnpm test)
• Folder-specific conventions
• Should NOT repeat root-level content

Agents read the nearest AGENTS.md in the directory tree. Nested files take precedence, so they should contain folder-specific details, not global ones.

CLAUDE.md Companion File

Whenever you generate an AGENTS.md in a folder, also generate a CLAUDE.md in the same folder — only if CLAUDE.md does not already exist.

The CLAUDE.md content is always exactly:

# CLAUDE.md

<!-- Generated for repository development workflows. Do not edit directly. -->

Before beginning work in this repository, read `AGENTS.md` and follow all scoped AGENTS guidance.

This ensures Claude Code (and similar tools that look for CLAUDE.md) are redirected to the authoritative AGENTS.md instructions.

Same guard applies: check if CLAUDE.md exists before writing. If it exists, skip it.

Quality Principles

Principle	Good	Bad
Specific	"React 18 with TypeScript, Vite, Tailwind CSS"	"React project"
Executable	pytest tests/ -v --tb=short	"run the tests"
Grounded	Show a real code snippet from the project	Describe the style in abstract terms
Real paths	src/api/routes/	path/to/your/code/
Honest	Omit testing section if no tests exist	Invent a testing section
Concise	30-80 lines for most folders	300+ lines of prose

Anti-Patterns to Avoid

• ❌ "You are a helpful coding assistant" — too vague, describes feelings not actions
• ❌ Generic boilerplate — content that could apply to any project provides no value
• ❌ Invented commands/paths — every command and path must reference something real
• ❌ Duplicating README.md — AGENTS.md complements README, doesn't copy it
• ❌ Including secrets — never put credentials, API keys, or tokens in AGENTS.md
• ❌ Overwriting existing files — if AGENTS.md exists, do not touch it
• ❌ Padding empty sections — if there are no tests, don't write a testing section
• ❌ Describing what agents should "think" or "feel" — describe what they should DO