diff --git a/src/docs/Ways-of-Working/Principles/Software-Design.md b/src/docs/Ways-of-Working/Principles/Software-Design.md index 08c78f4..5aad48e 100644 --- a/src/docs/Ways-of-Working/Principles/Software-Design.md +++ b/src/docs/Ways-of-Working/Principles/Software-Design.md @@ -1,6 +1,6 @@ --- title: Software design -description: SOLID, extensibility, DRY with judgment, and making change easy before making the change. +description: SOLID, extensibility, smart defaults with local overrides, DRY with judgment, and making change easy before making the change. --- # Software design @@ -19,6 +19,28 @@ Extend by adding, not by modifying what already works — the Open/Closed princi The system stays pluggable: the docs do not change when a new agent runtime is added — only a new integration layer is written. See the [Agentic Development](../Agentic-Development.md) specification for how this plays out in practice. +## Smart defaults, local overrides + +The default is the smart, secure choice — what you would pick most of the time, and the safe option when unsure. A system with no configuration is already correct, safe, and useful out of the box. Configuration exists to *deviate* from a good default, never to reach a usable one. + +Set the default at the broadest scope, and let each narrower scope override it. The setting closest to the thing it controls wins: + +```text +org / ecosystem the widest default — set once, inherited everywhere +└── repository may narrow the default for one codebase + └── directory may narrow it further for one area + └── item the last word — closest to what it configures +``` + +This shape is chosen for manageability over the life of a system, and it earns two properties at once: + +- **Manageable across the wide.** Change the default in one place and everything that has not opted out follows. You set the norm once instead of finding and editing many copies of it. +- **Flexible in the narrow.** Deviating is a small, local edit beside the item that needs it — not a fight with the system, and not a change that ripples outward. The exception lives with the thing it applies to. + +Make the wide default easy to set and the local override easy to make. When the two disagree, the more specific one wins — predictably, by its position in the hierarchy, never by special-casing. + +This is [Easy and Safe](../../index.md) expressed as design: doing the right thing takes no effort because it is the default, and deviating is deliberate and contained because it is a local override. [Least-privilege](Purpose-and-Direction.md#least-privilege) and [secure by default](../../Coding-Standards/Security.md#secure-by-default) are this principle applied to permissions and security; the way [the vision cascades](../../Vision/index.md#how-the-vision-cascades) is its shape applied to knowledge. + ## DRY — with judgment Don't Repeat Yourself, but **don't extract too early**. Wait until the same non-trivial logic appears in three or more places, or until the duplication is clearly load-bearing. Premature abstraction is more expensive than duplication. diff --git a/src/docs/Ways-of-Working/Principles/index.md b/src/docs/Ways-of-Working/Principles/index.md index 26afc1c..9b80264 100644 --- a/src/docs/Ways-of-Working/Principles/index.md +++ b/src/docs/Ways-of-Working/Principles/index.md @@ -15,7 +15,7 @@ Principles are grouped by theme; each theme is its own page so an agent can load | --- | --- | | [Purpose and direction](Purpose-and-Direction.md) | Why we build, who we build for, and the least-privilege stance under every decision. | | [AI-first development](AI-First-Development.md) | Agents as first-class participants, determinism before intelligence, and how humans and agents share the work. | -| [Software design](Software-Design.md) | SOLID, extensibility, DRY with judgment, and making change easy before making the change. | +| [Software design](Software-Design.md) | SOLID, extensibility, smart defaults with local overrides, DRY with judgment, and making change easy before making the change. | | [Engineering practices](Engineering-Practices.md) | Write it down, everything as code, evergreen docs, test-driven development, and shift-left quality. | | [Planning and delivery](Planning-and-Delivery.md) | Roadmapping, lean delivery, and the loops that keep iteration fast. | | [References](References.md) | The literature behind these principles. |