Authoring Agent System Prompts

Introduction and Context

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: Shell codex Once inside this interactive view, you are ready to start configuring your agent.

Initializing the Rulebook with /init

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. Shell /init 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.

Defining Style and Formatting

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: Markdown # Agent Instructions ## Coding Style - Use 2 spaces for indentation. - Use double quotes for strings in TypeScript files. # 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: Markdown # Agent Instructions ## Coding Style - Use 2 spaces for indentation. - Use double quotes for strings in TypeScript files. - Always include a trailing comma in multi-line objects and arrays. 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.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Enforcing Quality with Testing Rules

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:

Markdown

# Agent Instructions

## Coding Style
- Use 2 spaces for indentation.
- Use double quotes for strings in TypeScript files.
- Always include a trailing comma in multi-line objects and arrays.

## Testing Requirements
- When changing behavior, you must add or adjust tests to match.
- Run the fastest local test command after making changes and before presenting the final diff: `npm test -- --watchAll=false`
- If the test run fails, do not finalize the change. Investigate the failure, apply a fix, and re-run tests until they pass (or report the failure and ask for guidance if it can’t be resolved quickly).

# Agent Instructions

## Coding Style
- Use 2 spaces for indentation.
- Use double quotes for strings in TypeScript files.
- Always include a trailing comma in multi-line objects and arrays.

## Testing Requirements
- When changing behavior, you must add or adjust tests to match.
- Run the fastest local test command after making changes and before presenting the final diff: `npm test -- --watchAll=false`
- If the test run fails, do not finalize the change. Investigate the failure, apply a fix, and re-run tests until they pass (or report the failure and ask for guidance if it can’t be resolved quickly).

## 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.

Setting Safety Boundaries and Commit Standards

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.

Markdown

# Agent Instructions

## Coding Style
- Use 2 spaces for indentation.
- Use double quotes for strings in TypeScript files.
- Always include a trailing comma in multi-line objects and arrays.

## Testing Requirements
- When changing behavior, you must add or adjust tests to match.
- After implementing a change, run the fastest local test command before presenting the final diff: `npm test -- --watchAll=false`

## Safety Boundaries
- Lockfiles: do not modify lockfiles (e.g., package-lock.json). If a lockfile change seems required, ask for confirmation first and explain why.
- Comments: keep existing explanatory comments. If a comment is inaccurate, update it rather than deleting it.

# Agent Instructions

## Coding Style
- Use 2 spaces for indentation.
- Use double quotes for strings in TypeScript files.
- Always include a trailing comma in multi-line objects and arrays.

## Testing Requirements
- When changing behavior, you must add or adjust tests to match.
- After implementing a change, run the fastest local test command before presenting the final diff: `npm test -- --watchAll=false`

## Safety Boundaries
- Lockfiles: do not modify lockfiles (e.g., package-lock.json). If a lockfile change seems required, ask for confirmation first and explain why.
- Comments: keep existing explanatory comments. If a comment is inaccurate, update it rather than deleting it.

## 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:

Markdown

# Agent Instructions

## Coding Style
- Use 2 spaces for indentation.
- Use double quotes for strings in TypeScript files.
- Always include a trailing comma in multi-line objects and arrays.

## Testing Requirements
- When changing behavior, you must add or adjust tests to match.
- After implementing a change, run the fastest local test command before presenting the final diff: `npm test -- --watchAll=false`

## Safety Boundaries
- Lockfiles: do not modify lockfiles (e.g., package-lock.json). If a lockfile change seems required, ask for confirmation first and explain why.
- Comments: keep existing explanatory comments. If a comment is inaccurate, update it rather than deleting it.

## Commit Messages
- Use the Conventional Commits format.
- Examples: `feat: add login logic`, `fix: resolve crash in header`.

# Agent Instructions

## Coding Style
- Use 2 spaces for indentation.
- Use double quotes for strings in TypeScript files.
- Always include a trailing comma in multi-line objects and arrays.

## Testing Requirements
- When changing behavior, you must add or adjust tests to match.
- After implementing a change, run the fastest local test command before presenting the final diff: `npm test -- --watchAll=false`

## Safety Boundaries
- Lockfiles: do not modify lockfiles (e.g., package-lock.json). If a lockfile change seems required, ask for confirmation first and explain why.
- Comments: keep existing explanatory comments. If a comment is inaccurate, update it rather than deleting it.

## Commit Messages
- Use the Conventional Commits format.
- Examples: `feat: add login logic`, `fix: resolve crash in header`.

## Commit Messages: This ensures that if the agent commits code for you, the history stays readable.
Conventional Commits: This is a standard industry format (using prefixes like feat: or fix:) that makes project history very easy to follow.

Authoring Agent System Prompts

Introduction and Context

Initializing the Rulebook with /init

Defining Style and Formatting

Join the 1M+ learners on CodeSignal

Enforcing Quality with Testing Rules

Setting Safety Boundaries and Commit Standards

Summary