Prompt Engineering Best Practices (Demeterics)

Design prompts that are robust, testable, and observable in production. Demeterics adds two powerful capabilities on top of your normal prompts:

• Triple‑slash comments (///) for documentation and inline notes that are automatically stripped before provider calls (no token/cost impact)
• Triple‑slash metadata headers extracted into BigQuery columns for analytics (e.g., APP, FLOW, VARIANT, VERSION)

This guide shows how to structure prompts to take advantage of both.

1) Add a Metadata Header (free, not sent to models)

Place a compact “header” at the top of your prompt with one field per line. These lines are parsed, stored as columns, and then removed before requests reach LLM providers.

Supported keys (case‑insensitive; aliases supported):

• Business: APP, FLOW, PRODUCT, COMPANY, UNIT
• User/Session: USER, SESSION, MARKET
• Technical: VARIANT, VERSION, ENVIRONMENT (ENV), PROJECT
• Other: PRIORITY, TAGS

Accepted formats (choose one consistently):

/// KEY: value
/// KEY value
/// KEY[value]
/// KEY=value
/// KEY : value with spaces
/// KEY: "value with, commas and spaces"

Environment and priority values are normalized (e.g., dev|development → development; urgent|p0 → critical). See metadata_extraction_guide.md for details.

Recommended minimum in production:

/// APP MyProduct
/// FLOW onboarding.signup
/// VERSION 3.2
/// VARIANT control
/// PRIORITY medium

2) Use Inline Comments safely with ///

Use /// to annotate any line. Everything after the first /// on a line is removed before the request is sent. Entire lines beginning with /// (after optional whitespace) are removed.

Examples

You are a helpful assistant. /// Team note: v3 tone tweaks

/// Reviewer: add more examples next iteration
When answering:
1) Be concise /// No long digressions
2) Be accurate /// Cite sources if provided

Notes

• URLs like http:///https:// are protected and not treated as comments.
• Only triple slash is recognized; // or # are not comments.
• Works across all proxied providers (OpenAI, Anthropic, Groq) via Demeterics.

3) Structure of a strong prompt

Recommended prompt sections (adjust to your use case):

1. Metadata header (free context for analytics)
2. Role and objectives (system‑style instruction)
3. Constraints and policies (tone, compliance, safety)
4. Inputs/context (facts, snippets, knowledge)
5. Output contract (schema, format, examples)
6. Quality checklist (self‑review rubric)

Template

/// APP MyProduct
/// FLOW onboarding.signup
/// VERSION 3.2
/// VARIANT control
/// PRIORITY medium

You are an assistant that helps new users complete account signup. /// Internal: reviewed by Trust&Safety 2025‑10‑10

Requirements:
- Be brief and friendly
- Ask for missing information explicitly
- Never invent data or links

Context:
{{facts_or_input}}

Output:
Return JSON with keys: reason, steps, risk_flags.
Example:
{
  "reason": "...",
  "steps": ["...", "..."],
  "risk_flags": ["none"]
}

Quality checklist:
- Answer is faithful to provided context
- Steps are actionable and minimal
- JSON is valid and matches keys

4) Use with Demeterics Reverse Proxy

The reverse proxy automatically strips comments and extracts metadata. Use standard OpenAI-compatible chat completions:

Example with Groq:

curl -X POST https://api.demeterics.com/groq/v1/chat/completions \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-versatile",
    "messages": [
      {
        "role": "system",
        "content": "/// APP MyProduct\n/// FLOW onboarding.signup\n/// VERSION 3.2\n\nYou are a helpful onboarding assistant."
      },
      {
        "role": "user",
        "content": "I need help choosing a plan"
      }
    ]
  }'

Example with OpenAI:

curl -X POST https://api.demeterics.com/openai/v1/chat/completions \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5",
    "messages": [
      {
        "role": "system",
        "content": "/// APP MyProduct\n/// FLOW onboarding.signup\n/// VERSION 3.2\n\nYou are a helpful onboarding assistant."
      },
      {
        "role": "user",
        "content": "Help me select the right pricing plan"
      }
    ]
  }'

Example with Anthropic (Claude):

curl -X POST https://api.demeterics.com/anthropic/v1/messages \
  -H "Authorization: Bearer dmt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "/// APP MyProduct\n/// FLOW onboarding.signup\n/// VERSION 3.2\n\nHelp me choose the best plan for my startup"
      }
    ]
  }'

Guidelines

• Use the reverse proxy endpoints (/groq/v1, /openai/v1, /anthropic/v1)
• Model names must match those in your pricing configuration (see config/pricing.yaml)
• Metadata headers go at the start of the first message (system or user role)
• Comments (///) and metadata are automatically stripped before provider calls (zero token cost)

5) A/B testing and versioning

• Use VARIANT for experiments (e.g., control, v2‑tone, v3‑examples).
• Increment VERSION for any prompt change that could affect output.
• Keep non‑functional notes in /// comments; they won’t affect outputs.
• Analyze results in BigQuery using meta_variant, meta_version, meta_flow, meta_app.

Example query

SELECT meta_variant,
       COUNT(*)               AS interactions,
       AVG(latency_ms)        AS avg_latency,
       AVG(error=TRUE)        AS error_rate
FROM   `project.dataset.interactions`
WHERE  meta_app = 'MyProduct'
  AND  meta_flow = 'onboarding.signup'
  AND  DATE(question_time) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
GROUP BY meta_variant
ORDER BY interactions DESC;

6) Safety and privacy

• Don’t put secrets or PII in comments or metadata.
• Keep metadata values concise and standardized; avoid free‑form sentences.
• Prefer organization‑wide taxonomies for APP, FLOW, and TAGS.

7) Troubleshooting checklist

• Comments not removed? Ensure you’re calling the Demeterics proxy endpoints and using /// (triple slash).
• Metadata not appearing? Put metadata lines at the top; verify key names/aliases; confirm BigQuery columns exist.
• Model errors? Verify the model name is valid for your provider/account; configure via env or app settings.

8) Quick reference for metadata keys

Common keys and BigQuery columns:

• APP → meta_app
• FLOW → meta_flow
• PRODUCT → meta_product
• COMPANY → meta_company
• UNIT → meta_unit
• USER → meta_user
• SESSION → meta_session
• MARKET → meta_market
• VARIANT → meta_variant
• VERSION → meta_version
• ENV/ENVIRONMENT → meta_environment
• PROJECT → meta_project
• PRIORITY → meta_priority
• TAGS → tags array (stored alongside)

Tip: Keep keys in a fixed order at the top of the prompt for consistency and easy reviews.