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 (/)
• Wiki folder (wiki/) — if generated by deep-wiki (has package.json with VitePress)

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

```markdown
## 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

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]

## Documentation
[Only include if wiki/, llms.txt, or docs/ exist in the repo]
- Wiki: `wiki/` — architecture, API, onboarding guides
- LLM Context: `llms.txt` — project summary for coding agents (full version: `wiki/llms-full.txt`)
- Onboarding: `wiki/onboarding/` — guides for contributors, staff engineers, executives, PMs

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

Wiki AGENTS.md (wiki/AGENTS.md)

ALWAYS check if wiki/AGENTS.md exists before generating — same only-if-missing guard as all other folders. If it exists, skip it.

Use this template (adapt to the actual project):

# Wiki — Agent Instructions

## Overview
Generated VitePress documentation site. Contains architecture docs, onboarding guides, and API references with source-linked citations and dark-mode Mermaid diagrams.

## Build & Run
- Install: `npm install`
- Dev server: `npm run dev`
- Build: `npm run build`
- Preview: `npm run preview`

## Wiki Structure
- `index.md` — Landing page with project overview and navigation
- `onboarding/` — Audience-tailored guides (contributor, staff engineer, executive, product manager)
- `{NN}-{section}/` — Numbered documentation sections
- `llms.txt` — LLM-friendly project summary (links + descriptions)
- `llms-full.txt` — LLM-friendly full content (inlined pages)
- `.vitepress/config.mts` — VitePress config with sidebar and Mermaid setup
- `.vitepress/theme/` — Dark theme (custom.css) and zoom handlers (index.ts)

## Content Conventions
- All Mermaid diagrams use dark-mode colors (fills `#2d333b`, borders `#6d5dfc`, text `#e6edf3`)
- Every page has VitePress frontmatter (`title`, `description`)
- Citations link to source repository with line numbers
- Tables include a "Source" column with linked citations
- Mermaid diagrams followed by `<!-- Sources: ... -->` comment blocks

## Boundaries
- ✅ **Always do:** Add new pages following existing section numbering, use dark-mode Mermaid colors
- ⚠️ **Ask first:** Change theme CSS, modify VitePress config, restructure sections
- 🚫 **Never do:** Delete generated pages without understanding dependencies, use light-mode colors, remove citation links

## Documentation
- Wiki: `./` — This folder is the wiki
- LLM Context: `llms.txt` — Quick summary; `llms-full.txt` — Full content
- Onboarding: `onboarding/` — Four audience-tailored guides

Fill in the real section names, technologies, and project-specific conventions.

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