DEV Community: Irving

A Practical Guide to AGENTS.md: Writing Instructions for Codex

Irving — Mon, 05 Oct 2026 08:49:04 +0000

AI helped draft and revise the Chinese original, then translate and adapt it into English.

Why should Codex users know about AGENTS.md?

If you use Codex to build projects, or do a lot of vibe coding, some of these problems may sound familiar:

You're a product manager who wants to discuss the user experience and possible solutions, but the AI keeps getting into technical details.
You only want to talk through an idea, but the AI starts changing code. By the time you realize it's going in the wrong direction, there's work to undo.
Your project already has a module that does the job, but the AI builds another one. The project gets messier with every change.
You just told it not to change a particular part of the project. In the next chat, you have to say it all again.
You ask it to change a button, and it also changes the nearby text and layout.
Your project already has shared components, styles, and coding conventions, but the AI's changes don't follow them.
You've already agreed on the product positioning and business rules, but the AI changes those details while editing a page.
The AI says the work is done. You open the result, find problems, and realize it never checked its changes.
Every new task starts with another explanation of the project structure, how to run it, and what to watch out for.

Part of the problem is that the rules you want the AI to follow haven't been provided clearly and consistently. And we can't always remember to explain everything, at the right time, in every conversation.

If you've used Claude Code, you can think of AGENTS.md as a file with a similar purpose to CLAUDE.md.

At their core, CLAUDE.md and AGENTS.md serve the same purpose: they record ongoing collaboration requirements and project knowledge so an AI coding assistant can load them into its context while it works. Both tools' official documentation describes using these files for project conventions, workflows, and personal preferences.

Put simply, they're instruction manuals for the AI. They tell it:

How to work with you.
What rules the project follows.
What it shouldn't change without asking.

How do you write an AGENTS.md file?

1. Group the problems into categories

Let's start by grouping the problems above:

Problem	Category
1. You want to discuss the user experience and possible solutions, but the AI keeps explaining technical details.	Your background and communication preferences
2. You're only discussing an idea, but the AI starts changing code.	The workflow for discussion and implementation
3. The functionality already exists, but the AI builds it again.	Existing modules and reuse requirements
4. You have to repeat the same restrictions in every new chat.	Ongoing agreements and restrictions on changes
5. You ask for a button change, but other things get changed too.	Scope of changes
6. The components, styles, and code don't follow the project's conventions.	Development conventions
7. The AI changes product positioning or business rules you've already agreed on.	Product positioning and business rules
8. It says the work is done without checking the result.	Completion criteria and verification requirements
9. You have to keep explaining the project structure and how to run it.	Project structure and setup instructions

If we then group these requirements by where they apply, we get two broad categories:

Personal preferences and collaboration requirements: your background, communication preferences, how you move from discussion to implementation, and general expectations about scope and delivery. You usually want the AI to work with you this way even when you switch projects.
Project context and conventions: this project's structure and setup, existing modules and reuse requirements, development conventions, product positioning, business rules, and specific restrictions and verification steps.

Some problems involve both. For example, "Check your changes and tell me if you haven't" is a general requirement. "Here is how to check changes in this project" is a project convention.

Codex supports managing these instructions at both the global and project levels.

Here are the main points from the official AGENTS.md documentation, summarized:

Global: The Codex home directory defaults to ~/.codex. You can change it with CODEX_HOME. Codex prefers AGENTS.override.md; otherwise, it uses AGENTS.md.
Project: Codex checks each directory along the path from the project root to the current working directory. In each directory, it prefers AGENTS.override.md, then AGENTS.md. You can also configure fallback filenames. Codex uses at most one file per directory.
Combined instructions: Codex combines the files in order: global, project root, then deeper directories along the path. If instructions conflict, those closer to the current working directory take priority.

Put simply, Codex loads the applicable global and project instructions into its context to guide its work.

Use the global file for general requirements, and the project file for that project's context and rules. Instructions that don't conflict work together. Where they do conflict, the more specific project instructions take priority.

Following this approach, we can write two AGENTS.md files:

Global AGENTS.md: stored at ~/.codex/AGENTS.md by default, for personal preferences and collaboration requirements that apply across projects.
Project AGENTS.md: stored in the project root, for that project's context and conventions.

You don't have to write both. Start with the instructions you actually need.

2. What goes in a global AGENTS.md?

Location: ~/.codex/AGENTS.md by default.

Content: requirements that still apply when you switch projects, such as your background, communication preferences, discussion and implementation workflow, and general expectations about scope and delivery.

Example: Here's a short global AGENTS.md for a product manager. Adjust it to match your background and how you like to work.

# How to work with me

- I'm a product manager. Prioritize user problems, product ideas, the user
  experience, and final copy in our discussions.
- When discussing a technical approach, explain why you recommend it, its impact,
  and the tradeoffs. Explain code details when needed.
- When I ask for opinions, analysis, or a discussion of possible solutions,
  discuss first. Change files when I explicitly ask you to implement and the
  goal and scope are clear.
- Only change what the current task involves. If you need to expand the scope,
  explain why and confirm with me first.
- When you're done, tell me what users will see, what you verified, and what
  remains unresolved.

3. What goes in a project AGENTS.md?

Location: the project root.

Content: the project's background and specific requirements, such as its structure and how to run it, existing modules and reuse requirements, development conventions, product positioning, business rules, and specific restrictions and verification steps.

Example: Here's a short project AGENTS.md. Replace the text in square brackets with your project's actual details.

# Project conventions

- This project is [project description], mainly for [target users].
- Main features live in [directory], and shared components live in [directory].
  Check the existing implementation before developing a feature, and prefer
  reusing existing modules and components.
- Reuse the project's existing components and follow its styles and naming
  conventions.
- Use [document path] as the source of truth for product positioning and business
  rules. When editing pages, don't change agreed pricing, plan benefits, or
  business workflows without approval.
- Start the project locally with [command]. Run checks and tests with [commands].
- After changing [feature], verify [the relevant user flow].

4. Optional: AGENTS.override.md

What it does: provides an instruction file that takes priority. Within the same directory, Codex reads AGENTS.override.md instead of that directory's AGENTS.md.

When it can be useful:

Temporarily changing your global requirements. Put the instructions you want to use for a while in ~/.codex/AGENTS.override.md. Keep the original AGENTS.md so you can return to it later.
Giving a module its own requirements. For example, your payments module might need a different way to run tests. You can create an AGENTS.override.md in the payments directory. Starting a chat with that directory as the working directory brings those instructions into context.

Things to keep in mind:

Only one file is loaded per directory. If there are instructions in the original AGENTS.md that you still need, include them in the override file too.
Instructions from other levels still load. An override in the payments directory doesn't clear the global and project instructions. Where they conflict, the instructions closer to the current working directory take priority.
It doesn't expire automatically. If you're using it temporarily, move it out of the directory or rename it when you're done, then start a new chat.
You don't need an AGENTS.md first. You can use an override file even if there's no regular AGENTS.md in that directory. You can also put a subdirectory's specific instructions in a regular AGENTS.md. What makes the override different is its priority within the same directory.

If you're just getting started, write the global and project instructions you need first. Use an override when there's a reason to.

Optional reading: How AGENTS.md works

1. When does Codex read AGENTS.md?

When you start a new chat in a project and begin a task, Codex automatically loads the applicable AGENTS.md instructions.

If you update one of these instruction files during a chat, you can ask Codex to read it again, or start a new chat to load the updated instructions.

2. How does Codex find AGENTS.md?

Codex looks for global instructions first, then checks the directories along the path from the project root to the current working directory.

For example, if you start a chat with the project's payments directory as the working directory, the order is:

Global instructions -> Project root instructions -> Payments directory instructions

If any directories in between have instruction files, Codex loads those too. The search stops at the current working directory.

3. If both files are in the same directory, which one does Codex read?

Codex prefers AGENTS.override.md. If there isn't a usable override file, it reads AGENTS.md. Empty files are skipped.

4. How do you check after creating or updating a file?

Save the file, start a new chat in the project, and check whether the instructions have loaded. You can ask:

List the paths of the instruction files loaded for this chat, and summarize the main requirements from each.

Check the paths and summaries, then try a small task. For example, if you wrote "Don't change code while we're discussing an approach," see whether Codex follows that instruction. Along with checking what it says it loaded, check what it actually does.

References

My own experience with nearly a year of regular vibe coding.
Official AGENTS.md documentation

The main reference for this guide. Covers file locations, loading order, overrides, and ways to check which instructions are loaded.

Rethinking skills and prompts for GPT-6 Astra

Explains how to remove outdated instructions, provide context for the task at hand, and make collaboration boundaries clear. Some recommendations are specific to GPT-6 Astra.

Official Projects and chats documentation

Explains the working directory used for new chats in the desktop app and where Codex automatically looks for AGENTS.md.

Official Claude Code documentation

Explains what CLAUDE.md is for and how it stores collaboration requirements and project conventions.

I Built a Tesla Digital Wrap Editor in Two Weeks of Late Nights—and Someone Paid Before I Started Promoting It in Earnest

Irving — Thu, 17 Sep 2026 09:22:05 +0000

Last month, I shared photos of the latest digital wrap I'd made for my Tesla and asked people what they thought. To my surprise, what they really wanted to know was, “How did you make that?” Some of them were Tesla owners themselves.

A quick explanation: a Tesla digital wrap changes the appearance of the 3D vehicle model on the car's screen and in the Tesla app. The actual car stays the same.

Left: the Tesla touchscreen. Right: the Tesla app.

A Friend's Idea That Stuck with Me

One friend who owns a Tesla messaged me privately. He wanted to put photos of his own pets on a digital wrap, so he could see them whenever he got into the car or opened the app. I thought that sounded pretty cute.

I told him how to do it using Tesla's official templates and Photoshop, but he didn't know how to use Photoshop and eventually gave up.

Earlier this month, I saw people in a group chat discussing a Tesla digital wrap product. It caught my interest, so I searched online and found other people looking for similar things.

The group also mentioned a few products, which I checked out. They offered plenty of ready-made wraps to download and use for free, which was nice. They also supported AI generation: describe the theme and style you want, and AI helps generate a wrap.

At that point, the features seemed pretty comprehensive. You could download an existing design or generate one based on your own ideas.

Later, while chatting with that friend one evening, I was about to recommend those products to him. Then I remembered that he'd specifically wanted to use photos of his own cats and dogs.

So I took another look: could he upload his own photo, resize and rotate it, and put it where he wanted, as he would in Photoshop? In the products I checked at the time, I couldn't find a convenient way to do that.

That made me realize that “I want a dog-themed wrap” and “I want this photo of my own dog on the car door” are two different needs. In the second case, the person already has an image they like. They need an easy way to edit it and see what the result will look like.

Two Weeks to Build the First Version

I'm a Tesla owner and have a background in development. The more I thought about it, the more I felt this was something I could build.

So I got to work. After two weeks of late nights, I finally had the first version! It's called Tesla Wrap Studio, and it lets you create digital wraps right in your browser.

The first version has two main parts.

1. A Wrap Gallery: Pick a Design and Download It

I put together a gallery of ready-made digital wraps, including designs provided by Tesla, that people can download and use for free. If you don't want to design something from scratch, there are options to choose from.

2. Custom Wraps: Use Your Own Images or Generate a Design with AI

This was the part I most wanted to build. The editor lets you upload images, add text, and adjust your design for each area of the car's body.

Thinking about my friend's request, simply being able to upload a photo wasn't enough. He also needed an easy way to put it where he wanted. So I wanted people to be able to select an area such as a door or the hood, then adjust the image's size, position, and rotation while seeing a live 3D preview alongside it.

In the example below, I've placed a dog's photo on the right front door. As the photo is adjusted, the preview on the right shows how it looks on the car.

You can also enlarge the preview and rotate the car to check the image's placement and see how the design looks overall.

If you don't have an image to start with, you can describe the theme and style you want and use AI to generate a wrap. This cartoon dog design is one example.

Here's how the same design looks on the vehicle model:

I also added an AI refinement feature. For example, if you've finished one or two areas of the car, AI can help complete the remaining areas. If the styles across different areas don't quite work together, it can also help make the design more consistent and refine the result.

A Paying Customer Before I'd Started Promoting It in Earnest

With the first version ready, I felt it was time to start getting it in front of people, so I asked friends to try it out.

Then, one morning, before I'd started promoting it in earnest, a payment came in: a user in Japan had found the product through Google and paid for it!

Seeing that payment notification made me really happy. I'd spent so many nights working late over those two weeks. Having someone willing to pay for something I'd built was a real encouragement.

But someone being willing to pay doesn't mean the product is already as easy to use as it should be.

It's a very specific need, but it's one I share. Being able to build something that my friends and I wanted to use means a lot to me.

Next, I want to keep improving the process of uploading photos, adjusting their position, previewing the design, and exporting it. My friend originally gave up because he didn't know how to use Photoshop. I'd like someone trying digital wraps for the first time to be able to bring their own idea to life without getting stuck.

My Product Got “Interviewed”

Irving — Mon, 17 Aug 2026 11:58:32 +0000

A couple of weeks ago, I saw someone on X repost an open call from Jason
Zhu, the founder of Ship2Market. He was inviting founders to submit their
products, and his team would choose three to promote for free.

I immediately thought of one of my own products. I still believed in the
idea, but getting traffic had been a constant headache. The opportunity felt
like a good fit, so I applied.

More than 70 products were submitted, and I was lucky enough to be selected
for a conversation with the team.

We scheduled the call for today. Jason came across as warm and easy to talk
to. I had expected it to be just Jason and Vivian, but four people showed up.
As an introvert, I got a little nervous, and for a while my thoughts came out
more jumbled than I would have liked.

The product I submitted was InkStudio.ai, which I started building over Lunar
New Year.

I first discovered the category while browsing Toolify’s revenue rankings for
AI products. The fact that even these smaller products were making money told
me there was at least some real willingness to pay.

Then I tried the products myself.

My honest first reaction was: Isn’t this just another AI wrapper?

You type in a prompt, and it generates a tattoo image. It didn’t seem
especially difficult to build. Then I tried looking at the products from a
user’s perspective, and I still couldn’t find anything that truly wowed me.

At the time, I had just started experimenting with AI tools for a global
audience and wanted to get more hands-on practice, so I decided to build one.

At the beginning of the call, Jason asked me:

How is your product different from the competition?

My answer was this:

Most competing products follow the same basic pattern: enter a prompt,
generate a tattoo image, and stop there.

That can certainly give people tattoo inspiration. But it’s also something
most products in the space can do fairly easily, which makes it difficult to
stand out.

These days, with endless content online and generative AI everywhere, finding
inspiration isn’t particularly hard.

But tattoos are permanent, and regret can be expensive.

While researching the market on Reddit, I came across many people who said
they regretted their tattoos afterward. Some were getting their first tattoo.
Others were naturally shy or introverted. They either didn’t know how to speak
up or didn’t feel comfortable giving feedback to the tattoo artist during the
process.

By the time the tattoo was finished, they weren’t happy with the result.

If I had to reduce InkStudio.ai’s core value to one thing, it would be this:

Help people find inspiration and preview how a tattoo might actually look on
their body, so they can communicate more clearly with their tattoo artist,
walk into the shop with confidence, and walk out happy.

When I started building the product, I knew very little about reaching users
in international markets.

SEO was what almost everyone in my circle seemed to be doing, so once the
product was ready, I followed the same playbook. I worked on on-page SEO,
off-page SEO, and programmatic SEO.

But SEO was slow—especially for keywords with any real competition.

At first, I was getting double-digit impressions and single-digit clicks.
Eventually, impressions grew and clicks reached double digits, but the search
queries in Google Search Console showed that the traffic still wasn’t well
targeted.

Without enough of the right users, I couldn’t see where people were dropping
off, what needed to be improved, or what I should build next.

I was essentially building in a vacuum and trusting my own gut.

Waiting for Google to bless you with traffic is anxiety-inducing. Early-stage
products rarely deliver a great experience right away, and I worried that a
weak early experience could make my SEO efforts even harder.

So I decided to be more proactive and look for channels that could help me
reach users—and get feedback—more quickly.

I tried Reddit. My account was banned within a few days.

I tried TikTok. I asked people for advice, worked through all the setup, and
started posting. My videos either got zero views or around 100.

Once again, I had no idea what I was doing.

Instagram and Facebook came with their own learning curves. Every platform
had its own rules, and simply posting wasn’t enough.

As a complete beginner to marketing on global social platforms, testing one
channel after another—and making mistakes on every one of them—was honestly
painful.

During the call, Vivian shared some of what she had learned about how people
in different markets think about tattoos.

She also asked whether I had considered offering temporary tattoos.

I immediately thought the idea made sense. If someone is worried about
regretting a permanent tattoo, a temporary tattoo gives them a lower-risk way
to try the design first.

Since InkStudio.ai is ultimately about helping people reduce the chance of
regret, the idea felt aligned with the product’s philosophy.

Jason also shared how he approaches getting a new product off the ground,
including Google Ads and social media.

Toward the end of the call, I asked him:

The selected products get three days of free promotion. What would it look
like to keep working together after that?

Looking back, that question revealed the biggest challenge I currently face
as a product-manager-turned-indie developer:

The cold-start problem—and, more simply, traffic.

Indie developers often have to handle everything themselves: identifying the
problem, designing the product, building it, and figuring out growth.

It isn’t an easy path.

SEO can consume a huge amount of time. If traffic arrives before the product
is ready, you may not be able to make the most of it. But if you focus entirely
on building the product, you can end up with something polished and no
traffic—which also means no meaningful user feedback.

Building the product is hard. Building the feedback loop around it may be even
harder.

One more thing that meant a lot to me: Ziye, who helped review my product and
previously worked as an AI product manager at TikTok, shared a post about my
product on WeChat Moments, WeChat’s social feed, and encouraged me.

When you’re building alone and constantly wondering whether you’re on the
right track, that kind of encouragement means more than people realize.

I Built an AI Website in 3 Hours. It Got 562 Sign-Ups in 8 Hours—and Left Me More Lost.

Irving — Wed, 12 Aug 2026 12:13:32 +0000

This is a true story from eight months ago.

One night around 9 p.m., I noticed a search term beginning to spike on Google Trends. It looked like people were starting to search for something new—and that there might be an opportunity.

I shared it in a group chat and asked if anyone wanted to build a product around it. No one did, so I decided to give it a try myself.

Three hours later, the website was live. The core feature, user authentication, and AI model integration were all working. It was close to 1 a.m. when I shut down my laptop and went to bed.

Just another practice project, I thought.

At around 9 the next morning, I searched the keyword on Google and saw my website at the top of the results.

I was excited, so I took a screenshot and shared it with the group. Soon, someone tried the website and told me:

“Your website has a bug. It’s throwing an error!”

I checked and found that it wasn’t a problem with the code. The API credits I had bought had already run out.

I was confused. I had just added more credits. How could they be gone after a single night?

Then I opened the user dashboard.

Just eight hours after launch, the website already had 562 registered users.

To understand why that number mattered so much to me, you need to know where I was at the time.

I had been building products independently for less than a month after working as a product manager. I had already launched five websites using AI, and none of them had attracted any attention.

But this time, it felt like I had finally made the whole process work—from spotting a need to building a product and finding users.

It was the clearest sign yet that I might be on the right track.

Why I Wanted to Build Products Myself

It all started with anxiety.

Over the past few years, AI has advanced at an incredible pace.

Last year in particular, AI seemed to be everywhere, and the tools kept getting smarter.

That made me increasingly anxious.

AI was already changing the way people worked, yet I was still mostly just chatting with ChatGPT and DeepSeek.

If the AI boom was creating real opportunities, simply chatting with AI tools wasn’t going to give me an edge. Too many people could already do that.

To get a better grasp of AI, I began studying the fundamentals of generative AI. I also learned how to build agents and workflows with Coze.

I used them to help my company produce content at scale, and they improved our efficiency.

But I soon began to question myself again:

Was writing prompts and building workflows really enough to say I understood AI?

These skills were useful, but they weren’t hard to replicate. Anyone willing to spend some time learning could do the same.

I wanted to go further.

That meant getting much more hands-on with AI. I didn’t want to use it for just one part of the process; I wanted to build a complete product on my own.

My First Month as a Solo Builder

Toward the end of last year, I came across a group of people using AI to build web products for global markets.

The playbook was simple:

Use tools such as Google Trends to identify emerging needs.
Build products quickly with AI.
Acquire users through SEO.

After trying it for a few days, I managed to build a product of my own. I was thrilled, and I immediately shared it with my friends.

In the past, taking a product from idea to launch could involve at least six different roles: a product manager, a designer, front-end and back-end developers, a QA engineer, and a DevOps engineer. But now, one person working with AI could handle the entire process.

In my first month, excluding practice projects, I launched five websites. The fastest was the website from the beginning of this story. It took only three hours to go from identifying the need to launching the product.

That was the first time I truly felt it:

The AI era wasn’t on its way. It was already here.

I Thought I Had Completed the Transition

My background was in product management. My work usually involved researching user needs, writing PRDs, creating prototypes, and then handing everything over to designers and developers.

I could define what to build, but I couldn’t build it myself. Now I could research user needs, design the product, build it, test it, and launch it—all on my own. That felt like a huge leap.

For a while, I thought I had completed the transition. I had gone from working on one part of the product process to taking a product from idea to launch on my own.

But that excitement didn’t last long.

Building a Product Wasn’t the Same as Building a Business

Over the next two or three months, I continued launching products.

Most of them ended up in one of two situations:

I had a product, but no users.
I had users, but no one was willing to pay.

I had gone through every step of the process, but only at a surface level.

SEO, for example, looked like a clear user-acquisition channel. But in practice, it was far from simple.

Low-competition keywords often had little search volume or didn’t point to a problem people would pay to solve. Keywords with real commercial value were usually already dominated by established competitors. In the short term, it was difficult to gain even a small foothold.

Building a product quickly was one thing. Figuring out how to turn it into a viable business was another.

Even with 562 sign-ups in eight hours, I still couldn’t answer some basic questions:

What problem were the users actually trying to solve?
Why did some users pay while others didn’t? What were they actually willing to pay for?
Would they return once interest in the keyword declined?

Every step in the user journey raised another question, and I had to work through them one by one.

This experience made me realize:

Traffic is not demand. A sign-up is not validation. Launching a product does not mean you have a viable business.

At the same time, AI had clearly lowered the barrier to building products.

Tasks that once required months of technical learning had become much easier with AI. Work that once required several different roles could now be handled by one person.

But that barrier had fallen for everyone.

If I could use AI to launch a website in three hours, someone more familiar with the process might be even faster.

Both knowing how to use AI and being able to build products with AI may gradually become baseline skills rather than lasting competitive advantages.

So what would actually set me apart?

Eight months ago, that question left me feeling lost all over again, right when I thought I had reached a new starting point.

Eight months later, after building more products, making more mistakes, and gradually figuring out what I wanted to pursue, I now have my own answer.

Originally published on Medium.