How coding agents find your design rules

This page is for a founder who put a design.md file in a project and expected the coding tool to follow it. Codex, Claude Code, and Gemini do not look for that filename. Each one reads a different instruction file. Your prices, colors, and refusals are invisible until that instruction file tells the tool to open design.md. The notes below come from each product's own documentation on 22 September 2026. This page does not report a run inside any of the three products. The longer Codex walkthrough stays at the existing article, DESIGN.md for Codex.

Codex looks for instructions in two places. In your Codex home folder it reads AGENTS.override.md if that file exists, and otherwise AGENTS.md. Inside the project it starts at the project root and walks down to the folder you are working in. It takes at most one instruction file from each folder and joins them into one note. Files closer to your work come last, so they can override the earlier ones. Empty files are skipped. It stops adding text when the combined note reaches 32 KiB by default. The setting is named project_doc_max_bytes, and the limit is measured in bytes, not characters. Do not paste a whole design system into AGENTS.md. Codex has no documented reason to open design.md unless AGENTS.md tells it to, or you add design.md to the fallback list in config.toml. The older docs address on developers.openai.com redirected to the ChatGPT Learn page when this guide was checked.

Claude Code reads CLAUDE.md when a session starts. The memory guide treats that file as background the model can see, not as a lock that stops a bad edit. It suggests keeping CLAUDE.md under about 200 lines, and putting a step-by-step procedure in a skill that is loaded only when the task needs it. design.md is not on Claude's list. Import it from CLAUDE.md, or tell the session to open it. AGENTS.md is the awkward case. By default Claude reads AGENTS.md only when the project has no CLAUDE.md and no CLAUDE.local.md. That direct read needs Claude Code version 2.1.277 or later. If CLAUDE.md is already there, Claude reads CLAUDE.md and skips AGENTS.md unless you change the project-instructions setting. Some sessions, including Amazon Bedrock, cannot read AGENTS.md at all. In those sessions, import the rules from CLAUDE.md.

Gemini CLI reads GEMINI.md files through the project hierarchy. A project file can import another file, and the context.fileName setting can change the filename Gemini looks for. Check the current Gemini CLI documentation before depending on an account-specific or preview feature. Keep one source of truth and inspect the hierarchy and imported files so the same rule is not repeated in several places.

Leave the visual rules in design.md. Then add one short pointer in the file the tool already reads. For Codex, put a line in AGENTS.md that says to read design.md before changing marketing pages. You can instead add the filename to the fallback list, but the combined instructions still stop at 32 KiB by default. For Claude Code, import design.md from CLAUDE.md with the @path syntax in the memory guide, or keep the short rules in CLAUDE.md and put the long example in a skill. For Gemini CLI, import design.md from GEMINI.md or add the filename through context.fileName. These rules can change, so recheck the product page before you hand the steps to someone else.