├── LICENSE └── README.adoc /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.adoc: -------------------------------------------------------------------------------- 1 | = Semantic Anchors for LLMs 2 | :toc: left 3 | :toclevels: 3 4 | :sectnums: 5 | :icons: font 6 | :experimental: 7 | 8 | == Introduction to Semantic Anchors 9 | 10 | Semantic anchors are well-defined terms, methodologies, or frameworks that serve as reference points in communication with Large Language Models (LLMs). They act as shared vocabulary that triggers specific, contextually rich knowledge domains within the LLM's training data. 11 | 12 | === Why Semantic Anchors Matter 13 | 14 | When working with LLMs like Claude, using semantic anchors provides several advantages: 15 | 16 | * *Precision*: Anchors reduce ambiguity by referencing established bodies of knowledge 17 | * *Efficiency*: A single anchor term can activate complex conceptual frameworks without lengthy explanations 18 | * *Consistency*: Well-known anchors ensure the LLM interprets concepts as intended by the broader community 19 | * *Context Compression*: Anchors allow you to convey rich context with minimal tokens 20 | 21 | === How to Use Semantic Anchors Effectively 22 | 23 | . *Be Specific*: Use the full, precise name of methodologies (e.g., "TDD, London School" rather than just "mocking") 24 | . *Combine Anchors*: Reference multiple anchors to triangulate your meaning 25 | . *Verify Understanding*: Ask the LLM to explain its interpretation when precision is critical 26 | . *Update Over Time*: As new methodologies emerge, incorporate them into your anchor vocabulary 27 | 28 | == Semantic Anchor Catalog 29 | 30 | Below is a curated list of semantic anchors useful for software development, architecture, and requirements engineering. Each anchor includes related concepts and practices. 31 | 32 | The catalog is organized into the following categories: 33 | 34 | * <> 35 | * <> 36 | * <> 37 | * <> 38 | * <> 39 | * <> 40 | * <> 41 | 42 | [[testing-quality-practices]] 43 | === Testing & Quality Practices 44 | 45 | [[tdd-london-school]] 46 | ==== TDD, London School 47 | 48 | [%collapsible] 49 | ==== 50 | *Also known as*: Mockist TDD, Outside-In TDD 51 | 52 | *Core Concepts*: 53 | 54 | * *Mock-heavy testing*: Heavy use of test doubles (mocks, stubs) to isolate units 55 | * *Outside-in development*: Start from the outermost layers (UI, API) and work inward 56 | * *Interaction-based testing*: Focus on verifying interactions between objects 57 | * *Behavior verification*: Test how objects collaborate rather than state 58 | * *Interface discovery*: Use tests to discover and define interfaces 59 | * *Walking skeleton*: Build end-to-end functionality early, then fill in details 60 | 61 | *Key Proponents*: Steve Freeman, Nat Pryce ("Growing Object-Oriented Software, Guided by Tests") 62 | 63 | *When to Use*: 64 | 65 | * Complex systems with many collaborating objects 66 | * When designing APIs and interfaces 67 | * Distributed systems where integration is costly 68 | ==== 69 | 70 | [[tdd-chicago-school]] 71 | ==== TDD, Chicago School 72 | 73 | [%collapsible] 74 | ==== 75 | *Also known as*: Classicist TDD, Detroit School 76 | 77 | *Core Concepts*: 78 | 79 | * *State-based testing*: Verify the state of objects after operations 80 | * *Minimal mocking*: Use real objects whenever possible; mock only external dependencies 81 | * *Inside-out development*: Start with core domain logic and build outward 82 | * *Simplicity focus*: Emergent design through refactoring 83 | * *Red-Green-Refactor*: The fundamental TDD cycle 84 | * *YAGNI*: You Aren't Gonna Need It - avoid premature abstraction 85 | 86 | *Key Proponents*: Kent Beck, Martin Fowler 87 | 88 | *When to Use*: 89 | 90 | * Domain-driven design projects 91 | * When business logic is central 92 | * Smaller, cohesive modules 93 | ==== 94 | 95 | [[property-based-testing]] 96 | ==== Property-Based Testing 97 | 98 | [%collapsible] 99 | ==== 100 | *Also known as*: Generative Testing, QuickCheck-style Testing 101 | 102 | *Core Concepts*: 103 | 104 | * *Properties*: Invariants that should always hold 105 | * *Generators*: Automatic test data creation 106 | * *Shrinking*: Minimizing failing test cases to simplest form 107 | * *Universal quantification*: Testing "for all inputs" 108 | * *Specification testing*: Testing high-level properties, not examples 109 | * *Edge case discovery*: Finds cases you didn't think of 110 | * *Complementary to example-based*: Works alongside traditional unit tests 111 | * *Stateful testing*: Testing sequences of operations 112 | * *Model-based testing*: Compare implementation against simpler model 113 | 114 | *Key Tools*: QuickCheck (Haskell), Hypothesis (Python), fast-check (JavaScript), FsCheck (.NET) 115 | 116 | *When to Use*: 117 | 118 | * Testing pure functions and algorithms 119 | * Validating business rules and invariants 120 | * Testing parsers and serializers 121 | * Finding edge cases in complex logic 122 | * Complementing example-based TDD 123 | ==== 124 | 125 | [[testing-pyramid]] 126 | ==== Testing Pyramid 127 | 128 | [%collapsible] 129 | ==== 130 | *Full Name*: Testing Pyramid according to Mike Cohn 131 | 132 | *Core Concepts*: 133 | 134 | * *Three layers*: 135 | ** *Unit tests* (base): Many fast, isolated tests 136 | ** *Integration tests* (middle): Moderate number, test component interaction 137 | ** *End-to-end tests* (top): Few, test complete user journeys 138 | * *Proportional distribution*: More unit tests, fewer E2E tests 139 | * *Cost and speed*: Unit tests cheap and fast, E2E tests expensive and slow 140 | * *Feedback loops*: Faster feedback from lower levels 141 | * *Anti-pattern: Ice cream cone*: Too many E2E tests, too few unit tests 142 | * *Test at the right level*: Don't test through UI what can be tested in isolation 143 | * *Confidence gradient*: Balance confidence with execution speed 144 | 145 | *Key Proponent*: Mike Cohn ("Succeeding with Agile", 2009) 146 | 147 | *When to Use*: 148 | 149 | * Planning test strategy for projects 150 | * Balancing test types in CI/CD pipelines 151 | * Evaluating existing test suites 152 | * Guiding team testing practices 153 | ==== 154 | 155 | [[mutation-testing]] 156 | ==== Mutation Testing 157 | 158 | [%collapsible] 159 | ==== 160 | *Also known as*: Mutation Analysis, Fault-Based Testing 161 | 162 | *Core Concepts*: 163 | 164 | * *Test quality assessment*: Evaluate how effective tests are at detecting bugs 165 | * *Code mutations*: Deliberately introduce small, syntactic changes (mutants) into source code 166 | * *Mutation operators*: Rules for creating mutants (e.g., change `>` to `>=`, flip boolean, remove statement) 167 | * *Killed mutants*: Mutations caught by failing tests (good) 168 | * *Survived mutants*: Mutations not detected by tests (indicates test weakness) 169 | * *Equivalent mutants*: Mutations that don't change program behavior (false positives) 170 | * *Mutation score*: Percentage of killed mutants: `(killed / (total - equivalent)) × 100%` 171 | * *First-order mutations*: Single atomic change per mutant 172 | * *Higher-order mutations*: Multiple changes combined 173 | * *Weak mutation*: Test only needs to create different internal state 174 | * *Strong mutation*: Test must produce different final output 175 | * *Test adequacy criterion*: "Are tests good enough?" not just "Is coverage high enough?" 176 | 177 | *Key Proponents*: Richard Lipton (theoretical foundation, 1971), Richard DeMillo, Timothy Budd 178 | 179 | *Key Tools*: 180 | 181 | * PITest (Java) 182 | * Stryker (JavaScript/TypeScript, C#, Scala) 183 | * Mutmut (Python) 184 | * Infection (PHP) 185 | * Mull (C/C++) 186 | 187 | *When to Use*: 188 | 189 | * Evaluating test suite quality beyond coverage metrics 190 | * Identifying gaps in test assertions 191 | * Critical systems requiring high test confidence 192 | * Complementing code coverage as a quality metric 193 | * Refactoring legacy code with existing tests 194 | * Teaching effective testing practices 195 | * Continuous improvement of test effectiveness 196 | 197 | *Practical Challenges*: 198 | 199 | * *Computational cost*: N mutations × M tests = expensive 200 | * *Equivalent mutant problem*: Hard to automatically detect functionally identical mutants 201 | * *Time investment*: Can be slow on large codebases 202 | * *Mitigation strategies*: Selective mutation, mutation sampling, incremental analysis 203 | 204 | *Relationship to Other Practices*: 205 | 206 | * *Code coverage*: Mutation testing reveals that high coverage ≠ good tests 207 | * *TDD*: Strong TDD often produces high mutation scores naturally 208 | * *Property-based testing*: Orthogonal but complementary approaches 209 | * *Fault injection*: Similar concept applied to production systems 210 | ==== 211 | 212 | [[architecture-design]] 213 | === Architecture & Design 214 | 215 | [[arc42]] 216 | ==== arc42 217 | 218 | [%collapsible] 219 | ==== 220 | *Full Name*: arc42 Architecture Documentation Template 221 | 222 | *Core Concepts*: 223 | 224 | * *12 standardized sections*: From introduction to glossary 225 | * *Section 1*: Introduction and Goals 226 | * *Section 2*: Constraints 227 | * *Section 3*: Context and Scope 228 | * *Section 4*: Solution Strategy 229 | * *Section 5*: Building Block View 230 | * *Section 6*: Runtime View 231 | * *Section 7*: Deployment View 232 | * *Section 8*: Crosscutting Concepts 233 | * *Section 9*: Architecture Decisions 234 | * *Section 10*: Quality Requirements 235 | * *Section 11*: Risks and Technical Debt 236 | * *Section 12*: Glossary 237 | * *Pragmatic documentation*: Document only what's necessary 238 | * *Multiple formats*: AsciiDoc, Markdown, Confluence, etc. 239 | 240 | *Key Proponents*: Gernot Starke, Peter Hruschka 241 | 242 | *When to Use*: 243 | 244 | * Medium to large software projects 245 | * When stakeholder communication is critical 246 | * Long-lived systems requiring maintainability 247 | ==== 248 | 249 | [[adr-according-to-nygard]] 250 | ==== ADR according to Nygard 251 | 252 | [%collapsible] 253 | ==== 254 | *Full Name*: Architecture Decision Records according to Michael Nygard 255 | 256 | *Core Concepts*: 257 | 258 | * *Lightweight documentation*: Short, focused records 259 | * *Standard structure*: 260 | ** Title 261 | ** Status (proposed, accepted, deprecated, superseded) 262 | ** Context (forces at play) 263 | ** Decision (what was chosen) 264 | ** Consequences (both positive and negative) 265 | * *Immutability*: ADRs are never deleted, only superseded 266 | * *Version control*: ADRs stored with code 267 | * *Decision archaeology*: Understanding why past decisions were made 268 | * *Evolutionary architecture*: Supporting architecture that changes over time 269 | 270 | *Key Proponent*: Michael Nygard 271 | 272 | *When to Use*: 273 | 274 | * All software projects (low overhead, high value) 275 | * Distributed teams needing shared understanding 276 | * When onboarding new team members 277 | * Complex systems with evolving architecture 278 | ==== 279 | 280 | [[c4-diagrams]] 281 | ==== C4-Diagrams 282 | 283 | [%collapsible] 284 | ==== 285 | *Full Name*: C4 Model for Software Architecture Diagrams 286 | 287 | *Core Concepts*: 288 | 289 | * *Four levels of abstraction*: 290 | ** *Level 1 - Context*: System in its environment (users, external systems) 291 | ** *Level 2 - Container*: Applications and data stores that make up the system 292 | ** *Level 3 - Component*: Components within containers 293 | ** *Level 4 - Code*: Class diagrams, entity relationships (optional) 294 | * *Zoom in/out*: Progressive disclosure of detail 295 | * *Simple notation*: Boxes and arrows, minimal notation overhead 296 | * *Audience-appropriate*: Different diagrams for different stakeholders 297 | * *Supplementary diagrams*: Deployment, dynamic views, etc. 298 | 299 | *Key Proponent*: Simon Brown 300 | 301 | *When to Use*: 302 | 303 | * Communicating architecture to diverse stakeholders 304 | * Onboarding new team members 305 | * Architecture documentation and review 306 | * Replacing or supplementing UML 307 | ==== 308 | 309 | [[hexagonal-architecture]] 310 | ==== Hexagonal Architecture (Ports & Adapters) 311 | 312 | [%collapsible] 313 | ==== 314 | *Also known as*: Ports and Adapters, Onion Architecture (variant) 315 | 316 | *Core Concepts*: 317 | 318 | * *Hexagonal structure*: Core domain at the center, isolated from external concerns 319 | * *Ports*: Interfaces defining how the application communicates 320 | * *Adapters*: Implementations that connect to external systems 321 | * *Dependency inversion*: Dependencies point inward toward the domain 322 | * *Technology independence*: Core logic doesn't depend on frameworks or infrastructure 323 | * *Primary/Driving adapters*: User interfaces, APIs (inbound) 324 | * *Secondary/Driven adapters*: Databases, message queues (outbound) 325 | * *Testability*: Easy to test core logic in isolation 326 | * *Symmetry*: All external interactions are treated uniformly 327 | 328 | *Key Proponent*: Alistair Cockburn (2005) 329 | 330 | *When to Use*: 331 | 332 | * Applications requiring high testability 333 | * Systems that need to support multiple interfaces (web, CLI, API) 334 | * When you want to defer infrastructure decisions 335 | * Microservices with clear domain boundaries 336 | ==== 337 | 338 | [[clean-architecture]] 339 | ==== Clean Architecture 340 | 341 | [%collapsible] 342 | ==== 343 | *Full Name*: Clean Architecture according to Robert C. Martin 344 | 345 | *Core Concepts*: 346 | 347 | * *The Dependency Rule*: Dependencies only point inward 348 | * *Concentric circles*: Entities → Use Cases → Interface Adapters → Frameworks & Drivers 349 | * *Independent of frameworks*: Architecture doesn't depend on libraries 350 | * *Testable*: Business rules testable without UI, database, or external elements 351 | * *Independent of UI*: UI can change without changing business rules 352 | * *Independent of database*: Business rules not bound to database 353 | * *Independent of external agencies*: Business rules don't know about outside world 354 | * *Screaming Architecture*: Architecture reveals the intent of the system 355 | * *SOLID principles*: Foundation of the architecture 356 | 357 | *Key Proponent*: Robert C. Martin ("Uncle Bob") 358 | 359 | *When to Use*: 360 | 361 | * Enterprise applications with complex business logic 362 | * Systems requiring long-term maintainability 363 | * When team size and turnover are high 364 | * Projects where business rules must be protected from technology changes 365 | ==== 366 | 367 | [[design-principles-patterns]] 368 | === Design Principles & Patterns 369 | 370 | [[solid-principles]] 371 | ==== SOLID Principles 372 | 373 | [%collapsible] 374 | ==== 375 | *Full Name*: SOLID Object-Oriented Design Principles 376 | 377 | *Core Concepts*: 378 | 379 | * *Single Responsibility Principle (SRP)*: Each class should have one responsibility 380 | * *Open/Closed Principle (OCP)*: Entities should be open for extension, closed for modification 381 | * *Liskov Substitution Principle (LSP)*: Subtypes must be substitutable for their base types 382 | * *Interface Segregation Principle (ISP)*: Clients should not be forced to depend on interfaces they do not use 383 | * *Dependency Inversion Principle (DIP)*: Depend on abstractions, not concrete implementations 384 | 385 | *Key Proponent*: Robert C. Martin ("Uncle Bob") 386 | 387 | *When to Use*: 388 | 389 | * Designing maintainable and scalable object-oriented systems 390 | * Refactoring legacy code to improve structure 391 | * Building systems where flexibility and testability are important 392 | * Teaching or enforcing good software design practices 393 | ==== 394 | 395 | [[domain-driven-design]] 396 | ==== Domain-Driven Design according to Evans 397 | 398 | [%collapsible] 399 | ==== 400 | *Full Name*: Domain-Driven Design according to Eric Evans 401 | 402 | *Core Concepts*: 403 | 404 | * *Ubiquitous Language*: Shared vocabulary between developers and domain experts 405 | * *Bounded Context*: Explicit boundaries where a model is defined and applicable 406 | * *Aggregates*: Cluster of domain objects treated as a single unit 407 | * *Entities*: Objects defined by identity, not attributes 408 | * *Value Objects*: Immutable objects defined by their attributes 409 | * *Repositories*: Abstraction for object persistence and retrieval 410 | * *Domain Events*: Significant occurrences in the domain 411 | * *Strategic Design*: Context mapping, anti-corruption layers 412 | * *Tactical Design*: Building blocks (entities, value objects, services) 413 | * *Model-Driven Design*: Code that expresses the domain model 414 | 415 | *Key Proponent*: Eric Evans ("Domain-Driven Design: Tackling Complexity in the Heart of Software", 2003) 416 | 417 | *When to Use*: 418 | 419 | * Complex business domains with intricate rules 420 | * Long-lived systems requiring deep domain understanding 421 | * When business and technical teams need close collaboration 422 | * Systems where the domain logic is the core value 423 | ==== 424 | 425 | [[requirements-engineering]] 426 | === Requirements Engineering 427 | 428 | [[problem-space-nvc]] 429 | ==== Problem Space NVC 430 | 431 | [%collapsible] 432 | ==== 433 | *Full Name*: Problem Space in Nonviolent Communication 434 | 435 | *Core Concepts*: 436 | 437 | * *Observations*: Concrete, objective facts without evaluation 438 | * *Feelings*: Emotions arising from observations 439 | * *Needs*: Universal human needs underlying feelings 440 | * *Requests*: Specific, actionable requests (not demands) 441 | * *Empathic connection*: Understanding before problem-solving 442 | * *Separating observation from interpretation*: Avoiding judgment 443 | * *Needs-based conflict resolution*: Finding solutions that meet everyone's needs 444 | 445 | *Key Proponent*: Marshall Rosenberg 446 | 447 | *Application in Software Development*: 448 | 449 | * Requirements elicitation that uncovers real user needs 450 | * Stakeholder communication and conflict resolution 451 | * User story formulation focused on needs 452 | * Retrospectives and team communication 453 | ==== 454 | 455 | [[ears-requirements]] 456 | ==== EARS-Requirements 457 | 458 | [%collapsible] 459 | ==== 460 | *Full Name*: Easy Approach to Requirements Syntax 461 | 462 | *Core Concepts*: 463 | 464 | * *Ubiquitous requirements*: "The shall " 465 | * *Event-driven requirements*: "WHEN the shall " 466 | * *Unwanted behavior*: "IF , THEN the shall " 467 | * *State-driven requirements*: "WHILE , the shall " 468 | * *Optional features*: "WHERE , the shall " 469 | * *Structured syntax*: Consistent templates for clarity 470 | * *Testability*: Requirements written to be verifiable 471 | 472 | *Key Proponent*: Alistair Mavin (Rolls-Royce) 473 | 474 | *When to Use*: 475 | 476 | * Safety-critical systems 477 | * Regulated industries (aerospace, automotive, medical) 478 | * When requirements traceability is essential 479 | * Large, distributed teams 480 | ==== 481 | 482 | [[user-story-mapping]] 483 | ==== User Story Mapping 484 | 485 | [%collapsible] 486 | ==== 487 | *Full Name*: User Story Mapping according to Jeff Patton 488 | 489 | *Core Concepts*: 490 | 491 | * *Narrative flow*: Horizontal arrangement of user activities 492 | * *User activities*: High-level tasks users perform 493 | * *User tasks*: Steps within activities 494 | * *Walking skeleton*: Minimal end-to-end functionality first 495 | * *Release planning*: Horizontal slices for releases 496 | * *Prioritization by value*: Vertical ordering by importance 497 | * *Shared understanding*: Collaborative mapping builds team alignment 498 | * *Big picture view*: See the whole journey, not just backlog items 499 | * *Opportunity for conversation*: Stories as placeholders for discussion 500 | 501 | *Key Proponent*: Jeff Patton ("User Story Mapping", 2014) 502 | 503 | *When to Use*: 504 | 505 | * Planning new products or major features 506 | * When backlog feels overwhelming or fragmented 507 | * Release planning for incremental delivery 508 | * Onboarding team members to product vision 509 | ==== 510 | 511 | [[impact-mapping]] 512 | ==== Impact Mapping 513 | 514 | [%collapsible] 515 | ==== 516 | *Full Name*: Impact Mapping according to Gojko Adzic 517 | 518 | *Core Concepts*: 519 | 520 | * *Four levels*: Goal → Actors → Impacts → Deliverables 521 | * *Goal*: Business objective (Why?) 522 | * *Actors*: Who can produce or prevent desired impact? (Who?) 523 | * *Impacts*: How can actors' behavior change? (How?) 524 | * *Deliverables*: What can we build? (What?) 525 | * *Visual mapping*: Mind-map style collaborative diagram 526 | * *Assumption testing*: Make assumptions explicit 527 | * *Scope management*: Prevent scope creep by linking to goals 528 | * *Roadmap alternative*: Goal-oriented rather than feature-oriented 529 | 530 | *Key Proponent*: Gojko Adzic ("Impact Mapping", 2012) 531 | 532 | *When to Use*: 533 | 534 | * Strategic planning for products or projects 535 | * When stakeholders disagree on priorities 536 | * Aligning delivery with business outcomes 537 | * Avoiding building features that don't serve business goals 538 | ==== 539 | 540 | [[jobs-to-be-done]] 541 | ==== Jobs To Be Done (JTBD) 542 | 543 | [%collapsible] 544 | ==== 545 | *Full Name*: Jobs To Be Done Framework (Christensen interpretation) 546 | 547 | *Core Concepts*: 548 | 549 | * *Job definition*: Progress people want to make in a particular context 550 | * *Functional job*: Practical task to accomplish 551 | * *Emotional job*: How people want to feel 552 | * *Social job*: How people want to be perceived 553 | * *Hire and fire*: Customers "hire" products to do a job, "fire" when inadequate 554 | * *Context matters*: Jobs exist in specific circumstances 555 | * *Competition redefined*: Anything solving the same job is competition 556 | * *Innovation opportunities*: Unmet jobs or poorly served jobs 557 | * *Job stories*: Alternative to user stories focusing on context and motivation 558 | 559 | *Key Proponents*: Clayton Christensen, Alan Klement, Bob Moesta 560 | 561 | *When to Use*: 562 | 563 | * Product discovery and innovation 564 | * Understanding why customers choose solutions 565 | * Identifying true competition 566 | * Writing more meaningful user stories 567 | * Market segmentation based on jobs, not demographics 568 | ==== 569 | 570 | [[documentation]] 571 | === Documentation 572 | 573 | [[docs-as-code]] 574 | ==== Docs-as-Code according to Ralf D. Müller 575 | 576 | [%collapsible] 577 | ==== 578 | *Full Name*: Docs-as-Code Approach according to Ralf D. Müller 579 | 580 | *Core Concepts*: 581 | 582 | * *Plain text formats*: AsciiDoc, Markdown 583 | * *Version control*: Documentation in Git alongside code 584 | * *Automated toolchains*: Build pipelines for documentation 585 | * *Single source of truth*: Generate multiple output formats from one source 586 | * *Diagrams as code*: PlantUML, Mermaid, Graphviz, Kroki 587 | * *Continuous documentation*: Updated with every commit 588 | * *Developer-friendly*: Use same tools and workflows as for code 589 | * *Review process*: Pull requests for documentation changes 590 | * *Modular documentation*: Includes and composition 591 | 592 | *Key Proponent*: Ralf D. Müller (docToolchain creator) 593 | 594 | *Technical Stack*: 595 | 596 | * AsciiDoc/Asciidoctor 597 | * docToolchain 598 | * Gradle-based automation 599 | * Kroki for diagram rendering 600 | * Arc42 template integration 601 | 602 | *When to Use*: 603 | 604 | * Technical documentation for software projects 605 | * When documentation needs to stay synchronized with code 606 | * Distributed teams collaborating on documentation 607 | * Projects requiring multiple output formats (HTML, PDF, etc.) 608 | ==== 609 | 610 | [[diataxis-framework]] 611 | ==== Diátaxis Framework 612 | 613 | [%collapsible] 614 | ==== 615 | *Full Name*: Diátaxis Documentation Framework according to Daniele Procida 616 | 617 | *Core Concepts*: 618 | 619 | * *Four documentation types*: 620 | ** *Tutorials*: Learning-oriented, lessons for beginners 621 | ** *How-to guides*: Task-oriented, directions for specific goals 622 | ** *Reference*: Information-oriented, technical descriptions 623 | ** *Explanation*: Understanding-oriented, conceptual discussions 624 | * *Two dimensions*: 625 | ** Practical vs. Theoretical 626 | ** Acquisition (learning) vs. Application (working) 627 | * *Separation of concerns*: Each type serves a distinct purpose 628 | * *User needs*: Different users need different documentation at different times 629 | * *Quality criteria*: Each type has specific quality indicators 630 | * *Systematic approach*: Framework for organizing any documentation 631 | 632 | *Key Proponent*: Daniele Procida 633 | 634 | *When to Use*: 635 | 636 | * Organizing technical documentation 637 | * Improving existing documentation 638 | * Planning documentation structure 639 | * Evaluating documentation quality 640 | * Complementing Docs-as-Code approaches 641 | ==== 642 | 643 | [[decision-making-strategy]] 644 | === Decision Making & Strategy 645 | 646 | [[pugh-matrix]] 647 | ==== Pugh-Matrix 648 | 649 | [%collapsible] 650 | ==== 651 | *Full Name*: Pugh Decision Matrix (also Pugh Controlled Convergence) 652 | 653 | *Core Concepts*: 654 | 655 | * *Baseline comparison*: Compare alternatives against a reference solution 656 | * *Criteria weighting*: Assign importance to evaluation criteria 657 | * *Relative scoring*: Better (+), Same (S), Worse (-) than baseline 658 | * *Structured evaluation*: Systematic comparison across multiple dimensions 659 | * *Iterative refinement*: Multiple rounds to converge on best solution 660 | * *Team decision-making*: Facilitates group consensus 661 | * *Hybrid solutions*: Combine strengths of different alternatives 662 | 663 | *Key Proponent*: Stuart Pugh 664 | 665 | *When to Use*: 666 | 667 | * Multiple viable alternatives exist 668 | * Decision criteria are known but trade-offs are unclear 669 | * Team needs to reach consensus 670 | * Architecture or technology selection decisions 671 | ==== 672 | 673 | [[cynefin-framework]] 674 | ==== Cynefin Framework 675 | 676 | [%collapsible] 677 | ==== 678 | *Full Name*: Cynefin Framework according to Dave Snowden 679 | 680 | *Core Concepts*: 681 | 682 | * *Five domains*: 683 | ** *Clear* (formerly "Simple"): Best practices apply, sense-categorize-respond 684 | ** *Complicated*: Good practices exist, sense-analyze-respond 685 | ** *Complex*: Emergent practices, probe-sense-respond 686 | ** *Chaotic*: Novel practices needed, act-sense-respond 687 | ** *Confused* (center): Don't know which domain you're in 688 | * *Domain transitions*: How situations move between domains 689 | * *Safe-to-fail probes*: Experiments in complex domain 690 | * *Complacency risk*: Moving from clear to chaotic 691 | * *Decision-making context*: Different domains require different approaches 692 | * *Facilitation tool*: Helps teams discuss and categorize challenges 693 | 694 | *Key Proponent*: Dave Snowden (1999) 695 | 696 | *When to Use*: 697 | 698 | * Understanding what type of problem you're facing 699 | * Choosing appropriate decision-making approaches 700 | * Facilitating team discussions about complexity 701 | * Strategic planning in uncertain environments 702 | ==== 703 | 704 | [[wardley-mapping]] 705 | ==== Wardley Mapping 706 | 707 | [%collapsible] 708 | ==== 709 | *Core Concepts*: 710 | 711 | * *Value chain*: Map components from user needs down 712 | * *Evolution axis*: Genesis → Custom → Product → Commodity 713 | * *Movement*: Components naturally evolve over time 714 | * *Situational awareness*: Understanding the landscape before deciding 715 | * *Gameplay patterns*: Common strategic moves 716 | * *Climatic patterns*: Forces that affect all players 717 | * *Doctrine*: Universal principles of good strategy 718 | * *Inertia*: Resistance to change in organizations 719 | * *Strategic planning*: Visual approach to strategy 720 | * *Build-Buy-Partner decisions*: Based on evolution stage 721 | 722 | *Key Proponent*: Simon Wardley 723 | 724 | *When to Use*: 725 | 726 | * Strategic technology planning 727 | * Build vs. buy decisions 728 | * Understanding competitive landscape 729 | * Communicating strategy visually 730 | * Identifying opportunities for disruption 731 | ==== 732 | 733 | [[development-practices]] 734 | === Development Practices 735 | 736 | [[mental-model-according-to-naur]] 737 | ==== Mental Model according to Naur 738 | 739 | [%collapsible] 740 | ==== 741 | *Full Name*: Programming as Theory Building (Mental Model) according to Peter Naur 742 | 743 | *Core Concepts*: 744 | 745 | * *Theory building*: Programming is creating a mental model, not just writing code 746 | * *Theory of the program*: Deep understanding of why the program works and how it relates to the problem domain 747 | * *Knowledge in people*: The real program exists in developers' minds, not in the code 748 | * *Theory decay*: When original developers leave, the theory is lost 749 | * *Documentation limitations*: Written documentation cannot fully capture the theory 750 | * *Maintenance as theory*: Effective maintenance requires possessing the theory 751 | * *Communication is key*: Theory must be shared through collaboration and conversation 752 | * *Ramp-up time*: New team members need time to build the theory 753 | * *Code as artifact*: Code is merely a representation of the underlying theory 754 | 755 | *Key Proponent*: Peter Naur (Turing Award winner, 1978) 756 | 757 | *Original Work*: "Programming as Theory Building" (1985) 758 | 759 | *Application in Software Development*: 760 | 761 | * Understanding why knowledge transfer is challenging 762 | * Emphasizing pair programming and mob programming 763 | * Justifying time for onboarding and code walkthroughs 764 | * Explaining technical debt accumulation when teams change 765 | * Supporting documentation practices that capture "why" not just "what" 766 | * Advocating for team stability and continuity 767 | 768 | *Contrast with Other Views*: 769 | 770 | * Programming as text production → Focus on code output 771 | * Programming as problem solving → Focus on algorithms 772 | * Programming as theory building → Focus on understanding 773 | ==== 774 | 775 | [[conventional-commits]] 776 | ==== Conventional Commits 777 | 778 | [%collapsible] 779 | ==== 780 | *Core Concepts*: 781 | * A specification for adding human and machine readable meaning to commit messages 782 | * Determining a semantic version bump (based on the types of commits landed) 783 | * Communicating the nature of changes to teammates, the public, and other stakeholders 784 | * *Schema*: [!][(optional scope)]: + optional body/footer 785 | * *Common Types*: 786 | ** *feat:* - introduce new feature to the codebase (-> Semver Minor) 787 | ** *fix:* - patches a bug in your codebase (-> SemVer Patch) 788 | ** *docs:* - documentation improvements to the codebase 789 | ** *chore:* - codebase/repository housekeeping changes 790 | ** *style:* - formatting changes that do not affect the meaning of the code 791 | ** *refactor:* - implementation changes that do not affect the meaning of the code 792 | ** *!* - BREAKING CHANGE (-> SemVer Major) 793 | * *BREAKING CHANGE:* introduces a breaking API change 794 | 795 | *Key Proponents*: Benjamin E. Coe, James J. Womack, Steve Mao 796 | 797 | *When to Use*: 798 | 799 | * everything-as-code paradigm targeted 800 | * team-/community-communication 801 | * repository quality improvements 802 | 803 | ==== 804 | 805 | [[semantic-versioning]] 806 | ==== Semantic Versioning (SemVer) 807 | 808 | [%collapsible] 809 | ==== 810 | *Full Name*: Semantic Versioning Specification 811 | 812 | *Core Concepts*: 813 | 814 | * *Version format*: MAJOR.MINOR.PATCH (e.g., 2.4.7) 815 | ** *MAJOR*: Incompatible API changes (breaking changes) 816 | ** *MINOR*: Backward-compatible functionality additions 817 | ** *PATCH*: Backward-compatible bug fixes 818 | ** *Pre-release versions*: Append hyphen and identifiers (e.g., 1.0.0-alpha.1) 819 | * *Build metadata*: Append plus sign and identifiers (e.g., 1.0.0+20241111) 820 | * *Version precedence*: Clear rules for version comparison 821 | * *Initial development*: 0.y.z for initial development (API unstable) 822 | * *Public API declaration*: Once public API declared, version dependencies matter 823 | 824 | *Key Proponent*: Tom Preston-Werner 825 | 826 | *When to Use*: 827 | 828 | * Libraries and APIs consumed by other software 829 | * Software with defined public interfaces 830 | * Projects requiring dependency management 831 | * Communication of change impact to users/consumers 832 | 833 | ==== 834 | 835 | [[bem-methodology]] 836 | ==== BEM Methodology 837 | 838 | [%collapsible] 839 | ==== 840 | *Full Name*: Block Element Modifier (BEM) (S)CSS Methodology 841 | 842 | *Core Concepts*: 843 | 844 | * *Motivation*: Solve CSS specificity wars, naming conflicts, and stylesheet maintainability issues in large codebases 845 | * *Block*: Standalone component that is meaningful on its own (e.g., `menu`, `button`, `header`) 846 | * *Element*: Part of a block with no standalone meaning (e.g., `menu__item`, `button__icon`) 847 | * *Modifier*: Flag on blocks or elements that changes appearance or behavior (e.g., `button--disabled`, `menu__item--active`) 848 | * *Naming convention*: `block__element--modifier` structure 849 | * *Independence*: Blocks are self-contained and reusable 850 | * *No cascading*: Avoid deep CSS selectors, use flat structure 851 | * *Explicit relationships*: Clear parent-child relationships through naming 852 | * *Reusability*: Components can be moved anywhere in the project 853 | * *Mix*: Combining multiple BEM entities on a single DOM node 854 | * *File structure*: Often paired with component-based file organization 855 | 856 | *Naming Examples*: 857 | 858 | * Block: `.search-form` 859 | * Element: `.search-form__input`, `.search-form__button` 860 | * Modifier: `.search-form--compact`, `.search-form__button--disabled` 861 | 862 | *Key Proponents*: Yandex development team 863 | 864 | *When to Use*: 865 | 866 | * Large-scale web applications with many components 867 | * Team projects requiring consistent (S)CSS naming conventions 868 | * When (S)CSS maintainability and scalability are priorities 869 | * Projects where developers need to quickly understand (S)CSS structure 870 | * Component-based architectures (React, Vue, Angular) 871 | 872 | ==== 873 | 874 | == Testing and Contributing Semantic Anchors 875 | 876 | === Testing a Semantic Anchor 877 | 878 | Before adding a new semantic anchor to your catalog, it's valuable to test whether the LLM recognizes it and what concepts it associates with the term. This helps you: 879 | 880 | * Verify that the anchor is well-established in the LLM's training data 881 | * Understand how the LLM interprets the concept 882 | * Identify gaps or misconceptions in the LLM's understanding 883 | * Decide whether the anchor needs additional context or clarification 884 | 885 | ==== The Testing Prompt 886 | 887 | Use the following prompt pattern to test a semantic anchor: 888 | 889 | [source] 890 | ---- 891 | What concepts do you associate with ''? 892 | ---- 893 | 894 | Or in German: 895 | 896 | [source] 897 | ---- 898 | Welche Konzepte verbindest Du mit ''? 899 | ---- 900 | 901 | ==== Evaluating the Response 902 | 903 | When the LLM responds, evaluate the following: 904 | 905 | 1. *Recognition*: Does the LLM recognize the term at all? 906 | 2. *Accuracy*: Are the associated concepts correct and relevant? 907 | 3. *Depth*: Does the LLM show deep understanding or just surface knowledge? 908 | 4. *Specificity*: Does the LLM distinguish this concept from similar ones? 909 | 5. *Practical application*: Does the LLM understand when and how to use it? 910 | 911 | ==== Example Test Session 912 | 913 | [source] 914 | ---- 915 | Human: What concepts do you associate with 'Pugh-Matrix'? 916 | 917 | Claude: I associate the Pugh-Matrix with: 918 | - Baseline comparison methodology 919 | - Weighted decision criteria 920 | - Relative scoring (better/same/worse) 921 | - Team-based evaluation 922 | - Iterative refinement process 923 | [...] 924 | ---- 925 | 926 | Based on the response, you can determine: 927 | 928 | * ✅ *Good anchor*: LLM shows strong understanding → Add to catalog 929 | * ⚠️ *Partial recognition*: LLM knows it but lacks depth → Add with extra context 930 | * ❌ *Unknown*: LLM doesn't recognize it → May not be a good semantic anchor yet 931 | 932 | === Contributing New Anchors 933 | 934 | Once you've tested a semantic anchor and confirmed it's valuable, you can contribute it to this catalog. 935 | 936 | ==== Quick Contribution via GitHub 937 | 938 | The easiest way to contribute is to click the edit button (pencil icon) on this file in GitHub, make your changes, and submit a pull request directly. 939 | 940 | ==== Format for New Anchors 941 | 942 | Add a new section following this pattern: 943 | 944 | [source,asciidoc] 945 | ---- 946 | === Your New Anchor Name 947 | 948 | [%collapsible] 949 | ==== 950 | *Full Name*: Complete name or expansion 951 | 952 | *Core Concepts*: 953 | 954 | * Key concept 1 955 | * Key concept 2 956 | * ... 957 | 958 | *Key Proponent*: Name(s) of key figures 959 | 960 | *When to Use*: 961 | 962 | * Use case 1 963 | * Use case 2 964 | ==== 965 | ---- 966 | 967 | TIP: You can use your LLM to help generate a properly formatted entry. Ask it to analyze the semantic anchor and produce an entry following the established pattern in this document. 968 | 969 | == Conclusion 970 | 971 | Semantic anchors create a shared language between you and LLMs, enabling more precise and efficient communication. By referencing established methodologies, frameworks, and practices, you can quickly activate relevant knowledge domains and ensure consistent interpretation of concepts. 972 | 973 | As your work evolves, continue to identify and catalog new semantic anchors that emerge in your field. This living vocabulary becomes a powerful tool for effective collaboration with AI assistants. 974 | 975 | --- 976 | 977 | _This document itself serves as a semantic anchor catalog, providing you with quick reference terminology for software development conversations._ 978 | --------------------------------------------------------------------------------