Overview
Effective software development is connected, contract-first, semi-automated and agile. It embodies a UX-first, a test-first, a contract-first and an API-first attitude, and a patterns-oriented design. It uses techniques and rituals that connect various specialists — end-users, UX designers, domain experts, software developers, architects, quality engineers, product owners and operations engineers. Ultimately, AI serves as a booster and an enabler of automation.
High-quality software is essential for sustainable design, low maintenance costs, fast delivery, and a positive developer experience.
Software craftsmanship makes us question the relevance of a line of code, its purpose, its location, its testability and its durability. On a larger scale, it guides us towards a sustainable and easily extensible design without technical debt.
This hub is where that development takes place.
The two questions
Section titled “The two questions”Everything below serves one of two questions, and a team is only effective when it is asking both.
To do the right thing — correctness and completeness. Is this what the user needs, and does it hold in every case that matters? Answered from outside the software, by the people who will live with it.
To do the thing right — good code and good design, driving towards low maintenance costs and towards software the next person can understand and estimate without guessing, carrying no technical debt. Answered from inside, and it is where economy and developer experience turn out to be one concern rather than two competing ones.
Neither survives alone: the right thing built wrong dies of its next feature, and the thing right built on the wrong thing is deleted. The process follows both questions through every activity, from inception to a running cluster.
The four properties
Section titled “The four properties”Each is a claim about how the work is organised, not about how it feels.
| Property | What it means here |
|---|---|
| Connected | The specialists talk to each other during the work, not through documents produced after it. That is what the practices are: named, repeatable conversations with a defined output. |
| Contract-first | Every boundary is written down and agreed before it is implemented, and the agreement is machine-checkable. It is both a disposition and a practice; see also API-first. |
| Semi-automated | Everything mechanical is generated, scaffolded or retro-engineered. Everything that requires a decision stays human. See MCP. |
| Agile | Short cycles with real feedback at the end of each one — which only works if the previous three properties hold, because otherwise the feedback arrives too late to act on. |
Semi-automated is the deliberate word. Full automation of a design activity produces plausible output with nobody accountable for it; no automation wastes people on work a machine does better. The line between them is the thing worth arguing about, and it is drawn per task rather than once.
The four attitudes
Section titled “The four attitudes”Each has a page of its own under attitudes. They are separated from the practices because a practice is a ritual with participants and an output, while an attitude is what someone brings to it — and is what decides whether the ritual produces anything.
They are also a chain rather than a list, with contract-first as the hinge: user-first produces contracts, test-first consumes them. A need is discovered, the need becomes a promise, the promise becomes a failing build. API-first is where the first two overlap.
User-first (UX-first) means the journey of the person using the software is the first artefact, ahead of the architecture, and is still first-class while the thing is being built. It is the cheapest moment to find out that what is being built is the wrong thing.
Test-first means deciding how a component could be shown to be wrong before deciding what it looks like. Not to catch bugs, which is a side effect — the test is the code’s first caller, so if it is painful to write, the design is telling you something while it is still cheap to listen. Testing is a design method, and an under-evaluated one.
Contract-first means deciding what each side of a boundary promises before either side is built. The question it puts first — if I change this, who finds out, and when? — is a design question about coupling and ownership, and a contract is the rare design artefact a machine can disagree with. It spans five kinds of agreement — UX, functional, non-functional, API and architecture — of which only the API one has an obvious file format, and written first each becomes an executable input: that is what makes contract-driven development and testing possible. It is the attitude behind the property of the same name two sections above: the property is the claim, this is the disposition that produces it, and the practice is the ritual that enforces it.
API-first is that attitude at the one boundary whose other side is a person: the interface is the product, and the implementation behind it is the replaceable part. It is where contract-first meets user-first, because an API’s user is a developer — and a governed, versioned, conformance-tested interface nobody can figure out passes every check a pipeline runs while failing the only one its consumer applies.
Patterns-oriented design
Section titled “Patterns-oriented design”A pattern is a shared vocabulary for a problem you already have. It is not a shelf to shop from, and reaching for one before you have the problem is how codebases acquire layers nobody can justify. The code design section carries the five catalogues — GoF, tactical DDD, architecture, integration and use case — each with the forces that make it the right answer, and the cost of choosing it when it is not.
One of them reaches further than the rest. Domain-driven design decides not only how the code is arranged but what it is called: the class names, the method names and the package tree come from the language the business already speaks. That is why it appears twice — as a practice, for the boundaries it draws, and as a pattern catalogue, for what a developer types because of them.
Where AI sits
Section titled “Where AI sits”Last, and on purpose. AI multiplies whatever discipline it finds: a codebase with contracts and tests gets faster, and a codebase without them gets a larger mess sooner. Its place here is scaffolding from known patterns, generating and retro-engineering models, and drafting an API design that a human then decides on — the MCP section is exactly that list.
How this hub is organised
Section titled “How this hub is organised”- The process — the two questions, and how the artefacts connect from inception to delivery on a cluster.
- Attitudes — test-first, user-first, contract-first and API-first, the four dispositions the practices express.
- Practices — the thirteen rituals that connect specialists.
- Stacks — the same practices and patterns expressed on the six technology stacks, where the advice has to name a framework.
- Code design — the five pattern catalogues.
- Testing tools — what enforces contract-first, API-first and ATDD, rather than merely describing them.
- MCP — the five model-driven tools that carry the automated half.
- Catalog — everything to look up rather than read: APIs, C4 models, events and components.
- Academy — seven learning paths through all of it.
What is here today
Section titled “What is here today”This portal is a scaffold. The documentation sections above are written; the MCP servers they describe are not built, the Academy lessons are not recorded, and the stack pages are outlines rather than worked guides — each says so on its own page.
Four catalogues are real, because they are not built here: the API catalogue is api-hub, and the C4, event and component catalogues are arch-hub modules.