Architectural Fitness Function Evaluation Prompt

This prompt is for platform engineers and architects who need to automate architecture governance in CI/CD pipelines. It evaluates a codebase or system design against predefined coupling rules and produces a structured pass/fail result with specific violation evidence. Use this when you want to enforce rules like 'no circular dependencies between packages,' 'no direct imports from infrastructure layer to domain layer,' or 'no shared database access across bounded contexts.' The prompt is designed to be wired into a build pipeline where it acts as a gate: pass allows the build to continue, fail blocks it with a detailed report.

Do not use this prompt for subjective architecture review, greenfield design exploration, or trade-off analysis. It is a compliance check, not a design advisor. The prompt requires a concrete set of rules expressed as machine-readable constraints—such as forbidden import patterns, allowed dependency directions, or maximum coupling thresholds—and a source of evidence like a dependency graph, import analysis output, or architecture model. Without these structured inputs, the model will hallucinate violations or miss real ones. The ideal user is someone who already knows which rules matter for their system and needs a repeatable, automated enforcement mechanism rather than a one-time review.

Before wiring this into a pipeline, confirm that your rules are unambiguous and your evidence source is deterministic. If your rules require human interpretation—for example, 'avoid excessive coupling' without a numeric threshold—this prompt will produce inconsistent results. Pair it with static analysis tools that generate the raw dependency data, and use the prompt only for the evaluation layer. For high-risk systems where a false negative could allow a dangerous change to deploy, always include a human review step on failures and periodically audit pass results against manual spot checks to catch rule gaps.

This prompt template is designed to be the core instruction set for an automated architectural governance gate. It takes a set of defined fitness functions—specific, measurable criteria for architectural qualities like coupling, cohesion, or dependency direction—and evaluates a provided system description or codebase analysis against them. The output is a structured, machine-readable report that can be directly consumed by a CI/CD pipeline to automatically pass or fail a build based on architectural rules.

textCopy
You are an architectural fitness function evaluator. Your task is to assess a system's architecture against a set of predefined, measurable rules called fitness functions. You will receive the system's architectural context and a list of fitness functions to evaluate. For each function, you must determine a pass or fail status and provide concrete, source-grounded evidence for your decision.

INPUT SYSTEM CONTEXT:
[SYSTEM_CONTEXT]

FITNESS FUNCTIONS TO EVALUATE:
[FITNESS_FUNCTIONS]

EVALUATION CONSTRAINTS:
[CONSTRAINTS]

OUTPUT SCHEMA:
You must produce a JSON object conforming to the following structure. Do not include any text outside the JSON object.
{
  "evaluation_results": [
    {
      "function_id": "string",
      "function_description": "string",
      "status": "PASS" | "FAIL" | "INCONCLUSIVE",
      "evidence": [
        {
          "source_reference": "string",
          "finding": "string"
        }
      ],
      "rationale": "string"
    }
  ],
  "aggregate_result": "PASS" | "FAIL",
  "summary": "string"
}

RULES:
1. Evaluate every fitness function provided in the [FITNESS_FUNCTIONS] list.
2. For a FAIL status, the evidence must contain at least one specific, source-grounded violation.
3. For a PASS status, the evidence must demonstrate how the system satisfies the rule.
4. Use INCONCLUSIVE only when the provided [SYSTEM_CONTEXT] lacks the necessary information to make a determination.
5. The aggregate_result is PASS only if all individual function statuses are PASS. If any function FAILs or is INCONCLUSIVE, the aggregate_result is FAIL.
6. Adhere strictly to the [CONSTRAINTS] provided.
7. If [RISK_LEVEL] is HIGH, you must include a note in the rationale for any FAIL status recommending a mandatory human architecture review.

RISK LEVEL: [RISK_LEVEL]

To adapt this template for your environment, replace the square-bracket placeholders with concrete data. [SYSTEM_CONTEXT] should be populated with a structured representation of your architecture, such as a dependency graph, a list of components and their imports, or an architecture decision record. [FITNESS_FUNCTIONS] must be a list of specific, testable rules, like 'The data package shall not depend on the ui package' or 'No circular dependencies are allowed between top-level modules.' The [CONSTRAINTS] placeholder allows you to inject context-specific rules, such as ignoring test directories or allowing exceptions for shared kernel libraries. Before integrating this into a pipeline, run it against known-clean and known-violating architectures to calibrate its sensitivity and ensure the evidence it provides is accurate and actionable.

This prompt is designed to operate as a deterministic gate inside a CI/CD pipeline, not as a conversational advisor. The harness must treat the model output as a structured pass/fail signal with evidence, not as a suggestion. The primary integration point is a pull-request check or a pre-merge build step that runs the fitness function against the proposed change set. The harness is responsible for providing the model with the correct [ARCHITECTURE_RULES], the [CHANGE_DIFF] or [DEPENDENCY_GRAPH], and the [FAILURE_THRESHOLD] configuration. The model's job is to apply the rules to the evidence and return a structured verdict.

The implementation should follow a strict validate → execute → parse → gate loop. First, validate that all required inputs are non-empty and well-formed before calling the model. Use a lightweight JSON Schema validator to confirm the [ARCHITECTURE_RULES] payload contains the expected rules[] array with id, description, and severity fields. If the input is malformed, fail the check immediately with a clear configuration error rather than sending garbage to the model. For the execution step, use a low-temperature setting (0.0–0.1) and a constrained output schema via structured output mode or a tool-calling API to guarantee the response shape. The output must include a top-level verdict field (PASS or FAIL), a violations[] array, and a violation_count. After receiving the response, parse it and validate that every violation references a specific rule ID from the input and a specific file path or module from the change set. If the model hallucinates a rule ID that doesn't exist in the input, discard that violation and log a warning. If violation_count exceeds the configured [FAILURE_THRESHOLD], the CI check fails and the violations are posted as inline annotations on the pull request.

For high-risk repositories where false negatives could allow architectural degradation, add a human review escalation path. When the model returns a PASS verdict but the change touches files in a pre-defined high-sensitivity path list (e.g., core domain modules, shared kernel packages), the harness should flag the check as requiring manual approval rather than auto-passing. This prevents a model blind spot from silently eroding critical boundaries. Log every evaluation run—including the full prompt, the raw model response, the parsed verdict, and the final gate decision—to a structured logging system. This audit trail is essential for tuning rules, debugging false positives, and demonstrating governance compliance to auditors. Do not use this prompt as the sole gate for safety-critical or security-critical architecture rules; those should always require a human sign-off in addition to the automated check.

When choosing a model, prefer one with strong instruction-following and structured output reliability. The prompt relies on the model applying explicit rules to explicit evidence without creative interpretation. Test the harness with a golden dataset of known violations and known clean changes before enabling it as a blocking check. Include negative test cases where the change is architecturally sound but structurally unusual to catch over-eager failure modes. The harness should also implement a retry with backoff for transient API failures, but never retry on a FAIL verdict—only on parse errors or model refusals. A parse error after one retry should escalate to a human operator, not silently pass.