Service Dependency Audit Prompt: Map Coupling Risk

Every architecture diagram lies a little. It shows the dependencies someone remembered to draw, not the ones that grew in over three years of shipping. A service dependency audit prompt reads the actual code and config and tells you where the coupling really is, ranked by how much risk it carries. Not a prettier diagram. A graded report you can act on.

Search for this and you'll find tool roundups and thought-leadership. Augment Code's roundup of dependency-mapping tools is a product comparison with no copyable prompt (augmentcode.com). Devox's "practical approach" piece sells the value of runtime-aware graphs but ships no template, schema, or example you could run today (devoxsoftware.com). The gap is the same one as everywhere in this space: lots of platforms, no prompt.

Here's the prompt, plus how to run it so the output is a ranked audit and not a wall of edges.

What a dependency audit answers that a diagram doesn't

This isn't blast-radius analysis. If you want "I'm about to change the payments service, what breaks downstream," that's a per-change question, and the monorepo impact analysis prompt handles that one. A dependency audit is the standing question: across the whole system, where does the coupling live, and which edges are the dangerous ones?

The two compose. You audit the graph quarterly to know your structural risk. You run impact analysis per PR to know your immediate risk. Different jobs, different prompts.

• Map every service-to-service call from code and config
• Flag synchronous chains three hops deep (the latency and failure traps)
• Surface shared-database coupling that no import graph shows
• Catch hidden dependencies: shared queues, caches, feature flags, schema
• Rank each coupling by blast potential and reversibility
• Find the service that everything depends on but nothing owns
• Produce a written audit, not just a picture, so it lands in a design review

Why static tooling misses the dangerous edges

Import graphs and call-tree tools are good at what they see: direct, in-code references. They're blind to the coupling that hurts most. Two services that both write the orders table are tightly coupled, but neither imports the other, so the graph shows them as independent. That's the dependency that turns a small schema change into an outage.

A prompt reads the config the parser ignores. It sees that service-a publishes to a queue service-b consumes, that both reference the same Redis namespace, that a shared feature-flag key gates behavior in three places. In practice, teams running this kind of audit find the riskiest coupling is almost never in the import graph. It's in the shared state.

Anatomy of the prompt

Give the model the artifacts, a role, and a locked output schema. The schema is what turns raw edges into a ranked audit.

Role:    You are a staff engineer auditing service coupling.
Inputs:  {{repo_structure}}, {{service_manifests}}, {{config_files}},
         {{shared_resources}}, {{risk_focus}}
Task:    Audit cross-service dependencies and grade coupling risk.

Output contract:
1. Dependency table — Caller | Callee | Mechanism | Sync/Async
2. Hidden coupling — shared DB/queue/cache/flag, with evidence
3. Risk grades — each coupling: severity (H/M/L) + one-line why
4. Hotspots — services with the most inbound edges
5. Top 5 fixes — ranked, each with the decoupling pattern to apply

Put the output contract last, after the inputs. Models weight recent tokens, so a long pasted set of manifests above the schema will pull the model toward summarizing the code instead of grading it. Claude holds a numbered contract well across a big context; for GPT-4o, restate "grade each coupling H/M/L with evidence" on the final line if the report comes back as a flat list.

Step-by-step usage

1. Gather the inputs

You don't need the whole monorepo. Service manifests, config files, queue and database wiring, and the directory tree are usually enough for the model to infer the graph. Paste structure over volume.

2. Set the risk focus

{{risk_focus}} steers the audit. "Find latency-coupling before our scale event" produces a different report than "find what blocks our microservice extraction." Tell the model what you're auditing for.

3. Run it

Read the hidden-coupling section first. That's where the value is — the dependency table mostly confirms what you knew, but the shared-state findings are the surprises.

4. Verify the evidence

Every flagged coupling should cite the file or config that proves it. If the model claims two services share a table, it should point at the connection string or the migration. Drop any finding it can't ground. Models will confidently invent an edge if you let them.

5. Turn findings into a backlog

The top-5 fixes section is your decoupling backlog. Each one should name a pattern: introduce an event, add an anti-corruption layer, split the shared table. Vague "reduce coupling" advice is useless; make the prompt prescribe the move.

Prompt-craft patterns that sharpen the audit

Demand evidence per edge. The single most useful instruction: "For every dependency, cite the file and line or config key that proves it." This kills hallucinated edges and makes the audit reviewable. An ungrounded dependency map is worse than none, because people trust it.

For each dependency and each coupling finding, include an
"evidence" field quoting the exact config key, import, or
connection string. Omit any finding you cannot ground.

Grade reversibility, not just severity. A high-severity coupling that's easy to undo is a smaller problem than a medium one baked into a public contract. Ask for a reversibility note alongside each grade so the backlog ranks by effort-adjusted risk.

Separate the "god service." Ask explicitly for the service with the most inbound edges. That node is your coordination bottleneck and your single point of failure, and it rarely has a clear owner. Naming it is half the fight.

Variables you'll set

Getting started

1. Collect the directory tree plus manifests and config for the services in scope.
2. Write a one-line {{risk_focus}} so the audit has a goal.
3. Run the prompt in Claude (its long context handles a big manifest dump well).
4. Read the hidden-coupling section first; verify each finding's evidence.
5. Drop any ungrounded edge, then turn the top-5 fixes into tickets.
6. Re-run after the decoupling work to confirm the graph actually got simpler.
7. Schedule it quarterly so coupling debt stays visible.

If hand-assembling the contract isn't your idea of a good afternoon, the Cross-Service Dependency Audit pack ships the schema, the evidence rule, and the risk grading ready to run. The Service Decomposition Playbook picks up where the audit ends.

An audit is a snapshot; the work is what you do with it. Once you've graded the coupling, the monolith to microservices prompt helps sequence the extractions the audit recommends, and the technical debt triage prompt slots the decoupling fixes into the rest of your backlog so they don't get starved by feature work. Map it, grade it, then actually pay it down.