Skip to main content
pdd update is the Code-to-Prompt Update workflow. When code has been modified — manually or by another tool — pdd update reads those changes and rewrites the prompt to reflect them, preserving the PDD principle that prompts are the source of truth. By default, pdd update uses an agentic AI (Claude Code, Gemini, or Codex) to produce compact, high-quality prompts. It falls back to a simpler two-stage LLM process when no agentic CLI is available.

​
Usage

# Repository-wide mode (no arguments)
pdd [GLOBAL OPTIONS] update

# Generate or regenerate a prompt for a code file
pdd [GLOBAL OPTIONS] update MODIFIED_CODE_FILE

# Update a prompt using git history
pdd [GLOBAL OPTIONS] update --git INPUT_PROMPT_FILE MODIFIED_CODE_FILE

# Update a prompt by providing the original code manually
pdd [GLOBAL OPTIONS] update INPUT_PROMPT_FILE MODIFIED_CODE_FILE ORIGINAL_CODE_FILE

​
Arguments

​
MODIFIED_CODE_FILE
string
The code file that was modified, or the code file for which a prompt should be generated. Required in all single-file modes.
​
INPUT_PROMPT_FILE
string
The existing prompt file to update. Required for update modes (B and C). Not used in generation mode (A) or repository-wide mode.
​
ORIGINAL_CODE_FILE
string
The original (pre-modification) code file. Required for manual update mode (C). Not used when --git is set or in generation mode.

​
Options

​
--git
boolean
default:"false"
Use git history to find the original code file automatically, eliminating the need for ORIGINAL_CODE_FILE. Requires the prompt file and the modified code file as arguments.
​
--output
string
Where to save the updated prompt file. If not specified, the original prompt file is overwritten in place to maintain it as the authoritative source of truth. Also reads from PDD_UPDATE_OUTPUT_PATH.
​
--simple
boolean
default:"false"
Use the legacy two-stage LLM update process instead of the default agentic mode. Faster, but requires no agentic CLI tools.
​
--extensions
string
Comma-separated file extensions to process in repository-wide mode (e.g., py,js,ts). Cannot be used in single-file modes.
​
--base-branch
string
default:"main"
Base branch for change detection in repository-wide mode. Cannot be used in single-file modes.

​
Agentic update (default)

The default agentic update runs a 4-step optimization:
1

Assess differences

Read the prompt (including all <include> files) and compare it against the modified code.
2

Filter using guide and tests

Consult docs/prompting_guide.md and existing tests to determine what content belongs in the prompt.
3

Remove duplication

Eliminate redundant content that duplicates what included files already provide.
4

Validate

Confirm the prompt is human-readable and can reliably regenerate the modified code.
Prerequisites: At least one of the following CLIs must be installed and configured:
  • claude (Anthropic Claude Code) with ANTHROPIC_API_KEY
  • gemini (Google Gemini CLI) with GOOGLE_API_KEY or GEMINI_API_KEY
  • codex (OpenAI Codex CLI) with OPENAI_API_KEY
If none are available, pdd update automatically falls back to the legacy simple mode.
When tests exist for a module (e.g., test_my_module.py), the agentic update discovers and considers them automatically. Behaviors already verified by tests do not need to be restated in the prompt, producing more concise output.

​
Modes

Scans the entire repository, finds all code/prompt pairs, creates any missing prompt files, and updates all of them based on the latest git changes. The easiest way to keep the entire project in sync.
pdd update

# Filter by file extension
pdd update --extensions py,js

​
Examples

# Agentic mode (default) — uses claude/gemini/codex
pdd update --git my_module_python.prompt src/my_module.py

# Legacy simple mode — faster, no agentic CLI required
pdd update --simple --git my_module_python.prompt src/my_module.py

# Overwrite original prompt in place (default behavior)
pdd update \
  factorial_calculator_python.prompt \
  src/modified_factorial_calculator.py \
  src/original_factorial_calculator.py
# This overwrites factorial_calculator_python.prompt

# Save updated prompt to a different location
pdd update \
  --output updated_factorial_calculator_python.prompt \
  factorial_calculator_python.prompt \
  src/modified_factorial_calculator.py \
  src/original_factorial_calculator.py
By default, pdd update overwrites the original prompt file. This is intentional — the prompt is the source of truth in PDD. Use --output if you want to preview changes before committing to the overwrite.
  • pdd sync — Calls pdd update as the final step of its automated workflow.
  • pdd generate — The reverse direction: generates code from a prompt.

Build docs developers (and LLMs) love

Get started for freeTalk to us