You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/Agents/Principles.md
+19Lines changed: 19 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -101,6 +101,14 @@ Distance between a thing and its documentation is the rate at which they drift a
101
101
-**Interface Segregation.** Don't make consumers depend on things they don't use.
102
102
-**Dependency Inversion.** Depend on abstractions, not concretions.
103
103
104
+
## Coupling and cohesion
105
+
106
+
**Coupling** — two elements are coupled *with respect to a particular change* if changing one implies changing the other. Not merely "A calls B", but "changing A forces a change to B". Coupling is always relative to a specific kind of change, and it can be invisible until a change reveals it.
107
+
108
+
The cost of software is roughly the cost of change. Changes follow a power-law distribution: most are cheap; a few cascade into very expensive ones. Coupling is what conducts that cascade — change A, must change B, must change C. Reducing coupling flattens the tail of expensive changes and extends how long a codebase can keep absorbing new requirements.
109
+
110
+
**Cohesion** — an element is cohesive to the degree that all its sub-elements are coupled to each other: change one, change all. Grouping things that must change together into their own element reduces the scope of coupling you have to reason about. You can always find opportunities to improve cohesion locally, even when global decoupling feels intractable.
111
+
104
112
## DRY — with judgment
105
113
106
114
Don't Repeat Yourself, but **don't extract too early**. Wait until the same non-trivial logic appears in three or more places, or until the duplication is clearly load-bearing. Premature abstraction is more expensive than duplication.
@@ -187,6 +195,17 @@ Write code that is understandable. Code is read more often than it is written. N
187
195
188
196
Don't decide what you don't yet know. Experiment, iterate, treat design as a product — not a fixed contract. Architecture earns its right to be permanent by surviving change.
189
197
198
+
## Make change easy, then make the easy change
199
+
200
+
When a change is hard, resist the temptation to force it. First, restructure the system so the change becomes easy — as a separate, focused step. Then make the change itself. This separates two concerns:
201
+
202
+
-**Prepare** — refactor, rename, extract, reorganise. No behaviour change.
203
+
-**Change** — add, remove, or alter behaviour. No structural churn.
204
+
205
+
Applied recursively: if the preparation step is also hard, first make that easy. Work like a zipper — each structural step unlocks the next, until the actual behaviour change is trivial.
206
+
207
+
Keeping the two steps separate also lets you apply different levels of rigour. Structural changes are reversible — an extracted helper can be inlined again, a rename can be undone. Behaviour changes are often not — output sent, a form filed, a side effect triggered cannot be recalled. Irreversible decisions deserve more care. Separating the two gives you room to apply that care where it actually matters.
208
+
190
209
## Ways of working
191
210
192
211
One size does not fit all. The way we work follows the principles above, including the principle of evolving how we work.
0 commit comments