Skip to content

Commit 546956c

Browse files
feat(docs): add principles of coupling and cohesion, and restructure change management guidance
Closes #11
1 parent 96709fb commit 546956c

2 files changed

Lines changed: 20 additions & 0 deletions

File tree

docs/Agents/Principles.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,14 @@ Distance between a thing and its documentation is the rate at which they drift a
101101
- **Interface Segregation.** Don't make consumers depend on things they don't use.
102102
- **Dependency Inversion.** Depend on abstractions, not concretions.
103103

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+
104112
## DRY — with judgment
105113

106114
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
187195

188196
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.
189197

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+
190209
## Ways of working
191210

192211
One size does not fit all. The way we work follows the principles above, including the principle of evolving how we work.

docs/Agents/Workflow.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,7 @@ Borrowed from [Principles → Roadmapping](Principles.md#roadmapping). The plann
104104
| README-Driven Context | Implement |
105105
| GTD ("write it down") | All agents |
106106
| Determinism over intelligence | Implement |
107+
| Make change easy first | Implement |
107108
| Git Worktrees (parallel work) | Implement |
108109
| Dogfooding | Run / operate phase |
109110

0 commit comments

Comments
 (0)