Skip to main content

​
Overview

pdd example creates a minimal, token-efficient example program that shows how to use a generated module. It is similar to a header file or API documentation — it illustrates the interface without reproducing the full implementation. The example file serves three roles in the PDD workflow:
  • Interface reference — Other prompts can include the example as a lightweight dependency via <include>.
  • Sanity check — pdd crash and pdd verify run this program to confirm the module executes without errors and behaves as intended.
  • Auto-deps discovery — pdd auto-deps scans example files to identify useful dependencies to inject into prompts.

​
Usage

pdd [GLOBAL OPTIONS] example [OPTIONS] PROMPT_FILE CODE_FILE
Arguments:
  • PROMPT_FILE — Path to the prompt file that generated the code.
  • CODE_FILE — Path to the existing code file.

​
Options

​
--output
string
Where to save the generated example. Accepts a file path or directory. Defaults to <basename>_example.<language_extension> in the current directory, or to PDD_EXAMPLE_OUTPUT_PATH if that environment variable is set.
​
--format
string
default:"code"
Output format for the generated example.
  • code — Uses the language-specific file extension (e.g., .py for Python, .js for JavaScript).
  • md — Generates a Markdown file with a .md extension.
When --format is combined with an explicit --output path, the format constrains the output file extension accordingly.

​
When sync calls example

pdd sync automatically invokes example as step 3 of its workflow. It runs the example step when:
  • No example file exists for the module yet.
  • The code file has changed since the last example was generated (detected via fingerprint comparison).
Once generated, the example is immediately used as the program for the subsequent crash and verify steps.

​
Project-specific context

The example command looks for a context/example.prompt file in the current working directory. If found, its content is included in the internal prompt, allowing you to specify project conventions such as required import patterns or preferred output styles. 
context/example.prompt

Please ensure all examples use argparse for CLI arguments and print results to stdout as JSON.

​
Examples

# Generate example for a calculator module
pdd example factorial_calculator_python.prompt src/factorial_calculator.py

# Save to a specific output location
pdd example --output examples/factorial_calculator_example.py \
  factorial_calculator_python.prompt src/factorial_calculator.py

# Generate in Markdown format
pdd example --format md \
  factorial_calculator_python.prompt src/factorial_calculator.py
Generated examples are intentionally compact. They show the interface and demonstrate key usage patterns, not the full behavior. This keeps them token-efficient when other prompts include them as dependencies.

Build docs developers (and LLMs) love

Get started for freeTalk to us