Agent WranglersARC-85Recommended
Split off a service only for a written reason
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.
How to do it
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 and bounded contexts, 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 says. Record each split in a decision record, as Build only what is needed now asks of every abstraction.
How to 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.
Related rules
- ARC-63 Point dependencies inward in Clean code and architecture
- ARC-74 Give each bounded context its own model and words in Clean code and architecture
- SCL-10 Run web and worker processes apart in Scaling
- DOC-10 Number decision records and link each one from the code it governs in Documentation
- ARC-48 Build only what is needed now in Clean code and architecture
- ARC-87 Check each architecture decision with a fitness function in Clean code and architecture
For agents: this playbook is free to use under CC 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.