RC-401h · Module 3

Environment-Specific Prompt Variants (Dev/Staging/Prod)

4 min read

The same prompt does not belong in development and production without modification. A development prompt may include verbose debug output, relaxed schema validation, permissive fallback behaviors, and detailed reasoning chains that would be inappropriate in production. A production prompt is tightened: minimal output verbosity, strict schema enforcement, defined fallback behaviors, and compressed reasoning chains that preserve quality without wasting tokens.

Environment-specific variants are not copies of the same file with minor edits. They are registered library entries with their own namespace path — the environment segment in the namespace schema from Lesson 2. The variant differences are documented explicitly in the library metadata, and the promotion pipeline enforces the sequence: development is approved first, staging variant is validated, production variant is promoted from staging with documented delta.

Do This

  • Maintain environment-specific variants as separate registered library entries with explicit delta documentation
  • Define the production variant as the tightest version — least verbose, most strictly validated
  • Enforce promotion sequencing: dev → staging → prod with documented validation at each gate
  • Use environment variables to select the active variant at runtime, not hardcoded namespace paths

Avoid This

  • Use the same prompt string in dev and prod and assume behavior is equivalent
  • Maintain environment variants as informal forks with no documented relationship or diff
  • Promote directly from dev to prod, bypassing staging validation
  • Debug production prompt failures using the dev variant, which may behave differently
// Environment-aware prompt resolution
// Reads PROMPT_ENV from the runtime environment
// Supports: dev | staging | prod (defaults to prod if unset)

const ENV = (process.env.PROMPT_ENV ?? 'prod') as 'dev' | 'staging' | 'prod';

// Fallback chain: if the exact environment variant doesn't exist,
// fall back to prod. Never fall back to dev from prod.
const ENV_FALLBACK: Record<typeof ENV, (typeof ENV)[]> = {
  dev:     ['dev', 'staging', 'prod'],
  staging: ['staging', 'prod'],
  prod:    ['prod'],
};

export async function resolvePromptForEnv(
  agent: string,
  variant: string,
  version: string = 'latest'
): Promise<ResolvedPrompt> {
  const candidates = ENV_FALLBACK[ENV];

  for (const env of candidates) {
    const ref = `${agent}/${env}/${variant}/${version}`;
    const prompt = await promptLibrary.get(ref);
    if (prompt) {
      return { ...prompt, resolved_ref: ref, environment: env };
    }
  }

  throw new PromptNotFoundError(
    `No prompt found for ${agent}/*/${variant}/${version} in any environment`
  );
}