In our last lesson, we learned how to use Codex to explore a new project and understand its structure. However, every time you start a new chat, the agent "forgets" your specific preferences unless you tell it again. To fix this, we use a file called AGENTS.md.

Think of AGENTS.md as the permanent instruction manual for your repository. It acts as a System Prompt. Every time you launch Codex, it reads this file from your repository root to understand your rules, coding style, and safety boundaries. By keeping these instructions in a file, you ensure that Codex always behaves consistently, no matter who is using it or when the session starts.

As a reminder from our previous work, you can always enter the interactive mode by typing this command in your terminal:

Once inside this interactive view, you are ready to start configuring your agent.

You don't have to create the AGENTS.md file by hand from scratch. Codex has a built-in shortcut to help you get started.

Inside the Codex interactive session, you can use the /init command.

When you run this, Codex automatically generates a basic AGENTS.md file in the root directory of your project. In the CodeSignal IDE, you will see this new file appear in your file explorer on the left.

The default file provides a skeleton structure. It often includes placeholders for the project's purpose and basic instructions. This saves you time and ensures the file is named and placed correctly so that Codex can find it later.

The first major section you should add to your AGENTS.md is Coding Style. This ensures the AI doesn't write code that looks "out of place" compared to the rest of your project.

Let's start building our file content. We will begin with a simple header and some style rules:

• # Agent Instructions: This is the main title of your rulebook.
• ## Coding Style: This sub-header tells Codex exactly where to look for formatting rules.
• The bullet points give clear, simple directions. By specifying 2 spaces and double quotes, you prevent the agent from using its own default settings, which might be different from your project's existing code.

Now, let's add one more detail to make the code even cleaner:

• Adding the "trailing comma" rule helps keep your git diffs clean. When the agent knows these small details, you won't have to manually fix the formatting after the AI finishes its work.

A great agent doesn't just write code; it verifies that the code actually works. We can enforce this by adding a Testing Requirements section that tells the agent exactly what “done” looks like: update tests when behavior changes, then run a quick local test command to validate the result before sharing the final patch. If tests fail, the agent should fix the code (or the tests, if the expectations are wrong) and re-run until the suite passes.

Let's update our AGENTS.md file to include these rules:

• ## Testing Requirements: This section tells the agent that quality is a priority.
• "add or adjust tests": This prevents the agent from "fixing" a bug but forgetting to update the test suite.
• “after making changes and before presenting the final diff”: This sets the expected workflow (implement → test → present).
• Failure handling: ensures the agent treats failing tests as a stop sign, not something to ignore.
• npm test -- --watchAll=false: By providing the exact command, you give the agent a specific tool to use. The --watchAll=false flag ensures the tests run once and exit, rather than hanging in a "watch" mode.

To make our agent truly professional, we need to set safety boundaries and define how it should document its work.

When writing safety rules for an AI agent, it’s often more reliable to avoid “negation-only” instructions (like “never do X”) and instead provide a clear alternative behavior (like “if X seems necessary, ask first” or “instead of X, do Y”). This reduces ambiguity and makes it easier for the agent to stay within guardrails.

Let’s add a Safety Boundaries section and a Commit Messages section.

• ## Safety Boundaries: These are the "guardrails."
• Lockfiles rule: instead of only saying “don’t,” it tells the agent what to do if it thinks a lockfile update is needed (ask first).
• Comments rule: instead of deleting comments, the agent should preserve or improve documentation.

Finally, we define the Commit Messages:

• ## Commit Messages: This ensures that if the agent commits code for you, the history stays readable.

You have now seen how to build a complete AGENTS.md file. By combining Style, Testing, Safety, and Documentation rules, you have transformed Codex from a general AI into a specialized agent tailored specifically for your project.

Here is a summary of what we covered:

• Using /init to create the file structure quickly.
• Writing style rules to keep code consistent.
• Running tests after implementing changes and before finalizing the proposed diff to ensure code quality.
• Setting safety boundaries with clear “what to do instead” rules to keep your project safe.
• Standardizing commit messages for professional workflows.

In the upcoming practice exercises, you will get hands-on experience starting from an empty repository and building this file piece by piece. Remember, on CodeSignal, once you save your AGENTS.md file in the editor, Codex will immediately start using those rules in your next interaction!