righting-software
Juval Löwy's "The Method" (Righting Software, 2019) as an operating procedure. Decompose a system by axes of volatility, never by functionality; classify components into the fixed taxonomy (Client, Manager, Engine, ResourceAccess, Resource, Utilities); validate by call chains; then design the project that builds it. Use when the user asks for system design, architecture review, service decomposition, "The Method", volatility-based decomposition, or asks how long/costly a build will be.
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- righting-software
- description
- Juval Löwy's "The Method" (Righting Software, 2019) as an operating procedure. Decompose a system by axes of volatility, never by functionality; classify components into the fixed taxonomy (Client, Manager, Engine, ResourceAccess, Resource, Utilities); validate by call chains; then design the project that builds it. Use when the user asks for system design, architecture review, service decomposition, "The Method", volatility-based decomposition, or asks how long/costly a build will be.
02 资源文件 1
- 资产文件assets/design_doc_template.md1.7 KB
03 SKILL.md 正文
Righting Software (The Method)
The Method is two formulas: system design + project design. The architecture is a means to an end — the end is a defensible answer to "how long will it take and how much will it cost".
The Prime Directive, from which almost everything else follows:
Never design against the requirements. Design the smallest set of components that can be composed to satisfy present and future, known and unknown requirements. When the requirements change and your design changes with them, the design added no value.
A component is justified only by the volatility it encapsulates. If you cannot name the axis of change a component absorbs, it must not exist.
1. The two forbidden decompositions
These are the failure modes the skill exists to catch. They are also the most natural things to do, which is why they win.
| What it is | Why it fails | |
|---|---|---|
| Functional decomposition | One component per required functionality (Invoicing, Billing, Shipping); components named after steps in a use case | Couples the architecture to the requirements. Change is by definition not in one place. Produces either an explosion of tiny services or god-monoliths, often both side by side. Precludes reuse — lift B and A and C hang off it. Forces the client to orchestrate, so the client becomes the system. Multiple points of entry for security, scaling, transactions. Untestable: defects live in the interactions, not the units. |
| Domain decomposition | One component per business domain (Sales, Accounting, Kitchen) | Functional decomposition in disguise. Behaviours that cross domains have nowhere to live; cross-domain communication degrades to CRUD. Each domain becomes an ugly grab bag. |
Test for functional decomposition: can you state the axis of volatility the component encapsulates in one sentence? If the answer is "it does X", it is functional.
Anti-design check. When a team insists its design is fine, run the contest: half the team produces the best design, half produces the design that maximises future pain. Compare. They are usually the same design, with different labels.
2. Volatility, not variability
Two axes, and they are independent:
- Time — for the same customer, what can change over time?
- Customers — with time frozen, what differs across customers?
Rules:
- Volatility is not variability. Something handleable with an
if/else, a flag, or a config value is variability, not volatility. Variability is a parameter; volatility is a boundary. - Watch for solutions masquerading as requirements. "The system must use a message bus" is a solution. Ask what could change, then decide whether a component is the right container.
- Design for your competitor (or another division of your company). The things you do differently are volatility. The things that are the nature of the business are not — and the nature of the business is almost never volatile. Encapsulating it is the speculating-design trap.
- Anything absent from the volatility list is assumed not volatile enough to need a component. Call out volatilities early: designating a component costs nothing now, and buys effort later.
- Volatility decreases top-down; reuse increases top-down. Clients are the most volatile, Resources the least. If the components you depend on most are also the most volatile, the system will implode.
3. The taxonomy (fixed — do not invent categories)
Every code unit belongs to exactly one category. If you cannot decide which, the unit is wrong.
| Category | Answers | Encapsulates | Notes |
|---|---|---|---|
| Client | Who interacts | Client technology, presentation, protocol, channel | A user or another system. Must not contain business logic. Single point of entry. |
| Manager | What is required | Volatility in the sequence of activities (workflow, use case) | One Manager = a family of related use cases. Holds transient workflow state only. |
| Engine | How the business logic runs | Volatility in a single activity (rules, formulas, policy) | Stateless. Strategy pattern. Shared across Managers. |
| ResourceAccess | How the system reaches data | Data-access technology | The only component allowed to touch a Resource. Exposes atomic business verbs, not CRUD. |
| Resource | Where state lives | Storage/vendor/schema | Passive. Calls nothing. No business logic in schemas, triggers, or stored procedures. |
| Utilities | Cross-cutting | Infrastructure | Security, Logging, Diagnostics, Hosting, Configuration, Localization, Pub/Sub bus, Identity. Callable from any layer. No business logic. |
Naming: <NounOfVolatility>Manager, <Gerund>Engine, <NounOfResource>Access. Atomic business
verbs belong on operations, never on service names. PricingEngine beats OrderService when
pricing is the volatility boundary.
The four questions are also the validation pass. After the design, re-ask them: is every Client pure who, with no trace of what? Is every Manager free of who and where? Overlap is a red flag — unless you can still defend the encapsulation, in which case keep it.
4. Communication rules (closed architecture)
Closed architecture trades flexibility for encapsulation. These are the sanctioned relaxations, not a licence to improvise:
- Clients call Managers only. A Client must not call multiple Managers in one use case.
- Managers call Engines and ResourceAccess, and any Utility.
- Manager → Manager is queued only (pub/sub through the bus). Never synchronous.
- Engines never call Engines. Engines never call ResourceAccess. The Manager pulls, then passes in.
- Nothing calls upward. Engines and ResourceAccess never call Clients.
- ResourceAccess is the only path to a Resource. No ORM call in a Manager, no raw SQL in an Engine.
- Never queue calls to Engines or ResourceAccess. Engines and ResourceAccess do not publish or subscribe to events.
- Between layers pass primitives, arrays of primitives, data contracts, arrays of data contracts. Logic behind a data contract does not cross a layer. Passing "entities" breaks encapsulation.
- Strive for symmetry. Use cases that call in different shapes signal a design problem worth investigating.
- When you feel you must "open up" the architecture, that is a signal you need pub/sub or queuing — not a licence to break the rule. Name the underlying need; do not dismiss the transgression.
Subsystems: group Managers, Engines, and ResourceAccess into a cohesive slice. Max 3 Managers per subsystem. A component inside a subsystem cannot be released alone — release one subsystem at a time. Do not assume each slice is a microservice; a microservice may be a group of slices.
Golden ratio (Manager : Engine). 1:(0 or 1), 2:1, 3:2, 5:3. As Managers grow, the need for Engines grows at a decelerating rate. Many Managers relative to Engines means you decomposed by function. Redesign. Order of magnitude for a whole system is ~10 components, not hundreds.
5. Workflow
- Vision → objectives → mission. Write the vision as a single sentence, legal-grade. Objectives that do not serve the vision are cut. The mission states how the work is executed. This hierarchy outranks architecture in argument; it is how you refuse irrelevant demands.
- Use cases. Separate core use cases (the essence of the business — the ones that do not change unless the nature of the business changes) from the fluff (happy, sad, incomplete paths). Use activity diagrams with swim lanes, not flowcharts.
- Volatility list. Work both axes. Mark each entry volatile or variable. Flag any entry that is really a solution.
- Map volatilities to components. Rarely 1:1 — one component may absorb several volatilities, some map to an operational concept or a third-party component. Classify each into the taxonomy.
- Validate by call chains. Take the top 4–6 distinct use cases and show them as interactions between the minimal set of components. Iterate the factoring until every conceivable use case is satisfiable by composition. Any component that appears in no call chain is unnecessary.
- Check the shape. Golden ratio, volatility decreasing top-down, reuse increasing top-down, symmetry across call chains, ≤3 Managers per subsystem.
- Allocation. Assemblies, hosts/processes (layer boundary is usually process boundary; Engines and ResourceAccess run in-proc to a Manager), identities (minimise; trusted subsystem pattern — each layer authenticates its immediate caller), authentication/authorization boundaries, transactions (start as far upstream as possible, engulf as much as possible, keep under 1 second), and logical threads of execution — any reentrant cyclic path means deadlock or a design error.
- Project design (§6) — only after the architecture exists.
6. Project design (the second half)
Project design is the assembly instruction. It derives from the architecture, not from optimism.
- Core team = project manager + product manager + architect, three roles, three people, present for the whole project. The architect owns both the system design and the project design. One architect for design integrity. One developer per service, 1:1 — anything else cannot be estimated reliably.
- Fuzzy front end is 15–25% of project duration. Nothing is committed before cost, schedule, and risk exist.
- Estimates are accurate, not precise. Quantum of 5 days. Itemise the full lifecycle of every
service: learning curve, test client, installation, integration points, peer review, documentation.
PERT:
E = (T + 4M + P) / 6. - Critical path = longest path through the activity network = the duration of the project. No project can be accelerated beyond it. Assign the best resources to the critical path first; accelerating non-critical paths accelerates nothing.
- Floats are the project's safety margin and its risk meter. Low float = high risk. Trade float for resources deliberately.
- Risk index (normalised 0–1):
Risk = (4C + 3R + 2Y + 1G) / (4N)over critical/red/yellow/green activities. Acceptable band 0.3–0.75; decompress toward 0.5. Crossover ≈ 0.75. Subcritical staffing pushes risk to ~0.9 and costs at least 25% more for 35% longer — there is no saving. - Present several options, not one plan: cheapest, fastest, safest, best combination. Points above the time-cost curve are feasible; points below it are impossible — a project committed below the curve has already failed.
- God activities (oversized, placeholder for uncertainty) must be broken up or factored out as separate projects; they distort the whole risk calculation.
7. Output artifact
Write the design as a document with these sections, in order. Template:
assets/design_doc_template.md.
- Vision, objectives, mission
- Core use cases (and the fluff, listed but not load-bearing)
- Volatility list — two axes, each entry marked volatile / variable / solution-in-disguise
- Component table — name, category, the single axis of volatility it encapsulates, what it calls
- Call chains for the top 4–6 use cases
- Allocation — assemblies, processes, identities, auth boundaries, transactions
- Unassigned volatilities and components in no call chain — see §8
- Project design options — duration, cost, risk index per option
8. The section that catches the gap
Two checks must be run against the actual document, not from memory, and reported plainly:
- Every volatility in §3 has an owner. A volatility with no component is an assumption that the change will never happen.
- Every component is in at least one call chain. A component in no call chain is decoration.
Then state whether the design is currently validatable: can the core use cases be walked as call chains with the components that exist in the document? If not, say so. A design document that lists components it never uses reads as complete and is not.
9. Gotchas
- The allure is the problem. Functional decomposition looks free. Design that costs no effort adds no value — there is no free lunch. If a decomposition could be done by a tool, it is not design.
- Volatility is not self-evident. It takes longer than functional decomposition, and it fights management. The Dunning–Kruger effect is the default state: people who cannot see the volatilities are also the people most confident their decomposition is right.
- Do not design against the requirements even when the deadline demands it. The deadline is paid for in multiples later.
- Unit testing is the streetlight effect. It is necessary and nearly useless on its own: defects live in the interactions between units, and changing one unit invalidates the others. Regression testing of interactions is the real check.
- The Method is not a silver bullet. It does not remove creativity, responsibility for getting the use cases right, or liability for getting it wrong. It mechanises the decisions so the crunch is spent on judgment, not on enumeration.
- Time crunch is load-bearing. 3–5 days, top 4–6 use cases, ~40–60 diagrams. Without the crunch you get analysis-paralysis and gold-plating.
- Boxes and arrows communicate only so much. Non-obvious decisions must be written down, with the tradeoff that produced them.
- Do not mix architectures. The taxonomy is the only one allowed in the system. Do not blend it with DDD aggregates, Clean Architecture use-case layers, hexagonal ports, onion shells, or vertical slices. If a hybrid is required, the volatility was mis-identified — fix that instead.
10. Routing
Routes here for: system design, architecture review, service decomposition, "is this decomposition right?", naming a component, validating a design against use cases, and the schedule/cost/risk question for a build.
Does not route here for: implementation (design authority is not build authority), detailed design — interfaces, class hierarchies, and idioms are below The Method and can change without touching the decomposition — coding-style review, or technology selection.
The Method mechanises design decisions. It does not make the decisions. Every component in the output must trace to a named volatility; a component with no volatility is reintroduced assumption.
Changelog
- v1.0.0 (2026-11-07) — Initial skill. Prime Directive, the two forbidden decompositions, volatile-vs-variable, the two axes, the fixed taxonomy and the four questions, closed-architecture communication rules, golden ratio and subsystem caps, call-chain validation, the mandatory unassigned-volatility / no-call-chain check, and the project-design half (core team, critical path, floats, risk index, options). Distilled from the book's chapters 2–4 plus Löwy's SDD 2022 deck and the InfoQ author interview.
04 同仓库更多 Skills
to-syllabus
Turns a topic, a fixed experienced-developer audience, and a domain into a learning syllabus and a companion technical guide. Use when someone says "syllabus this" or asks to create a learning path framed inside a domain.
to-icebox
Transforms a stream of thoughts, rough conversation, or scattered ideas into a structured feature request document. Use when someone says "icebox this".
documentation-writer
Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.
defensive-architecture-pr-review
Reviews pull request diffs against a legacy codebase using Juval Löwys Volatility-Based Decomposition (The Method). Detects architectural decay, leakage of business-rule volatility, and boundary infractions