Safe Configuration File Modification Prompt

This prompt is designed for AI coding agents and automated refactoring pipelines that need to modify structured configuration files—YAML, JSON, TOML, or environment files—where a single syntax error can break a deployment, crash a service, or corrupt a critical system state. The job-to-be-done is a validated, traceable edit that produces a schema-conformant, parseable output file and a backup copy, not just a raw text patch. The ideal user is a platform engineer, DevOps lead, or AI toolchain builder integrating an LLM into a CI/CD pipeline, infrastructure-as-code workflow, or internal developer platform where configuration changes must be safe by default.

Use this prompt when the target file has a known schema, the modification is scoped to specific fields or sections, and the cost of malformed output is high—production outages, failed deployments, or silent misconfigurations. The prompt requires the following inputs to be useful: the full original file content, a machine-readable schema (JSON Schema, YAML schema definition, or a strict type specification), the specific modification instruction, and any organizational policies such as 'never remove comments' or 'preserve key ordering.' Do not use this prompt for unstructured text files, for files where the schema is unknown or ambiguous, or when the modification requires reasoning about runtime behavior that cannot be validated statically. It is also inappropriate for files where a backup copy cannot be created due to security or storage constraints.

Before wiring this prompt into an automated pipeline, confirm that your system can provide a parseable schema and that you have a validation step in place to check the output before it overwrites the original file. The prompt includes built-in guardrails—schema validation, syntax checking, and backup generation—but it does not replace integration tests, canary deployments, or human review for production-critical configuration. If the modification touches security settings, authentication credentials, or network policies, always require a human approval step after the prompt produces its output. The next section provides the copy-ready template you can adapt to your specific file format and schema.

This prompt template provides the core instruction set for an AI coding agent to modify a configuration file while enforcing strict safety guardrails. It is designed to be copied directly into your agent's system prompt or task context, with square-bracket placeholders that you replace with your specific file path, edit intent, and validation rules. The template assumes the agent has access to file-system tools for reading, writing, and executing validation commands.

textCopy
You are a configuration file editor with mandatory safety guardrails. Your task is to modify [FILE_PATH] according to [EDIT_INTENT].

## PRE-EDIT CHECKS (execute before any modification)
1. Read the current file content and compute its SHA-256 hash.
2. Verify the file is parseable using [VALIDATION_COMMAND]. If parsing fails, abort and report the pre-existing error.
3. Create a timestamped backup at [BACKUP_DIR]/[FILENAME].[TIMESTAMP].bak.
4. Confirm the backup file content matches the original by comparing hashes.
5. Check that [FILE_PATH] is not a symlink to a file outside [ALLOWED_DIRECTORY]. If it is, abort.

## EDIT CONSTRAINTS
- Modify only the sections or keys specified in [EDIT_INTENT]. Do not reorder, reformat, or alter unrelated sections.
- Preserve all comments unless [EDIT_INTENT] explicitly requires their removal.
- Preserve the original file encoding and line endings.
- If the file uses [SCHEMA_FORMAT] (e.g., JSON Schema, YAML anchor references), validate the proposed change against [SCHEMA_PATH] before writing.
- Do not introduce syntax errors. If the edit would produce malformed output, abort and explain why.

## POST-EDIT VERIFICATION
1. Write the modified content to [FILE_PATH].
2. Immediately run [VALIDATION_COMMAND] on the modified file.
3. If validation fails, restore from the backup, report the failure, and do not retry without human approval.
4. If validation passes, compute the new SHA-256 hash and produce a structured diff summary.

## OUTPUT FORMAT
Return a JSON object with the following structure:
{
  "pre_edit_hash": "string",
  "post_edit_hash": "string",
  "backup_path": "string",
  "validation_passed": boolean,
  "diff_summary": "string describing only the changed lines",
  "warnings": ["list of any non-blocking concerns such as deprecated keys or formatting inconsistencies"]
}

## FAILURE MODE RULES
- If pre-edit validation fails, set validation_passed to false and include the parse error in warnings. Do not modify the file.
- If post-edit validation fails, restore the backup, set validation_passed to false, and explain the failure.
- If [EDIT_INTENT] is ambiguous or would affect more than [MAX_SCOPE_KEYS] keys, request clarification before proceeding.

To adapt this template, replace the square-bracket placeholders with concrete values for your environment. [VALIDATION_COMMAND] should be a shell command that returns a non-zero exit code on failure, such as python -c 'import yaml; yaml.safe_load(open("config.yaml"))' or jq empty config.json. [SCHEMA_PATH] is optional but strongly recommended for structured formats; omit the schema validation block if no schema exists. [MAX_SCOPE_KEYS] controls how many top-level keys the edit may touch before the agent must ask for human confirmation, preventing overly broad changes. Wire this prompt into your agent harness with a timeout on the validation step and a hard limit of one retry before escalating to a human reviewer.

This prompt is designed to be called from an automated pipeline or coding agent, not a free-text chat interface. The application layer is responsible for supplying the file path, current content, and requested change description as structured inputs. The model's output must be treated as a candidate edit, never applied directly to disk without passing through a validation harness. The harness should parse the model's structured response, extract the proposed new content, and run it through a syntax validator specific to the file format (YAML, JSON, TOML, or dotenv) before any file write occurs.

The implementation loop follows a strict sequence: snapshot → prompt → validate → apply or reject. First, capture a pre-edit snapshot of the file with a SHA-256 hash and a backup copy written to a .bak or versioned path. Second, assemble the prompt with the file content, change description, and format-specific schema constraints injected into the [CONFIG_FORMAT], [CURRENT_CONTENT], and [CHANGE_DESCRIPTION] placeholders. Third, parse the model's JSON response and validate the proposed_content field using a format-specific parser (e.g., yaml.safe_load for YAML, json.loads for JSON). If parsing fails, increment a retry counter and re-invoke the prompt with the parse error message appended to [CONSTRAINTS]. Fourth, if parsing succeeds, compare the original and proposed content structurally to confirm the change is scoped correctly—no unexpected key deletions, no type coercion of existing values, and no silent truncation. Fifth, write the validated content to the target file and log the diff, hash, and validation results to an audit trail.

For production deployments, set a hard retry limit of 3 attempts before escalating to a human reviewer. Each retry should include the accumulated error context so the model can self-correct. Choose a model with strong structured output support—GPT-4o or Claude 3.5 Sonnet with strict JSON mode enabled. Avoid using smaller or older models for this task because malformed configuration files can cause system outages. Wire the harness into your existing CI/CD or agent orchestration layer with explicit logging of every step: snapshot hash, prompt invocation ID, validation result, retry count, and final outcome. Never skip the backup step; a verified rollback path is the safety net that makes automated configuration edits acceptable in production.