---
title: "Split off a service only for a written · Agent Wranglers"
url: https://agentwranglers.se/playbook/architecture/structure/split-services-for-a-reason
id: ARC-85
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 913
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Split off a service only for a written reason

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Structure](https://agentwranglers.se/playbook/architecture/structure.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: ARC-85
- Level: Recommended
- Chapter: [Structure](https://agentwranglers.se/playbook/architecture/structure.md)
- Rule: Keep the product as one deployable app made of modules until a written reason needs a separate service. The reasons are a separate team that owns it, a different scaling need or a different security boundary.
- Check: Every separately deployed service in the repository links a decision record that names one of the three reasons. The module dependency check passes inside the main app.
- How: Each service adds network calls that can fail, a deploy, logs to join and data to keep in step. A small team pays that cost without a gain. Draw module borders inside the app first, with [Point dependencies inward](https://agentwranglers.se/playbook/architecture/structure/layers-point-inward.md) and [bounded contexts](https://agentwranglers.se/playbook/architecture/domain-model/bounded-contexts.md), and check them in the build. A module with clean borders can move out later without a rewrite. Slow work often fits a worker process of the same app, as [Run web and worker processes apart](https://agentwranglers.se/playbook/scaling/stateless-app-servers/web-and-worker-processes.md) says. Record each split in a [decision record](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/linked-decision-records.md), as [Build only what is needed now](https://agentwranglers.se/playbook/architecture/solid-and-dry/no-speculative-abstraction.md) asks of every abstraction.

## Related rules

- ARC-63 [Point dependencies inward](https://agentwranglers.se/playbook/architecture/structure/layers-point-inward.md) in Clean code and architecture
- ARC-74 [Give each bounded context its own model and words](https://agentwranglers.se/playbook/architecture/domain-model/bounded-contexts.md) in Clean code and architecture
- SCL-10 [Run web and worker processes apart](https://agentwranglers.se/playbook/scaling/stateless-app-servers/web-and-worker-processes.md) in Scaling
- DOC-10 [Number decision records and link each one from the code it governs](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/linked-decision-records.md) in Documentation
- ARC-48 [Build only what is needed now](https://agentwranglers.se/playbook/architecture/solid-and-dry/no-speculative-abstraction.md) in Clean code and architecture
- ARC-87 [Check each architecture decision with a fitness function](https://agentwranglers.se/playbook/architecture/system-architecture/fitness-functions.md) in Clean code and architecture

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/architecture/structure/split-services-for-a-reason">Agent Wranglers clean code and architecture playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Keep generated code apart and never edit it by hand](https://agentwranglers.se/playbook/architecture/structure/generated-code-apart.md)
- Next: [Delete code that nothing uses](https://agentwranglers.se/playbook/architecture/structure/delete-unused-code.md)
- [Structure](https://agentwranglers.se/playbook/architecture/structure.md)