PRD for Codex (OpenAI): Crafting AI-ready specs for reliable delivery
This page shows how to write a PRD for Codex (OpenAI), focused on GitHub-based, test-first development. See a real-world filled example, a step-by-step process, and actionable tradeoffs between Codex, Claude Code, and Lovable workflows. Internal links to practical PRD templates included.
What this is
A PRD for Codex (OpenAI) is a structured Product Requirements Document designed so OpenAI’s Codex agent can ingest your spec from a GitHub issue, create a feature branch, propose a pull request, and pass the required tests. This approach is tailored for the ChatGPT app with the Codex coding agent, where branch naming, pull request titles, and specs must be machine-readable and concrete. Tools like Cursor and Lovable, alongside classic GitHub, make this process 10x faster for PMs and founders building AI-assisted products.
Compared to alternatives
| Option | Best for | Trade-off |
|---|---|---|
| Codex (OpenAI) PRD workflow | PMs using ChatGPT with Codex agent and GitHub automation | Requires explicit branch/PR details; tests must be spec’d clearly up front |
| Claude Code PRD style | Teams using Anthropic’s Claude with Slack/GitHub integrations | More forgiving on branch handling, less deterministic on PR format |
| Lovable PRD template | Rapid prototyping and collaborative AI agents on code + design | Great for MVPs, but less prescriptive about tests or code reviews |
| Replit spec | Rapid cloud IDE iteration, especially solo founders | Limited native CI; less GitHub/PR structure |
| Traditional Gherkin BDD | QA-heavy orgs needing user story traceability | Verbose; can frustrate AI agents if not tightly scoped |
A real example
GitHub Issue Title: [Feature] AI-Powered Markdown Export for Blog Editor
Branch Name: feature/markdown-export Proposed PR Title: Add Markdown export feature to Blog Editor
Context: Our in-browser blog editor (Next.js, deployed via Vercel) needs a one-click Markdown export option, requested by users (18% of support tickets). Speed is key: rolling this out in <3 weeks reduces manual migration by at least 40%.
Feature Description:
- Add an 'Export as Markdown' button to the blog editor UI.
- Clicking button should:
- Export the editor’s current rich text (using Slate.js) as valid Markdown (.md).
- Download the file to local machine with the current blog post title as filename.
- Error toast if export fails.
- Code and logic must be in
/components/MarkdownExport.tsx. Refactor existing export logic if needed.
Branch/PR requirements:
- Feature must be in its own branch (
feature/markdown-export), not main. - One PR titled exactly “Add Markdown export feature to Blog Editor”.
- PR should reference this issue and auto-close it upon merge.
Acceptance Criteria:
- Markdown export button visible in editor.
- Downloaded .md matches content in preview, preserving headers, bullet lists, and bold/italic text.
- Handles error gracefully (toast visible for 2s).
Test Requirements:
- Jest tests for:
- Successful export (file contents = input in Markdown)
- Export failure (simulated exception, error toast shown)
- Non-regression (nothing breaks in existing export features)
Dependencies:
- Relies on Slate.js content state; uses
remarklibrary for conversion.
Out of scope:
- PDF export, cloud sync, third-party Markdown upload.
How to use this
- Start with an actionable GitHub issue: Create a new issue in your repo. Title it clearly so Codex can read and map it. Describe the context, user story, and business rationale in 2–3 sentences.
- Specify branch and PR details up front: Explicitly name the branch Codex should use (e.g., feature/markdown-export), as well as the exact PR title to use when proposing a pull request. This keeps the workflow deterministic.
- Put the full feature spec in the issue body: Document what should change, where (files, folders), and include concrete UI/UX acceptance criteria. Tooling like Next.js or Stripe? Name them.
- Add machine-checkable test requirements: List expected automated tests: what files, which test framework (e.g., Jest, Supabase functions), and measurable success/failure. Codex acts more reliably when test scaffolding is explicit.
- Declare dependencies and out-of-scope features: Mention any required libraries (remark, Cursor, Vercel) and clarify what’s not being built now, so Codex doesn’t overreach.
- Review and post for Codex execution: Double-check that all structure is in place, assign issue to Codex (OpenAI) agent, and monitor draft PR. Provide fast async feedback if Codex proposes changes.
FAQ
How detailed should a PRD be for Codex (OpenAI)?
Include precise branch names, PR titles, test coverage, and technical stack details. The agent performs best when structure is clear—avoid ambiguity in acceptance criteria, dependencies, and what’s out-of-scope. Use measurable metrics and tie each requirement to user outcomes.
What tests do I need to specify for Codex?
You should outline at least unit and feature-level automated tests (e.g., Jest, Playwright). For best results, describe test file locations and the conditions for passing/failing. The clearer your test matrix, the more reliably Codex will generate passing code.
Can I use Codex with tools like Replit or Vercel?
Yes, but Codex’s workflow is optimized for GitHub-based flows. If deploying on Replit or Vercel, call them out in your PRD (e.g., environment config, CI hooks) and clarify any special deployment or integration steps.
Does Codex understand all third-party libraries?
Codex does well with popular libraries (like Next.js, Stripe, remark), but if you use a niche or recently updated package, give explicit documentation links or usage examples in your PRD.
How do I handle rollbacks if Codex’s code is off?
Require PRs and branch isolation in your PRD. If code isn’t right, close the PR without merging or leave review comments. Enabling GitHub Actions for tests protects main from regressions.