Agent-Friendly Software Architecture

Transcript

1. Agent-friendly Architecture Is Human-Friendly Architecture Henning Schwentner — WPS – Workplace Solutions
2. Metro Goldwyn Lolcat
3. Hi, I’m Henning
7. Programming Yesterday hschwentner.io
8. Programming Today hschwentner.io
9. Programming Today hschwentner.io
10. Programming Today hschwentner.io
11. How to Not Make A Mess? hschwentner.io
12. Give the Agent Context what the agent sees Market Square Mill Way Quayside City Park hschwentner.io
13. Good context is not “as much context as possible,” but “the right slice of context” hschwentner.io
14. Too big context window ➔ quality sinks ➔ cost rises hschwentner.io
15. ➔ How to pick the right slice of context? hschwentner.io
16. Computer science has had answers for picking that slice for a long time
17. Structure, Modularization, Cognitive Load hschwentner.io
18. No Architecture Program hschwentner.io
19. No Architecture Mess hschwentner.io
20. In the Old Days Program: == chaos goto goto goto goto goto hschwentner.io
21. We solved this once already—for humans. hschwentner.io
22. Structured Programming callable unit callable Edgar Dijkstra: Go To Statement Considered Harmful callable unit unit Edsger Dijkstra hschwentner.io 1968
23. Information Hiding accessible 1972 interface implementation hidden hschwentner.io David Parnas
24. Architecture Term: Module accessible A part of a software that hides its implementation/a decision behind an interface. interface Study it without reading the rest. implementation e.g. a method, a class, a bounded context hschwentner.io hidden
26. Separation of Concerns “…study in depth an aspect in isolation […], all the time knowing that one is occupying oneself only with one of the aspects.” Edsger Dijkstra one aspect in isolation 1974 hschwentner.io
27. Loose Coupling/ High Cohesion 1979 knowledge needed to work on the left Ed Larry module hschwentner.io Yourdon Constantine
28. We do all this to limit cognitive load—for humans. hschwentner.io
29. Cognitive Load 1956 everything else in the repo 40 files of context the actual task 1988 hschwentner.io George A. Miller John Sweller
30. Hypothesis 1: To keep the “cognitive load” of an agent right, keep the context window right
31. Hypothesis 2: the architecture that makes a codebase legible to an agent is the same architecture that has always made it legible to humans
32. Hypothesis 3: This gets even more important for the dark software factory
33. What To Do? hschwentner.io
34. descriptive ARCHITECTURE.md vs. ARCHITECTURE-RULES.md prescriptive
35. ARCHITECTURERULES.md # Architecture Rules How this system is built. Not a survey of what exists. Prescription, not description → The current architecture lives in ARCHITECTURE.md ## Style - Hexagonal, not layered. Adapters depend inward; the domain depends on nothing. [DependencyRulesTest] - Domain imports no framework types. [DomainPurityTest] - One module per bounded context; modules talk through published interfaces, never through each other's tables. [ModuleApiTest] Style, not domain. ## Choices, where others are also reasonable - Ports live beside the domain, not in their own package. [PortLocationTest] - Mapping is hand-written. No MapStruct. [no test] - Persistence returns domain types, not entities. [no test] The contexts and their language live in CONTEXT-MAP.md. ## Enforcement Every rule here is an ArchUnit test. Rules marked [no test] are not yet enforced: if you touch code they govern, write the test first. Make it fail, then fix the code. Where a test and this file disagree, the file wins — fix the test. Where code breaks a rule and the suite stays green, the test is missing. All can be referenced from AGENTS.md. ## Known deviations - sales reads risk tables directly (owner: HS, #412). Do not add to this. New code goes through the port. hschwentner.io
36. ARCHITECTURERULES.md # Architecture Rules Style, not domain. The contexts and their How this system should be built. language live in CONTEXT## Style MAP.md. - Hexagonal, not layered. Adapters depend inward; the # Architecture Rules How this system is built. Not a survey of what exists. Not a survey of what exists. domain depends on nothing. [DependencyRulesTest] - Domain imports no framework types. [DomainPurityTest] - One module per bounded context; modules talk through published interfaces, never through each other's tables. [ModuleApiTest] Both referenced from AGENTS.md. ## Choices, where others are also reasonable - Ports live beside the domain, not in their own package. [PortLocationTest] - Mapping is hand-written. No MapStruct. [no test] - Persistence returns domain types, not entities. [no test] ## Enforcement Every rule here is an ArchUnit test. Rules marked [no test] are not yet enforced: if you touch code they govern, write the test first. Make it fail, then fix the code. Where a test and this file disagree, the file wins — fix the test. Where code breaks a rule and the suite stays green, the test is missing. ## Known deviations - sales reads risk tables directly (owner: HS, #412). Do not add to this. New code goes through the port. hschwentner.io
37. ARCHITECTURERULES.md ## Style # Architecture Rules How this system is built. Not a survey of what exists. ## Style - Hexagonal, not layered. Adapters depend inward; the domain depends on nothing. [DependencyRulesTest] - Domain imports no framework types. [DomainPurityTest] - One module per bounded context; modules talk through published interfaces, never through each other's tables. [ModuleApiTest] Style, not domain. The contexts and their language live in CONTEXTdepend inward; the domain depends MAP.md. - Hexagonal, not layered. Adapters on nothing. ## Choices, where others are also reasonable - Ports live beside the domain, not in their own package. [PortLocationTest] - Mapping is hand-written. No MapStruct. [no test] - Persistence returns domain types, not entities. [no test] [DependencyRulesTest] Both referenced from AGENTS.md. - Domain imports no framework types. [DomainPurityTest] - One module per bounded context; ## Enforcement Every rule here is an ArchUnit test. Rules marked [no test] are not yet enforced: if you touch code they govern, write the test first. Make it fail, then fix the code. Where a test and this file disagree, the file wins — fix the test. Where code breaks a rule and the suite stays green, the test is missing. modules talk through published interfaces. [ModuleApiTest] ## Known deviations - sales reads risk tables directly (owner: HS, #412). Do not add to this. New code goes through the port. hschwentner.io
38. ARCHITECTURERULES.md # Architecture Rules How this system is built. Not a survey of what exists. ## Choices, where others are also reasonable ## Style - Hexagonal, not layered. Adapters depend inward; the domain depends on nothing. [DependencyRulesTest] - Domain imports no framework types. [DomainPurityTest] - One module per bounded context; modules talk through published interfaces, never through each other's tables. [ModuleApiTest] Style, not domain. The contexts and their language live in CONTEXT- Ports live beside the domain.MAP.md. ## Choices, where others are also reasonable - Ports live beside the domain, not in their own package. [PortLocationTest] - Mapping is hand-written. No MapStruct. [no test] - Persistence returns domain types, not entities. [no test] [PortLocationTest] Both referenced from AGENTS.md. - Mapping is hand-written. No MapStruct. [no test] ## Enforcement Every rule here is an ArchUnit test. Rules marked [no test] are not yet enforced: if you touch code they govern, write the test first. Make it fail, then fix the code. Where a test and this file disagree, the file wins — fix the test. Where code breaks a rule and the suite stays green, the test is missing. - Persistence returns domain types. [no test] ## Known deviations What (owner: the model cannot - sales reads risk tables directly HS, #412). Do not add to this. New code goes through the port. guess. hschwentner.io
39. ARCHITECTURERULES.md # Architecture Rules How this system is built. Not a survey of what exists. ## Style - Hexagonal, not layered. Adapters depend inward; the domain depends on nothing. [DependencyRulesTest] - Domain imports no framework types. [DomainPurityTest] - One module per bounded context; modules talk through published interfaces, never through each other's tables. [ModuleApiTest] ## Enforcement Style, not domain. The contexts and their language live in CONTEXT- Ports live beside the domain, not in their own Rules marked [no test] are not yet MAP.md. package. [PortLocationTest] Every rule here is an ArchUnit test. ## Choices, where others are also reasonable - Mapping is hand-written. No MapStruct. [no test] - Persistence returns domain types, not entities. [no test] enforced: if you touch code theyBoth referenced from govern, write the test first. ## Enforcement Every rule here is an ArchUnit test. Rules marked [no test] are not yet enforced: if you touch code they govern, write the test first. Make it fail, then fix the code. Where a test and this file disagree, the file wins — fix the test. Where code breaks a rule and the suite stays green, the test is missing. AGENTS.md. Make it fail, then fix the code. Where a test and this file disagree, ## Known deviations - sales reads risk tables directly (owner: HS, #412). Do not add to this. New code goes through the port. the file wins - fix the test. Suite green on broken rule? Test missing. hschwentner.io
40. ARCHITECTURERULES.md # Architecture Rules How this system is built. Not a survey of what exists. ## Style - Hexagonal, not layered. Adapters depend inward; the domain depends on nothing. [DependencyRulesTest] - Domain imports no framework types. [DomainPurityTest] - One module per bounded context; modules talk through published interfaces, never through each other's tables. [ModuleApiTest] ## Known deviations ## Choices, where others are also reasonable - Ports live beside the domain, not in their own package. [PortLocationTest] - Mapping is hand-written. No MapStruct. [no test] - Persistence returns domain types, not entities. [no test] - sales reads risk tables directly. owner: HS, issue #412 ## Enforcement Every rule here is an ArchUnit test. Rules marked [no test] are not yet enforced: if you touch code they govern, write the test first. Make it fail, then fix the code. Where a test and this file disagree, the file wins — fix the test. Where code breaks a rule and the suite stays green, the test is missing. Do not add to this. New code goes through ## Known deviations - sales reads risk tables directly (owner: HS, #412). Do not add to this. New code goes through the port. the port. Honest about what is already broken. hschwentner.io
41. Conclusion hschwentner.io
42. Trainings: Agentic Engineering wps.de/agenta hschwentner.io
43. Photo: Henning Schwentner
44. FEEDBACK @hschwentner
45. Bibliography Cockburn, Alistair. “Hexagonal Architecture.” January 4, 2005. https://alistair.cockburn.us/hexagonal-architecture/. Dijkstra, Edsger. “Go To Statement Considered Harmful.” Communications of the ACM 11, no. 3 (March 1968): 147–48. Evans, Eric. Domain-Driven Design: Tackling Complexity in the Heart of Software. Boston: Addison-Wesley, 2004. Lilienthal, Carola and Henning Schwentner. Domain-Driven Transformation: Modernize Legacy Software and Mitigate Risk. Santa Rosa, CA: O’Reilly, 2026. Parnas, David L. “On the Criteria To Be Used in Decomposing Systems into Modules.” Communications of the ACM 15, no. 12 (December 1972): 1053–58. Yourdon, Edward and Larry L. Constantine. Structured Design: Fundamentals of a Discipline of Computer Program and Systems Design. New York: Yourdon Press, 1979. hschwentner.io
46. This has been a presentation Metro Goldwyn Lolcat
47. Henning Schwentner   https://hschwentner.io in/henningschwentner hs@wps.de
48. Glossary hschwentner.io
49. AI Term: Large Language Model a.k.a. LLM, foundation model, frontier model, model Predicts the next →token from those before it. No memory between runs. It knows nothing about your repository except what is in the →context window. e.g. Sonnet, GPT, Gemini—the model matters less than the codebase. hschwentner.io
50. AI Term: Prompt a.k.a. instruction, request What you ask for, in words, plus whatever the →harness attaches to it. It is the smallest part of the →context window. The files around it do most of the work. e.g. “Add VAT to the invoice total”—four words, and forty files of context. hschwentner.io
51. AI Term: Token a.k.a. subword The unit a →model reads and writes—not a word, not a line. Roughly four characters of English. Limits and bills are counted in tokens. e.g. getCustomerById is about four tokens: get · Customer · By · Id. hschwentner.io
52. AI Term: Context Window a.k.a. prompt budget Everything the model sees at once: →prompt, files, its own output. Measured in →tokens. Outside the context window nothing exists—it cannot look anything up. e.g. 200,000 tokens is roughly 15,000 lines of code, answer included. hschwentner.io
53. AI Term: Lost in the Middle a.k.a. position bias A model attends most to the beginning and the end of its context. What sits in the middle is weighted least. So, a full →context window is not a well-read one. e.g. the rule it needed sat in file 30 of 60; it used the one from file 2. hschwentner.io
54. AI Term: Coding Agent a.k.a. agent, coding assistant An →LLM in a loop with tools. It reads, greps, edits, runs the tests—and picks what to read next. An assistant completes your line. An agent chooses its own context. e.g. “Add VAT to the invoice total”: it greps, opens three files, edits one. hschwentner.io
55. AI Term: Harness a.k.a. agent scaffold, agent loop The program around the →model: it picks what enters the →context window. The model is fixed; the harness is not. Your repository is half of it. e.g. Claude Code and Cursor run the same models, and behave differently. hschwentner.io
56. AI Term: Context Rot a.k.a. context degradation, context pollution Answers get worse as the context window fills up. Stale plans, dead ends, and its own old output crowd the window. A long session degrades even inside the limit. e.g. hour three: it re-implements what it deleted in hour one. hschwentner.io
57. AI Term: Hallucination a.k.a. confabulation Output that is fluent, plausible, and not true. The model fills a gap with what usually follows. Missing context is the gap. e.g. a method name that should exist by every convention here, but doesn’t. hschwentner.io
58. AI coding assistants can generate features, refactor code, and explain complex logic within seconds.
59. But their effectiveness varies dramatically from one codebase to another.
60. Codebase A Agent nails it. Clean diff. First try. Codebase B Agent flails. Hallucinated methods. Broken tests.
61. Same model. Same prompt.
62. The difference is rarely the model.
63. It is the architecture. hschwentner.io
64. What an Agent Actually Needs hschwentner.io
65. When an agent analyzes a codebase, it has to infer… hschwentner.io
66. Domain concepts Dependencies Responsibilities
67. …from structure. hschwentner.io
68. No one hands it a design doc.
69. It reads files, greps, and guesses.
70. Context is not optional. It’s the raw material.
71. It weights what it read first and last. Everything in between gets diluted. A small, self-contained slice beats a large, complete one.
72. The context window has a size. And it fills up fast. Every extra file costs more and buys noise.
73. My Argument, in Two Sentences hschwentner.io
74. Agents need context. Modularity gives context.
75. Not as an abstraction—as five concrete kinds of context. Let’s go through them.
76. A Very Short History of “Good Structure” hschwentner.io
77. Naming Things Gives Context Too hschwentner.io
78. This gives you VOCABULARY context: the words in the code are the domain’s own words.
79. Structure alone gets an LLM surprisingly far. Names help most where the domain isn’t a textbook one.
80. Strategic Design The domain— which subdomains is it made of? bank hschwentner.io Eric Evans
81. This gives you MEANING-BOUNDARY context: “here’s where this word’s meaning ends.”
82. Big Ball of Mud Banking 3000 Big Ball of Mud hschwentner.io
83. Big Ball of Mud meets Large Language Model. hschwentner.io
84. Big Ball of Mud Clean bounded context Noisy suggestions. Coherent suggestions. Brittle changes. Local changes. Risky refactors. Safe refactors.
85. What Goes Wrong hschwentner.io
86. HAL 9000. Skynet. Ultron. The Master Control Program.
87. That’s not what we’re building. (MCP was evil long before it stood for Model Context Protocol.)
88. A hallucinated method name that “should” exist—but doesn’t. A “fix” that duplicates logic instead of finding the one true place for it. A one-line domain change that becomes a 12-file agent diff.
89. No modularity → no context → noisy, brittle, risky suggestions.
90. This isn’t a prompting problem. It’s a structure problem.
91. Example: LeasingNinja hschwentner.io
92. Hypothetical, illustrative: one LeasingApp class does sales, risk scoring, and web—all in one place hschwentner.io
93. Same task, same agent, same prompt: it can’t tell where risk logic ends and sales logic begins.
94. The real LeasingNinja: leasingninja-sales • leasingninja-riskmanagement • leasingninja-webapp hschwentner.io
95. Same task, same agent, same prompt: it goes straight to the right bounded context.
96. Before After One tangled module. Explicit bounded contexts. No named boundary. Named domain concepts.
97. What changed was the architecture— specifically, the context it made available.
98. Bonus: local changes are also easier for a human to check in the loop.
99. Back to the Argument hschwentner.io
100. Agents need context. Modularity gives context.
101. That’s not a new idea. It’s just a new reader for an old one.
102. If we want AI to be a reliable development partner… hschwentner.io
103. …we have to build architectures that make context explicit. hschwentner.io
104. Agent-friendly architecture is human-friendly architecture. hschwentner.io