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-servicegit init && git add . && git commit -m "initial: FastAPI order service (no AGENTS.md)"
aws configure # configure AWS credentials (or use env vars / a profile)atxI 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

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.xfor structured logging, and httpx 0.27+ as an HTTP client. It uses hatchlingas 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 aPython 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 returnPydantic response models directly.
A /health endpoint is defined directly in src/main.py for liveness checks.
## Build and Run
# Install dependenciespip install -e ".[dev]"
# Run locallyuvicorn src.main:app --reload
# Run full test suitepytest
# Run a single test filepytest tests/test_orders.py
# Run a single testpytest tests/test_orders.py::test_create_order
# Lintruff check src tests
# Formatruff format src tests
# Build for productionpip 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 StructureEach source file starts with a module docstring, followed by imports, thenmodule-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 Resource1. Add fields to schema in src/schemas/\<resource\>.py if needed2. Add business logic method to service in src/services/\<resource\>_service.py3. Add route handler in src/api/\<resource\>.py4. Add test case in tests/test_\<resource\>.py
### Add a New Test File1. Create tests/test_\<name\>.py2. Import the app: from src.main import app3. Add async client fixture with ASGITransport4. Write async def test_\<name\>(client): functions with assert statementsThat'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:
-
/healthendpoint not mentioned in Architecture - The endpoint exists insrc/main.pybut wasn't called out.
- Fix: Added "A /health endpoint is defined directly in src/main.py for liveness checks."
-
cancel/state-change methods missing from Common Tasks - The OrderService has acancelmethod 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.
-
__pycache__/.pytest_cachein "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:
- Architecture tree missing
__init__.pyfiles - 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__.pyfiles to the tree + note "New directories must include one."
- Architecture tree missing
.gitignore- Listed in Do Not Modify but not shown in the tree.
- Fix: Added to root-level files in the tree.
- No note about missing user tests - Only
test_orders.pyexists. An AI might assume all resources have tests.
- Fix: Added "(only orders covered currently)" annotation to tests/ in tree.
- Route handlers are sync but this wasn't documented - Since FastAPI supports both
defandasync 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."
- Ruff line-length and target-version not mentioned -
pyproject.tomlsets 100 chars and py311. These affect generated code style.
- Fix: Added new "Style" subsection with both values.
- Service file naming convention not called out - Services use
\<resource\>_service.pybut 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 teamatx custom def publish \ --transformation-name "generate-agents-md" \ --description "Generate AGENTS.md for AI coding tool context" \ --sd .
# Run on any repo, non-interactivelyatx custom def exec \ --transformation-name "generate-agents-md" \ --code-repository-path /path/to/any/repo \ --non-interactive --trust-all-toolsBatch Across Your Org
#!/bin/bashfor repo in /path/to/repos/*/; do echo "=== $(basename $repo) ===" atx custom def exec \ -n "generate-agents-md" \ -p "$repo" \ -x -tdoneIn 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.pywithShipmentCreateandShipmentResponse(correct naming)
- Create
src/services/shipment_service.pywithShipmentServiceclass (correct suffix)
- Create
src/api/shipments.pywithrouterandserviceinstances (correct naming)
- Register in
src/main.pywith correct prefix pattern
- Create
tests/test_shipments.pywith async fixtures (correct structure)
- Use
structlogfor logging (correct library)
- Return
Nonefor not-found in service, raiseHTTPException(404)in handler (correct pattern)
- Use synchronous
defhandlers (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 repocd your-repoatx
# Ask ATX to generate AGENTS.mdOne file. Every repo. AI-ready.
Resources
- AWS Transform Custom docs: docs.aws.amazon.com/transform/latest/userguide/custom.html
- ATX pricing: $0.035/agent-minute
References
[1] AWS, "AWS Transform Custom documentation." https://docs.aws.amazon.com/transform/latest/userguide/custom.html
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 .
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article