Codex Tips

Nikos Katsikanis - July 12, 2025

Constantly Evolving

Agents keep improving, so these tips may be out of date in a month or two.

Keep PRs Focused

Limit each pull request to one or two features, archive the context, and start fresh to avoid confusion.

Simplify Instructions

The clearer the instructions, the better the results.

Ask Questions

It is fine for the agent to ask questions to verify the code and explain why it works.

Agents File

Maintain an AGENTS.md that spells out repository rules. Ours looks like:

All code must be production ready, well tested, and documented.
Use latest versions of Ruby libraries and frameworks.
Where possible use full unit tests, and e2e tests with seed quality data that we can even use for live demos.
Don't allow any pr to be made that has failing tests.
All test must pass GitHub Actions consistently. Do not make and PR that does not pass all tests.
Don't include any binary files in any pull request.
At the start of each week on a Monday review every *_help_content.html partial and update its guidance so it matches the current codebase. Don't update if the guidance is updated already that day for that item.
Avoid touching help pages when the only change is the "Last updated" date.
llms.txt files:
https://daisyui.com/llms.txt

Automatically updating help files from the code saves time, and the llms.txt link explains why this policy matters.

Testing

Prefer full unit and end-to-end tests with quality seed data for demos. Never open a pull request with failing tests—GitHub Actions must pass.

Docs Automation

Each Monday an automated task updates every *_help_content.html file so the guidance matches the codebase. The llms.txt file helps motivate this practice.

Codex Can Be Lazy

Sometimes you need to repeat a request or explain it in more detail.