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.full.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-42 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')
Note: references/refactoring-guru.full.md is an index that routes to two part
files (refactoring-guru.full-smells-and-priorities.md and
refactoring-guru.full-technique-playbook-and-safety.md). Loading the index
shows the "Parts of this reference" table; then load the specific part you need.
| 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 |
index + 2 parts |
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-principles3description: Apply distilled coding principles from 14 classic software books to code review, refactoring, design, and implementation decisions. Do not use for language- or framework-specific tutorials, tool manuals, or tasks already governed by a project's established conventions.4license: MIT5compatibility: Platform-agnostic. Works with any agent that supports the Agent Skills6 directory format. No external dependencies.7metadata:8 source: https://skillmd.com/skills/magnus919/programming-principles9 upstream: https://github.com/mattpocock/agent-rules-books10---1112# Programming Principles (14 Books)1314Principles distilled from the `mattpocock/agent-rules-books` repo — 14 pre-made15AGENTS.md rule sets derived from classic software engineering books. Use this16skill directly during code review, refactoring, design, and implementation.17For deeper per-book coverage, load the relevant reference file.1819## Task-to-Book Mapping2021When the task involves... Load / apply principles from22────────────────────────────────────────────────────────────────────────23Everyday implementation & code review Clean Code, Code Complete24Refactoring existing code Refactoring, WELC25Architecture / dependency management Clean Architecture, APoSD26Domain modeling / business rules DDD, DDD Distilled, IDDD27Enterprise app patterns / layering PoEAA28Production reliability / stability Release It!29Data consistency / scalability / events DDIA30Engineering craft / automation Pragmatic Programmer31Designing APIs / module boundaries APoSD32Legacy code / risky changes WELC, Refactoring3334## How to Perform a Code Assessment3536For a structured, reproducible workflow that combines book principles with37actual repo exploration, see `references/code-assessment-workflow.md`. It38covers: 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.4142## Cross-Cutting Principles4344Principles synthesized from multiple books, organized by concern.4546### Naming & Communication4748- One term per concept across the codebase. RENAMING is design work.49- Names reveal abstraction, not mechanism. Prefer domain vocabulary over50 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 constraints54 — never to narrate code or compensate for bad names.5556### Functions & Routines5758- 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 its62 full scope, it's a candidate for decomposition. Split by stable63 responsibility boundary, not by execution order or framework convention.64- The happy path must be readable. Isolate error handling, edge cases, and65 cleanup from the main flow.66- A function too long to name precisely is too long. Extract.6768### Architecture & Boundaries6970- Source dependencies point INWARD toward higher-level policy. Domain and use71 cases never import frameworks, databases, UI, or vendor SDKs.72- Every external dependency — HTTP clients, filesystems, databases, vendor73 SDKs — must sit behind a trait or interface owned by inner layers. Direct74 instantiation of infrastructure code inside application or domain logic is75 a structural violation (Dependency Inversion Principle).76- Frameworks, databases, delivery mechanisms, and devices are outer-layer77 details. Keep them behind ports, gateways, and adapters.78- Organize by business capability / use case first, NOT by technical layer79 (controllers/, services/, repositories/).80- The dependency rule: inner layers OWN the interfaces they need; outer layers81 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.8586### Data & State8788- Prefer types that make invalid states unrepresentable. Use enums for closed89 sets, Value Objects for meaningful primitives, and booleans only for binary90 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 must94 earn themselves.95- Keep identity, lifecycle, mutation, and loading behavior visible.96- One authoritative representation per piece of system knowledge. Derive or97 generate everything else.9899### Testing100101- Tests are production code: readable, deterministic, aligned with behavior.102- Keep tests focused on externally visible behavior, not internal103 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.108109### Error & Failure Handling110111- Distinguish: programmer errors (assert), contract violations (panic/fail),112 expected domain failures (return/result type), retryable failures, and113 permanent failures.114- Treat every dependency, timeout, retry, queue, and degraded state as capable115 of failing in slow, partial, or prolonged ways.116- Timeouts on ALL outbound calls. No infinite waits. Finite retries with117 exponential backoff and jitter. Never retry validation errors or permanent118 failures — distinguish retryable from non-retryable outcomes.119- Validate external input at trust boundaries. Never trust shape, size, or120 semantics of things from outside the process.121- Fail fast when continuing hides unrecoverable trouble. Let-it-crash only with122 supervision and isolation.123124### Refactoring & Change125126- Refactoring is behavior-preserving structural improvement. Never disguise a127 feature or redesign as cleanup.128- Work in small, reversible, buildable steps. Split patches too large for129 local reasoning.130- Identify the structural friction blocking a change. Refactor BEFORE the131 feature only when it makes the feature safer or simpler.132- Target the current blocking smell, not every smell in sight. Stop when the133 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+ distinct136 responsibilities. A module you can't name in a single sentence is137 doing too much — extract the cohesive sub-concepts.138- Prefer the simplest named move: rename, extract, inline, move, split, or139 substitute.140141## Per-Book Compressed Rules142143### Clean Code (Martin)144Readability, local reasoning, maintainability. Corrects: "working code = clean."145- Functions: one thing, one level of abstraction, top-down narrative146- Names: intention-revealing, pronounceable, one concept per term147- No boolean flags, no output parameters, no hidden side effects148- Comments only for rationale/constraints, never to narrate149- Tests as production code: readable, deterministic, fast150- Boy Scout Rule: leave touched code cleaner151152### 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 detail156- Design interfaces around what callers need to know, not how impl works157- Reduce exception surface via stronger invariants. Define away invalid states.158- Comments document design decisions and hidden complexity159- Names, consistency, and obviousness ARE design information160161### 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 action165- Frameworks, DB, delivery = outer-layer details behind Ports/Adapters166- Inner layers OWn interfaces; outer layers IMPLEMENT167- Use cases are not merged by sharing; duplication from different actors stays168- Core tests run without real DB, network, framework, or hardware169170### Code Complete (McConnell)171Construction discipline, defect reduction, verifiable code. Corrects: "typing = construction."172- Sketch pseudocode at consistent abstraction before complex routines173- 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.178179### 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 module182- One term per concept within the context. Code speaks Ubiquitous Language.183- Aggregates: small, one root, invariant-protected, one per transaction default184- Value Objects: immutable, validated at construction, compare by value185- Repositories return domain objects, not tables or ORM rows186- Domain Events: past-tense business facts, not property-change notifications187- Anti-corruption layer at every context boundary188- Core Domain gets richer modeling; supporting subdomains stay simpler189190### Implementing DDD (Vernon)191Practical DDD: aggregates, events, services, persistence. Corrects: "renamed CRUD = DDD."192- Reference other Aggregates by identity, not by object graph193- Domain Services for operations that fit no Entity or Value Object194- Application Services coordinate use cases — they don't own domain decisions195- CQRS when consistency or representation needs justify separate models196- Event Sourcing only when the event sequence IS the right persistence model197- Test invariants, valid/invalid state transitions, and events directly198199### 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 Model202- Service Layer for use-case coordination and transaction boundaries203- Repository speaks domain terms; Data Mapper keeps SQL out of domain objects204- Unit of Work for one logical commit; Identity Map for one identity per scope205- Remote Facade + DTOs at cross-layer boundaries — never leak domain internals206- Session state chosen deliberately: client, server, or DB with scaling accounted for207208### 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 feature213- Targeted at the current blocking smell, not every smell in sight214- Simplest named move: rename, extract, inline, move, encapsulate, substitute215- Stop when the requested change is easy and the blocking smell is gone216217### 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 code221- Break the ONE blocking dependency before making the change222- Sprout Method, Sprout Class, Wrap Method, Wrap Class for insertion223- Leave the area more testable than found224- Reject: hidden dependency expansion, cosmetic-only refactoring, big rewrites225226### 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 EXPLICIT229- Treat crashes, partial writes, duplicates, and timeouts as normal input230- 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/writers233- Partition by workload-relevant locality; make hot-key and cross-partition costs explicit234- Transactions and isolation matched to actual invariants, not blanket defaults235236### 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 failures240- Design overload behavior: finite queues, load shedding, capacity for critical traffic241- Startup, health checks, migrations, and operational controls: restartable, observable242- Validate external responses for shape, plausibility, and semantics before trusting243- Observability at every boundary: latency, saturation, errors, queue depth, breaker state244245### 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 concerns249- Tracer bullets over piles of isolated pieces. Validate architecture end-to-end early.250- Automate repetitive, error-prone, easy-to-forget work251- Shorten feedback loops: relevant tests, automated checks, cheap early signals252- Broken windows: fix or visibly contain small quality decay before it normalizes253- Debug from reproduced facts: observe, isolate, explain, fix, verify254255### Refactoring.Guru256Smell catalog and technique catalog. Corrects: "pattern = always the answer."257- Diagnose the smell before choosing the technique258- Prefer the simplest treatment: rename before extract, extract before redesign259- Each smell has a specific root cause and treatment path260- See `references/refactoring-guru.full.md` for the full catalog261262## Compatibility Guide263264Books that CONFLICT (do not load as equal guidance):265- DDD ❌ PoEAA — different data ownership paradigms266- IDDD ❌ PoEAA — same conflict at implementation level267268Books that OVERLAP (choose one, they push similar pressure):269- Clean Code 🔁 Pragmatic Programmer, Code Complete, APoSD — code quality270- DDD 🔁 DDD Distilled, IDDD — DDD at different depths; pick the level you need271- Clean Architecture 🔁 IDDD, PoEAA — architecture/layering overlap272- Refactoring 🔁 Refactoring.Guru — code improvement; choose Refactoring for strategy, Guru for catalog273274All other pairs are complementary. Default: one primary always-on book, others275loaded on-demand per task.276277## Local Reference Files278279Each book's mini rule set is available as a local reference file under280`references/`. Load any with:281282```283skill_view(name='programming-principles', file_path='references/{book-dir}.mini.md')284```285286| 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 |303304Each book also has a **full** version (11-42 KB) for deep reference when you need305the complete rule catalog. Load on demand:306307```308skill_view(name='programming-principles', file_path='references/{name}.full.md')309```310311Note: `references/refactoring-guru.full.md` is an index that routes to two part312files (`refactoring-guru.full-smells-and-priorities.md` and313`refactoring-guru.full-technique-playbook-and-safety.md`). Loading the index314shows the "Parts of this reference" table; then load the specific part you need.315316| Full File | Book | Size |317|-----------|------|------|318| `references/a-philosophy-of-software-design.full.md` | A Philosophy of Software Design | 13 KB |319| `references/clean-architecture.full.md` | Clean Architecture | 17 KB |320| `references/clean-code.full.md` | Clean Code | 13 KB |321| `references/code-complete.full.md` | Code Complete | 12 KB |322| `references/designing-data-intensive-apps.full.md` | Designing Data-Intensive Applications | 16 KB |323| `references/domain-driven-design.full.md` | Domain-Driven Design | 42 KB |324| `references/domain-driven-design-distilled.full.md` | DDD Distilled | 11 KB |325| `references/implementing-domain-driven-design.full.md` | Implementing DDD | 12 KB |326| `references/patterns-of-eaa.full.md` | Patterns of Enterprise App Architecture | 15 KB |327| `references/refactoring.full.md` | Refactoring | 17 KB |328| `references/refactoring-guru.full.md` | Refactoring.Guru | index + 2 parts |329| `references/release-it.full.md` | Release It! | 13 KB |330| `references/the-pragmatic-programmer.full.md` | The Pragmatic Programmer | 13 KB |331| `references/working-effectively-with-legacy-code.full.md` | Working Effectively with Legacy Code | 13 KB |332333Progressive disclosure pattern: load the **mini** file for daily guidance (triggers,334decision rules, final checklist). Load the **full** file only for deep sessions,335audits, or when you need the complete rule catalog with code-smell indexes and336technique references.337338## Known Weaknesses (from repo criticism)339340- No empirical measurement of improvement — these are principle-based, not341 benchmarked. Apply judgment about whether rules improve actual outcomes.342- Loading too many rule sets at once causes context saturation. Use at most one343 primary always-on set + one task-specific on-demand set.344- Rules are book-derived, not incident-derived. The highest-value agent rules345 come from real failures, not theory.346- Risk of pseudo-compliance: agent follows the letter of rules while missing347 the actual task. Test outputs against real requirements, not rule conformity.