Capstone: Ship a Feature with Codex

What This Capstone Is

The previous lessons in this track taught you the individual components: how Codex works, how to write effective AGENTS.md files, how to use MCP to extend Codex's capabilities, and how to delegate async tasks via Codex cloud. This capstone lesson walks the complete pipeline end-to-end — from "I have a feature to ship" to "the feature is live and verified."

By the end of this lesson, you will have a workflow you can repeat for every feature you ship with Codex.

Step A: Scope the Task

The single highest-leverage step in the entire workflow happens before Codex writes a single line of code. That step is scoping.

A well-scoped task answers four questions with specificity:

What is the desired behavior? Not "improve the login flow" but "when a user's session expires, redirect them to /login with a query parameter that captures the URL they were trying to reach, so after login they return to the correct page."

What does done look like? Write the acceptance criteria before you write the code. "The redirect includes the returnTo query parameter. After login, the user lands on the page they originally requested. If returnTo is missing or invalid, default to the dashboard." These are checkable statements, not aspirations.

What is in scope and what is not? For a large codebase, naming the files or modules Codex should touch — and explicitly naming what it should not touch — prevents scope creep and out-of-scope side effects that will fail your diff review.

What constraints apply? Tech stack, architectural preferences, security requirements, performance targets. The things Codex needs to know before it makes architectural choices.

Document this before starting the session. The act of writing it forces clarity. If you cannot write specific acceptance criteria, you do not understand the feature well enough to delegate it.

Step B: Update AGENTS.md

AGENTS.md is the living contract between you and Codex. Before starting any session that involves your codebase, verify it is current.

Check that it covers:

File naming conventions and directory structure
The test command that must pass before any PR is opened
The lint and type check commands
Any modules or files that are off-limits
Recent architectural decisions Codex should be aware of

Updating AGENTS.md is not a one-time setup task — it is a recurring maintenance task. Every time Codex produces a PR that surprises you (wrong style, wrong location, modified something it should not have), that surprise is a signal that AGENTS.md needs updating. The session where something goes wrong is the best time to improve the contract for next time.

Think of it as a feedback loop: you run sessions, you update AGENTS.md based on what you observe, future sessions improve. Over time, a well-maintained AGENTS.md turns Codex from a capable-but-inconsistent contributor into a reliable one.

Step C: Run the Session

With a clear scope and a current AGENTS.md, start the Codex session.

For short, interactive tasks: use the Codex CLI. You are present, you can steer, you see output in real time.

For longer, well-scoped tasks: use Codex cloud. Assign the task, walk away, review the PR when it is ready.

In both cases, the task description you give Codex should mirror the scope document you wrote in Step A. Paste the acceptance criteria directly. Name the files in scope. Give Codex the same clarity you gave yourself.

If you are using the CLI interactively, resist the urge to steer aggressively before Codex has a chance to read the relevant code. Let it make its plan, review the plan before it executes, and correct course at the planning stage rather than mid-execution. Changing direction mid-execution produces messy diffs.

Step D: Review the Diff

The PR is not the finish line — it is the handoff point. Your job in diff review is not to confirm that CI is green. Your job is to understand every change Codex made and verify it is the right change.

Read each modified file. For every change, ask:

Is this change in scope, or did Codex stray into something I did not ask for?
Does this change do what I think it does, or is there a subtle bug in the logic?
Does this code follow the conventions in AGENTS.md, or is it inconsistent?
Are the tests adequate, or did Codex write tests that only test the happy path?

If you find out-of-scope changes, revert them and update AGENTS.md. If you find logic errors, leave comments on the PR and let Codex revise. If the tests are inadequate, say so explicitly — "add a test for the case where returnTo is an external URL" — and Codex will add them.

Reviewing a Codex diff takes the same discipline as reviewing a human's diff. The fact that Codex is fast does not mean the review should be fast. A three-minute review of a 200-line PR is a rubber stamp, not a code review.

Step E: Run the Tests

Before merging, run the full test suite locally. Do not rely solely on CI.

CI tests are the gates you defined — they catch what you thought to test. A local run with coverage enabled shows you what Codex did and did not test. If coverage dropped, find out why. If new code paths have zero test coverage, that is a gap to address before merge.

The 90% coverage floor is not an arbitrary target — it is the threshold below which the probability of shipping bugs that tests would have caught becomes unacceptably high. Enforce it before merge, not after.

Step F: Open the PR

Push the branch and open a pull request. The PR description should:

State what changed and why
Link to the original task or issue
List any known limitations or follow-up work
Include the specific tests you want reviewers to focus on

A clear PR description is not bureaucracy — it is the context that makes review faster and merge safer.

Step G: Verify the Running System

This is the step most developers skip. It is also the step that separates operators who compound from operators who plateau.

After merge, confirm the feature works in the deployed environment:

Trigger the specific user flow the feature addresses
Verify the acceptance criteria you wrote in Step A are satisfied in production
Check that adjacent features still work — deployments can have side effects

The operators who build reliable systems using AI agents are not the ones who trust Codex most — they are the ones who verify most rigorously. Trust the process, verify the outcome.

The Capstone Definition of Done

Cost Awareness

One discipline that distinguishes operators from casual users: tracking cost as a feature of the workflow, not an afterthought.

Each Codex session consumes tokens. Each MCP tool call may incur latency or external API costs. Cloud task runs consume compute time. For personal projects, the costs are small. For teams running dozens of parallel tasks daily, they compound.

Good cost hygiene looks like:

Prefer READ tools over WRITE tools where possible — READ tools are cheaper and safer
Write tight task briefs — vague briefs produce longer sessions with more back-and-forth
Use Codex cloud for long tasks rather than running the CLI idle waiting for output
Set a budget threshold per task and review anything that exceeds it

This is not about being frugal — it is about the same discipline you apply to AI API costs in production systems. The operator mindset applies to the tools you use to build, not just the tools you build.

Putting It Together: Your First Real Codex Feature

The track project for Codex Basics is to build and ship a real feature using the complete workflow from this lesson.

Pick something you actually want to ship: a new endpoint, a UI component, a bug fix in a real repo. Not a tutorial app — something you will actually use or something real users will see.

Work through all seven steps:

Write the scope document with acceptance criteria
Update AGENTS.md for the repo
Run a Codex session (CLI or cloud — your choice)
Review the diff thoroughly
Run the full test suite with coverage
Open a PR with a complete description
Verify the feature on the deployed system

The full operator workflow for building with AI agents is documented at jeremyknox.ai — including how parallel agent dispatch and the quality gate standard translate into real team practices. The Codex Basics track gives you the foundation. The compound effect comes from applying it consistently to every feature you ship.

The Capstone Challenge: Prove You Can Steer the Agent

Every other challenge in this track had a function to make green — write the validator, route the model, define the schema. This one does not, and that is deliberate. A capstone for an agent course cannot be graded by a unit test, because a passing test only proves you can write TypeScript. It has to prove you can operate the agent.

So the deliverable is evidence, not a green checkmark. You will take a small sample repo with a deliberate trap — a shared currency.ts helper that a "helpful" agent is tempted to rewrite when asked to clean up an unrelated route — and you will:

Author a real src/AGENTS.md for that repo: a Scope rule, an explicit Do Not Touch list naming src/lib/currency.ts by path, the exact test command, and a "stop and ask" instruction for off-limits files.
Run an actual Codex session with the provided task prompt, AGENTS.md present.
Capture the steered behavior — the transcript excerpt or diff where Codex explicitly declines to touch the off-limits helper and keeps its changes inside the one file you scoped.

The strongest submissions include a control run with the Do Not Touch rule removed, showing Codex reaching into currency.ts exactly as the rule was written to prevent. That contrast — same task, one rule's difference — is the entire point of the lesson made visible. AGENTS.md does not make the agent smarter; it makes the agent's blast radius smaller. Everything in this track has been building the judgment to draw those lines. This challenge is where you prove you can.