---
title: "Write scoped instructions for Codex."
description: "Create a concise AGENTS.md and reason about directory scope with a fictional project."
canonical: https://editmd.app/learn/lessons/agents-md/
markdown: https://editmd.app/learn/lessons/agents-md.md
status: pre-release, waiting list open
generated: editmd-website
---

# Write scoped instructions for Codex.

Lesson 09 of 12 in Markdown School. Create a concise AGENTS.md and reason about directory scope with a fictional project.

## Project guidance has a particular filename

Codex reads `AGENTS.md` as project instructions. The uppercase plural name matters; an arbitrary `agent.md` is not automatically the same convention. Codex builds a chain of applicable instruction files from broader scope toward the working directory. Within a directory, `AGENTS.override.md` takes precedence over `AGENTS.md`. [OpenAI's AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md/).

These files supply context. They do not change model weights, prove facts or replace the host's actual permission controls.

## Start with a small, observable contract

This is an original example for a fictional project whose package script really is `npm test`. Replace it with the command your project actually supports:

```markdown
# Garden project

## Scope

Edit documentation only.

## Checks

Run npm test and report failures.

## Boundaries

Ask before publishing. Do not invent results.
```

“Use good practices” is difficult to evaluate. “Report the command and its result” gives a reviewer evidence to inspect. Keep project facts separate from a one-off user request, and remove stale commands when the project changes.

## Reason about a directory tree

```text
garden-project/
  AGENTS.md
  docs/
    AGENTS.md
    planting.md
```

For work launched in `docs/`, identify both instruction files on the route from the root. A useful `docs/AGENTS.md` could add “Preserve existing source links.” Do not assume the same discovery model applies to Claude Code or Gemini CLI; their lessons document their own mechanisms. [Codex discovery and verification](https://developers.openai.com/codex/guides/agents-md/).

## Test the instruction, not just its headings

In a disposable project, ask Codex to identify the instruction sources it loaded and propose a documentation-only change. Inspect whether its proposed scope matches the files you intended. Give it a small change, then compare the reported test command with the actual terminal result. A model saying “all tests passed” is not itself evidence.

Try a second request that would require publishing. The example says to ask first. Record what happened; writing the boundary is not proof that it was enforced. Use actual permissions to control tools and external effects.

## Your exercise

Write the three sections below using the supplied fictional facts. The browser checks headings, nonempty sections and the named test command. It does not launch Codex or certify that your instructions will be followed. After it passes, explain which rule belongs at the root and which belongs only under `docs/`.

Sources checked 17 September 2026. Host behavior can change; verify it against the linked documentation when using these examples.

## Exercise

Write a project title and populated Scope, Checks and Boundaries sections. Name the supplied test command and keep publication outside this task.

## Takeaway

Use the exact filename, inspect scope and test behavior on a small task.

Related guide: https://editmd.app/docs/ai-use/. All lessons: https://editmd.app/learn.md