The task started with an anxious urge to quickly update AGENTS.md for GPT-5.6 Sol. But the most dangerous move in that situation is to open the working file right away and start rewriting the rules by feel.
Instead, the first step was to lock down the starting state: the boundaries of the change, a verification matrix, and a rollback path. Only after that was the large, permanently-loaded instruction layer split into a short core and topic-specific documents, with behavior checked against real-world scenarios.
What changed
The core shrank from 70 KB to 18 KB. Permanent rules became roughly 75% smaller without removing any critical constraints.
Testing covered 10 baseline scenarios plus 4 new ones. Both the old and new structures were run through risky working situations before rollout.
The setup spans two machines: a MacBook Pro M5 and a Mac mini M4 Pro, both brought to consistent Codex behavior.
Rule architecture: the old file wasn't bad, just too permanent
A single always-loaded file had accumulated rules for security, production, Git, Notion, Linear, GitHub, secrets, subagents, design, and separate operating modes. The problem wasn't the rules themselves — it was that the model received all of them for almost any minor task.
The short core. The permanent AGENTS.md now contains only the rules that must always apply: priority of direct user constraints, mutation boundaries, secrets handling, dirty-repo behavior, checks, and pre-production stops.
Topic-specific instructions. Detailed processes moved into separate files: Codex-first workflows, operational tasks, design and tooling, access management, MCP, and runtime isolation.
This wasn't a stylistic edit. The task became designing a working contract between human and agent, rather than polishing a large prompt.
Before making changes, the size, structure, checkpoints, boundaries, and rollback path were all recorded, so a feeling of order wouldn't be mistaken for actual proof.
Verification matrix: shrinking the file wasn't enough
It had to be proven that caution was preserved. The team didn't evaluate how nice the new wording sounded — it evaluated model behavior: commands, tool calls, file changes, and signs of external mutation.
Old scenarios still passed. All ten general safety scenarios succeeded on both the original version and the new instruction structure.
The new architecture got its own tests. Four additional scenarios specifically checked how the model handled the topic-specific files and the new rule separation.
Secrets stayed contained. Tests used synthetic values; the model never printed them or leaked them outward.
Writes stayed under control. No unauthorized writes occurred, and in the one scenario where a change was expected, exactly one necessary write happened.
Context got lighter. Across short checks, the permanent input context shrank by roughly 36%.
Speed wasn't oversold. Responses weren't consistently faster — sometimes the new version was even a touch slower — so the result wasn't presented as a speed win.
Access and MCP: a second layer surfaced after AGENTS.md
Identical rules don't guarantee an identical working environment. In practice, a single service could exist simultaneously as a built-in MCP, an app, a direct API, and a local MCP process. Some routes worked; others produced authorization errors.
Verification without exposing secrets. Only names, purpose, owner, scope, revocability, and presence were checked — key values were never read or printed.
No rotation for the sake of ritual. The audit found no evidence that active keys were compromised, so access wasn't revoked purely for a sense of security.
One proven route per service. Instead of a pile of duplicate paths — where one route works and a neighboring one breaks the launch with a noisy error — each service kept a single clear working path.
Static credentials and OAuth stayed separate. Static credentials remained in encrypted storage and were passed into the child process, while OAuth sessions stayed inside each application's own storage.
Two machines: the Mac mini wasn't a copy, it was its own rollout stage
The MacBook Pro M5 was the primary working machine; the Mac mini M4 Pro served as a second permanent environment. Even after copying the files over, it was still necessary to check Codex CLI versions, OAuth state, Node.js paths, MCP setup, local file permissions, and a fresh launch.
Synchronization isn't the same as behavior. An identical AGENTS.md doesn't prove that Codex starts and acts the same way on two machines.
Actual launches were verified. In the end, both machines started up without authorization errors, redirects, missing executables, or stale local addresses.
Byte-for-byte identity wasn't required. OAuth state, local paths, and machine-specific details can differ — what matters is that the rules and the observed behavior match.
Private evidence was kept separate from the public writeup. Local paths, account details, provider responses, and internal infrastructure specifics were not turned into public material.
Avoiding shortcuts: control came from a chain of small, verifiable decisions
Along the way there were plenty of temptations to move faster: rewrite the file immediately, raise the limits, trust someone else's analysis at face value, export keys globally, or declare success after the first machine. Every one of these shortcuts was deliberately rejected.
The working file wasn't touched before measurements were taken. First the starting state, the verification matrix, the boundaries, and the rollback plan — only then the changes.
Publication wasn't confused with proof. Official sources, personal observations, and hypotheses were kept clearly separate.
Access wasn't widened without reason. Secrets weren't exported globally, OAuth sessions weren't moved into shared storage, and active keys weren't revoked without evidence of compromise.
One machine wasn't treated as the whole system. The second computer went through its own verification path, because it has its own versions, sessions, paths, and local processes.
The result: a shorter, clearer, verified contract with Codex
The main outcome isn't that the file got smaller. What matters is that a more autonomous model now receives far less constant noise, while the human side kept its boundaries, evidence, stop points, and a clear rollout path.
The permanent layer became more compact. AGENTS.md shrank from roughly 70 KB to 18 KB, and the line count dropped from 342 to 133.
Critical rules stayed in the core. Security boundaries, Git handling, secrets, dirty-repo behavior, checks, and pre-production stops all remained in the permanent layer.
Processes became callable by topic. Detailed instructions are now loaded only when a task genuinely touches Codex-first work, operations, design, or access management.
Rollout was verified across two environments. The MacBook and the Mac mini were brought to consistent behavior without demanding artificial byte-for-byte sameness.
This kind of migration is less about trimming a prompt and more about renegotiating the working contract between a person and an increasingly autonomous system — proving, step by step, that shorter instructions don't mean looser control.