GPT-5.6 Sol Changes How We Prompt—and How We Write AGENTS.md

Many AGENTS.md files are becoming miniature operating manuals: hundreds of lines of repeated rules, rigid workflows, and reminders that modern coding agents may already follow reliably. OpenAI's GPT-5.6 Sol guidance suggests that this extra scaffolding can become counterproductive. If you are new to repository instruction files, first read Use AGENTS.md, CLAUDE.md, Cursor Rules, and Prompt Logs to Keep AI Coding Bots in Context.

The guide is written primarily for API developers, but its instruction-design principles can also inform persistent Codex guidance. The mechanisms are not identical: API settings such as text.verbosity, Responses API state, and Programmatic Tool Calling do not change how Codex discovers AGENTS.md. Applying the guide to repository instructions is therefore a practical interpretation, not a new AGENTS.md specification.

The short version is:

• Keep using AGENTS.md.
• Keep the rules that are genuinely specific to the repository.
• Remove repeated reminders and step-by-step ceremony that do not improve results.
• State what success means, how work should be validated, and where the agent's authority stops.
• Put local rules near the code they govern instead of loading every rule into one root file.

GPT-5.6 Sol does not replace AGENTS.md, and it does not change how Codex discovers it. It changes what a well-designed instruction file should emphasize.

The Main Prompting Change: Describe the Destination

Older prompts often attempted to control an agent by scripting its entire process:

Read the repository.
Find the relevant files.
Create a detailed plan.
Review the plan.
Ask for approval.
Edit one file at a time.
Review every edit.
Run all tests.
Explain everything you did.

This may look careful, but it can force the wrong workflow onto a simple task. It also spends context on behavior that a capable coding agent may already perform reliably.

An outcome-first version is shorter and more useful:

Implement the requested change within the existing architecture.
Keep the diff limited to the requested behavior, preserve public interfaces unless
the request changes them, and run the most relevant available validation.
Report any check that could not be completed.

The second prompt still establishes boundaries and a completion bar. It simply leaves the search and implementation path to the model.

In a sample of OpenAI's internal coding-agent evaluation runs, leaner system-prompt configurations improved scores by roughly 10 to 15 percent while reducing total token use by 41 to 66 percent and cost by 33 to 67 percent. The GPT-5.6 Sol prompting guide describes these figures as directional, not universal, so they should be tested against each application's real workloads rather than treated as an independently reproduced benchmark.

That caveat matters. The lesson is not that every short prompt is good or every long prompt is bad. The lesson is to keep instructions that change behavior and remove those that merely repeat intent.

What Should Stay in a Prompt

A strong GPT-5.6 prompt should make the following clear when they matter:

• The user-visible goal.
• The conditions that define success.
• Safety, permission, evidence, and business constraints.
• Which tools or sources are authoritative.
• The required response or artifact format.
• What to validate before finishing.
• When to retry, ask a question, use a fallback, or stop.

This is more precise than adding broad commands such as “be thorough,” “keep trying,” or “double-check everything.” Those phrases do not tell the model which evidence is required or what a successful answer looks like.

One practical structure derived from the guidance is:

Role: What function the agent is performing
Goal: The result the user should receive
Success: What must be true before the task is complete
Constraints: Safety, permission, scope, and evidence boundaries
Tools: Which tools matter and when to use them
Output: Required format, sections, length, or tone
Stop rules: When to retry, ask, fall back, or finish

Not every request needs all seven fields. A one-step question may need only a goal. A tool-heavy production workflow may need all of them.

Use Absolute Rules Only for Real Invariants

Words such as always, never, must, and only should be reserved for rules that truly have no contextual exception. Examples include security boundaries, destructive commands, required approval points, mandatory output fields, and legal or compliance requirements.

For decisions that depend on the task, use a decision rule instead.

Overly broad rule:

Always ask before changing any file.

Better boundary:

Read-only inspection, in-scope local edits, and non-destructive validation are
authorized for change requests. Ask before destructive actions, external writes,
production changes, purchases, credential changes, or material expansion of scope.

The second version allows normal development work to continue while preserving the approval boundaries that matter. It also prevents a repeated “ask first” instruction from causing unnecessary pauses.

Separate Personality from Collaboration

GPT-5.6 Sol is more concise by default than GPT-5.5, so an old instruction such as “always be extremely brief” may now overcorrect. For API applications, OpenAI recommends using the text.verbosity setting for a general detail level and using the prompt for task-specific length requirements.

Personality and collaboration are also different controls:

• Personality describes tone, warmth, formality, humor, and polish.
• Collaboration describes initiative, assumptions, questions, verification, tradeoffs, and uncertainty.

Keep both small. Neither is a substitute for a clear goal, constraints, or completion criteria.

Tool Instructions Should Explain Decisions

A long catalog of every available tool is rarely useful. Include task-relevant tools and explain the decision points that determine when they should be used.

Weak tool rule:

Use search, Git, the shell, the browser, the database tool, and testing tools
whenever possible.

Better tool routing:

Use repository search for code discovery. Consult current official documentation
when correctness depends on a versioned API or standard. Inspect the current schema
before changing a query that depends on it. Run the smallest relevant test first,
then broader checks when shared behavior is affected.

The improved version defines prerequisites and routing. It does not turn tool use into a ceremony.

The guide also distinguishes direct tool calls from Programmatic Tool Calling. Programmatic calling is most useful for bounded, deterministic reduction work such as filtering, joining, deduplicating, sorting, or aggregating large results. Direct calls remain preferable when each result changes the next decision, approval is involved, citations must be preserved, or semantic judgment is required between calls.

Context Should Be Layered, Not Dumped

The new guidance also reinforces a broader context-engineering principle: do not inject the entire project history, architecture guide, database schema, deployment runbook, style manual, and troubleshooting archive into every task.

Large undifferentiated context creates several risks:

• Important rules become harder to locate.
• Outdated details remain available to influence current work.
• Contradictory instructions accumulate.
• Every request pays the token cost for unrelated material.
• Large reusable prompt prefixes change more often, reducing prompt-cache efficiency.

A better repository might look like this:

repo/
|-- AGENTS.md
|-- docs/
|   |-- architecture.md
|   |-- development.md
|   |-- testing.md
|   |-- deployment.md
|   `-- security.md
|-- services/
|   |-- api/
|   |   `-- AGENTS.md
|   `-- worker/
|       `-- AGENTS.md
`-- tests/
    `-- AGENTS.md

The root AGENTS.md can provide a small repository contract and context map. Detailed documentation should be loaded when the task actually depends on it.

For long-running API conversations, OpenAI also recommends compacting after meaningful milestones instead of after every turn, keeping reusable prompt prefixes stable, and avoiding reliance on persisted reasoning when the objective or assumptions have changed. Stale reasoning can anchor new work to an outdated approach.

Does GPT-5.6 Change How AGENTS.md Works?

No. Codex's current AGENTS.md documentation still says Codex reads these files before it begins work and combines instructions from multiple scopes.

The discovery model remains:

1. At global scope, Codex reads the first non-empty file it finds between AGENTS.override.md and AGENTS.md in the Codex home directory.
2. At project scope, it starts at the project root and walks toward the current working directory.
3. In each directory, it includes at most one file, preferring AGENTS.override.md, then AGENTS.md, then configured fallback names.
4. Files closer to the working directory appear later and can override broader guidance.
5. The combined project instruction size is limited by configuration, with a 32 KiB default.

What changed is the recommended writing philosophy. OpenAI's Codex customization guidance now explicitly says to keep AGENTS.md small, add only instructions that matter, place guidance in the closest relevant directory, and codify feedback when a problem actually repeats.

A Useful Mental Model: AGENTS.md as a Repository Contract

OpenAI does not formally define AGENTS.md as a “repository contract,” but it is a useful way to interpret the documentation. The file should capture ownership boundaries, authoritative commands, repo-specific conventions, approval limits, validation requirements, and context routing. It usually should not narrate every search step, repeat the same rule, copy entire reference documents, or list tools unrelated to the current repository.

Before and After: A Leaner AGENTS.md

Here is an example of an overly procedural instruction block:

# Agent Instructions

1. Read every file in the repository.
2. Create a detailed plan before doing anything else.
3. Ask for approval before changing any file.
4. Edit one file at a time and review it after every edit.
5. Always use every available search and testing tool.
6. Run every test in the repository after all changes.
7. Never finish until you have checked everything twice.

Those rules force the same expensive workflow onto a typo, a focused bug fix, and a cross-cutting architecture change. A more useful repository contract defines scope, authority, routing, and evidence:

# Repository Guidance

## Scope

- Application code lives in `src/`; tests live in `tests/`.
- Treat `vendor/`, generated files, and third-party packages as read-only unless
  the request explicitly targets them.

## Working agreement

- Keep changes scoped to the requested behavior and preserve public interfaces
  unless the request explicitly changes them.
- Follow existing architecture and naming patterns in the affected component.
- Local inspection, in-scope edits, and non-destructive validation are authorized.
- Ask before destructive actions, external writes, production changes, new
  production dependencies, or material expansion of scope.

## Validation

- Run targeted tests for changed behavior.
- Run lint, type, or build checks that apply to the affected package.
- Add regression coverage for corrected defects when practical.
- Report any required check that could not be run.

## Context routing

- Read `docs/architecture.md` before changing component boundaries.
- Read `docs/database.md` before changing schemas or migrations.
- Read `docs/deployment.md` before changing release behavior.
- Do not load unrelated documentation.

The leaner example does not merely contain fewer words. It preserves the instructions that change behavior while allowing the agent to choose a workflow appropriate to the task.

Use Nested Files for Local Rules

If a rule applies only to one language, service, or directory, place it near that code.

The root file might say:

Preserve public interfaces unless the task explicitly changes them.
Run validation appropriate to the affected component.

A nested services/payments/AGENTS.md could add:

Run `make test-payments` for payment-service changes.
Never use live payment credentials in local tests.
Changes to settlement logic require the documented reconciliation smoke test.

A tests/AGENTS.md could add:

Do not weaken assertions merely to make a failing test pass.
Prefer behavior-based coverage over implementation-detail tests.

This keeps the root prompt useful to every task without forcing unrelated rules into every working context.

Keep Model-Specific Tuning Out of Durable Repo Rules

The GPT-5.6 guide is model-specific. A repository may also be used by another model, an older Codex configuration, or a different coding tool.

In practice, durable project facts such as commands, constraints, ownership, review expectations, and validation usually belong in AGENTS.md. One-off details usually belong in the current prompt. Reusable procedures are often better implemented as skills or scripts, while tests, linters, hooks, CI, and permissions are stronger choices for requirements that should be mechanically enforced. These are engineering recommendations, not new GPT-5.6 rules, and a short universal procedure may still reasonably remain in AGENTS.md.

Only add model-specific wording to AGENTS.md when it fixes a measured, recurring repository problem and still makes sense for every agent expected to read the file.

Do Not Rewrite a Working Prompt All at Once

The safest migration process is incremental:

1. Run representative tasks with the existing prompt and reasoning setting.
2. Save the results as a baseline.
3. Remove one category of repeated or obsolete instructions.
4. Run the same tasks again.
5. Add a targeted instruction only when a measured failure needs it.
6. Compare correctness, completeness, tool use, tokens, latency, cost, and retries.

If the entire prompt stack, tool set, reasoning level, and model change at once, it becomes difficult to know what improved or caused a regression.

The same approach applies to AGENTS.md. Do not delete half the file simply because “shorter is better.” Audit it, consolidate duplicates, move local rules closer to their directories, and verify the new version on real repository work.

A Practical AGENTS.md Audit

For each instruction, ask:

• Is this specific to the repository or team?
• Does it change behavior on a real task?
• Is it written somewhere else too?
• Does it conflict with another rule?
• Is an absolute word necessary?
• Is this a goal, a constraint, or unnecessary process narration?
• Should it live in a nested AGENTS.md, project document, skill, script, hook, or CI check instead?
• Can completion be verified with a command or observable result?
• Would a new team member understand why the rule exists?

Keep the rule when it protects an invariant, prevents a recurring mistake, routes the agent to required context, or defines successful validation. Rewrite or relocate it when its value depends on the task. Remove it when it only repeats what the agent already does reliably.

Final Takeaway

GPT-5.6 Sol does not make prompt engineering less important. It makes instruction design more disciplined.

Good prompting is moving away from scripting every operational step and toward defining outcomes, evidence, constraints, authority, validation, and stopping conditions. A useful application of that principle is to treat AGENTS.md as a small, durable repository contract supported by nested local guidance and on-demand documentation.

The goal is not the shortest possible prompt. The goal is the smallest prompt that reliably produces the right result.

Primary Sources

• OpenAI: Prompting guidance for GPT-5.6 Sol
• OpenAI: Codex customization and AGENTS guidance
• OpenAI: Custom instructions with AGENTS.md

Secondary Commentary

• Decrypt: Stop Over-Prompting—OpenAI's New GPT-5.6 Guidelines Change Everything