You open the Codex PR. The title is “Update components.” The body says “Refactored several components for better readability.” That is it — 12 files changed, 400 lines diff, no explanation of what changed, why, or how it was tested. As a reviewer you now have to read the entire diff cold, with no model of the author’s intent.
This is not a Codex capability problem. The agent will produce a great PR description when you ask for one. The default is bad because most repos have no PR template, no AGENTS.md rule about description format, and the model fills the void with vague phrasing.
The fix is a .github/PULL_REQUEST_TEMPLATE.md plus an AGENTS.md block telling Codex to use it and how to fill each section from its own commit log.
Common causes
1. Repo has no PR template
When you click “New pull request” the body is empty. Codex has nothing to anchor on, so it produces one sentence and moves on.
How to spot it: ls .github/PULL_REQUEST_TEMPLATE.md returns nothing. The PR description starts directly with the model’s prose.
2. AGENTS.md says nothing about PR descriptions
Codex follows AGENTS.md. If the file has zero guidance on PR format, the agent uses its training-data default, which tends toward generic.
How to spot it: grep -i 'pull request\|pr description\|pr body' AGENTS.md returns nothing.
3. The task prompt is itself one line
You said “fix the date picker bug.” Codex’s PR body is approximately as detailed as your prompt. Short input, short output.
How to spot it: Compare the Codex task description with the PR body. If both are one sentence, the prompt is the bottleneck.
4. Agent’s harness truncates the PR body
Some Codex CLIs and wrappers send the PR body via a CLI flag that has a length cap, or pipe it through a script that strips newlines. The model wrote a detailed body; the upload was truncated.
How to spot it: Compare the body in git log (or the agent transcript) with what is on GitHub. If GitHub’s body is shorter, the harness ate it.
5. Codex used the first commit message as the body
Without other guidance, the agent copies the first commit subject as both title and body. Result: PR body is identical to the commit subject, no detail beyond it.
How to spot it: Check if PR body equals first commit message. If yes, the harness or prompt did not request a richer body.
Shortest path to fix
Step 1: Add a PR template
Create .github/PULL_REQUEST_TEMPLATE.md:
## What changed
<one paragraph summary>
## Why
<the problem, motivation, or linked issue>
## Before / After
<for behavior changes: describe or screenshot before and after>
## How I tested
- [ ] `npm test` passes locally
- [ ] manual check: <steps>
- [ ] new tests added for <case>
## Risk
<what could break, who depends on the changed code>
## Related
<linked issues, related PRs>GitHub auto-populates the PR body with this template. Codex sees the empty sections and fills them.
Step 2: Add an AGENTS.md instruction
Append to AGENTS.md:
## PR description
Every PR you open must follow `.github/PULL_REQUEST_TEMPLATE.md` exactly. Fill
every section. Specifically:
- **What changed**: list the user-visible behavior changes or the structural
changes by file path. Not "refactored components" — say "Extracted
`useSession` from `Header.tsx` so the dashboard can reuse it."
- **Why**: link the issue if one exists, or describe the bug / requirement.
- **Before / After**: for UI or behavior changes, show both states.
- **How I tested**: list the actual commands you ran, not "tested locally."
- **Risk**: name at least one place that could break.
If a section does not apply, write "N/A — <reason>", not blank.This converts a template into enforced structure.
Step 3: Use the commit log to draft the body
Add this guidance to AGENTS.md:
When drafting the PR body, base "What changed" on the commit log:
git log --reverse origin/main..HEAD --pretty=format:'- %s'
Each commit becomes a bullet in "What changed." Then expand each bullet with
one sentence of context. This way the PR body matches the actual changes.The agent now has a concrete source for the description, not vibes.
Step 4: Validate description length in CI
Add a workflow that fails PRs with a too-short body:
# .github/workflows/pr-description.yml
name: PR description check
on:
pull_request:
types: [opened, edited, synchronize]
jobs:
check:
runs-on: ubuntu-latest
steps:
- name: Require non-trivial description
env:
BODY: ${{ github.event.pull_request.body }}
run: |
if [ -z "$BODY" ] || [ ${#BODY} -lt 200 ]; then
echo "PR body is too short (need 200+ chars). Use the template."
exit 1
fi
for section in "What changed" "Why" "How I tested"; do
if ! echo "$BODY" | grep -q "$section"; then
echo "Missing section: $section"
exit 1
fi
doneRequired-status-check this workflow and Codex cannot land with a one-liner.
Step 5: Write better task prompts
The agent mirrors your prompt’s detail. Use a prompt template:
TITLE: <one sentence, imperative mood>
CONTEXT: <why this matters, link the issue>
SCOPE: <files / glob>
ACCEPTANCE:
- <specific test or behavior 1>
- <specific test or behavior 2>
NOTES FOR PR BODY:
- mention <X> in "Before / After"
- link issue #<N>Codex turns these notes into PR sections.
Prevention
- Ship
.github/PULL_REQUEST_TEMPLATE.mdwith the sections you actually want - Tell
AGENTS.mdto fill every template section and forbid “N/A” without reason - Have the agent draft “What changed” from
git log, not from a fresh summary - CI-check PR body length and section headers; required status check
- Provide structured task prompts so the agent has material for the PR body
- Inspect the actual GitHub PR body, not the transcript — the harness may truncate