Prompt Engineering Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• prompts/system_prompts.yaml
• src/core/prompt_manager.py
• configs/llm_config.json
• src/utils/template_renderer.py

Introduction

The Prompt Engineering Guidelines define the standardized approach for creating, managing, and optimizing interactions with Large Language Models (LLMs) within the Dev-Template project. These guidelines ensure consistency, reliability, and maintainability across all AI-driven features by decoupling prompt logic from application code.

The project utilizes a template-driven system where prompts are stored in external configuration files and rendered dynamically at runtime. This modular architecture allows developers to iterate on prompt instructions without modifying the core logic of the service.

Sources: README.md, src/core/prompt_manager.py:1-15

Prompt Management Architecture

The system centralizes prompt storage and retrieval through a dedicated management layer. This architecture separates the raw prompt text (defined in YAML/JSON) from the execution logic, facilitating version control and environmental overrides.

Core Components

Component	Description	Primary File
Prompt Manager	Orchestrates the loading, caching, and retrieval of prompt templates.	src/core/prompt_manager.py
Template Renderer	Handles variable substitution and logical branching within prompts using Jinja2 syntax.	src/utils/template_renderer.py
System Prompts	Centralized YAML repository for base system instructions and personas.	prompts/system_prompts.yaml
LLM Configuration	Defines model parameters such as temperature, top_p, and max tokens.	configs/llm_config.json

Sources: src/core/prompt_manager.py:20-45, configs/llm_config.json:2-10

Prompt Retrieval Flow

The following diagram illustrates how the application requests a prompt and receives a fully rendered string ready for the LLM.

The flow ensures that context-specific data (like user input or database results) is merged into the static prompt template only at the moment of execution.

Sources: src/core/prompt_manager.py:50-75, src/utils/template_renderer.py:10-25

Implementation Guidelines

Template Syntax and Variable Injection

Prompts MUST use the {{ variable_name }} syntax for placeholders. The TemplateRenderer class validates that all required keys are present in the context dictionary before rendering to prevent partial prompts from being sent to the model.

# Example of dynamic rendering in src/utils/template_renderer.py
def render(template_str, context):
    return jinja2.Template(template_str).render(**context)

Sources: src/utils/template_renderer.py:30-40

Configuration Parameters

Model behavior is controlled via configs/llm_config.json. Developers should adjust these parameters based on the specific use case:

• Temperature: Set lower (0.1 - 0.3) for factual extraction or code generation. Set higher (0.7 - 0.9) for creative tasks.
• Presence Penalty: Used to discourage the model from repeating the same tokens.
• Stop Sequences: Defined to prevent the model from generating beyond the desired output format.

Sources: configs/llm_config.json:5-15

System vs. User Prompts

The project distinguishes between "System" instructions (long-term behavior) and "User" instructions (short-term task). System prompts are stored in prompts/system_prompts.yaml and should include:

1. Role Definition: e.g., "You are an expert software architect."
2. Constraint Sets: e.g., "Always return responses in valid JSON format."
3. Tone and Style: e.g., "Use concise technical language."

Sources: prompts/system_prompts.yaml:1-20

Execution Sequence

The sequence diagram below shows the interaction between the LLM client and the internal prompt components during a standard request.

Conclusion

By adhering to these prompt engineering guidelines, the project maintains a clear separation of concerns. Centralizing prompts in prompts/system_prompts.yaml and using the PromptManager ensures that the AI's behavior is predictable, testable, and easily updated without necessitating deep code changes.