Which Instructions Belong in AGENTS.md?

Save durable, scoped, testable project rules in AGENTS.md. Keep one-off deliverables, temporary preferences, and stale facts in the current task.

A durable instruction should recur, remain valid across tasks, make sense to someone without the chat history, and be verifiable. One-time deadlines, temporary state, secrets, and unconfirmed preferences do not belong in project instructions or AGENTS.md.

If you repeatedly tell Codex to read the README first, preserve published URLs, and run tests after changes, those rules may deserve a permanent home. If you also add today’s error message, an event deadline, and a one-off draft request, the file quickly becomes a junk drawer.

OpenAI describes AGENTS.md as an open-format README for agents that can contain repository structure, run instructions, testing commands, conventions, prohibitions, and completion criteria. ChatGPT Projects can also have instructions that apply within the project. OpenAI: Codex best practices OpenAI: Projects in ChatGPT

The two mechanisms are not technically identical. Both influence many future tasks, so restraint matters.

The official documentation explains their purpose. The four tests below—recurring, durable, understandable, and verifiable—are my method for deciding whether a rule belongs there. They are not an official OpenAI scorecard.

1. Does the rule genuinely recur?

“Send the first version by Friday” belongs to one task. “Verify sources before publishing any external article” may continue to apply.

Observe two or three runs. If you repeatedly paste the same reminder or correct the same class of mistake, add it as a candidate. One failure is not a reason to create ten permanent safeguards.

2. Will the rule remain true later?

Durable instructions should describe stable behavior rather than current state.

Temporary:

The latest file is draft-final-3.md.
The API is unavailable today.
Skip images this time.

More durable:

Record the official version entry point in README.md. Do not infer it from “final” in a filename.
If an external service is unavailable, report the blocker. Do not switch to a paid fallback without approval.
Only begin image work when the request explicitly includes images.

The first set expires quickly. The second says how to behave when a similar situation occurs again.

3. Can a newcomer understand it without the history?

“Handle it the same way as last time” and “Aaron said not to change that” are incomplete. Name the scope, required behavior, and reason:

Do not rename published article URLs. External links and search indexes depend on the existing canonical path.
If a request requires a URL change, stop and request explicit approval.

A durable rule should not require the agent to reconstruct what “that” meant from an old conversation.

4. Can you verify whether the rule was followed?

“Write better,” “stay professional,” and “care about quality” cannot be tested. Convert them into observable actions:

After a change, run the specified tests. If a test cannot run, report the unverified item and reason.
Attach original sources and retrieval dates for external facts. Mark author judgment in the first person.

If you can answer “Did the test run?” or “Where is the source?”, the rule can shape real work.

Keep these items out of durable instruction files

A secret does not belong in an instruction file merely because it is repeatedly needed. Use the product’s supported secret management or environment configuration, and let the rule state where credentials come from and that they must never be exposed.

Write a maintainable rule in five fields

Rule name:
Scope: which folder, project, or task?
Required behavior: when should what happen?
Verification: how can someone confirm compliance?
Owner and update condition: who reviews it, and when?

Example:

Rule name: Protect published URLs
Scope: all article and course-content changes
Required behavior: do not change an existing canonical; stop and request approval if a change is required
Verification: compare the publishing registry before and after the change
Owner and update condition: content owner; update only after a formal migration decision

Practice: choose three rules from repeated reminders

Review your last three AI tasks. List the instructions you repeated, then keep only those that pass all four tests.

Delete once more after drafting. If removing a line would not change future behavior, it may be commentary rather than a rule. More rules create more conflicts and more opportunities for stale instructions.

The next lesson deals with a related problem: over time, old decisions and new versions conflict, while AI context remains limited. You need a context and version record that does not depend on chat length.

References