Before asking Codex to change your application, give it the orientation you would give a new teammate: where features belong, which packages own shared behavior, and how to check a patch. Codex recognizes AGENTS.md as persistent repository guidance. Use it to describe your working agreements, not to reproduce your entire documentation site. ([developers.openai.com](https://developers.openai.com/cookbook/examples/codex/iterating-development-workflows-with-codex))
1. Inspect Your Repository Before Writing Instructions
Start with the actual checkout. Read the top-level README, package manifests, test configuration, and an existing feature. Identify application entry points, shared libraries, generated files, and deployment configuration. Verify each directory’s purpose rather than inferring it from its name.
For this walkthrough, imagine a JavaScript monorepo with a web application, an API service, and a shared package. Treat the following paths and commands as examples to replace, not defaults to copy blindly.
2. Create AGENTS.md at the Repository Root
Create a file named AGENTS.md beside the root README. Alternatively, run /init inside Codex to generate a starting draft from the repository context, then review every claim and command. OpenAI documents this command as a way to bootstrap the file. ([developers.openai.com](https://developers.openai.com/cookbook/examples/codex/iterating-development-workflows-with-codex))
Begin with one sentence explaining the application’s purpose. Follow it with a compact repository map. Write entries as decisions: what belongs here, what does not, and which nearby implementation provides a useful example.
- apps/web: Browser routes, page components, and client-side state. Keep database access outside this application.
- apps/api: Request handlers and server-side business logic. Follow the existing handler and service separation.
- packages/shared: Types and validation used by both applications. Avoid importing application-specific modules here.
- generated: Generated artifacts. Update their source definitions and regenerate instead of editing outputs directly.
3. Record Commands with Their Working Directories
Replace vague instructions such as “run the tests” with commands you have verified locally. For the example repository, an entry might say: “From the repository root, run npm ci, then npm run lint and npm test.” Only include those commands if the lockfile and scripts actually support them.
Add narrower checks for common changes. State whether an API test runs from the root or from apps/api. Explain required environment variables by name, but never include credentials. Ask Codex to report checks that could not run and why, rather than presenting unexecuted checks as successful.
4. Put Package-Specific Guidance Near the Package
Keep shared conventions in the root file and specialized rules in files such as apps/api/AGENTS.md. Codex builds project guidance along the path from the repository root to its working directory, with more specific guidance appearing later. Start a package-focused session in that package when verifying its instructions. ([developers.openai.com](https://developers.openai.com/codex/guides/agents-md))
For example, the API file could identify the integration-test directory and require request validation at the handler boundary. Avoid duplicating the root map or creating nested files without a real difference in workflow.
5. Check Overrides Before Debugging Conflicting Rules
Inspect relevant directories for AGENTS.override.md. Codex checks that filename before AGENTS.md in each directory; it does not combine both files from that same directory. Global guidance in the Codex home directory can also affect the instruction chain. ([developers.openai.com](https://developers.openai.com/codex/guides/agents-md))
Prefer explicit, consistent boundaries: “Do not change deployment configuration unless requested” is more actionable than “be careful.” Keep enforcement in tests, permissions, and review processes rather than relying on prose alone.
6. Verify the Repository Map in a Fresh Session
Start a fresh Codex session after editing guidance so the instruction chain is rebuilt. ([developers.openai.com](https://developers.openai.com/codex/guides/agents-md)) Ask: “Before editing, summarize the repository instructions, identify the files involved in adding an API endpoint, and list the checks you would run.” Compare the answer with the checkout. Then try a small patch and inspect its diff.
7. Keep Repository Guidance Separate from Provider Setup
If you use SwiftRelay with Codex, keep relay credentials and provider configuration outside AGENTS.md. SwiftRelay is a practical pay-as-you-go option for a workflow that also uses Claude Code or Gemini CLI. Sign up for SwiftRelay to try that setup with the small gift credit for new accounts.
Commit the reviewed AGENTS.md with your repository, and update it whenever paths, commands, or ownership boundaries change. Make checking the guide part of reviewing structural changes.