OpenAI Codex Tutorial #6 - Using the AGENTS.md file

Key Takeaways

Okay then my friends in the previous lesson we talked about commands which come baked into the Codex CLI tool and one of those commands was the init command which generates an agents.md file for us in this project. Now we're going to run this command shortly but just very quickly first of all I want to talk about what an agents file actually is and why we would use one. So you can think of an agents file as a bit like a readme but instead of being written for humans it's written for the coding agents that you're working with. It lives in your project, usually in the root folder, and it tells the agent how your codebase works, what commands it should use to build and test things, what coding styles you prefer, how your project is structured, and so forth. It's basically like a little cheat sheet that helps the agent slot into your workflow and code basically how you would like them to code. So, Codeex leans heavily into this agents.md file. And whenever you ask Codeex to do something either locally or on Codex cloud, it's going to look for that file in your project, if it's there, it's going to use any information inside that file as context within your prompts and any task that you give it. If you've used any other AI coding agents like Claude Code or Copilot, you have probably seen similar kinds of files in those things. In Clawed Code, we use a claw.md file for projectwide instructions. And in copilot, we use a copilot instructions markdown file for the same kind of uh stuff. And these all serve a similar purpose, right? In that they give each agent memory and concise project context. Where they differ is that the agents.mmd file is being pushed as a standard across different AI coding tools. So that instead of juggling these different files for different coding agents, the idea is that we can have just a unified agents file which could then be used across all of them. And there's already a bunch of different tools incorporating this agents.mmd file. So let's head back to the code then and use the codec cli to scaffold an agents file for us. Okay then. So I'm currently in a codec session and I'm going to use the init command to generate a new agents.mmd file. And when we use this command, codeex is automatically going to scan the codebase and scaffold the file for us with any code styles, testing preferences, and other things it finds. Sometimes it might add its own personal preferences as well. So you have to rein those in a little bit if you see those. And along the way, we might need to approve certain commands as well. But then after a few moments, it's going to make it for us and place it in the root of our project. Okay, so it looks like it's done it. Let's go and have a look over here at this new file. And you can see it's written some fairly comprehensive guidelines. It's a little lean, but you can always add to this later. So we have different headings for different things. So for example, the project structure and module organization talks about where different things live. So we have the app which lives inside this folder and then we have different route segments like this. We also have the layout and the global CSS file. Reusable UI components live here. Okay. So that all looks pretty good. Uh we've got some building testing and development commands down here which all look quite accurate. Yep. Then we have some coding style and naming conventions. It says use Pascal case like this. Okay. So basically this is all generic stuff but all it's doing is looking at our current uh project as it is at the moment and inferring the guidelines from there and it all looks quite accurate at the moment. It's got some testing guidelines down here as well and it talks about this test folder to put the test inside and then at the bottom we've got some commit and pull request guidelines as well. Awesome. So then you should also probably commit this agents file to your GitHub repository if you want the Codex cloud to use it when you're running remote tasks because again whenever you ask it to do something on the cloud it's going to look for this file automatically and it's going to use it as context for that task. And for that reason I'm going to push this change up to the GitHub repo once I finish recording this video just to keep everything up to date and in sync. And by the way, this file isn't something you should just create and forget about. As your project changes and evolves, you should update your agent file as well with anything new the coding agent should know about. For example, if you start using particular libraries or frameworks or if you change your project structure or testing procedures, etc. Because if you don't keep the file up to date, then codeex might go off track and do things the old way as outlined in the original agents file if you don't change it. So definitely come back and update the file as and when you need to.