AWS Builder Center

Make Every Repo AI-Ready with a Generated AGENTS.md

AWS Transform generates an AGENTS.md from your actual code, verifies every convention against the source, and iterates until it is accurate.



The Problem: AI Tools Guessing Wrong

I've been using Kiro, Claude Code, and Amazon Q Developer against production codebases for over a year. The pattern that keeps repeating: the AI generates code that compiles but gets rejected in code review.
It puts test files in the wrong directory. It uses  print()  when the project uses  structlog . It creates a new module when the convention is to extend an existing one. It generates a REST endpoint that returns a raw dict when every other endpoint returns a Pydantic schema. It uses  async def  when all handlers are synchronous.
These aren't model quality problems. The AI is capable of following conventions. It just doesn't know what they are. It's the same problem a new engineer has on day one, except the new engineer eventually reads the team wiki. The AI gets no onboarding at all.
The fix: tell the AI how your project works in a format it can consume. That format is  AGENTS.md .

What is AGENTS.md

A structured markdown file in your repo root that provides context to AI coding tools. Think of it as  .editorconfig  for AI assistants, except instead of tab width it communicates architecture, conventions, build commands, and boundaries.
Kiro reads it as project context. Claude Code looks for it. Amazon Q Developer respects it. It's the emerging standard for making a repository "AI-ready."
The information already exists in your code. It's just scattered: the build command is in a Makefile, the conventions are implicit in the source files, the architecture is obvious to the original author but invisible to everyone else. AGENTS.md consolidates it into one machine-readable source of truth.

The Starting Point

A FastAPI order service. Clean code, minimal documentation:
  • 225 lines of Python across 15 files
  • Layered architecture: api/ → schemas/ → services/
  • 4 passing tests using httpx + ASGITransport
  • README: "Order management REST API." (one line)
  • No AGENTS.md, no architecture docs, no conventions guide
If an AI tool opens this repo, it has to infer everything from the code. Sometimes it infers correctly. Often it doesn't.

Running ATX

cd order-service
git init && git add . && git commit -m "initial: FastAPI order service (no AGENTS.md)"

aws configure # configure AWS credentials (or use env vars / a profile)
atx
I describe what I want:
\> Create a transformation that generates an AGENTS.md file in the repository
root. This file provides context for AI coding assistants (Kiro, Claude Code,
Amazon Q Developer). Analyze the codebase and generate AGENTS.md with these
sections: 1) Project Overview, 2) Architecture, 3) Build and Run,
4) Conventions, 5) Do Not Modify, 6) Common Tasks.
Be specific and opinionated. The audience is an AI that needs to generate
code following this project's exact conventions.

ATX's Clarifying Questions

ATX didn't just start generating. It asked six questions to make the transformation definition precise:
Question
ATX's Recommendation
My Answer
Language-specific or generic?
Generic (works on any codebase)
use defaults
Overwrite existing AGENTS.md?
Yes (derived from code, always fresh)
use defaults
Infer tasks from code or use templates?
Infer (reverse-engineer from existing modules)
use defaults
Produce AGENTS.md only or .agents/ directory?
Just AGENTS.md (universally recognized)
use defaults
How aggressive on "Do Not Modify"?
Flag everything auto-generated or externally managed
use defaults
Validate section headers after generation?
Yes (verify all 6 exist)
use defaults
Every recommendation was correct. ATX then built a 9-step transformation definition.

The Transformation Definition ATX Created

ATX generated a comprehensive TD covering the full analysis and generation workflow:
Step 1: Discover tech stack from build/dependency files (pyproject.toml, package.json, pom.xml, etc.)
Step 2: Map directory structure with purpose annotations, identifying layering patterns
Step 3: Extract exact commands for install, run, test, lint, format, build
Step 4: Identify conventions by reading 3-5 representative source files (naming, imports, types, error handling, logging, docstrings)
Step 5: Identify test conventions (framework, naming, organization, fixtures, mocking)
Step 6: Identify protected files (lock files, generated code, CI config, migrations, vendor dirs, "DO NOT EDIT" markers)
Step 7: Reverse-engineer common tasks by examining existing modules to determine the step-by-step process for adding new ones
Step 8: Write AGENTS.md with all 6 sections, overwriting if existing
Step 9: Validate that all 6 section headers are present
The TD is fully generic: it works on any codebase, any language. Once published, anyone can run it against their repos.

The Generated AGENTS.md

ATX Generate AGENTS.md Transformation Flow

Here's what ATX produced for the FastAPI order service (after iterative refinement):
# AGENTS.md

## Project Overview

order-service is an order management REST API built with Python 3.11+,
FastAPI 0.109+, Pydantic 2.x for request/response validation, structlog 24.x
for structured logging, and httpx 0.27+ as an HTTP client. It uses hatchling
as the build backend and uvicorn as the ASGI server. Data is stored in-memory
(no database).

## Architecture

.
├── src/
│ ├── __init__.py
│ ├── main.py # FastAPI app instantiation and router registration
│ ├── api/ # Route handlers (one file per resource)
│ │ ├── __init__.py
│ │ ├── orders.py
│ │ └── users.py
│ ├── schemas/ # Pydantic request/response models (one file per resource)
│ │ ├── __init__.py
│ │ ├── orders.py
│ │ └── users.py
│ └── services/ # Business logic classes (one file per resource)
│ ├── __init__.py
│ ├── order_service.py
│ └── user_service.py
├── tests/ # Test suite (only orders covered currently)
│ ├── __init__.py
│ └── test_orders.py
├── .gitignore
├── pyproject.toml # Project metadata, dependencies, tool config
└── README.md

Every directory under src/ and tests/ contains an __init__.py to mark it as a
Python package. New directories must include one.

Data flows through three layers: API routes (src/api/) receive HTTP requests,
validate input via schemas (src/schemas/), and delegate to services
(src/services/) which contain business logic and data storage. Routes return
Pydantic response models directly.

A /health endpoint is defined directly in src/main.py for liveness checks.

## Build and Run

# Install dependencies
pip install -e ".[dev]"

# Run locally
uvicorn src.main:app --reload

# Run full test suite
pytest

# Run a single test file
pytest tests/test_orders.py

# Run a single test
pytest tests/test_orders.py::test_create_order

# Lint
ruff check src tests

# Format
ruff format src tests

# Build for production
pip install build && python -m build

## Conventions

### Naming
- Files: snake_case.py
- Classes: PascalCase (OrderService, OrderCreate, OrderResponse)
- Functions/variables: snake_case
- Router instances: always named `router`
- Service instances in route files: always named `service`
- Pydantic models: \<Resource\>Create for input, \<Resource\>Response for output
- Service files: \<resource\>_service.py (with _service suffix)
- API and schema files: \<resource\>.py (no suffix)

### Imports
- Standard library first, then third-party, then local (src.*). Separated by
blank lines.
- Always use absolute imports from the src package.

### Types
- Strict type annotations on all function signatures and class attributes.
- Use dict | None union syntax (Python 3.10+ style), not Optional for new code.
- Use list[T] not List[T].

### Style
- Line length: 100 characters (enforced by ruff in pyproject.toml).
- Target Python version for linting: 3.11.

### Error Handling
- Raise fastapi.HTTPException in route handlers for client errors (404, 400).
- Services return None for not-found cases; the route handler translates to 404.
- No try/except blocks around internal logic.
- Route handlers are synchronous (def, not async def) since all current logic
is CPU-bound and in-memory. Use async def only if awaiting I/O.

### Logging
- Use structlog.get_logger() at module level, assigned to `logger`.
- Log events as snake_case strings with keyword arguments for context:
logger.info("order_created", order_id=order["id"])
- Log at info level for successful operations, warning for recoverable issues.

### Tests
- Framework: pytest with pytest-asyncio (auto mode).
- File naming: test_\<resource\>.py in the tests/ directory.
- Use httpx.AsyncClient with ASGITransport for integration tests.
- Fixtures defined per-file using @pytest.fixture.
- Assertions use plain assert statements, not unittest-style.
- All test functions are async def.

### Module Structure
Each source file starts with a module docstring, followed by imports, then
module-level setup (logger, router), then class/function definitions.

## Do Not Modify
- pyproject.toml: dependency versions and tool configuration are project-wide;
coordinate changes carefully
- .gitignore: shared ignore rules

## Common Tasks

### Add a New API Resource (e.g., "products")
1. Create src/schemas/products.py:
- Define ProductCreate(BaseModel) with input fields
- Define ProductResponse(BaseModel) with output fields
- Template: src/schemas/orders.py

2. Create src/services/product_service.py:
- Define ProductService class with create, get, list_all, and state-change
methods (e.g., cancel)
- Add logger = structlog.get_logger() at module level
- State-change methods return None when resource not found
- Template: src/services/order_service.py

3. Create src/api/products.py:
- Create router = APIRouter()
- Instantiate service = ProductService()
- Add route handlers: POST /, GET /{id}, GET /,
PATCH /{id}/\<action\> for state changes
- Raise HTTPException(404) when service returns None
- Template: src/api/orders.py

4. Register router in src/main.py:
- Import: from src.api.products import router as products_router
- Add: app.include_router(products_router, prefix="/api/products",
tags=["products"])

5. Create tests/test_products.py:
- Add client fixture using AsyncClient with ASGITransport(app=app)
- Write async test functions for each endpoint
- Template: tests/test_orders.py

### Add a New Endpoint to an Existing Resource
1. Add fields to schema in src/schemas/\<resource\>.py if needed
2. Add business logic method to service in src/services/\<resource\>_service.py
3. Add route handler in src/api/\<resource\>.py
4. Add test case in tests/test_\<resource\>.py

### Add a New Test File
1. Create tests/test_\<name\>.py
2. Import the app: from src.main import app
3. Add async client fixture with ASGITransport
4. Write async def test_\<name\>(client): functions with assert statements
That's 155 lines of specific, opinionated, actionable context. Every convention is concrete. Every command is runnable. Every Common Task step references real files.

Validation Round 1: Build Commands and Convention Check

ATX didn't just generate and stop. It ran the build commands and verified every convention against the actual source:
Build commands tested:
Command
Result
 pip install -e ".[dev]" 
Installs successfully
 pytest 
4 tests pass
 ruff check src tests 
All checks pass
 ruff format src tests 
13 files already formatted
Conventions verified against actual code (13/13 match):
Convention in AGENTS.md
Actual Code
Match?
 structlog.get_logger()  at module level as  logger 
order_service.py:  logger = structlog.get_logger() 
PASS
Log events as snake_case with kwargs
 logger.info("order_created", order_id=...) 
PASS
Router instances named  router 
Both route files:  router = APIRouter() 
PASS
Service instances named  service 
Both route files:  service = OrderService() 
PASS
Services return  None  for not-found
 self._orders.get(order_id)  returns None if missing
PASS
Routes raise  HTTPException(404) 
 raise HTTPException(status_code=404, ...) 
PASS
Pydantic models:  \<Resource\>Create  /  \<Resource\>Response 
 OrderCreate ,  OrderResponse 
PASS
 dict | None  union syntax
 -\> dict | None  in service methods
PASS
 Optional  in Pydantic models
 cancelled_at: Optional[datetime] = None 
PASS
Files start with module docstring
All checked files confirm
PASS
Tests use  httpx.AsyncClient  with  ASGITransport 
test_orders.py confirms exactly
PASS
All test functions are  async def 
Confirmed
PASS
pytest-asyncio auto mode
pyproject.toml configures this
PASS
Every single convention ATX documented was verified against the actual source code. Zero false claims.

Validation Round 2: First Set of Issues (3 found, 3 fixed)

After the initial validation passed, ATX ran a deeper check and found:
  1.  /health  endpoint not mentioned in Architecture - The endpoint exists in  src/main.py  but wasn't called out.
  • Fix: Added "A /health endpoint is defined directly in src/main.py for liveness checks."
  1.  cancel /state-change methods missing from Common Tasks - The OrderService has a  cancel  method and PATCH route, but Common Tasks only showed create/get/list.
  • Fix: Added "and any state-change methods (e.g., cancel)" to service step, "PATCH /{id}/<action> for state changes" to route step.
  1.  __pycache__ / .pytest_cache  in "Do Not Modify" was redundant - These are generated directories covered by .gitignore, not files an AI would edit.
  • Fix: Removed them, keeping only pyproject.toml and .gitignore.

Validation Round 3: Thorough Review (6 more issues found, 6 fixed)

A third review pass caught:
  1. Architecture tree missing  __init__.py  files - These mark directories as Python packages. An AI assistant creating a new module might forget to add one without seeing them in the tree.
  • Fix: Added all  __init__.py  files to the tree + note "New directories must include one."
  1. Architecture tree missing  .gitignore  - Listed in Do Not Modify but not shown in the tree.
  • Fix: Added to root-level files in the tree.
  1. No note about missing user tests - Only  test_orders.py  exists. An AI might assume all resources have tests.
  • Fix: Added "(only orders covered currently)" annotation to tests/ in tree.
  1. Route handlers are sync but this wasn't documented - Since FastAPI supports both  def  and  async def , this is a convention that needs explicit statement.
  • Fix: Added "Route handlers are synchronous (def, not async def) since all logic is CPU-bound. Use async def only if awaiting I/O."
  1. Ruff line-length and target-version not mentioned -  pyproject.toml  sets 100 chars and py311. These affect generated code style.
  • Fix: Added new "Style" subsection with both values.
  1. Service file naming convention not called out - Services use  \<resource\>_service.py  but API/schema files use plain  \<resource\>.py . This asymmetry needs to be explicit.
  • Fix: Added to Naming conventions.
After 3 rounds: the AGENTS.md is thoroughly validated and accurate. Every claim is verified. Every pattern documented actually exists in the code.

The Reusable Transformation

The TD ATX created ( generate-agents-md ) is fully generic. It works on any codebase:
# Publish for your team
atx custom def publish \
--transformation-name "generate-agents-md" \
--description "Generate AGENTS.md for AI coding tool context" \
--sd .

# Run on any repo, non-interactively
atx custom def exec \
--transformation-name "generate-agents-md" \
--code-repository-path /path/to/any/repo \
--non-interactive --trust-all-tools

Batch Across Your Org

#!/bin/bash
for repo in /path/to/repos/*/; do
echo "=== $(basename $repo) ==="
atx custom def exec \
-n "generate-agents-md" \
-p "$repo" \
-x -t
done
In one afternoon, every repo in your org has an AGENTS.md. Every AI tool interaction from that point forward is better: correct directory placement, correct naming, correct patterns, correct test structure.

What Changes for AI Tool Quality

With AGENTS.md present, an AI tool asked to "add a shipment tracking endpoint" will:
  • Create  src/schemas/shipments.py  with  ShipmentCreate  and  ShipmentResponse  (correct naming)
  • Create  src/services/shipment_service.py  with  ShipmentService  class (correct suffix)
  • Create  src/api/shipments.py  with  router  and  service  instances (correct naming)
  • Register in  src/main.py  with correct prefix pattern
  • Create  tests/test_shipments.py  with async fixtures (correct structure)
  • Use  structlog  for logging (correct library)
  • Return  None  for not-found in service, raise  HTTPException(404)  in handler (correct pattern)
  • Use synchronous  def  handlers (correct choice for in-memory logic)
Without AGENTS.md, the same prompt produces code that violates 3-5 of these conventions.

Cost

In one example run this took a few agent minutes (including the validation rounds) at $0.035/agent-minute, on the order of ~$0.15. Agent-minutes are non-deterministic and vary per run and codebase, so treat this and any fleet total as an estimate and run a pilot to establish your own baseline.

Getting Started

# Install ATX (requires Node.js 22+)
curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash

# Authenticate (configure AWS credentials)
aws configure # or set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION

# Run against your repo
cd your-repo
atx

# Ask ATX to generate AGENTS.md
One file. Every repo. AI-ready.



Resources

References

[1] AWS, "AWS Transform Custom documentation."  https://docs.aws.amazon.com/transform/latest/userguide/custom.html 
[2] AWS, "AWS Transform pricing."  https://aws.amazon.com/transform/pricing/ 


Disclaimer: Opinions expressed are personal and do not represent the official position of any organization. All claims about ATX capabilities are verified against the  official documentation .
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article