Service Boundary Interface Contract Review Prompt

This prompt is for platform engineers and architects reviewing the interface contract between two services before implementation or during a migration. It produces a structured assessment of coupling, data leakage, chatty interactions, and missing abstractions. The ideal user has a concrete interface specification—such as an OpenAPI fragment, a gRPC proto definition, or a detailed textual description of request and response schemas—and needs an objective, design-level review before code is written or a migration is committed.

Use this prompt during design reviews, service extraction planning, or when evaluating a proposed integration contract. It assumes the interface is already defined enough to reason about its shape. The prompt works best when you provide the full contract text, the names and responsibilities of the two services, and any known non-functional constraints like latency budgets or data residency requirements. The output is a structured report, not a runtime debug trace or a security threat model.

Do not use this prompt for runtime debugging, code-level review, or security threat modeling. It will not find implementation bugs, memory leaks, or injection vulnerabilities. It is also not a substitute for consumer-driven contract testing or performance profiling. If you lack a concrete interface specification, start with an API design prompt first. For high-risk domains like payments or healthcare, always pair the output with a human architecture review and consider additional compliance checks before finalizing the contract.

The following prompt template is designed to be copied directly into your AI harness, IDE, or orchestration layer. It expects you to provide the interface contract for two services, along with any relevant architectural context. Replace every square-bracket placeholder with concrete values before sending the prompt to the model. The prompt instructs the model to act as a platform architect and produce a structured assessment of coupling, data leakage, chatty interactions, and missing abstractions.

textCopy
You are a platform architect reviewing the interface contract between two services. Your goal is to identify risks that will cause operational pain, slow delivery, or expensive refactoring if left unresolved.

## INPUT

Service A: [SERVICE_A_NAME]
Service B: [SERVICE_B_NAME]

Interface Contract:
[INTERFACE_CONTRACT_SPECIFICATION]

Architectural Context:
[ARCHITECTURAL_CONTEXT]

## CONSTRAINTS

- Focus on the boundary between Service A and Service B.
- Do not review internal implementation details of either service unless they leak through the interface.
- Classify each finding by severity: CRITICAL, HIGH, MEDIUM, LOW.
- For each finding, provide a concrete recommendation.

## OUTPUT_SCHEMA

Return a JSON object with the following structure:
{
  "assessment_summary": "string (2-3 sentence summary of overall boundary health)",
  "findings": [
    {
      "id": "string (unique finding identifier, e.g., FIND-001)",
      "category": "COUPLING | DATA_LEAKAGE | CHATTY_INTERACTION | MISSING_ABSTRACTION | CONTRACT_EVOLVABILITY | ERROR_HANDLING",
      "severity": "CRITICAL | HIGH | MEDIUM | LOW",
      "description": "string (clear description of the issue)",
      "evidence": "string (specific reference to the contract, e.g., endpoint, field, or interaction pattern)",
      "impact": "string (what breaks, slows down, or becomes risky if unresolved)",
      "recommendation": "string (concrete, actionable fix)"
    }
  ],
  "coupling_score": "number (1-10, where 10 is extremely tight coupling)",
  "data_leakage_risk": "LOW | MEDIUM | HIGH | CRITICAL",
  "chatty_interaction_count": "number (estimated number of calls needed for a typical consumer workflow)",
  "missing_abstractions": ["string (list of concepts or resources that should be explicitly modeled in the contract)"]
}

## EVALUATION CRITERIA

Before returning the output, verify:
- Every finding references specific evidence from the contract.
- Severity ratings are justified by concrete impact, not speculation.
- The coupling score reflects the number and strength of dependencies.
- Chatty interaction count is based on a realistic consumer workflow, not worst-case.
- Missing abstractions are concepts that would reduce coupling or data leakage if added.

## RISK_LEVEL

[HIGH_RISK | MEDIUM_RISK | LOW_RISK]

If RISK_LEVEL is HIGH_RISK, flag any finding where human review is mandatory before implementation.

How to adapt this template: The [INTERFACE_CONTRACT_SPECIFICATION] placeholder should contain the full API specification, event schema, gRPC proto file, or message queue contract that defines the boundary. This can be pasted as raw text, OpenAPI YAML, or a structured description. The [ARCHITECTURAL_CONTEXT] placeholder should include system diagrams, data flow descriptions, non-functional requirements, and known constraints that shape the boundary. The [RISK_LEVEL] placeholder controls the model's caution: set to HIGH_RISK for payment systems, healthcare data, or auth boundaries; use MEDIUM_RISK for internal services with SLOs; use LOW_RISK for non-critical asynchronous pipelines. After receiving the output, validate the JSON structure before ingesting it into your review pipeline. Run the findings through your existing eval harness to catch false positives—particularly coupling flags that are actually intentional design choices documented in your architecture decision records.

This prompt is designed to operate on a structured input representing the interface contract between two services. In production, you should not paste raw chat logs or informal API descriptions. Instead, build a pre-processing step that normalizes the interface definition into a consistent format—typically a JSON object containing the method signatures, data schemas, error responses, and call sequences for the boundary under review. The prompt expects this structured [INTERFACE_CONTRACT] as its primary input, along with optional [SERVICE_CONTEXT] describing each service's responsibility and [REVIEW_CRITERIA] for weighting specific concerns like latency sensitivity or data residency requirements.

The implementation harness should enforce a strict output schema. After the model returns its assessment, validate the response against a JSON Schema that requires the boundary_violations array, coupling_score integer, data_leakage_flags array, and missing_abstractions array. Each violation must include a severity enum of CRITICAL, WARNING, or INFO. If the model output fails schema validation, retry once with the validation errors appended to the prompt as [PREVIOUS_ERRORS]. After two failed attempts, log the raw output and escalate for human review. For high-risk service boundaries—such as those handling payment data, PII, or safety-critical operations—always require a human architect to sign off on the assessment before it is accepted into your design review system.

Model choice matters here. Use a model with strong reasoning capabilities and a large context window, such as Claude 3.5 Sonnet or GPT-4o, because the prompt must hold the full interface contract, service context, and review criteria in a single request. If your interface contracts are large, implement a context budget check before calling the model. When the combined input exceeds 60% of the model's context window, split the review into multiple passes: first review the data schemas for leakage, then review the call patterns for chatty interactions, then synthesize a combined report. Log every review result with the prompt version, model identifier, input hash, and output signature so you can trace regressions when the prompt or model changes.

To prevent false positives—where the model flags acceptable patterns as coupling violations—maintain a suppression list of known acceptable patterns for your organization. After the model returns its assessment, run a post-processing step that filters out any violation matching a suppression rule. For example, if your architecture standard allows shared envelope types across all internal services, suppress data_leakage flags for those types. Conversely, run a coverage check against a checklist of required boundary concerns: every review must address coupling direction, data ownership, call frequency, error propagation, and abstraction level. If the model output is missing any required concern, flag the review as incomplete and retry with explicit instructions to cover the missing dimension.

Wire the prompt into your existing design review workflow through a CI-like pipeline. When a team proposes a new service boundary or changes an existing interface contract, trigger this review automatically. Post the results to your architecture review channel or attach them to the design document. Store the structured output in a queryable format so you can track boundary health over time and identify services that accumulate unresolved coupling warnings. Avoid using this prompt as a gating check that blocks deployment—use it as an advisory signal that informs architecture discussions and highlights risks that merit deeper human analysis.