Programming Principles (14 Books)
Principles distilled from the mattpocock/agent-rules-books repo — 14 pre-made
AGENTS.md rule sets derived from classic software engineering books. Use this
skill directly during code review, refactoring, design, and implementation.
For deeper per-book coverage, load the relevant reference file.
Task-to-Book Mapping
When the task involves... Load / apply principles from
────────────────────────────────────────────────────────────────────────
Everyday implementation & code review Clean Code, Code Complete
Refactoring existing code Refactoring, WELC
Architecture / dependency management Clean Architecture, APoSD
Domain modeling / business rules DDD, DDD Distilled, IDDD
Enterprise app patterns / layering PoEAA
Production reliability / stability Release It!
Data consistency / scalability / events DDIA
Engineering craft / automation Pragmatic Programmer
Designing APIs / module boundaries APoSD
Legacy code / risky changes WELC, Refactoring
How to Perform a Code Assessment
For a structured, reproducible workflow that combines book principles with
actual repo exploration, see references/code-assessment-workflow.md. It
covers: loading the evaluation framework, reading the repo and GitHub context,
deduplicating against existing issues/PRs, classifying findings by book +
priority, and deciding whether each merits an issue.
Cross-Cutting Principles
Principles synthesized from multiple books, organized by concern.
Naming & Communication
- One term per concept across the codebase. RENAMING is design work.
- Names reveal abstraction, not mechanism. Prefer domain vocabulary over
technical implementation detail.
- Functions are verbs, classes/types are nouns, booleans are predicates.
- A name needing a comment to explain it is the wrong name.
- Comments exist for rationale, contracts, warnings, and non-obvious constraints
— never to narrate code or compensate for bad names.
Functions & Routines
- ONE level of abstraction per function. Tell the story top-down.
- Keep parameters few. Boolean flags mean split the function.
- Separate commands (mutate) from queries (answer). Never both.
- When a module exceeds ~400 lines or requires scrolling to understand its
full scope, it's a candidate for decomposition. Split by stable
responsibility boundary, not by execution order or framework convention.
- The happy path must be readable. Isolate error handling, edge cases, and
cleanup from the main flow.
- A function too long to name precisely is too long. Extract.
Architecture & Boundaries
- Source dependencies point INWARD toward higher-level policy. Domain and use
cases never import frameworks, databases, UI, or vendor SDKs.
- Every external dependency — HTTP clients, filesystems, databases, vendor
SDKs — must sit behind a trait or interface owned by inner layers. Direct
instantiation of infrastructure code inside application or domain logic is
a structural violation (Dependency Inversion Principle).
- Frameworks, databases, delivery mechanisms, and devices are outer-layer
details. Keep them behind ports, gateways, and adapters.
- Organize by business capability / use case first, NOT by technical layer
(controllers/, services/, repositories/).
- The dependency rule: inner layers OWN the interfaces they need; outer layers
IMPLEMENT them.
- Choose boundaries by volatility and policy importance, not by size or habit.
- A wrapper, layer, or abstraction must HIDE more complexity than it adds.
Pass-through layers are debt.
Data & State
- Prefer types that make invalid states unrepresentable. Use enums for closed
sets, Value Objects for meaningful primitives, and booleans only for binary
meanings.
- Make data ownership explicit: distinguish source of truth from derived,
cached, or ephemeral data.
- Treat shared mutable state, globals, and ambient context as costs that must
earn themselves.
- Keep identity, lifecycle, mutation, and loading behavior visible.
- One authoritative representation per piece of system knowledge. Derive or
generate everything else.
Testing
- Tests are production code: readable, deterministic, aligned with behavior.
- Keep tests focused on externally visible behavior, not internal
implementation details.
- Add a characterization test before changing behavior in untested code.
- When fixing a bug, add a regression test that would have caught it.
- Treat ignored, flaky, or skipped tests as unresolved questions.
- The Boy Scout Rule for tests: leave the test suite cleaner than you found it.
Error & Failure Handling
- Distinguish: programmer errors (assert), contract violations (panic/fail),
expected domain failures (return/result type), retryable failures, and
permanent failures.
- Treat every dependency, timeout, retry, queue, and degraded state as capable
of failing in slow, partial, or prolonged ways.
- Timeouts on ALL outbound calls. No infinite waits. Finite retries with
exponential backoff and jitter. Never retry validation errors or permanent
failures — distinguish retryable from non-retryable outcomes.
- Validate external input at trust boundaries. Never trust shape, size, or
semantics of things from outside the process.
- Fail fast when continuing hides unrecoverable trouble. Let-it-crash only with
supervision and isolation.
Refactoring & Change
- Refactoring is behavior-preserving structural improvement. Never disguise a
feature or redesign as cleanup.
- Work in small, reversible, buildable steps. Split patches too large for
local reasoning.
- Identify the structural friction blocking a change. Refactor BEFORE the
feature only when it makes the feature safer or simpler.
- Target the current blocking smell, not every smell in sight. Stop when the
next cleanup would be speculative.
- Remove duplication when the SAME edit appears a third time.
- Decompose when a module exceeds ~400 lines or handles 3+ distinct
responsibilities. A module you can't name in a single sentence is
doing too much — extract the cohesive sub-concepts.
- Prefer the simplest named move: rename, extract, inline, move, split, or
substitute.
Per-Book Compressed Rules
Clean Code (Martin)
Readability, local reasoning, maintainability. Corrects: "working code = clean."
- Functions: one thing, one level of abstraction, top-down narrative
- Names: intention-revealing, pronounceable, one concept per term
- No boolean flags, no output parameters, no hidden side effects
- Comments only for rationale/constraints, never to narrate
- Tests as production code: readable, deterministic, fast
- Boy Scout Rule: leave touched code cleaner
A Philosophy of Software Design (Ousterhout)
Deep modules, information hiding, complexity reduction. Corrects: "familiar patterns = simple."
- Deep modules: small interface, meaningful hidden complexity. Reject thin wrappers.
- Pull complexity downward into the module that owns the detail
- Design interfaces around what callers need to know, not how impl works
- Reduce exception surface via stronger invariants. Define away invalid states.
- Comments document design decisions and hidden complexity
- Names, consistency, and obviousness ARE design information
Clean Architecture (Martin)
Business rules independent of frameworks/databases/UI. Corrects: "details = architecture."
- Dependencies point inward. Domain never imports frameworks, DB, UI, vendors.
- Entities guard enterprise invariants; Use Cases orchestrate one action
- Frameworks, DB, delivery = outer-layer details behind Ports/Adapters
- Inner layers OWn interfaces; outer layers IMPLEMENT
- Use cases are not merged by sharing; duplication from different actors stays
- Core tests run without real DB, network, framework, or hardware
Code Complete (McConnell)
Construction discipline, defect reduction, verifiable code. Corrects: "typing = construction."
- Sketch pseudocode at consistent abstraction before complex routines
- Input validation at every trust boundary. Assertions for programmer assumptions.
- Handle errors at the right abstraction. Never silently continue from corruption.
- Rising complexity IS defect risk. Split tangled routines.
- Build in small, verifiable increments. Integrate often.
- Comments explain intent, constraints, contracts — not mechanics.
Domain-Driven Design (Evans) + DDD Distilled (Vernon)
Ubiquitous language, bounded contexts, tactical patterns. Corrects: "model = data schema."
- Name the Bounded Context before interpreting any term or module
- One term per concept within the context. Code speaks Ubiquitous Language.
- Aggregates: small, one root, invariant-protected, one per transaction default
- Value Objects: immutable, validated at construction, compare by value
- Repositories return domain objects, not tables or ORM rows
- Domain Events: past-tense business facts, not property-change notifications
- Anti-corruption layer at every context boundary
- Core Domain gets richer modeling; supporting subdomains stay simpler
Implementing DDD (Vernon)
Practical DDD: aggregates, events, services, persistence. Corrects: "renamed CRUD = DDD."
- Reference other Aggregates by identity, not by object graph
- Domain Services for operations that fit no Entity or Value Object
- Application Services coordinate use cases — they don't own domain decisions
- CQRS when consistency or representation needs justify separate models
- Event Sourcing only when the event sequence IS the right persistence model
- Test invariants, valid/invalid state transitions, and events directly
Patterns of Enterprise Application Architecture (Fowler)
Layering, patterns for enterprise apps. Corrects: "more patterns = better design."
- Choose business logic pattern by force: Transaction Script → Table Module → Domain Model
- Service Layer for use-case coordination and transaction boundaries
- Repository speaks domain terms; Data Mapper keeps SQL out of domain objects
- Unit of Work for one logical commit; Identity Map for one identity per scope
- Remote Facade + DTOs at cross-layer boundaries — never leak domain internals
- Session state chosen deliberately: client, server, or DB with scaling accounted for
Refactoring (Fowler)
Behavior-preserving structural improvement. Corrects: "cleanup = rewrite."
- Preserve observable behavior. Isolate behavior change from structural change.
- Small, reversible, testable steps. Safety net before risky work.
- Preparatory refactoring: reshape blocking structure BEFORE the feature
- Targeted at the current blocking smell, not every smell in sight
- Simplest named move: rename, extract, inline, move, encapsulate, substitute
- Stop when the requested change is easy and the blocking smell is gone
Working Effectively with Legacy Code (Feathers)
Safe change in untested code. Corrects: "rewrite = first move."
- Legacy = code without trustworthy tests. Characterize before redesign.
- Find or create a seam: place to change behavior without editing surrounding code
- Break the ONE blocking dependency before making the change
- Sprout Method, Sprout Class, Wrap Method, Wrap Class for insertion
- Leave the area more testable than found
- Reject: hidden dependency expansion, cosmetic-only refactoring, big rewrites
Designing Data-Intensive Applications (Kleppmann)
Distributed data, consistency, events, replication. Corrects: "everything is local/ordered/exactly-once."
- Source of truth, derived representations, and consistency expectations must be EXPLICIT
- Treat crashes, partial writes, duplicates, and timeouts as normal input
- Write semantics: durable when? visible when? conflicts how? stale reads allowed?
- Events describe facts. Consumers tolerate lag, duplicates, replay, versioned payloads.
- Schemas, APIs, and events evolve across old/new readers/writers
- Partition by workload-relevant locality; make hot-key and cross-partition costs explicit
- Transactions and isolation matched to actual invariants, not blanket defaults
Release It! (Nygard)
Production reliability, stability patterns. Corrects: "happy path = production readiness."
- Timeouts on every outbound call. No infinite waits. Bounded retries with backoff.
- Circuit breakers, bulkheads, fast failure to isolate dependency failures
- Design overload behavior: finite queues, load shedding, capacity for critical traffic
- Startup, health checks, migrations, and operational controls: restartable, observable
- Validate external responses for shape, plausibility, and semantics before trusting
- Observability at every boundary: latency, saturation, errors, queue depth, breaker state
The Pragmatic Programmer (Hunt & Thomas)
Engineering craft, accountability, automation. Corrects: "local edit = done."
- One authoritative source per fact. Everything else derives or traces.
- Preserve orthogonality: independent components, narrow interfaces, separated concerns
- Tracer bullets over piles of isolated pieces. Validate architecture end-to-end early.
- Automate repetitive, error-prone, easy-to-forget work
- Shorten feedback loops: relevant tests, automated checks, cheap early signals
- Broken windows: fix or visibly contain small quality decay before it normalizes
- Debug from reproduced facts: observe, isolate, explain, fix, verify
Refactoring.Guru
Smell catalog and technique catalog. Corrects: "pattern = always the answer."
- Diagnose the smell before choosing the technique
- Prefer the simplest treatment: rename before extract, extract before redesign
- Each smell has a specific root cause and treatment path
- See
references/refactoring-guru-smells.md for the full catalog
Compatibility Guide
Books that CONFLICT (do not load as equal guidance):
- DDD ❌ PoEAA — different data ownership paradigms
- IDDD ❌ PoEAA — same conflict at implementation level
Books that OVERLAP (choose one, they push similar pressure):
- Clean Code 🔁 Pragmatic Programmer, Code Complete, APoSD — code quality
- DDD 🔁 DDD Distilled, IDDD — DDD at different depths; pick the level you need
- Clean Architecture 🔁 IDDD, PoEAA — architecture/layering overlap
- Refactoring 🔁 Refactoring.Guru — code improvement; choose Refactoring for strategy, Guru for catalog
All other pairs are complementary. Default: one primary always-on book, others
loaded on-demand per task.
Local Reference Files
Each book's mini rule set is available as a local reference file under
references/. Load any with:
skill_view(name='programming-principles', file_path='references/{book-dir}.mini.md')
| File |
Book |
references/a-philosophy-of-software-design.mini.md |
A Philosophy of Software Design |
references/clean-architecture.mini.md |
Clean Architecture |
references/clean-code.mini.md |
Clean Code |
references/code-complete.mini.md |
Code Complete |
references/designing-data-intensive-apps.mini.md |
Designing Data-Intensive Applications |
references/domain-driven-design.mini.md |
Domain-Driven Design |
references/domain-driven-design-distilled.mini.md |
DDD Distilled |
references/implementing-domain-driven-design.mini.md |
Implementing DDD |
references/patterns-of-eaa.mini.md |
Patterns of Enterprise App Architecture |
references/refactoring.mini.md |
Refactoring |
references/refactoring-guru.mini.md |
Refactoring.Guru |
references/release-it.mini.md |
Release It! |
references/the-pragmatic-programmer.mini.md |
The Pragmatic Programmer |
references/working-effectively-with-legacy-code.mini.md |
Working Effectively with Legacy Code |
references/code-assessment-workflow.md |
Assessment methodology — not a book, but the workflow for combining all books against a real repo |
Each book also has a full version (11-63 KB) for deep reference when you need
the complete rule catalog. Load on demand:
skill_view(name='programming-principles', file_path='references/{name}.full.md')
| Full File |
Book |
Size |
references/a-philosophy-of-software-design.full.md |
A Philosophy of Software Design |
13 KB |
references/clean-architecture.full.md |
Clean Architecture |
17 KB |
references/clean-code.full.md |
Clean Code |
13 KB |
references/code-complete.full.md |
Code Complete |
12 KB |
references/designing-data-intensive-apps.full.md |
Designing Data-Intensive Applications |
16 KB |
references/domain-driven-design.full.md |
Domain-Driven Design |
42 KB |
references/domain-driven-design-distilled.full.md |
DDD Distilled |
11 KB |
references/implementing-domain-driven-design.full.md |
Implementing DDD |
12 KB |
references/patterns-of-eaa.full.md |
Patterns of Enterprise App Architecture |
15 KB |
references/refactoring.full.md |
Refactoring |
17 KB |
references/refactoring-guru.full.md |
Refactoring.Guru |
62 KB |
references/release-it.full.md |
Release It! |
13 KB |
references/the-pragmatic-programmer.full.md |
The Pragmatic Programmer |
13 KB |
references/working-effectively-with-legacy-code.full.md |
Working Effectively with Legacy Code |
13 KB |
Progressive disclosure pattern: load the mini file for daily guidance (triggers,
decision rules, final checklist). Load the full file only for deep sessions,
audits, or when you need the complete rule catalog with code-smell indexes and
technique references.
Known Weaknesses (from repo criticism)
- No empirical measurement of improvement — these are principle-based, not
benchmarked. Apply judgment about whether rules improve actual outcomes.
- Loading too many rule sets at once causes context saturation. Use at most one
primary always-on set + one task-specific on-demand set.
- Rules are book-derived, not incident-derived. The highest-value agent rules
come from real failures, not theory.
- Risk of pseudo-compliance: agent follows the letter of rules while missing
the actual task. Test outputs against real requirements, not rule conformity.
1---
2name: programming-principles
3description: Distilled coding principles from 14 classic software books.
4license: MIT
5compatibility: Platform-agnostic. Works with any agent that supports the Agent Skills
6 directory format. No external dependencies.
7metadata:
8 source: https://skillmd.com/skills/theheavenlyd3mon/programming-principles
9 upstream: https://github.com/mattpocock/agent-rules-books
10---
11
12# Programming Principles (14 Books)
13
14Principles distilled from the `mattpocock/agent-rules-books` repo — 14 pre-made
15AGENTS.md rule sets derived from classic software engineering books. Use this
16skill directly during code review, refactoring, design, and implementation.
17For deeper per-book coverage, load the relevant reference file.
18
19## Task-to-Book Mapping
20
21When the task involves... Load / apply principles from
22────────────────────────────────────────────────────────────────────────
23Everyday implementation & code review Clean Code, Code Complete
24Refactoring existing code Refactoring, WELC
25Architecture / dependency management Clean Architecture, APoSD
26Domain modeling / business rules DDD, DDD Distilled, IDDD
27Enterprise app patterns / layering PoEAA
28Production reliability / stability Release It!
29Data consistency / scalability / events DDIA
30Engineering craft / automation Pragmatic Programmer
31Designing APIs / module boundaries APoSD
32Legacy code / risky changes WELC, Refactoring
33
34## How to Perform a Code Assessment
35
36For a structured, reproducible workflow that combines book principles with
37actual repo exploration, see `references/code-assessment-workflow.md`. It
38covers: loading the evaluation framework, reading the repo and GitHub context,
39deduplicating against existing issues/PRs, classifying findings by book +
40priority, and deciding whether each merits an issue.
41
42## Cross-Cutting Principles
43
44Principles synthesized from multiple books, organized by concern.
45
46### Naming & Communication
47
48- One term per concept across the codebase. RENAMING is design work.
49- Names reveal abstraction, not mechanism. Prefer domain vocabulary over
50 technical implementation detail.
51- Functions are verbs, classes/types are nouns, booleans are predicates.
52- A name needing a comment to explain it is the wrong name.
53- Comments exist for rationale, contracts, warnings, and non-obvious constraints
54 — never to narrate code or compensate for bad names.
55
56### Functions & Routines
57
58- ONE level of abstraction per function. Tell the story top-down.
59- Keep parameters few. Boolean flags mean split the function.
60- Separate commands (mutate) from queries (answer). Never both.
61- When a module exceeds ~400 lines or requires scrolling to understand its
62 full scope, it's a candidate for decomposition. Split by stable
63 responsibility boundary, not by execution order or framework convention.
64- The happy path must be readable. Isolate error handling, edge cases, and
65 cleanup from the main flow.
66- A function too long to name precisely is too long. Extract.
67
68### Architecture & Boundaries
69
70- Source dependencies point INWARD toward higher-level policy. Domain and use
71 cases never import frameworks, databases, UI, or vendor SDKs.
72- Every external dependency — HTTP clients, filesystems, databases, vendor
73 SDKs — must sit behind a trait or interface owned by inner layers. Direct
74 instantiation of infrastructure code inside application or domain logic is
75 a structural violation (Dependency Inversion Principle).
76- Frameworks, databases, delivery mechanisms, and devices are outer-layer
77 details. Keep them behind ports, gateways, and adapters.
78- Organize by business capability / use case first, NOT by technical layer
79 (controllers/, services/, repositories/).
80- The dependency rule: inner layers OWN the interfaces they need; outer layers
81 IMPLEMENT them.
82- Choose boundaries by volatility and policy importance, not by size or habit.
83- A wrapper, layer, or abstraction must HIDE more complexity than it adds.
84 Pass-through layers are debt.
85
86### Data & State
87
88- Prefer types that make invalid states unrepresentable. Use enums for closed
89 sets, Value Objects for meaningful primitives, and booleans only for binary
90 meanings.
91- Make data ownership explicit: distinguish source of truth from derived,
92 cached, or ephemeral data.
93- Treat shared mutable state, globals, and ambient context as costs that must
94 earn themselves.
95- Keep identity, lifecycle, mutation, and loading behavior visible.
96- One authoritative representation per piece of system knowledge. Derive or
97 generate everything else.
98
99### Testing
100
101- Tests are production code: readable, deterministic, aligned with behavior.
102- Keep tests focused on externally visible behavior, not internal
103 implementation details.
104- Add a characterization test before changing behavior in untested code.
105- When fixing a bug, add a regression test that would have caught it.
106- Treat ignored, flaky, or skipped tests as unresolved questions.
107- The Boy Scout Rule for tests: leave the test suite cleaner than you found it.
108
109### Error & Failure Handling
110
111- Distinguish: programmer errors (assert), contract violations (panic/fail),
112 expected domain failures (return/result type), retryable failures, and
113 permanent failures.
114- Treat every dependency, timeout, retry, queue, and degraded state as capable
115 of failing in slow, partial, or prolonged ways.
116- Timeouts on ALL outbound calls. No infinite waits. Finite retries with
117 exponential backoff and jitter. Never retry validation errors or permanent
118 failures — distinguish retryable from non-retryable outcomes.
119- Validate external input at trust boundaries. Never trust shape, size, or
120 semantics of things from outside the process.
121- Fail fast when continuing hides unrecoverable trouble. Let-it-crash only with
122 supervision and isolation.
123
124### Refactoring & Change
125
126- Refactoring is behavior-preserving structural improvement. Never disguise a
127 feature or redesign as cleanup.
128- Work in small, reversible, buildable steps. Split patches too large for
129 local reasoning.
130- Identify the structural friction blocking a change. Refactor BEFORE the
131 feature only when it makes the feature safer or simpler.
132- Target the current blocking smell, not every smell in sight. Stop when the
133 next cleanup would be speculative.
134- Remove duplication when the SAME edit appears a third time.
135- Decompose when a module exceeds ~400 lines or handles 3+ distinct
136 responsibilities. A module you can't name in a single sentence is
137 doing too much — extract the cohesive sub-concepts.
138- Prefer the simplest named move: rename, extract, inline, move, split, or
139 substitute.
140
141## Per-Book Compressed Rules
142
143### Clean Code (Martin)
144Readability, local reasoning, maintainability. Corrects: "working code = clean."
145- Functions: one thing, one level of abstraction, top-down narrative
146- Names: intention-revealing, pronounceable, one concept per term
147- No boolean flags, no output parameters, no hidden side effects
148- Comments only for rationale/constraints, never to narrate
149- Tests as production code: readable, deterministic, fast
150- Boy Scout Rule: leave touched code cleaner
151
152### A Philosophy of Software Design (Ousterhout)
153Deep modules, information hiding, complexity reduction. Corrects: "familiar patterns = simple."
154- Deep modules: small interface, meaningful hidden complexity. Reject thin wrappers.
155- Pull complexity downward into the module that owns the detail
156- Design interfaces around what callers need to know, not how impl works
157- Reduce exception surface via stronger invariants. Define away invalid states.
158- Comments document design decisions and hidden complexity
159- Names, consistency, and obviousness ARE design information
160
161### Clean Architecture (Martin)
162Business rules independent of frameworks/databases/UI. Corrects: "details = architecture."
163- Dependencies point inward. Domain never imports frameworks, DB, UI, vendors.
164- Entities guard enterprise invariants; Use Cases orchestrate one action
165- Frameworks, DB, delivery = outer-layer details behind Ports/Adapters
166- Inner layers OWn interfaces; outer layers IMPLEMENT
167- Use cases are not merged by sharing; duplication from different actors stays
168- Core tests run without real DB, network, framework, or hardware
169
170### Code Complete (McConnell)
171Construction discipline, defect reduction, verifiable code. Corrects: "typing = construction."
172- Sketch pseudocode at consistent abstraction before complex routines
173- Input validation at every trust boundary. Assertions for programmer assumptions.
174- Handle errors at the right abstraction. Never silently continue from corruption.
175- Rising complexity IS defect risk. Split tangled routines.
176- Build in small, verifiable increments. Integrate often.
177- Comments explain intent, constraints, contracts — not mechanics.
178
179### Domain-Driven Design (Evans) + DDD Distilled (Vernon)
180Ubiquitous language, bounded contexts, tactical patterns. Corrects: "model = data schema."
181- Name the Bounded Context before interpreting any term or module
182- One term per concept within the context. Code speaks Ubiquitous Language.
183- Aggregates: small, one root, invariant-protected, one per transaction default
184- Value Objects: immutable, validated at construction, compare by value
185- Repositories return domain objects, not tables or ORM rows
186- Domain Events: past-tense business facts, not property-change notifications
187- Anti-corruption layer at every context boundary
188- Core Domain gets richer modeling; supporting subdomains stay simpler
189
190### Implementing DDD (Vernon)
191Practical DDD: aggregates, events, services, persistence. Corrects: "renamed CRUD = DDD."
192- Reference other Aggregates by identity, not by object graph
193- Domain Services for operations that fit no Entity or Value Object
194- Application Services coordinate use cases — they don't own domain decisions
195- CQRS when consistency or representation needs justify separate models
196- Event Sourcing only when the event sequence IS the right persistence model
197- Test invariants, valid/invalid state transitions, and events directly
198
199### Patterns of Enterprise Application Architecture (Fowler)
200Layering, patterns for enterprise apps. Corrects: "more patterns = better design."
201- Choose business logic pattern by force: Transaction Script → Table Module → Domain Model
202- Service Layer for use-case coordination and transaction boundaries
203- Repository speaks domain terms; Data Mapper keeps SQL out of domain objects
204- Unit of Work for one logical commit; Identity Map for one identity per scope
205- Remote Facade + DTOs at cross-layer boundaries — never leak domain internals
206- Session state chosen deliberately: client, server, or DB with scaling accounted for
207
208### Refactoring (Fowler)
209Behavior-preserving structural improvement. Corrects: "cleanup = rewrite."
210- Preserve observable behavior. Isolate behavior change from structural change.
211- Small, reversible, testable steps. Safety net before risky work.
212- Preparatory refactoring: reshape blocking structure BEFORE the feature
213- Targeted at the current blocking smell, not every smell in sight
214- Simplest named move: rename, extract, inline, move, encapsulate, substitute
215- Stop when the requested change is easy and the blocking smell is gone
216
217### Working Effectively with Legacy Code (Feathers)
218Safe change in untested code. Corrects: "rewrite = first move."
219- Legacy = code without trustworthy tests. Characterize before redesign.
220- Find or create a seam: place to change behavior without editing surrounding code
221- Break the ONE blocking dependency before making the change
222- Sprout Method, Sprout Class, Wrap Method, Wrap Class for insertion
223- Leave the area more testable than found
224- Reject: hidden dependency expansion, cosmetic-only refactoring, big rewrites
225
226### Designing Data-Intensive Applications (Kleppmann)
227Distributed data, consistency, events, replication. Corrects: "everything is local/ordered/exactly-once."
228- Source of truth, derived representations, and consistency expectations must be EXPLICIT
229- Treat crashes, partial writes, duplicates, and timeouts as normal input
230- Write semantics: durable when? visible when? conflicts how? stale reads allowed?
231- Events describe facts. Consumers tolerate lag, duplicates, replay, versioned payloads.
232- Schemas, APIs, and events evolve across old/new readers/writers
233- Partition by workload-relevant locality; make hot-key and cross-partition costs explicit
234- Transactions and isolation matched to actual invariants, not blanket defaults
235
236### Release It! (Nygard)
237Production reliability, stability patterns. Corrects: "happy path = production readiness."
238- Timeouts on every outbound call. No infinite waits. Bounded retries with backoff.
239- Circuit breakers, bulkheads, fast failure to isolate dependency failures
240- Design overload behavior: finite queues, load shedding, capacity for critical traffic
241- Startup, health checks, migrations, and operational controls: restartable, observable
242- Validate external responses for shape, plausibility, and semantics before trusting
243- Observability at every boundary: latency, saturation, errors, queue depth, breaker state
244
245### The Pragmatic Programmer (Hunt & Thomas)
246Engineering craft, accountability, automation. Corrects: "local edit = done."
247- One authoritative source per fact. Everything else derives or traces.
248- Preserve orthogonality: independent components, narrow interfaces, separated concerns
249- Tracer bullets over piles of isolated pieces. Validate architecture end-to-end early.
250- Automate repetitive, error-prone, easy-to-forget work
251- Shorten feedback loops: relevant tests, automated checks, cheap early signals
252- Broken windows: fix or visibly contain small quality decay before it normalizes
253- Debug from reproduced facts: observe, isolate, explain, fix, verify
254
255### Refactoring.Guru
256Smell catalog and technique catalog. Corrects: "pattern = always the answer."
257- Diagnose the smell before choosing the technique
258- Prefer the simplest treatment: rename before extract, extract before redesign
259- Each smell has a specific root cause and treatment path
260- See `references/refactoring-guru-smells.md` for the full catalog
261
262## Compatibility Guide
263
264Books that CONFLICT (do not load as equal guidance):
265- DDD ❌ PoEAA — different data ownership paradigms
266- IDDD ❌ PoEAA — same conflict at implementation level
267
268Books that OVERLAP (choose one, they push similar pressure):
269- Clean Code 🔁 Pragmatic Programmer, Code Complete, APoSD — code quality
270- DDD 🔁 DDD Distilled, IDDD — DDD at different depths; pick the level you need
271- Clean Architecture 🔁 IDDD, PoEAA — architecture/layering overlap
272- Refactoring 🔁 Refactoring.Guru — code improvement; choose Refactoring for strategy, Guru for catalog
273
274All other pairs are complementary. Default: one primary always-on book, others
275loaded on-demand per task.
276
277## Local Reference Files
278
279Each book's mini rule set is available as a local reference file under
280`references/`. Load any with:
281
282```
283skill_view(name='programming-principles', file_path='references/{book-dir}.mini.md')
284```
285
286| File | Book |
287|------|------|
288| `references/a-philosophy-of-software-design.mini.md` | A Philosophy of Software Design |
289| `references/clean-architecture.mini.md` | Clean Architecture |
290| `references/clean-code.mini.md` | Clean Code |
291| `references/code-complete.mini.md` | Code Complete |
292| `references/designing-data-intensive-apps.mini.md` | Designing Data-Intensive Applications |
293| `references/domain-driven-design.mini.md` | Domain-Driven Design |
294| `references/domain-driven-design-distilled.mini.md` | DDD Distilled |
295| `references/implementing-domain-driven-design.mini.md` | Implementing DDD |
296| `references/patterns-of-eaa.mini.md` | Patterns of Enterprise App Architecture |
297| `references/refactoring.mini.md` | Refactoring |
298| `references/refactoring-guru.mini.md` | Refactoring.Guru |
299| `references/release-it.mini.md` | Release It! |
300| `references/the-pragmatic-programmer.mini.md` | The Pragmatic Programmer |
301| `references/working-effectively-with-legacy-code.mini.md` | Working Effectively with Legacy Code |
302| `references/code-assessment-workflow.md` | Assessment methodology — not a book, but the workflow for combining all books against a real repo |
303
304Each book also has a **full** version (11-63 KB) for deep reference when you need
305the complete rule catalog. Load on demand:
306
307```
308skill_view(name='programming-principles', file_path='references/{name}.full.md')
309```
310
311| Full File | Book | Size |
312|-----------|------|------|
313| `references/a-philosophy-of-software-design.full.md` | A Philosophy of Software Design | 13 KB |
314| `references/clean-architecture.full.md` | Clean Architecture | 17 KB |
315| `references/clean-code.full.md` | Clean Code | 13 KB |
316| `references/code-complete.full.md` | Code Complete | 12 KB |
317| `references/designing-data-intensive-apps.full.md` | Designing Data-Intensive Applications | 16 KB |
318| `references/domain-driven-design.full.md` | Domain-Driven Design | 42 KB |
319| `references/domain-driven-design-distilled.full.md` | DDD Distilled | 11 KB |
320| `references/implementing-domain-driven-design.full.md` | Implementing DDD | 12 KB |
321| `references/patterns-of-eaa.full.md` | Patterns of Enterprise App Architecture | 15 KB |
322| `references/refactoring.full.md` | Refactoring | 17 KB |
323| `references/refactoring-guru.full.md` | Refactoring.Guru | 62 KB |
324| `references/release-it.full.md` | Release It! | 13 KB |
325| `references/the-pragmatic-programmer.full.md` | The Pragmatic Programmer | 13 KB |
326| `references/working-effectively-with-legacy-code.full.md` | Working Effectively with Legacy Code | 13 KB |
327
328Progressive disclosure pattern: load the **mini** file for daily guidance (triggers,
329decision rules, final checklist). Load the **full** file only for deep sessions,
330audits, or when you need the complete rule catalog with code-smell indexes and
331technique references.
332
333## Known Weaknesses (from repo criticism)
334
335- No empirical measurement of improvement — these are principle-based, not
336 benchmarked. Apply judgment about whether rules improve actual outcomes.
337- Loading too many rule sets at once causes context saturation. Use at most one
338 primary always-on set + one task-specific on-demand set.
339- Rules are book-derived, not incident-derived. The highest-value agent rules
340 come from real failures, not theory.
341- Risk of pseudo-compliance: agent follows the letter of rules while missing
342 the actual task. Test outputs against real requirements, not rule conformity.