Prompts, AGENTS.md, Skills, or Automations: Where Codex Instructions Belong

Instructions Have Different Lifetimes

One of the fastest ways to make an AI engineering setup harder to use is to put every instruction in one giant prompt. The second fastest is to put every instruction in AGENTS.md.

Instructions have different lifetimes and audiences. Some are true only for one task. Some are durable rules for one repository. Some describe a reusable professional procedure. Others connect the agent to an external system or run on a schedule.

Treating these as separate layers reduces noise and makes behavior easier to audit. The useful question is not "Where can I write this?" It is "What is the narrowest durable surface that should own this rule?"

Use the Smallest Correct Surface

Use this placement model:

Task prompt

Use a prompt for the current objective, current evidence, temporary constraints, and the output needed now. A prompt should describe the problem, boundaries, and definition of done. It should not repeat stable repository setup on every task.

Example: "Fix the mobile overflow on the pricing page, preserve the existing desktop hierarchy, and add a regression test at 390 pixels."

AGENTS.md

Use AGENTS.md for repository-specific rules that should affect many tasks: required commands, architectural boundaries, security rules, UX expectations, product truth, and documentation obligations.

Example: "Analytics events must never include raw customer names, contact details, or search queries."

Linked repository documentation

Use focused documents for deeper knowledge: architecture diagrams, billing flows, provider contracts, release runbooks, and product decisions. AGENTS.md should point to them rather than duplicate them.

Reusable skill or procedure

Use a reusable skill when a method applies across repositories and benefits from a stable sequence, such as reviewing a migration, auditing analytics privacy, or creating an accessible blog article. Keep project-specific secrets and business data outside the reusable skill.

Tool or integration

Use an integration when the agent needs structured access to a system such as GitHub, a design tool, a browser session, or an internal API. The integration provides capability. Instructions still define when and how that capability may be used.

Automation

Use an automation for a repeatable trigger and outcome: a scheduled dependency review, a daily content research brief, or a release-health check. Automation needs explicit ownership, failure handling, review rules, and permission boundaries.

Design a Context Stack

A healthy Codex setup reads like a stack:

1. The task prompt says what must change now.
2. AGENTS.md says how this repository is safely changed.
3. Local documentation and tests explain the subsystem and its contracts.
4. Reusable skills provide specialist methods.
5. Integrations provide approved access to external systems.
6. Automations trigger established workflows without removing human ownership.

Each layer should add information that the layers below do not already contain. If a command changes, update its authoritative repository location and remove obsolete copies. If a product rule changes, update the product memory and the tests in the same work slice.

This is context engineering in practical form: making the right information available at the point where a decision is made.

Avoid Context Debt

Context debt accumulates when instructions are contradictory, stale, duplicated, or impossible to verify. Common symptoms include:

• The prompt says one command while AGENTS.md says another.
• A pricing document differs from the actual entitlement code.
• A skill assumes tools that the repository does not use.
• An automation silently fails because its owner or credential expired.
• Old project history is treated as current product truth.
• Confidential examples are copied into reusable templates.

Schedule instruction maintenance like code maintenance. Delete expired rules. Convert repeated explanations into tests or scripts. Keep source-of-truth links explicit. Mark assumptions that still need external verification.

Use an Instruction Placement Review

Ask Codex to help review the context system itself:

Review the instructions that govern this repository.

For each important rule, classify it as:
- one-task prompt context,
- durable AGENTS.md guidance,
- deeper repository documentation,
- reusable cross-project procedure,
- tool or integration configuration, or
- governed automation.

Identify contradictions, duplication, stale assumptions, missing tests, and any
confidential material that should be generalized or removed. Do not edit yet.
Return a proposed source-of-truth map and the smallest safe cleanup sequence.

Run this review before expanding an instruction file that already feels difficult to navigate. More text is not automatically more context.

Govern the System Like Code

Instructions influence implementation, access, and release decisions. Review them accordingly. Version durable instructions, test the behavior they describe, and require a human owner for automated actions with financial, production, security, or customer impact.

The outcome is not a perfectly configured agent. It is a legible delivery environment where people and agents can discover the current rules, act within them, and prove that the result is correct.

Official references

• Harness engineering with Codex
• How OpenAI uses Codex
• Codex use cases