The Pragmatic Programmer (Hunt & Thomas) — Full rules — comprehensive mandatory coding standards. Use when asked to apply The Pragmatic Programmer principles or review code against The Pragmatic Programmer standards.
The Pragmatic Programmer (Hunt & Thomas) — Full rules — comprehensive mandatory coding standards. Use when asked to apply The Pragmatic Programmer principles or review code against The Pragmatic Programmer standards.
origin
github.com/ciembor/agent-rules-books (MIT)
license
MIT
version
1.0.0
compatibility
yana-ai >= 0.14.0
OBEY The Pragmatic Programmer by Andrew Hunt and David Thomas
Purpose
This repository follows The Pragmatic Programmer in the sense of Andrew Hunt and David Thomas:
work pragmatically, take responsibility for quality, automate what is repetitive, and keep code and process adaptable.
All code generation, edits, and reviews must optimize for:
clear ownership and responsibility
avoiding duplicated knowledge
orthogonality
incremental delivery
ruthless feedback
automation of repetitive work
code that is easy to change and easy to reason about
This file is a binding engineering policy: MUST is binding, SHOULD is a strong default, and MUST NOT is forbidden.
Primary Directive
Be pragmatic, not dogmatic.
When uncertain, choose the option that:
reduces knowledge duplication
keeps concerns independent
shortens feedback loops
leaves the system easier to change
makes intent clearer to future maintainers
Do not follow style or process rituals that do not improve outcomes.
Core Pragmatic Principles
Own the Result
Take responsibility for the quality and changeability of the code you touch.
Do not blame tooling, framework defaults, or “existing style” for avoidable bad design.
Surface trade-offs, risks, and uncertainty explicitly.
Think Beyond the Local Edit
Every change affects future maintainability.
Small quick fixes that multiply future cost are usually a bad bargain.
Leave the area better than you found it.
Favor Adaptability
Build systems that are easy to observe, test, and change.
Prefer flexible boundaries over brittle cleverness.
Avoid premature commitment when requirements are still moving.
Named Pragmatic Habits
Treat quality as a requirement to negotiate with users and sponsors, not as an abstract pursuit of perfection.
Stop polishing when the software is good enough for its real users and risks.
Keep a knowledge portfolio: invest in learning, diversify skills, and revisit stale assumptions.
Communicate decisions, risks, and tradeoffs clearly enough that others can act on them.
Watch for entropy and small broken windows before they become normal.
Use Stone Soup tactics only to create real progress, not to hide missing agreement.
Watch for boiled-frog drift where gradual degradation becomes invisible.
DRY Rules
DRY means do not duplicate knowledge, not merely do not duplicate text.
A business rule should have one authoritative representation.
Validation logic for the same concept should not be scattered.
Status semantics, mappings, and calculations should not be copied across layers.
Configuration and schema meaning should not be repeated inconsistently.
Avoid duplicated process steps that can be automated.
Anti-patterns (MUST NOT):
the same rule encoded in UI, API, service, and DB trigger with no ownership
copy/paste with minor edits for “just this one case”
duplicated manual deployment or testing steps
one concept with multiple partially aligned implementations
Orthogonality Rules
Keep components independent so one change does not force unrelated changes elsewhere.
Minimize hidden couplings through globals, ambient context, or shared mutable state.
Avoid overlapping responsibilities between modules.
Separate policy from mechanism, data from presentation, orchestration from computation.
Anti-patterns (MUST NOT):
one change requiring edits in many unrelated places
one module knowing too much about internal details of others
Prefer a thin end-to-end slice over a pile of isolated pieces.
Use tracer bullets to validate architecture, integration, and assumptions early.
Keep the first slice simple but real enough to prove the path.
Refine from working feedback instead of predicting everything up front.
Anti-patterns (MUST NOT):
building many layers before anything runs end to end
treating prototypes as production without hardening
waiting for perfect certainty before integrating
Reversibility, Domain Languages, and Requirements
Preserve reversibility when requirements, vendors, platforms, databases, or deployment environments may change.
Avoid irreversible commitments until evidence makes them worth the cost.
Use a small domain language when it expresses domain rules more directly than general-purpose code.
Keep domain languages readable by the people who must validate or change them.
Dig for real requirements; do not accept current implementation details as requirements.
Do not fall into the specification trap where prose keeps growing but uncertainty does not fall.
Start building a working slice when further specification no longer reduces meaningful risk.
Respect informed hesitation: if the team is not ready, identify the missing information or feedback.
Prototyping Rules
Use prototypes to learn, not to pretend you are done.
Be explicit about what a prototype proves and what it does not.
Do not let experimental shortcuts silently become production defaults.
Carry forward only the lessons or code that still deserve to survive.
Automation Rules
Automate repetitive, error-prone, or easy-to-forget tasks.
Prefer repeatable scripts over tribal-knowledge commands.
Build, test, lint, format, package, and deploy steps should be reproducible.
Keep local automation aligned with the project's shared build, test, and release automation.
Anti-patterns (MUST NOT):
“works on my machine” build steps
manual release rituals with many hidden prerequisites
documentation that describes what a script should do instead of having the script
Feedback Loop Rules
Shorten the time between change and feedback.
Run relevant tests early and often.
Use automated checks where they reduce real risk.
Make failure visible fast.
Prefer a cheap early signal over a late expensive surprise.
Design by Contract and Assertions
Make assumptions explicit in code.
Use assertions or invariant checks where they clarify impossible states.
Distinguish between programmer errors, contract violations, and expected domain failures.
Keep contracts close to the abstraction they protect.
Anti-patterns (MUST NOT):
relying on comments for critical preconditions
hiding invariant assumptions in scattered callers
returning nonsense values for impossible states
Error Handling and Recovery
Detect errors close to their source.
Do not discard useful error context.
Let callers distinguish retryable, recoverable, and permanent failures where relevant.
Fail loudly enough to diagnose, but with boundaries that prevent system-wide collapse.
Naming and Communication Rules
Code is communication first.
Use names that reflect domain meaning and developer intent.
Prefer clarity over cleverness.
Write comments or docs where they convey decision rationale, contracts, or non-obvious behavior.
Writing is part of engineering, not overhead.
Text and Data Rules
Favor plain text and open formats for long-lived automation and integration where practical.
Make scripts and configs inspectable and diffable.
Keep serialization and config formats explicit and version-aware.
Avoid opaque binary or framework-specific lock-in unless justified.
State and Concurrency Rules
Treat shared mutable state as expensive.
Prefer immutability, isolation, or explicit synchronization when state is shared.
Keep concurrency assumptions visible.
Do not add asynchronous complexity unless it clearly earns its cost.
Estimation and Increment Rules
Break work into pieces that can be reasoned about, tested, and corrected.
Keep plans and estimates honest about uncertainty.
Prefer small deliverable increments to large hidden progress.
Make risk visible early.
Tooling Rules
Know and use the tools that amplify correctness and speed.
Do not hand-do tasks that should be scripted.
Keep editor, formatter, lint, tests, and local scripts aligned with team standards.
Improve the toolchain when repeated friction appears.
Basic Tool Rules
Use source control for every meaningful project, including small or solo work.
Prefer inspectable plain text for long-lived scripts, configs, data, and generated sources when practical.
Use shell tools for exploration, automation, and repeatable transformations where they fit.
Use editor capabilities to reduce repetitive manual edits.
Use text manipulation languages or scripts for systematic changes that would be error-prone by hand.
Use code generators to remove duplicated mechanical work, but keep the source specification authoritative.
When debugging, do not guess: reproduce, observe, isolate, explain, fix, and verify.
Do not rely on generated code, tools, specifications, or formal methods you do not understand.
Resource and Coupling Rules
Finish what you start when allocating, opening, locking, or otherwise acquiring resources.
Release every resource you acquire, preferably in the opposite order from acquisition.
Keep resource ownership local and explicit.
Apply shy-code and Law of Demeter discipline so modules reveal only necessary information.
Avoid temporal coupling; make ordering requirements explicit or remove them.
Use metaprogramming only when it reduces duplication or improves adaptability without hiding behavior.
Use blackboard-style coordination only when uncertain order, multiple sources, or opportunistic collaboration justify it.
Understand algorithmic growth before writing or accepting performance-sensitive code.
Project and Team Rules
Build pragmatic teams around shared responsibility, automation, fast feedback, and visible quality.
Test unit behavior, integration, validation and verification, resource exhaustion, errors and recovery, performance, usability, and tests themselves where relevant.
Treat writing as engineering work: docs, comments, commit messages, scripts, and tests must communicate intent.
Set expectations explicitly with users and stakeholders.
Take pride in code, tests, documentation, and generated artifacts.
Be skeptical of methods, diagrams, and ceremonies that do not improve the work.
Broken Windows Rule
Do not normalize local decay.
Fix small quality problems before they signal that nobody cares.
Tidy the code you touch where the cost is low and the value is immediate.
Avoid leaving behind “temporary” hacks with no cleanup plan.
Review Rules
When reviewing code, actively look for:
duplicated knowledge, not just duplicated lines
hidden couplings
missing automation opportunities
long feedback loops
local fixes that worsen future changeability
unclear contracts or assumptions
non-repeatable manual processes
brittle integration points
code that communicates poorly
Forbidden Patterns
Cargo-Cult Process
rituals followed with no benefit
documentation and checklists replacing automation
Knowledge Duplication
same rule in many places
copied logic because “layers need it too”
Non-Orthogonal Design
modules with overlapping responsibilities
changes leaking across boundaries by default
Manual Everything
repeated human steps for build, test, release, setup, or validation
hidden local environment assumptions
Prototype Fossilization
experimental code promoted to production without redesign or hardening
Code Generation Rules
When generating code, default to:
one clear source of truth for each rule
orthogonal responsibilities
fast local feedback
automation over repeated manual work
explicit contracts and assumptions
readable names and communication
incremental end-to-end slices when building new capabilities
Avoid by default:
copy/paste rule duplication
tangled modules
fragile manual workflows
overcommitting to an architecture before the first end-to-end path works
Testing Rules
Keep tests runnable quickly and often.
Prefer tests that align with the business or technical contract being protected.
Use automation so validation is habitual, not heroic.
Keep flaky or environment-dependent tests out of the critical feedback path where possible.
Review Checklist
Before finalizing any change, verify:
Did we reduce duplicated knowledge?
Are responsibilities more orthogonal after the change?
Did we improve or preserve fast feedback?
Did we automate anything repetitive that was hurting reliability?
Are contracts and assumptions clearer?
Is the code easier to communicate about?
Did we avoid prototype shortcuts becoming silent production defaults?
Did we fix at least one small “broken window” if it was in the touched area?
If any answer is no, revise before shipping.
Final Instruction
When uncertain, choose the option that:
removes duplicated knowledge
keeps concerns orthogonal
shortens feedback loops
improves automation
leaves the codebase easier to change tomorrow
Be pragmatic, and make the right thing the easy thing.
