Archspec investigate: How LLMs catch inter-service conflicts before code is written

A developer checked whether an LLM can detect inter-service conflicts at the planning stage — before the first line of code. The tool is archspec with machine-readable contracts `SERVICE_MAP.yaml`, the feature is automatic task reassignment after a freelancer's refusal.

Where LLM loses inter-service context

In the first part of the cycle, the author documented a structural problem of LLM-assisted development in microservice systems. Each service individually, the model describes neatly — but when a feature passes through multiple services, the plan falls apart. The reason: rules at service boundaries — permissible statuses, call order, transition constraints — are nowhere recorded in one place.

Each service is documented locally, in isolation. The LLM sees each fragment separately, but doesn't see the system as a whole. Inter-service agreements remain implicit, and the model misses them.

The feature "task reassignment after freelancer refusal" is a good test precisely because it touches multiple services at once: task queue, notifications, billing, performer profiles. An error in any transition breaks the entire flow. It was on this feature that the plan first failed to align.

Contracts instead of free-form Markdown

The second part of the cycle introduced archspec — a tool that generates a `SERVICE_MAP.yaml` file for each service. This is not free-form text documentation for humans with descriptive passages, but a machine-readable contract: explicit constraints, permissible state transitions between states, dependencies between services, and data requirements at each transition. The difference is fundamental. Free-form Markdown is text that an LLM interprets with assumptions. `SERVICE_MAP.yaml` is structured data that a model parses deterministically. There is no room for "hallucinations" about implicit agreements. Key elements of the contract:

• Explicit input and output formats for each service
• Permissible transitions between business object statuses
• Required fields for inter-service calls
• Constraints on business logic at service boundaries

What /archspec:investigate showed

Test conditions are strict: the same prompt, the same model (Claude Sonnet 4.6), the same feature. The only difference — machine-readable contracts on top of `SERVICE_MAP.yaml` instead of free-form text.

"The same prompt, the same model.

The question is: will the plan catch those inter-service errors before code is written," — the author formulates the essence of the experiment.

With contracts, the model detected inter-service conflicts already at the planning stage — the very ones that the first time surfaced only after code was written. Formalizing boundaries gave the LLM structured context sufficient for correct transitions between services before the first line of implementation is written. But the tool had limitations. Archspec investigate works exactly as well as the contracts themselves are accurate. If `SERVICE_MAP.yaml` has fallen behind the actual code — the model plans from an outdated map and misses again. The implementation itself was also separately checked against the final plan: there, too, points were found where the code "drifted" from the intended — and this is an honest part of the research.

What this means

Spec-driven development with LLM in microservices works — but requires explicit machine-readable contracts. Without them, the model structurally loses inter-service context: this is not a matter of prompt quality or model power. Archspec is a practical way to fix this context, the tool is available on GitHub. The main limitation: maintaining `SERVICE_MAP.yaml` up to date requires manual effort — this is a separate step that needs to be embedded in the development process. Without up-to-date contracts, the tool creates false confidence instead of real help.