System design with Codex

Codex supports system design by splitting the work across its surfaces: a read-only CLI run maps the current architecture, Plan mode drafts the options, Codex cloud tests the riskiest assumptions as throwaway spikes, and parallel worktrees build competing designs against the same scenarios. The decision is recorded as an ADR and enforced by a CI rule.

This page is for the developer or tech lead who owns an architecture decision and has to defend it. The situation: every deploy of your monolith is a gamble, the team has agreed to extract the payments module into its own service, and nobody agrees on the API boundary, the data migration or what happens while both systems run. You need a decision backed by evidence by the end of the sprint, not a plan that only one person has read.

What you get from designing a service extraction with Codex

• A six-step design loop, with the Codex surface, command and output file for each step
• Seven copy-paste prompts: the evidence map, the option comparison, two cloud spikes, the worktree bake-off, the ADR with its enforcement rule, and the design review
• A verification table that tells you which check proves each kind of design claim, and who signs off
• Recovery steps for the ways Codex-assisted design goes wrong

For the vendor-neutral method behind this page (short ADRs plus machine-checkable constraints), read architecture decisions agents can follow. This page is its Codex implementation.

Which Codex surface handles which part of a design?

Each step produces a file you can check, so the design never lives only in a chat transcript.

Step	Codex surface	Command	Output you keep
1. Map the current system	CLI, read-only sandbox	codex exec -s read-only -o …	docs/architecture/payments-map.md
2. Compare design options	Interactive CLI in Plan mode	/plan	docs/architecture/payments-options.md
3. Test risky assumptions	Codex cloud, best-of-N	codex cloud exec --env … --attempts 2	Spike diffs and a findings note, never merged
4. Build competing designs	Managed worktrees	codex --worktree	Two prototype branches and one comparison table
5. Record and enforce the decision	CLI	codex	An ADR, an AGENTS.md rule and a CI dependency rule
6. Review and watch for drift	CLI (read-only), @codex review, automations	codex exec -s read-only …	Review findings and a weekly drift report

Design work rewards more reasoning than Codex’s default effort gives it (the models hub lists the current default model and effort), so raise effort for these sessions before you consider another model. Add -c model_reasoning_effort="high" to any command on this page; the key exists in Codex CLI 0.157.1.

Map the current architecture with cited evidence

A design is only as good as its picture of the current system. Run the first pass headless and read-only, so Codex can inspect everything and change nothing. Run this in your terminal from the repository root:

mkdir -p docs/architecture
codex exec -s read-only -c model_reasoning_effort="high" \
  -o docs/architecture/payments-map.md \
  "$(cat prompts/payments-map.md)"

-s read-only blocks writes to the workspace, and -o saves Codex’s final message to the file, which the CLI itself writes. Put this prompt in prompts/payments-map.md:

Copy-paste prompt: evidence-backed map of the payments module

Map the architecture of the payments module in this repository. Change nothing.

1. Every file under src/services/payments/ and src/routes/payments/, grouped by responsibility.
2. Inbound dependencies: every module outside payments that imports or calls into it.
3. Outbound dependencies: everything payments imports or calls outside itself.
4. Database tables payments reads or writes, and which other modules touch the same tables.
5. Shared state: caches, queues, config values, feature flags, transactions that span modules.
6. Every HTTP endpoint and background job that payments exposes or consumes.

Rules:
- Cite path:line for every claim. If you infer something from a name or a config file rather than a call site, mark it INFERRED.
- List anything wired at runtime (dependency injection, event handlers, plugin registries, config-driven routing) in a section called "Not visible statically".
- End with the three most tightly coupled integration points and why each one would block an extraction.
Output Markdown only.

A language model counts imports badly and misses dynamic wiring, so treat the dependency part of the map as a draft and compute the static graph with a tool. For a TypeScript codebase (checked on 2026-09-26 with dependency-cruiser 18.4.0):

npx dependency-cruiser@18.4.0 src --no-config --output-type metrics > docs/architecture/metrics.txt
npx dependency-cruiser@18.4.0 src --no-config --output-type mermaid -f docs/architecture/deps.mmd

The metrics file gives coupling per module (afferent, efferent and instability); the Mermaid file holds every static import edge. Then ask Codex, in a new session, to read docs/architecture/deps.mmd and list every edge the tool found that the map missed and every map edge the tool does not show. Each disagreement is either a runtime link you now know about or an error you remove. For a deeper onboarding pass on an unfamiliar repository, see understanding codebases with Codex.

Compare design options in Plan mode

Start an interactive session with codex -c model_reasoning_effort="high" -c plan_mode_reasoning_effort="high", switch to Plan mode with /plan, and give Codex the map. Codex CLI 0.157.1 has a separate plan_mode_reasoning_effort key for Plan mode, so set both to keep the higher effort after the switch. In Plan mode the session produces a plan before any code, which is where a design discussion belongs.

Copy-paste prompt: design options grounded in the map

Read docs/architecture/payments-map.md and docs/architecture/metrics.txt. They describe the current system.

We are extracting payments into a separate service. Hard constraints:
- Zero downtime; both systems run side by side during the transition.
- No payment record becomes unreadable at any point.
- Existing API consumers keep working without changes.
- In the final state the payments service owns its tables; no shared tables.

For each decision below, propose two or three options. For every option give: the trade-off, the files and tables it touches (cite the map), the reversibility (how we back out after it ships), and the one assumption that would kill it if false.
1. The API boundary: which endpoints move and which stay.
2. Data migration: how the shared tables are split without downtime.
3. Routing during the transition: proxy, feature flag or both.
4. Service-to-service authentication.
5. Behaviour when the payments service is down or slow.

Recommend one option per decision. Then list the killer assumptions we must test before committing, ranked by risk. Do not edit any files until I approve the plan; after approval, write the result to docs/architecture/payments-options.md.

The ranked list of killer assumptions is the input to the next step. An option you cannot test is an option you are taking on faith, so say that in the document.

Test the riskiest assumptions as Codex cloud spikes

A spike is code written to answer one question and then thrown away. Codex cloud runs it in a container set up for your repository, so the spike does not touch your machine or your branch. ENV_ID is your cloud environment’s identifier: run codex cloud to browse environments, and see Codex cloud environments to set one up with your test database and setup script. codex cloud is marked experimental in Codex CLI 0.157.1, so check codex cloud exec --help if a flag below is rejected.

Commit docs/architecture/ and push the branch first. codex cloud exec runs against the branch on the remote (--branch, default: the current branch), not your working tree, so a spike cannot read an options file that exists only on your machine. The commands below name the branch explicitly as design/payments.

--attempts 2 asks for two independent attempts (best-of-N), which is useful here: if two attempts reach different answers to the same question, the question is not settled.

Copy-paste prompt: can the API boundary stand on its own?

codex cloud exec --env ENV_ID --branch design/payments --attempts 2 "Spike, not production code. Question: can the payments endpoints listed in docs/architecture/payments-options.md be served without reading any table outside the payments tables?

For each endpoint:
1. Trace the handler down to every query it runs. Cite path:line.
2. Flag every read of users, orders or any other non-payments table.
3. For each flagged read, propose one fix: the caller passes the data, the payments service calls a monolith API, or the data is replicated. State the cost of each.
Run the existing payments tests and report which ones would break if payments lost access to the non-payments tables.
Write everything to docs/architecture/spikes/boundary.md: the path:line traces, the flagged reads with their fixes, the test output, and on the first line a verdict: BOUNDARY HOLDS, HOLDS WITH N CHANGES, or DOES NOT HOLD."

Copy-paste prompt: dual-write versus change data capture

codex cloud exec --env ENV_ID --branch design/payments --attempts 2 "Spike, not production code. Compare two ways to migrate the payments tables with zero downtime.

A. Dual-write: the monolith writes to both databases; reads move to the new service gradually.
B. Change data capture: replicate the payments tables to the new database; switch reads when lag is acceptable.

For each approach, build the smallest proof of concept that answers these questions, using the test database in this environment:
1. After 1,000 writes that include updates and refunds, do both databases hold identical rows? Show the comparison query and its output.
2. What happens to a write when the new database is unavailable? Reproduce it and show the resulting state.
3. How do you roll back to the monolith alone at each phase?
Write the evidence, not an opinion, to docs/architecture/spikes/migration.md: the queries, their output and the reproduced failure state for each approach. If a question cannot be answered in this environment, say so in that file."

codex cloud diff prints only the files a task changed, not its final message. That is why both prompts write their findings to a file under docs/architecture/spikes/: the verdict and the evidence then appear in the diff of each attempt. When the tasks finish, compare the attempts from your terminal:

codex cloud list --env ENV_ID
codex cloud diff TASK_ID --attempt 1
codex cloud diff TASK_ID --attempt 2

Copy the verdicts and the evidence from those spike files into docs/architecture/payments-options.md. Do not run codex cloud apply on a spike: its job was to produce an answer, not code.

Build competing designs in parallel worktrees

When the team splits between two designs, for example synchronous REST calls against events for the transition period, build both and measure them against the same scenarios. Write the scenarios before either prototype exists; otherwise each prototype quietly picks the scenarios it wins.

1. Commit a shared scenario file, docs/architecture/payments-scenarios.md, with 10 numbered cases: a normal charge, a refund, a duplicate webhook, the payments service down for 30 seconds, a slow database, and so on. Each case states the expected outcome.

2. Start one Codex session per design, each in its own managed worktree, from two terminals:

   codex --worktree "$(cat prompts/prototype-rest.md)"
   codex --worktree "$(cat prompts/prototype-events.md)"

3. When both finish, run the same scenario script in each worktree and fill in one comparison table.

4. Bring both results files onto the design branch, because each prototype wrote its file inside its own worktree branch. From the main checkout, on design/payments, run git checkout <rest-worktree-branch> -- docs/architecture/results-rest.md and git checkout <events-worktree-branch> -- docs/architecture/results-events.md, then commit them. This works because each prototype prompt ends by committing its results file on its worktree’s branch. The next step’s prompt reads both files.

The two prompt files differ only in the first line. Here is the REST version; replace its first line with the events design for the second file:

Copy-paste prompt: prototype one design against shared scenarios

Design under test: the monolith calls the payments service over REST through a proxy with a circuit breaker.

Build the smallest prototype of this design that can run every case in docs/architecture/payments-scenarios.md. Do not change that file.
1. Implement only what the scenarios need. No production hardening.
2. Write one automated test per scenario, named after its number, and a script scripts/run-scenarios.sh that runs them all.
3. For each scenario record: pass or fail, the consistency guarantee you actually observed, and the latency added by the design (median of 20 runs).
4. Write the results to docs/architecture/results-rest.md as a table with one row per scenario.
5. Commit the prototype, the tests, scripts/run-scenarios.sh and the results file on this worktree's branch.
Stop and ask if a scenario cannot be expressed in this design; do not redefine it.

The comparison is now a table of scenario results rather than a whiteboard argument. See isolated Codex tasks with Git worktrees for bootstrapping and cleaning up worktrees, and multi-agent workflows when you run more than two variants.

Record the decision so later agent sessions follow it

A decision that exists only in a document erodes the first time an agent takes a shortcut. Record it three ways: an ADR for people, a rule in AGENTS.md that Codex reads at the start of every session, and a CI check that fails when the rule is broken.

Copy-paste prompt: ADR plus the rule that enforces it

Read docs/architecture/payments-options.md, the spike verdicts in it, and docs/architecture/results-rest.md and results-events.md.

1. Write docs/adr/0007-extract-payments-service.md with these sections: Context, Decision, Options considered (one line each, with the evidence that ruled it out), Consequences, Rollback plan per migration phase, and Enforcement.
2. Under Enforcement, add a dependency-cruiser rule to .dependency-cruiser.cjs that forbids any import of src/services/payments/** from outside that folder except through src/services/payments/client.ts. Name the rule after the ADR. Set the rule's severity to "error".
3. Add a short "Payments boundary" section to AGENTS.md: two or three sentences stating the rule and linking the ADR.
4. Run npx dependency-cruiser@18.4.0 src --config .dependency-cruiser.cjs and show me the output. List every current violation instead of fixing it.

The current violations become the migration’s work list, and the rule stops new ones from appearing while the migration runs, but only once CI runs it and it can fail. The prompt sets the rule’s severity to "error", so dependency-cruiser exits non-zero on a violation; check that it did, then add this as a CI step:

npx dependency-cruiser@18.4.0 src --config .dependency-cruiser.cjs

The fitness functions guide shows the full CI job. The same guide has equivalent rules for Python and Java, and AGENTS.md optimization covers keeping that file short enough to stay useful.

Review the design and watch for drift

Before the design branch merges, get an independent review. codex review --base main gives a general review of the branch, but it cannot take a custom checklist: in Codex CLI 0.157.1, codex review accepts custom instructions only when no --base, --commit or --uncommitted is given, and --base main "…" fails with an argument error. For an architecture-specific review, run a read-only codex exec against the branch diff:

Copy-paste prompt: design review against the base branch

codex exec -s read-only -c model_reasoning_effort="high" "Review the diff of this branch against main (git diff main...HEAD) for architecture decisions, not style. Check: the API boundary in docs/adr/0007-extract-payments-service.md matches the endpoints in code; no shared table survives in the final phase; every migration phase has a rollback that is actually possible; the dependency-cruiser rule matches the ADR. Flag anything that makes rollback hard, with file:line."

On GitHub, mention @codex review on the pull request; Codex also applies the review rules you write in AGENTS.md (OpenAI’s GitHub integration docs, checked 2026-08-28). The code review with Codex page covers setup.

For the months the migration runs, schedule a weekly drift check as a Codex automation in the desktop app or as a scheduled codex exec job in CI; scheduled Codex automations shows both. Give it the ADR and ask for a report of new imports across the boundary, new endpoints added to the monolith instead of the service, and ADR sections that no longer match the code. Let the dependency-cruiser rule do the blocking; the automation reports what a static rule cannot see.

How do you know the design is sound without reading every line?

Nobody should read every line of two prototypes and three spikes. Check each kind of claim with the evidence that proves it:

Claim	Evidence that proves it	Who signs off
“The map is complete”	Every edge cited as path:line; zero unexplained differences from the dependency-cruiser output; you spot-check three citations	The developer who owns the module
“The boundary holds”	Both cloud attempts return the same verdict, and the flagged reads have an agreed fix	Tech lead
“The migration is safe”	Row comparison output from the spike, a reproduced failure case and a written rollback per phase	Tech lead and the database owner
“Design A beats design B”	Both prototypes ran the same 10 committed scenarios; the results tables come from scripts/run-scenarios.sh, not from Codex’s summary	The team, in one review meeting
“The decision will hold”	The dependency-cruiser rule runs in CI at severity: "error" and fails the build on a deliberate test violation	Tech lead

The last row is the one teams skip. Add a throwaway import across the boundary on a branch and confirm CI goes red before you trust the rule.

When Codex-assisted system design goes wrong

The map misses hidden coupling. Codex finds imports and calls, but it can miss coupling through shared config values, transaction boundaries or middleware that injects dependencies at runtime. Recovery: compare the “Not visible statically” section with the tool output, then add logging at the three integration points Codex named and run the payments tests to see what really crosses the boundary.

A spike’s code ends up in production. Spikes skip error handling and security by design. Recovery: never codex cloud apply a spike; start every spike prompt with “Spike, not production code”, and rebuild the chosen design from the ADR in a fresh task.

The two attempts disagree. With --attempts 2, different verdicts mean the question depends on something the prompt did not pin down. Recovery: diff the attempts with codex cloud diff TASK_ID --attempt N, find the assumption they differ on, write it into the prompt and run it again.

The prototypes are not comparable. One prototype redefined a scenario or measured latency differently. Recovery: the scenario file is committed before the prototypes start and the prompt forbids editing it; rerun scripts/run-scenarios.sh yourself in both worktrees rather than trusting either summary.

The session loses the thread on a large monolith. Codex’s default context window (see the models hub) is finite, and a full map of a large monolith plus the options discussion can fill it. Recovery: keep each step in its own session and pass state through the files in docs/architecture/, not through the conversation.

The architecture document goes stale. A migration that takes three months drifts from the plan by month two. Recovery: the CI rule blocks new violations, the weekly drift report lists the rest, and one named person owns updating the ADR when the report finds a mismatch.

Where to go next with the payments extraction

Architecture decisions agents can follow The tool-neutral method: short ADRs plus machine-checkable constraints

Architecture fitness functions Dependency, layering and complexity rules as CI gates for three stacks

Codebase modernization with Codex Carry out the migration in waves once the design is decided

Architecture analysis with Claude Code The same design workflow in Claude Code plan mode