From e038071d9bd034958ba6b60153a737a9f690a4f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Mon, 9 Mar 2026 09:49:49 +0100 Subject: [PATCH] feat: add BDD and YAGNI semantic anchors (resolves merge conflicts from #138, #139) Content from @Nantero1's original PRs #138 and #139, rebased on current main after merging #137, #140, #142, #143. Co-Authored-By: Claude Opus 4.6 --- docs/all-anchors.adoc | 4 ++ docs/anchors/bdd-given-when-then.adoc | 48 +++++++++++++++++++ docs/anchors/yagni.adoc | 46 ++++++++++++++++++ .../references/catalog.md | 9 ++++ 4 files changed, 107 insertions(+) create mode 100644 docs/anchors/bdd-given-when-then.adoc create mode 100644 docs/anchors/yagni.adoc diff --git a/docs/all-anchors.adoc b/docs/all-anchors.adoc index bb99ab2..ed1e913 100644 --- a/docs/all-anchors.adoc +++ b/docs/all-anchors.adoc @@ -33,6 +33,8 @@ include::anchors/spot-principle.adoc[leveloffset=+2] include::anchors/ssot-principle.adoc[leveloffset=+2] +include::anchors/yagni.adoc[leveloffset=+2] + <<< == Development Workflow @@ -155,6 +157,8 @@ include::anchors/wardley-mapping.adoc[leveloffset=+2] == Testing & Quality Practices +include::anchors/bdd-given-when-then.adoc[leveloffset=+2] + include::anchors/iec-61508-sil-levels.adoc[leveloffset=+2] include::anchors/mutation-testing.adoc[leveloffset=+2] diff --git a/docs/anchors/bdd-given-when-then.adoc b/docs/anchors/bdd-given-when-then.adoc new file mode 100644 index 0000000..135d0d8 --- /dev/null +++ b/docs/anchors/bdd-given-when-then.adoc @@ -0,0 +1,48 @@ += BDD (Behavior-Driven Development) +:categories: testing-quality +:roles: software-developer, qa-engineer, business-analyst, product-owner +:proponents: Dan North +:related: tdd-london-school, tdd-chicago-school, user-story-mapping +:tags: bdd, gherkin, cucumber, specification-by-example, three-amigos, given-when-then, living-documentation + +[%collapsible] +==== +Also known as:: Specification by Example, Executable Specifications + +[discrete] +== *Core Concepts*: + +Given-When-Then:: Structured scenario format — Given a precondition, When an action occurs, Then an expected outcome results + +Specification by Example:: Concrete examples as executable specifications that define system behavior + +Three Amigos:: Collaborative discovery sessions between developer, tester, and business representative + +Gherkin syntax:: Domain-specific language for writing human-readable, machine-executable scenarios + +Living documentation:: Tests that serve as always-current system documentation + +Outside-in specification:: Start from desired business behavior, work inward to implementation + +Ubiquitous language:: Shared vocabulary bridging technical and business stakeholders in scenarios + +Discovery workshops:: Structured conversations to uncover requirements through examples before implementation + + +Key Proponent:: Dan North ("Introducing BDD", 2006), creator of JBehave which influenced Cucumber's design (Cucumber created by Aslak Hellesøy, 2008) + +[discrete] +== *When to Use*: + +* Cross-functional teams needing shared understanding of requirements +* Systems where business rules are complex and need clear documentation +* Projects requiring executable acceptance criteria +* Bridging communication gaps between technical and non-technical stakeholders + +[discrete] +== *Related Anchors*: + +* <> - Outside-in development approach that complements BDD +* <> - Developer-focused TDD practice +* <> - Requirements discovery that feeds BDD scenarios +==== diff --git a/docs/anchors/yagni.adoc b/docs/anchors/yagni.adoc new file mode 100644 index 0000000..68d4a5b --- /dev/null +++ b/docs/anchors/yagni.adoc @@ -0,0 +1,46 @@ += YAGNI (You Aren't Gonna Need It) +:categories: design-principles +:roles: software-developer, software-architect, consultant +:proponents: Ron Jeffries, Kent Beck +:related: dry-principle, spot-principle, tdd-chicago-school +:tags: yagni, extreme-programming, simplicity, incremental-design, over-engineering + +[%collapsible] +==== +Full Name:: You Aren't Gonna Need It + +[discrete] +== *Core Concepts*: + +Don't build for hypothetical futures:: Only implement functionality when it is actually needed, not when you foresee it might be needed + +Speculative generality:: Anti-pattern of building abstractions for imagined future requirements that may never materialize + +Incremental design:: Let design emerge through actual needs; evolve architecture as requirements become concrete + +Cost of carry:: Unused code adds maintenance burden, increases complexity, and creates cognitive load for the entire team + +Delete dead code:: Aggressively remove code that no longer serves a current purpose + +Extreme Programming origin:: Core XP practice alongside TDD, refactoring, and continuous integration + +Reversibility:: Prefer simple, changeable decisions over premature commitments to complex solutions + + +Key Proponents:: Ron Jeffries (coined the phrase), Kent Beck ("Extreme Programming Explained", 1999) + +[discrete] +== *When to Use*: + +* Fighting over-engineering and premature abstraction +* Agile projects with iterative delivery and evolving requirements +* Refactoring legacy systems burdened with unused features +* When tempted to add "just in case" functionality or configurability + +[discrete] +== *Related Anchors*: + +* <> - Eliminates duplication of existing knowledge (complementary but distinct) +* <> - Single Point of Truth, related simplicity principle +* <> - YAGNI is a core principle of classicist TDD +==== diff --git a/skill/semantic-anchor-translator/references/catalog.md b/skill/semantic-anchor-translator/references/catalog.md index 9bea58c..8d0e59b 100644 --- a/skill/semantic-anchor-translator/references/catalog.md +++ b/skill/semantic-anchor-translator/references/catalog.md @@ -14,6 +14,11 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors - **Proponents:** Kent Beck, Martin Fowler - **Core:** State-based testing, real objects over mocks, refactoring-focused +### BDD (Behavior-Driven Development) +- **Also known as:** Specification by Example, Executable Specifications +- **Proponents:** Dan North +- **Core:** Given-When-Then scenarios, Gherkin syntax, three amigos, living documentation, outside-in specification + ### Test Double (Meszaros) - **Proponents:** Gerard Meszaros - **Core:** Taxonomy of test substitutes — Dummy (unused), Stub (canned responses), Spy (records calls), Mock (verifies interactions), Fake (simplified implementation) @@ -86,6 +91,10 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors ### SSOT (Single Source of Truth) - **Core:** One system is the master for specific data +### YAGNI (You Aren't Gonna Need It) +- **Proponents:** Ron Jeffries, Kent Beck +- **Core:** Don't build for hypothetical futures, speculative generality anti-pattern, incremental design, delete dead code + ### GoF Design Patterns - **Also known as:** Design Patterns, Gang of Four Patterns - **Proponents:** Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides