Dependency-Aware Code Example Prompt

This prompt is for documentation engineers and DevRel teams who need to produce code examples that are guaranteed to build and run against a specific, declared dependency tree. The core job is not just generating a code snippet—it is generating a snippet that includes explicit version pins, correct import statements, and a manifest (such as package.json, requirements.txt, or go.mod) that resolves cleanly. Use this when your documentation pipeline must prevent the most common source of user frustration: examples that fail because of version drift, missing transitive dependencies, or incompatible runtime assumptions.

The ideal user is a technical writer or SDK engineer who maintains multi-version documentation and needs every published example to be reproducible. Required context includes the target language, runtime version, the exact library name and minimum version, and any peer-dependency constraints. You should also provide the API surface being demonstrated and the expected output shape. Do not use this prompt for architectural decision records, high-level conceptual docs, or code that intentionally omits dependency management (such as pseudocode or algorithm sketches). It is also not a substitute for a live CI/CD pipeline that tests examples against a real build environment—it is the prompt that generates the input to that pipeline.

Before wiring this into production, define a validation harness that runs the generated example in an isolated environment matching the declared dependencies. The harness should check that the example compiles, resolves all imports, and produces the expected output without errors. If the example fails, the harness should capture the build log and feed it back into a repair loop. For high-risk or security-sensitive libraries, add a human review step before publication. The next section provides the copy-ready prompt template you can adapt and embed in your documentation generation workflow.

This section provides the core prompt template for generating code examples that are explicitly tied to a target dependency tree. Unlike generic code generation prompts that might produce syntactically correct but unresolvable code, this template forces the model to declare its assumptions about library versions, language runtimes, and import paths. The output is designed to be fed directly into a validation harness that checks for compilation, dependency resolution, and runtime execution against a lockfile or manifest.

markdownCopy
You are a documentation engineer generating a runnable code example for a specific software library.

Your task is to produce a complete, self-contained code example that demonstrates [FUNCTIONALITY] using the [LIBRARY_NAME] library.

# Required Context
- **Target Language & Version:** [LANGUAGE_RUNTIME]
- **Primary Library & Version:** [LIBRARY_NAME]==[LIBRARY_VERSION]
- **Additional Dependencies:** [DEPENDENCY_LIST]
- **User Goal:** [USER_STORY]

# Output Requirements
1.  **Dependency Manifest:** Start with a code block containing the exact dependency declaration file (e.g., `requirements.txt`, `package.json`, `go.mod`, `Cargo.toml`) that pins all required libraries to specific, compatible versions.
2.  **Complete Source File:** Provide a single, complete source file that can be saved and executed. It must include all necessary import statements that match the declared dependencies.
3.  **Error Handling:** The example must include realistic error handling for [ERROR_CONDITIONS]. Do not use empty catch blocks or silent error suppression.
4.  **Comments:** Use inline comments to explain the 'why' behind non-obvious logic, not the 'what'. Focus on library-specific idioms, configuration choices, and error recovery strategies.
5.  **Output Contract:** The script should print a clear, structured result to standard output that matches [OUTPUT_SCHEMA].

# Constraints
- Do not use placeholder comments like `# ... your code here`.
- Do not reference files or environment variables that are not created within the example itself.
- Ensure the example is idempotent where possible, or clearly documents any side effects.
- Adhere strictly to the security guidelines in [SECURITY_POLICY].

# Example Pair (for style reference)
[FEW_SHOT_EXAMPLE]

To adapt this template, replace the square-bracket placeholders with concrete values from your documentation source of truth. The [DEPENDENCY_LIST] should be derived from your project's actual lockfile to ensure the generated example pins real, tested version combinations. The [ERROR_CONDITIONS] placeholder is critical for steering the model away from happy-path-only examples; specify the exact exception types or HTTP status codes your API surface can return. Before integrating this prompt into a CI/CD pipeline, run the generated output through a validation harness that executes pip install -r requirements.txt (or equivalent) and then runs the script to confirm it exits cleanly and produces output matching [OUTPUT_SCHEMA].

This prompt is designed to be called programmatically as part of a documentation generation pipeline, not as a one-off chat interaction. The core job of the harness is to take the model's output—a code block with explicit dependency declarations—and automatically verify that it actually resolves and builds against the specified dependency tree. Without this verification step, the prompt's value collapses to a suggestion rather than a guarantee. The harness should treat the prompt output as a hypothesis to be tested, not a finished artifact to be published.

The implementation should follow a generate → extract → validate → repair → publish loop. First, call the model with the prompt template, injecting the target language, framework, and version constraints into the [TARGET_RUNTIME] and [DEPENDENCY_CONSTRAINTS] placeholders. Parse the model's response to extract the code block and the dependency manifest (e.g., package.json, requirements.txt, go.mod). Write both to a temporary sandbox directory. Execute a build command inside a container that matches the declared runtime version—for example, docker run --rm -v $PWD:/app node:18-alpine sh -c 'cd /app && npm install && npm run build'. Capture the exit code, stdout, and stderr. If the build fails, feed the error output back into the model with a repair prompt: 'The following build error occurred when testing your example. Fix the code and dependency declarations to resolve it.' This retry loop should have a hard limit of 3 attempts before flagging the example for human review.

Logging and artifact storage are critical for auditability. For every generation attempt, persist the prompt input, raw model output, extracted files, build logs, and final pass/fail status. This trace allows documentation engineers to debug why a particular example failed and to detect drift over time—for instance, when a package registry removes a version that was previously valid. In high-stakes environments like security SDK documentation, add a human approval gate after automated validation passes. A reviewer should confirm that the generated example doesn't introduce subtle anti-patterns (e.g., disabling TLS verification for convenience) before it reaches the public docs site. For model selection, prefer models with strong code generation capabilities and deterministic output modes (temperature=0) to maximize reproducibility across runs.