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

cd order-servicegit 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 :- Deep codebase scan: Identify languages, frameworks, build systems, entry points, test frameworks, CI configs, infrastructure files, API layers, persistence layers
- Extract commands: Exact install, build, test, lint, format, and dev commands from package manager configs and CI files
- Identify conventions: Read actual source files to determine naming, imports, error handling, logging, dependency injection, code organization patterns
- Find do-not-modify zones: Lock files, generated code, CI config, build output, vendored dependencies, migration files
- Generate AGENTS.md: Full project context with all required sections
- Generate .kiro/steering/project-context.md: Kiro-specific steering with technical decisions, exemplar files, and anti-patterns
- Generate .cursorrules: Concise plain-text rules for Cursor's system prompt
- 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 linesFile 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:
## ArchitectureThis is a single-service monolith following a 3-layer architecture:1. API layer (src/api/) — FastAPI route handlers2. Schema layer (src/schemas/) — Pydantic v2 models3. 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 fileFile 2: .kiro/steering/project-context.md (Kiro-specific)
The full 53-line steering file ATX generated:
# Project Context
## OverviewOrder Service is a FastAPI microservice providing REST APIs for order and usermanagement. It uses a 3-layer architecture (api/schemas/services) with in-memorystorage, 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 orderand 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: pytestLint: 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.pyWhen writing tests, follow the pattern in tests/test_orders.pyValidation: 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 usestr | 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 TDatx custom def publish \ --transformation-name "generate-ai-coding-context" \ --description "Generate AGENTS.md, .kiro/steering/, and .cursorrules for AI tools" \ --sd .
# Run on every repofor repo in /path/to/repos/*/; do atx custom def exec \ -n "generate-ai-coding-context" \ -p "$repo" \ -x -tdoneCost: 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-repoatx
# Describe: Generate AGENTS.md, .kiro/steering/, and .cursorrules for this codebaseOne 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
- 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