Skip to content

Commit d0d3cac

Browse files
raifdmuellerclaude
andcommitted
feat: add 8 verified semantic anchors
Adds eight anchors that passed verification against the catalog's quality criteria (precise, rich, consistent, attributable) plus the recognition test, each with EN + DE docs, metadata, changelog and AgentSkill catalog entries: - Conway's Law (#506) — software architecture - CAP Theorem (#508) — software architecture - Fallacies of Distributed Computing (#507) — software architecture - Law of Demeter (#509) — design principles - First Principles Thinking (#510) — problem-solving - Postel's Law / Robustness Principle (#512) — design principles - Goodhart's Law (#513) — strategic planning - Inverted Pyramid Style (#538, proposed by @mhchem) — communication Borderline proposals (Inversion #511, One sentence per line #539, TDD Hamburg School #458) and the counter-example YOLO (#443) were left out pending rework/decision. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent f0681df commit d0d3cac

23 files changed

Lines changed: 1166 additions & 135 deletions

docs/anchors/cap-theorem.adoc

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
= CAP Theorem
2+
:categories: software-architecture
3+
:roles: software-architect, data-scientist, devops-engineer
4+
:related: event-driven-architecture, fallacies-of-distributed-computing
5+
:proponents: Eric Brewer, Seth Gilbert, Nancy Lynch
6+
:tags: cap, distributed-systems, consistency, availability, partition-tolerance, pacelc
7+
:tier: 3
8+
9+
[%collapsible]
10+
====
11+
Full Name:: CAP Theorem (Consistency, Availability, Partition tolerance)
12+
13+
Also known as:: Brewer's Theorem
14+
15+
[discrete]
16+
== *Core Concepts*:
17+
18+
The three properties:: *Consistency* (every read sees the most recent write), *Availability* (every request gets a non-error response), *Partition tolerance* (the system keeps working despite dropped/delayed messages between nodes)
19+
20+
The trade-off:: When a network partition occurs, a distributed system must choose between consistency and availability — it cannot have both during the partition
21+
22+
Partitions are not optional:: Real networks partition, so P is a given; the genuine design choice is CP vs AP behaviour *while partitioned*
23+
24+
Common misreading:: "Pick 2 of 3" is a simplification; outside a partition a system can be both consistent and available
25+
26+
PACELC extension:: Else (no partition), trade Latency against Consistency — captures the everyday tuning that CAP alone omits (Abadi, 2012)
27+
28+
Key Proponents:: Eric Brewer (2000 conjecture, PODC keynote); formally proved by Seth Gilbert & Nancy Lynch (2002); PACELC by Daniel Abadi (2012)
29+
30+
[discrete]
31+
== *When to Use*:
32+
33+
* Choosing or evaluating a distributed datastore (CP vs AP behaviour)
34+
* Framing a concrete consistency/availability trade-off for a feature
35+
* Reasoning about behaviour during network partitions and failover
36+
* Explaining why strong consistency costs availability or latency
37+
38+
[discrete]
39+
== *When NOT to Use*:
40+
41+
* For single-node systems with no replication (no partitions to tolerate)
42+
* As a crude "2 of 3" slogan — prefer the partition-time framing or PACELC
43+
44+
[discrete]
45+
== *Related Anchors*:
46+
47+
* <<event-driven-architecture,Event-Driven Architecture>> — eventual consistency as an AP design choice
48+
* <<fallacies-of-distributed-computing,Fallacies of Distributed Computing>> — the network assumptions CAP makes explicit
49+
====

docs/anchors/cap-theorem.de.adoc

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
= CAP Theorem
2+
:categories: software-architecture
3+
:roles: software-architect, data-scientist, devops-engineer
4+
:related: event-driven-architecture, fallacies-of-distributed-computing
5+
:proponents: Eric Brewer, Seth Gilbert, Nancy Lynch
6+
:tags: cap, distributed-systems, consistency, availability, partition-tolerance, pacelc
7+
:tier: 3
8+
9+
[%collapsible]
10+
====
11+
Vollständiger Name:: CAP-Theorem (Consistency, Availability, Partition tolerance)
12+
13+
Auch bekannt als:: Brewers Theorem
14+
15+
[discrete]
16+
== *Kernkonzepte*:
17+
18+
Die drei Eigenschaften:: *Consistency* (jeder Read sieht den letzten Write), *Availability* (jede Anfrage erhält eine Nicht-Fehler-Antwort), *Partition tolerance* (das System arbeitet trotz verlorener/verzögerter Nachrichten zwischen Knoten weiter)
19+
20+
Der Trade-off:: Bei einer Netzwerkpartition muss ein verteiltes System zwischen Consistency und Availability wählen — während der Partition geht nicht beides
21+
22+
Partitionen sind nicht optional:: Reale Netze partitionieren, also ist P gesetzt; die eigentliche Designwahl ist CP- vs. AP-Verhalten *während* der Partition
23+
24+
Häufiges Missverständnis:: „2 von 3 wählen" ist eine Vereinfachung; ohne Partition kann ein System gleichzeitig konsistent und verfügbar sein
25+
26+
PACELC-Erweiterung:: Else (keine Partition) Latency gegen Consistency abwägen — bildet das alltägliche Tuning ab, das CAP allein auslässt (Abadi, 2012)
27+
28+
Key Proponents:: Eric Brewer (Vermutung 2000, PODC-Keynote); formal bewiesen von Seth Gilbert & Nancy Lynch (2002); PACELC von Daniel Abadi (2012)
29+
30+
[discrete]
31+
== *Verwendung*:
32+
33+
* Auswahl/Bewertung eines verteilten Datenspeichers (CP- vs. AP-Verhalten)
34+
* Konkreter Consistency-/Availability-Trade-off für ein Feature
35+
* Verhalten bei Netzwerkpartitionen und Failover durchdenken
36+
* Erklären, warum starke Konsistenz Verfügbarkeit oder Latenz kostet
37+
38+
[discrete]
39+
== *Nicht verwenden*:
40+
41+
* Für Ein-Knoten-Systeme ohne Replikation (keine Partitionen zu tolerieren)
42+
* Als plumpe „2 von 3"-Parole — besser die Partitions-Sicht oder PACELC
43+
44+
[discrete]
45+
== *Verwandte Anker*:
46+
47+
* <<event-driven-architecture,Event-Driven Architecture>> — Eventual Consistency als AP-Designwahl
48+
* <<fallacies-of-distributed-computing,Fallacies of Distributed Computing>> — die Netzannahmen, die CAP explizit macht
49+
====

docs/anchors/conways-law.adoc

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
= Conway's Law
2+
:categories: software-architecture
3+
:roles: software-architect, team-lead, product-owner, consultant
4+
:related: domain-driven-design, cohesion-criteria, vertical-slice-architecture
5+
:proponents: Melvin E. Conway
6+
:tags: conways-law, organization, architecture, team-topologies, communication-structure, sociotechnical
7+
:tier: 3
8+
9+
[%collapsible]
10+
====
11+
Full Name:: Conway's Law
12+
13+
Also known as:: The Mirroring Hypothesis
14+
15+
[discrete]
16+
== *Core Concepts*:
17+
18+
Homomorphic force:: "Any organization that designs a system will produce a design whose structure is a copy of the organization's communication structure" — system boundaries mirror team boundaries
19+
20+
Communication paths:: Interfaces in the software appear wherever two teams must coordinate; the cost and friction of cross-team communication shapes where modules are split
21+
22+
Inverse Conway Maneuver:: Deliberately structure teams to match the desired architecture, rather than letting an accidental org chart dictate the system
23+
24+
Team Topologies:: Modern operationalization (Skelton & Pais) — stream-aligned, platform, enabling, and complicated-subsystem teams sized for a manageable cognitive load
25+
26+
Sociotechnical view:: Architecture is not purely technical; org design and system design are two sides of the same decision
27+
28+
Key Proponents:: Melvin E. Conway ("How Do Committees Invent?", Datamation 1968); popularized by Fred Brooks ("The Mythical Man-Month"); modern form in Matthew Skelton & Manuel Pais ("Team Topologies", 2019)
29+
30+
[discrete]
31+
== *When to Use*:
32+
33+
* Planning team structure for a new system or a re-architecture
34+
* Diagnosing why module boundaries are awkward or why integration is painful
35+
* Justifying microservice/bounded-context splits along team lines
36+
* Reviewing whether the org chart is fighting the intended architecture
37+
38+
[discrete]
39+
== *When NOT to Use*:
40+
41+
* As a deterministic prediction — it is a strong tendency, not a law of physics
42+
* For tiny single-team systems where there is only one communication path
43+
44+
[discrete]
45+
== *Related Anchors*:
46+
47+
* <<domain-driven-design,Domain-Driven Design>> — bounded contexts as team-aligned boundaries
48+
* <<cohesion-criteria,Cohesion Criteria>> — module cohesion that team boundaries should respect
49+
* <<vertical-slice-architecture,Vertical Slice Architecture>> — slices that map to stream-aligned teams
50+
====

docs/anchors/conways-law.de.adoc

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
= Conway's Law
2+
:categories: software-architecture
3+
:roles: software-architect, team-lead, product-owner, consultant
4+
:related: domain-driven-design, cohesion-criteria, vertical-slice-architecture
5+
:proponents: Melvin E. Conway
6+
:tags: conways-law, organization, architecture, team-topologies, communication-structure, sociotechnical
7+
:tier: 3
8+
9+
[%collapsible]
10+
====
11+
Vollständiger Name:: Conway's Law (Gesetz von Conway)
12+
13+
Auch bekannt als:: Mirroring-Hypothese
14+
15+
[discrete]
16+
== *Kernkonzepte*:
17+
18+
Homomorphe Kraft:: „Organisationen, die Systeme entwerfen, bringen Entwürfe hervor, deren Struktur die Kommunikationsstruktur der Organisation abbildet" — Systemgrenzen spiegeln Teamgrenzen
19+
20+
Kommunikationspfade:: Schnittstellen in der Software entstehen dort, wo zwei Teams sich abstimmen müssen; Kosten und Reibung der teamübergreifenden Kommunikation bestimmen, wo Module getrennt werden
21+
22+
Inverse Conway Maneuver:: Teams gezielt nach der gewünschten Architektur schneiden, statt ein zufälliges Org-Chart das System bestimmen zu lassen
23+
24+
Team Topologies:: Moderne Ausprägung (Skelton & Pais) — stream-aligned, platform, enabling und complicated-subsystem Teams, dimensioniert auf eine bewältigbare kognitive Last
25+
26+
Soziotechnische Sicht:: Architektur ist nicht rein technisch; Organisations- und Systemdesign sind zwei Seiten derselben Entscheidung
27+
28+
Key Proponents:: Melvin E. Conway („How Do Committees Invent?", Datamation 1968); popularisiert durch Fred Brooks („The Mythical Man-Month"); moderne Form bei Matthew Skelton & Manuel Pais („Team Topologies", 2019)
29+
30+
[discrete]
31+
== *Verwendung*:
32+
33+
* Planung der Teamstruktur für ein neues System oder eine Re-Architektur
34+
* Diagnose, warum Modulgrenzen ungünstig liegen oder Integration schmerzhaft ist
35+
* Begründung von Microservice-/Bounded-Context-Schnitten entlang der Teamgrenzen
36+
* Prüfung, ob das Org-Chart gegen die beabsichtigte Architektur arbeitet
37+
38+
[discrete]
39+
== *Nicht verwenden*:
40+
41+
* Als deterministische Vorhersage — es ist eine starke Tendenz, kein Naturgesetz
42+
* Für winzige Ein-Team-Systeme mit nur einem Kommunikationspfad
43+
44+
[discrete]
45+
== *Verwandte Anker*:
46+
47+
* <<domain-driven-design,Domain-Driven Design>> — Bounded Contexts als teamgerechte Grenzen
48+
* <<cohesion-criteria,Kohäsionskriterien>> — Modulkohäsion, die Teamgrenzen respektieren sollten
49+
* <<vertical-slice-architecture,Vertical Slice Architecture>> — Slices, die auf stream-aligned Teams abbilden
50+
====
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
= Fallacies of Distributed Computing
2+
:categories: software-architecture
3+
:roles: software-architect, software-developer, devops-engineer
4+
:related: cap-theorem, event-driven-architecture, hexagonal-architecture
5+
:proponents: L. Peter Deutsch, James Gosling
6+
:tags: distributed-systems, networking, reliability, latency, fallacies, resilience
7+
:tier: 3
8+
9+
[%collapsible]
10+
====
11+
Full Name:: The Eight Fallacies of Distributed Computing
12+
13+
Also known as:: Deutsch's Fallacies, Fallacies of Networked Computing
14+
15+
[discrete]
16+
== *Core Concepts*:
17+
18+
The eight false assumptions:: (1) The network is reliable. (2) Latency is zero. (3) Bandwidth is infinite. (4) The network is secure. (5) Topology doesn't change. (6) There is one administrator. (7) Transport cost is zero. (8) The network is homogeneous
19+
20+
Why it matters:: Each assumption is comfortable in local development and false in production; building on them produces systems that fail under real network conditions
21+
22+
As an audit checklist:: Invoke the list to interrogate a distributed design — for each fallacy, ask what happens when the real-world opposite is true (retries, timeouts, backpressure, encryption, service discovery, capacity limits, protocol negotiation)
23+
24+
Mitigation cues:: Reliability → retries/idempotency; latency → batching/locality; security → zero-trust; topology → service discovery; homogeneity → explicit contracts and versioning
25+
26+
Key Proponents:: L. Peter Deutsch (first seven, Sun Microsystems, c. 1994); James Gosling added the eighth ("the network is homogeneous"); early items credited to Bill Joy and Tom Lyon
27+
28+
[discrete]
29+
== *When to Use*:
30+
31+
* Reviewing or hardening a distributed/microservice design
32+
* Writing resilience requirements (timeouts, retries, circuit breakers)
33+
* Onboarding developers moving from monolith to distributed thinking
34+
* Post-incident analysis of network-related outages
35+
36+
[discrete]
37+
== *When NOT to Use*:
38+
39+
* For purely in-process, single-machine logic with no network calls
40+
* As a substitute for measuring your actual network's behaviour
41+
42+
[discrete]
43+
== *Related Anchors*:
44+
45+
* <<cap-theorem,CAP Theorem>> — the consistency/availability consequence of partitions
46+
* <<event-driven-architecture,Event-Driven Architecture>> — async patterns that assume unreliable networks
47+
* <<hexagonal-architecture,Hexagonal Architecture>> — isolating network adapters behind ports
48+
====
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
= Fallacies of Distributed Computing
2+
:categories: software-architecture
3+
:roles: software-architect, software-developer, devops-engineer
4+
:related: cap-theorem, event-driven-architecture, hexagonal-architecture
5+
:proponents: L. Peter Deutsch, James Gosling
6+
:tags: distributed-systems, networking, reliability, latency, fallacies, resilience
7+
:tier: 3
8+
9+
[%collapsible]
10+
====
11+
Vollständiger Name:: Die acht Trugschlüsse des verteilten Rechnens
12+
13+
Auch bekannt als:: Deutsch's Fallacies, Fallacies of Networked Computing
14+
15+
[discrete]
16+
== *Kernkonzepte*:
17+
18+
Die acht falschen Annahmen:: (1) Das Netzwerk ist zuverlässig. (2) Latenz ist null. (3) Bandbreite ist unendlich. (4) Das Netzwerk ist sicher. (5) Die Topologie ändert sich nicht. (6) Es gibt einen Administrator. (7) Transportkosten sind null. (8) Das Netzwerk ist homogen
19+
20+
Warum es zählt:: Jede Annahme ist in der lokalen Entwicklung bequem und in Produktion falsch; darauf aufgebaute Systeme scheitern unter realen Netzbedingungen
21+
22+
Als Audit-Checkliste:: Die Liste nutzen, um einen verteilten Entwurf zu hinterfragen — pro Fallacy fragen, was passiert, wenn das reale Gegenteil zutrifft (Retries, Timeouts, Backpressure, Verschlüsselung, Service Discovery, Kapazitätsgrenzen, Protokollverhandlung)
23+
24+
Mitigations-Hinweise:: Zuverlässigkeit → Retries/Idempotenz; Latenz → Batching/Lokalität; Sicherheit → Zero-Trust; Topologie → Service Discovery; Homogenität → explizite Contracts und Versionierung
25+
26+
Key Proponents:: L. Peter Deutsch (die ersten sieben, Sun Microsystems, ca. 1994); James Gosling ergänzte den achten („das Netzwerk ist homogen"); frühe Punkte werden Bill Joy und Tom Lyon zugeschrieben
27+
28+
[discrete]
29+
== *Verwendung*:
30+
31+
* Review oder Härtung eines verteilten/Microservice-Entwurfs
32+
* Formulieren von Resilienz-Anforderungen (Timeouts, Retries, Circuit Breaker)
33+
* Onboarding von Entwicklern vom Monolithen zum verteilten Denken
34+
* Post-Incident-Analyse netzbedingter Ausfälle
35+
36+
[discrete]
37+
== *Nicht verwenden*:
38+
39+
* Für rein In-Process-Logik auf einer Maschine ohne Netzaufrufe
40+
* Als Ersatz dafür, das Verhalten des echten Netzes zu messen
41+
42+
[discrete]
43+
== *Verwandte Anker*:
44+
45+
* <<cap-theorem,CAP Theorem>> — die Consistency-/Availability-Folge von Partitionen
46+
* <<event-driven-architecture,Event-Driven Architecture>> — Async-Muster, die unzuverlässige Netze annehmen
47+
* <<hexagonal-architecture,Hexagonal Architecture>> — Netz-Adapter hinter Ports isolieren
48+
====
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
= First Principles Thinking
2+
:categories: problem-solving
3+
:roles: software-architect, consultant, educator, product-owner
4+
:related: feynman-technique, socratic-method, five-whys
5+
:proponents: Aristotle, René Descartes
6+
:tags: first-principles, reasoning, decomposition, problem-solving, assumptions
7+
:tier: 3
8+
9+
[%collapsible]
10+
====
11+
Full Name:: First Principles Thinking
12+
13+
Also known as:: Reasoning from First Principles, Reasoning from Fundamentals
14+
15+
[discrete]
16+
== *Core Concepts*:
17+
18+
Reduce to fundamentals:: Break a problem down to the basic truths that cannot be deduced from anything more fundamental, then reason upward from those
19+
20+
Reason vs. analogy:: Contrast with reasoning by analogy ("we do it this way because that's how it's done") — first principles rebuild the answer from the ground up
21+
22+
Challenge inherited assumptions:: Each "requirement" or "constraint" is interrogated: is it a law of nature, or merely convention/legacy that can be discarded?
23+
24+
Ground-up synthesis:: After identifying the irreducible elements, recombine them into a solution unconstrained by how the problem was solved before
25+
26+
Cost of the method:: Powerful but expensive — reserve it for high-stakes or stuck problems; reasoning by analogy is fine for routine decisions
27+
28+
Key Proponents:: Rooted in Aristotle (the "first cause"/archē); sharpened by René Descartes' methodical doubt; popularized in modern engineering discourse (e.g. Elon Musk's cost-of-batteries example)
29+
30+
[discrete]
31+
== *When to Use*:
32+
33+
* A problem feels blocked because "that's just how it's done"
34+
* Re-examining requirements, cost structures, or architecture constraints
35+
* High-stakes design decisions where analogy may mislead
36+
* Teaching learners to separate fundamental truths from convention
37+
38+
[discrete]
39+
== *When NOT to Use*:
40+
41+
* Routine decisions where established patterns are good enough — the method is costly
42+
* When proven best practices already encode hard-won fundamentals
43+
44+
[discrete]
45+
== *Related Anchors*:
46+
47+
* <<feynman-technique,Feynman Technique>> — explain from fundamentals to expose gaps
48+
* <<socratic-method,Socratic Method>> — question assumptions to reach bedrock
49+
* <<five-whys,Five Whys>> — drill from symptom toward a root cause
50+
====

0 commit comments

Comments
 (0)