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