‘I apologize for the confusion. Let me try another way.’
Your AI agent replies (for the third time). Yet when you run it again, you’re greeted by an error about deprecated APIs. While AI coding agents promise to accelerate development, they often slow us down by suggesting outdated patterns or misunderstanding platform requirements.
The problem isn’t the AI—it’s the lack of a good Agent Experience (AX).
Today’s developers are rapidly adopting AI agents like Cursor, GitHub Copilot, Windsurf, and others as pair programmers. At their best they help code alongside us, by understanding documentation and APIs, generating test cases, and troubleshooting issues. The effectiveness of this collaboration depends heavily on how well agents understand your project.
Just as developers need clear documentation and well-structured codebases, AI agents need the right context to be helpful; without it you risk getting stuck in the perpetual error loop. When done right, good AX becomes a force multiplier for developer experience (DX) and productivity.
Improving DX via AX
One concrete example of AX improving DX is context files. Context files provide agents with essential information about your project’s architecture, coding standards, and integrations. When platforms provide official context files, they ensure AI tools have accurate, up-to-date information about platform capabilities and best practices.
For example, developers can use official Netlify context files (.mdc or .txt format) that help AI tools generate more reliable code.
These files can be:
- Added to project repositories
- Integrated with AI development tools
- Updated via CLI commands
- Customized for specific needs while maintaining compatibility
Here’s how this works with Netlify’s Edge Functions. Add context files to your codebase with the netlify recipes ai-context
command:
When an AI agent reads our context file, it learns the platform’s patterns:
Edge Functions
- ALWAYS use the latest format of an edge function structure.
- **DO NOT** add CORS headers (such as Access-Control-Allow-Origin) unless explicitly asked for them.
- if using typescript, ensure types are installed from `npm install @netlify/edge-functions`
- DO NOT put global logic outside of the exported function unless it is wrapped in a function definition
- ONLY use vanilla javascript if there are other ".js" files in the functions directory.
- ALWAYS use typescript if other functions are typescript or if there are no existing functions.
- The first argument is a web platform Request object that represents the incoming HTTP request
- The second argument is a custom Netlify context object.
- Edge functions have a global `Netlify` object that is also accessible.
- ONLY use `Netlify.env.*` for interacting with environment variables in code.
- Place function files in `YOUR_BASE_DIRECTORY/netlify/edge-functions` or a subdirectory.
- The serverless functions director can be changed via`netlify.toml`:
```toml
[build]
edge_functions = "my-custom-directory"
```
How has this helped developers using Netlify? Let’s check out an example where the agent is asked to create a Netlify function to return “Hello World!” Without improved context, the agent may create code that looks like this:
exports.handler = async function (event, context) {
return {
statusCode: 200,
headers: {
'Content-Type': 'application/json',
},
body: 'Hello World!'
};
};
Unfortunately, this code pattern is old and deprecated. This showcases how good and bad patterns have been trained into LLMs, especially platforms that have existed for a long time. With the official Netlify context given to the agent, it will produce the following code which is modern, typesafe, and ready for more complex workloads.
import type { Context } from "@netlify/functions";
export default async (req: Request, context: Context) => {
return new Response("Hello World!");
};
export const config = {
path: "/api/hello"
};
This creates a more reliable development experience. Just as good API documentation helps developers write better integrations, good context files help agents provide better guidance.
The future of Agent Experience
As the field of agent experience evolves, we expect to see:
- Improved tools for context management and versioning
- Enhanced agent-developer collaboration
- Deeper integration between AI, tools, and platforms
AX is the natural extension of a commitment to developer experience. For example, we’re building our platform with both human developers and their AI collaborators in mind, providing rich APIs and clear documentation that serves both audiences. This means going beyond context files to make the entire platform more AI-friendly, like automatically enabling form detection for sites created through AI code generation tools.
We believe that when agents understand a platform more effectively, developers can work more efficiently. The future of web development involves closer collaboration between developers and AI. Starting to optimize for AX today helps ensure that collaboration is as productive as possible.
If you want to help shape the future of AX or stay updated on best practices join us at agentexperience.ax.