Instructing Your AI Helpers

Things are evolving so quickly in the world of AI-assisted development, it's difficult to keep up at times.

For example: Codex, from OpenAI, is a coding agent designed to deeply understand your codebase and follow project-specific instructions using natural language. It works especially well when guided by AGENTS.md files in your repository (more on that below).

Codex was released last week. This week, GitHub announced major updates to Copilot with the introduction of Copilot Workspace, which takes assigned Github issues, spins up a development sandbox, and submits a PR with its results - almost like pairing with an AI engineer who knows your repo. I think this one has a good chance of massive adoption since it's already built into Github, where developers already live.

Visual Studio Code also announced that they’re becoming an open source AI IDE. They also now have "Agent Mode". That move feels like a direct response to Cursor, which has quickly gained traction by being AI-native from the start (and is a fork of VSC).

And just today, OpenAI announced the acquisition of LoveFrom.ai, Jony Ive’s AI hardware startup. The goal? Build consumer AI devices that are more intuitive and beautiful. The human interface layer for LLMs is going to be extremely important, and OpenAI just brought an absolute icon into the fold.

Despite the dizzying pace, this level of competition is a net positive for developers and software in general. Tools are getting better fast and the way we work with code is fundamentally changing.

---

Anyway, one thing I particularly liked in Codex is how it uses AGENTS.md files to guide its behavior:

Codex can be guided by AGENTS.md files placed within your repository. These are text files, akin to README.md, where you can inform Codex how to navigate your codebase, which commands to run for testing, and how best to adhere to your project's standard practices.

This is a clean concept. You place guidance where it’s contextually relevant, right alongside the code it refers to. It’s efficient, it’s easy to find, and it just works.

I also like how Cursor handles this with their .cursor/rules directory. You can set rules to be Always, Auto Attached, Agent Requested, or Manual, which gives you a clean and modular way to define how agents should behave.

At Quiltster, we’ve already invested in building a good set of Cursor rules. We’re also interested in giving Codex a try, but maintaining two sets of agent instructions sounds like a headache. So, we added an AGENTS.md file to our repos that tells agents to reference .cursor/rules for its instructions.

Here’s what it looks like:

# AGENTS.md

This project uses Codex-compatible agents (e.g., in Cursor) to assist with development, refactoring, and maintenance. To ensure consistent, context-aware behavior, all agents must follow the directives below.

---

## 🔁 Runtime Behavior for Agents

- **Always load and interpret all files in `./cursor/rules/` on every request.**  
  These files contain high-priority, agent-specific instructions and overrides that influence behavior, coding style, architectural decisions, and task-specific guidance.

- Treat every file in `./cursor/rules/` as essential context, regardless of file type or naming convention.

- Files in `./cursor/rules/` may:
  - Override or extend project-wide conventions
  - Define specialized behavior for a specific domain, app, or tool
  - Include instruction sets tailored to agents or Codex-like systems

- Do **not** proceed with code generation, refactoring, or architectural recommendations without evaluating the current contents of that directory.

---

## Agent Execution Guidance

- Look for `.md`, `.json`, or `.py` files within `./cursor/rules/`; all may contain logic or instructions for agent use.
- Assume that any file in the directory is actionable unless explicitly marked otherwise within the file.
- When files contain overlapping rules, follow the most specific applicable instruction set based on file naming and structure.

---

## Agent Initialization Sequence

When responding to a request:
1. Load and parse all files in `./cursor/rules/`
2. Combine guidance from this `AGENTS.md` file with rule-specific logic
3. Apply instruction sets before generating or modifying any code
4. Use the combined ruleset as authoritative, unless explicitly overridden by user instructions in-session

---

## Maintenance Notes

- The `./cursor/rules/` directory may evolve over time. Agents should always load the latest version during each execution.
- If the directory is empty, fall back to global defaults and instructions in this file.

---

## Developer Guidance

If you're writing rules for AI agents:
- Place them in `./cursor/rules/` and commit them with clear names and versioning
- Use plain Markdown, JSON, or Python files
- Document the intent, scope, and override behavior within each file

---

This `AGENTS.md` file should be interpreted as high-priority guidance. When used with Codex, Cursor, or any AI-assist tooling, this file governs the expected behavioral contract between human collaborators and AI agents.

Upon querying Cursor, it seems to understand these instructions very well! I provide this example because this is general enough for anyone to use. However, I'd like to point out that the contents were (perhaps obviously) written by ChatGPT. LLMs are surprisingly great at writing these kinds of structured instructions, so don’t hesitate to generate your own based on your repo’s specific needs.

If we ever add contextually-placed AGENTS.md files in our repos, we’ll also update our .cursor/rules to treat those as high-priority inputs. For now, this setup strikes a good balance between clarity and flexibility.

At least, that's how we're doing it for NOW. Things are changing so fast that this could all look different next month. 🙃

The whirlwind of activity makes this an exciting time to be in software. It reminds me of the iPhone and early Web 2.0 years. Paradigms are shifting, interfaces are taking new directions, and there’s lots of room for invention and competition. I’m completely here for it!