AWS Builder Center

Expose Your Codebase to AI Coding Tools in One Pass

One AWS Transform command generates AGENTS.md, .kiro steering, and .cursorrules from your code, so Kiro, Claude Code, Q, and Cursor understand it.

One ATX command. Three files generated. Your codebase is now visible to every AI coding tool: Kiro reads .kiro/steering/, Claude Code and Q Developer read AGENTS.md, Cursor reads .cursorrules. All derived from your actual code, all specific and opinionated, all in one pass.



The Multi-Tool Problem

The AI coding tool landscape is fragmented. Every team uses something different, and increasingly teams use multiple tools simultaneously:
  • A developer uses Kiro for spec-driven development and complex multi-file features
  • The same developer switches to Cursor for quick inline completions and chat
  • During code review, Claude Code or Amazon Q Developer provides suggestions
  • CI/CD pipelines use AI for automated code generation and analysis
Each tool has its own context mechanism. Kiro reads  .kiro/steering/  files. Claude Code and Q Developer read  AGENTS.md . Cursor reads  .cursorrules . If your repo only has one of these (or none), the tools without context files fall back to generic behavior: guessing conventions, inferring patterns, making assumptions.
The result is inconsistency. Kiro generates code that follows your patterns (because it has steering). Cursor generates code that doesn't (because it has no .cursorrules). The developer spends time fixing Cursor's output to match what Kiro would have produced. This is wasted effort that scales with team size.
AWS Transform Custom can generate all three files from a single analysis of your code, ensuring every AI tool gets the same conventions in its native format.

The Starting Point

A FastAPI order service with clean architecture but zero AI tool configuration:
order-service/
├── src/
│ ├── main.py
│ ├── api/orders.py, users.py
│ ├── schemas/orders.py, users.py
│ └── services/order_service.py, user_service.py
├── tests/test_orders.py
├── pyproject.toml
└── README.md ← "Order management REST API." (one line)
No AGENTS.md. No .kiro/steering/. No .cursorrules. Every AI tool working with this repo has to infer conventions from the code. Sometimes it gets them right. Often it doesn't.

Running the Transformation

ATX Multi-Tool Context Generatio

cd order-service
git init && git add . && git commit -m "initial: FastAPI order service"

aws configure # configure AWS credentials (or use env vars / a profile)
atx
> Expose this codebase to AI coding tools (Kiro, Claude Code, Amazon Q Developer,
Cursor) in one transformation. Generate: 1) AGENTS.md in the repo root,
2) .kiro/steering/project-context.md with Kiro-specific steering,
3) .cursorrules with Cursor-specific rules. All files should be derived from
the actual code. Be specific and opinionated.
ATX creates a custom TD called  generate-ai-coding-context  with an 8-step workflow: deep codebase scan, extract commands, identify conventions, find do-not-modify zones, then generate all three files and validate.

Why Each Tool Needs Different Context

AI coding tools aren't interchangeable. They consume project context through different mechanisms, in different formats, with different expectations:
AGENTS.md (Claude Code, Amazon Q Developer, generic agents): A structured markdown file read at session start. These tools expect sections with headers they can navigate: Project Overview, Architecture, Conventions. The format is broad because the tool needs to understand the entire project at a high level before generating anything.
Kiro steering files ( .kiro/steering/*.md ): Kiro's steering system is more prescriptive. It's not just "here's the project," it's "here are the rules you must follow." Steering files include explicit "Patterns to Follow" (with file path exemplars), "Patterns to Avoid" (anti-patterns), and "Key Technical Decisions" that override the AI's default behavior. Kiro reads these persistently across all interactions in the workspace.
Cursor rules ( .cursorrules ): A plain-text file applied as part of Cursor's system prompt for every completion. It needs to be concise, rule-based, and immediately actionable. No markdown headers, no lengthy explanations. Just declarations: "Use X, never use Y, follow the pattern in Z."
The same underlying information (your project's conventions) needs to be expressed three different ways. Writing all three by hand is tedious and they drift apart when conventions change. ATX generates all three from the same analysis pass, ensuring consistency.

The Transformation Definition: 8-Step Workflow

ATX created a comprehensive TD called  generate-ai-coding-context :
  1. Deep codebase scan: Identify languages, frameworks, build systems, entry points, test frameworks, CI configs, infrastructure files, API layers, persistence layers
  1. Extract commands: Exact install, build, test, lint, format, and dev commands from package manager configs and CI files
  1. Identify conventions: Read actual source files to determine naming, imports, error handling, logging, dependency injection, code organization patterns
  1. Find do-not-modify zones: Lock files, generated code, CI config, build output, vendored dependencies, migration files
  1. Generate AGENTS.md: Full project context with all required sections
  1. Generate .kiro/steering/project-context.md: Kiro-specific steering with technical decisions, exemplar files, and anti-patterns
  1. Generate .cursorrules: Concise plain-text rules for Cursor's system prompt
  1. Validate: Confirm all files exist, no placeholders remain, all referenced paths are real

What ATX Produced: 3 Files, 178 Lines

3 files changed, 178 insertions(+)
.cursorrules | 30 lines
.kiro/steering/project-context.md | 53 lines
AGENTS.md | 95 lines

File 1: AGENTS.md (for Claude Code, Q Developer, generic agents)

95 lines covering project overview, tech stack with exact versions, architecture description, directory structure, build commands, conventions, do-not-modify zones, common tasks, and testing strategy.
Key sections:
## Architecture
This is a single-service monolith following a 3-layer architecture:
1. API layer (src/api/) — FastAPI route handlers
2. Schema layer (src/schemas/) — Pydantic v2 models
3. Service layer (src/services/) — Business logic and in-memory storage

## Conventions
- Type hints: Use Python 3.11+ syntax (dict[str, str], X | None)
- Logging: structlog.get_logger() at module level
- Error handling: Raise HTTPException in route handlers
- IDs: str(uuid.uuid4())
- Timestamps: datetime.now(timezone.utc)
- Route decorators: Always specify response_model= and status_code=
- Service pattern: Module-level singleton in each router file

File 2: .kiro/steering/project-context.md (Kiro-specific)

The full 53-line steering file ATX generated:
# Project Context

## Overview
Order Service is a FastAPI microservice providing REST APIs for order and user
management. It uses a 3-layer architecture (api/schemas/services) with in-memory
storage, Pydantic v2 for validation, and structlog for structured logging.
Python 3.11+ is required.

## Key Technical Decisions
- All data is stored in-memory using Python dicts inside service classes. There
is no database or external persistence.
- The application uses synchronous route handlers (FastAPI handles them on the
thread pool). Tests use async httpx client with ASGITransport.
- Service classes are instantiated as module-level singletons in each router
file. Do not create new instances per request.
- Pydantic v2 models are used for both request validation and response
serialization. Always specify response_model on route decorators.
- structlog is used for all logging. Never use print() or the standard library
logging module directly.

## Code Style Requirements
- Use Python 3.11+ type hint syntax: dict[str, str] not Dict[str, str],
X | None not Optional[X].
- Every module must have a module-level docstring.
- Line length limit is 100 characters (enforced by Ruff).
- Target Python version for linting: py311.
- Follow Ruff's default rules plus isort (I) for import sorting.

## File Organization Rules
- Route handlers go in src/api/<resource>.py, one file per resource domain.
- Pydantic request/response models go in src/schemas/<resource>.py.
- Business logic and storage go in src/services/<resource>_service.py.
- Tests go in tests/test_<resource>.py.
- The app is assembled in src/main.py which registers all routers.

## Dependency Rules
- All dependencies are declared in pyproject.toml.
- Runtime deps go in [project.dependencies].
- Dev/test deps go in [project.optional-dependencies.dev].
- Approved runtime dependencies: fastapi, uvicorn, pydantic, structlog, httpx.
- Do not add ORM libraries or database drivers without architectural discussion.
- Do not add additional linting tools. Ruff handles linting and formatting.

## Testing Requirements
- All new endpoints must have corresponding async tests using the
httpx/ASGITransport pattern.
- Test files must be in the tests/ directory and named test_<feature>.py.
- Use the client fixture pattern from tests/test_orders.py for all API tests.
- Assert both status codes and response body structure.
- pytest-asyncio is in auto mode, async test functions are detected automatically.

## Patterns to Follow
- src/api/orders.py: exemplar for route handler structure, error handling, logging.
- src/schemas/orders.py: exemplar for Pydantic v2 model definitions with field
constraints.
- tests/test_orders.py: exemplar for async API test structure and fixture usage.

## Patterns to Avoid
- Do not use @app.get()/@app.post() directly on the app instance. Always use
APIRouter.
- Do not use Optional[X]. Use X | None instead.
- Do not use Dict, List, Tuple from typing. Use built-in generics.
- Do not instantiate services inside route handler functions. Use the
module-level singleton.
- Do not use print() for logging. Use structlog.get_logger().
- Do not write synchronous tests. All API tests must be async using
httpx.AsyncClient.
This is what makes Kiro's steering powerful: it doesn't just describe the project, it prescribes behavior. "Patterns to Follow" gives Kiro concrete files to reference. "Patterns to Avoid" prevents the most common AI mistakes for this specific project.

File 3: .cursorrules (Cursor-specific)

30 lines of plain-text rules in Cursor's expected format:
You are working in order-service, a Python FastAPI microservice for order
and user management with in-memory storage.

Tech stack: Python >= 3.11, FastAPI >= 0.109.0, Pydantic >= 2.0, uvicorn >= 0.27.0,
structlog >= 24.0, httpx >= 0.27.0, pytest >= 7.0, pytest-asyncio >= 0.23.0,
Ruff >= 0.4.0, Hatchling build system.

Build: pip install -e ".[dev]"
Test: pytest
Lint: ruff check src/ tests/

Rules:
- Use Python 3.11+ type syntax: dict[str, str], list[int], X | None
- Every module file must have a module-level docstring
- Line length limit is 100 characters
- Use structlog.get_logger() for all logging. Never use print()
- Raise fastapi.HTTPException for error responses
- Generate IDs with str(uuid.uuid4())
- Use APIRouter for all routes. Never decorate directly on the app instance
- All API tests must be async using httpx.AsyncClient with ASGITransport

Never modify: pyproject.toml [build-system] section, __pycache__/, .git/

When adding a new API endpoint, follow the pattern in src/api/orders.py
When writing tests, follow the pattern in tests/test_orders.py

Validation: All Content Verified Against Source

ATX didn't just generate and stop. It verified every claim:
Check
Result
All referenced directories exist
PASS (src/, src/api/, src/schemas/, src/services/, tests/)
All referenced files exist
PASS (12 files verified)
No placeholder text (TODO, [fill in], etc.)
PASS (grep returned zero matches)
structlog usage confirmed in source
PASS ( logger = structlog.get_logger() )
Pydantic v2 BaseModel confirmed
PASS (in all schema files)
APIRouter pattern confirmed
PASS (both route files)
UUID generation confirmed
PASS ( str(uuid.uuid4()) )
datetime.now(timezone.utc) confirmed
PASS
Python version constraint matches pyproject.toml
PASS (>=3.11)
Every convention documented in the generated files is verified against the actual source code.

Why Three Files Instead of One

Each AI tool has different context mechanisms:
Tool
File
Format
How it's used
Claude Code
AGENTS.md
Markdown with sections
Read at session start, guides all generation
Amazon Q Developer
AGENTS.md
Same
Same
Kiro
.kiro/steering/*.md
Markdown with steering format
Loaded as persistent project guidance
Cursor
.cursorrules
Plain text, rules-based
Applied as system prompt for completions
One transformation generates all three, keeping them consistent. When your conventions change, re-run the transformation and all three files update together.

Before/After: What Changes for AI Tool Quality

Without these files, an AI tool asked to "add a payments endpoint" will:
  • Possibly use  @app.post()  directly (wrong, should use APIRouter)
  • Possibly use  Optional[str]  (wrong, should use  str | None )
  • Possibly use  print()  for logging (wrong, should use structlog)
  • Possibly create a new service instance inside the handler (wrong, should use module-level singleton)
  • Might skip the response_model on the decorator
  • Might place the test file in the wrong location or use synchronous tests
With these files, the same prompt produces code that follows every convention because:
  • AGENTS.md tells it the architecture (3-layer, service-per-resource)
  • .kiro/steering/ tells it "follow src/api/orders.py as exemplar" and "never use Optional"
  • .cursorrules tells it "Use APIRouter, use structlog, all tests must be async"
Three files, three tools, one consistent set of conventions enforced everywhere.

Scaling Across Your Org

# Publish the TD
atx custom def publish \
--transformation-name "generate-ai-coding-context" \
--description "Generate AGENTS.md, .kiro/steering/, and .cursorrules for AI tools" \
--sd .

# Run on every repo
for repo in /path/to/repos/*/; do
atx custom def exec \
-n "generate-ai-coding-context" \
-p "$repo" \
-x -t
done
Cost: In one example run this took a few agent minutes at $0.035/agent-minute, on the order of ~$0.10 per repo. Agent-minutes are non-deterministic and vary per run, codebase, and how many validation/self-correction cycles ATX needs, so treat this as a ballpark, not a fixed price. Run a pilot on a representative repo to establish your own baseline.

Getting Started

curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash # requires Node.js 22+
aws configure # configure AWS credentials (or use env vars / a profile)
cd your-repo
atx

# Describe: Generate AGENTS.md, .kiro/steering/, and .cursorrules for this codebase
One transformation. Three files. Every AI tool gets project-specific context. No more guessing.
Worth noting: You don't have to leave your editor to do this. AWS Transform is now available as a Kiro Power, as agent plugins for Claude, Cursor, and Codex, and as an MCP server — start the transformation in your IDE, watch progress in the web console, and get results back in the same tool, all against one job with consistent state.



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