pragmatic-programmer
Skill1 starsChanged 5 months agoMITView on GitHub
Distill the five most impactful principles from The Pragmatic Programmer (Hunt & Thomas) into actionable rules for AI-assisted coding: DRY, orthogonality, reversible decisions, tracer bullets, and broken windows. These principles guard against the most common failure modes of AI-generated code — duplicated logic, implicit coupling, premature lock-in, uneven depth, and accumulating cruft — by replacing them with disciplined, maintainable habits. Apply at architecture decisions, code review, and any time the codebase starts to feel tangled or brittle. Reach for the…
4 other projects use a version of this.
Adopted by
Most recently taken up by
- travissmithv1/claude-skillstheir own version, first seen Nov 16, 2026
- grndlvl/software-patternstheir own version, first seen Nov 1, 2026
- Adhamxon/claude-code-skillstheir own version, first seen Jul 30, 2026
- wondelai/skillstheir own version, first seen Jul 16, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- wondelai/skills★ 2.7ksame name
- grndlvl/software-patterns★ 17same name
- Adhamxon/claude-code-skills★ 2same name
- travissmithv1/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository117 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- advanced-orchestrationSkill
- architect-agentSkill
- implementer-agentSkill
- quality-councilSkill
- reviewer-agentSkill
- tester-agentSkill
- writer-critic-pairSkill
- authoring-skillsSkill
- api-endpoint-qualitySkill
- async-job-qualitySkill
- auth-qualitySkill
- db-migration-qualitySkill
- frontend-state-qualitySkill
- acceptance-criteriaSkill
- adaptive-flowSkill
- adaptive-prompt-selectionSkill
- adversarial-code-reviewSkill
- architecture-decision-recordsSkill
- brainstormingSkill
- brownfield-spec-enhancementSkill
- bug-fix-lifecycleSkill
- checkpoint-validationSkill
- cicd-integrationSkill
- clarify-before-codeSkill
- claude-code-hooks-packSkill
- code-context-packSkill
- code-intelligence-reviewSkill
- context-policySkill
- context-rich-implementationSkill
- crash-proof-planningSkill
- critique-pass-protocolSkill
- dependency-aware-task-orderingSkill
- deprecation-migrationSkill
- disciplined-diagnosisSkill
- docs-authorSkill
- executing-plansSkill
- external-skillSkill
- finishing-a-development-branchSkill
- git-guardrailsSkill
- goal-driven-executionSkill
- grill-user-before-buildingSkill
- guard-bypass-protocolSkill
- improve-codebase-architectureSkill
- incremental-reviewSkill
- issue-slicingSkill
- lessons-learned-dbSkill
- loop-engineeringSkill
- model-aware-configSkill
- model-weakness-memorySkill
- multi-repo-learningSkill
- orchestration-workflowsSkill
- plan-driven-executionSkill
- plan-from-specSkill
- prd-from-contextSkill
- project-constitutionSkill
- prompt-architectureSkill
- prototype-before-commitmentSkill
- quality-engineSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. 0 are common, 17 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
17
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 34
Before writing new logic, search the codebase for existing implementations of the same concept.
- Distinctive: line 36
When a change requires touching multiple locations, that is a signal that DRY was violated.
- Distinctive: line 39
When AI generates a new function, compare it against existing ones — LLMs frequently regenerate what already exists rather than reusing it.
- Distinctive: line 48
Before adding a dependency between two modules, ask: "Does this create coupling that will make future changes harder?"
- Distinctive: line 49
Keep business logic separate from infrastructure.
- Distinctive: line 50
Test modules in isolation.
- Distinctive: line 51
When AI generates code that wires together multiple concerns (e.g., a function that queries a DB and formats HTML), split it into …
- Distinctive: line 52
Avoid global state and singletons — they create invisible coupling between everything they touch.
- Distinctive: line 61
Document the *why* behind decisions, not just the *what*.
- Distinctive: line 62
When choosing between two viable approaches, prefer the one that is easier to reverse.
- Distinctive: line 63
Use feature flags, dependency injection, or adapter patterns for decisions that touch multiple subsystems.
- Distinctive: line 64
Keep the cost of change visible.
- Distinctive: line 74
Do not perfect any single module before the whole flow is functional.
- Distinctive: line 75
After the tracer bullet works, fill in layers: add error handling, edge cases, validation, optimization — in that order.
- Distinctive: line 77
When AI suggests deep optimization before the full flow works, push back.
- Distinctive: line 78
Use the tracer bullet to discover integration surprises early — schema mismatches, API gaps, configuration errors — where they are cheap to …
- Distinctive: line 87
Leave code cleaner than you found it — but surgically.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Pragmatic Programmer Principles
Purpose
Distill the five most impactful principles from The Pragmatic Programmer (Hunt & Thomas) into actionable rules for AI-assisted coding: DRY, orthogonality, reversible decisions, tracer bullets, and broken windows. These principles guard against the most common failure modes of AI-generated code — duplicated logic, implicit coupling, premature lock-in, uneven depth, and accumulating cruft — by replacing them with disciplined, maintainable habits.
When to use
Apply at architecture decisions, code review, and any time the codebase starts to feel tangled or brittle. Reach for the individual principle that matches the symptom: rising duplication → DRY, unexpected cascading changes → orthogonality, fear of commitment → reversible decisions, half-baked polish → tracer bullets, spreading disrepair → broken windows.
Inputs
The current code, the change being considered, any architectural constraints, and whichever principle(s) the situation calls for.
Workflow
1. DRY — Don't Repeat Yourself
Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.
Concrete rules for AI:
- Before writing new logic, search the codebase for existing implementations of the same concept. Use semantic search or grep — the same idea often appears under different names.
- Extract shared logic into a single function, class, or module. Do not copy-paste code with minor modifications.
- When a change requires touching multiple locations, that is a signal that DRY was violated. Fix the duplication first, then make the change.
- DRY applies to knowledge, not coincidental similarity. Two loops that happen to look the same but represent different domain concepts should not be unified.
- Watch for duplication in: data schemas, validation logic, configuration paths, error handling patterns, test setup, and documentation.
- When AI generates a new function, compare it against existing ones — LLMs frequently regenerate what already exists rather than reusing it.
2. Orthogonality — Independence of Concerns
Changes in one area should not cascade to unrelated areas.
Concrete rules for AI:
- Design modules with narrow, well-defined interfaces. A module's internal changes should never leak through its public API.
- Before adding a dependency between two modules, ask: "Does this create coupling that will make future changes harder?"
- Keep business logic separate from infrastructure. Database schema changes should not require UI changes; API contract changes should not require database changes.
- Test modules in isolation. If testing A requires setting up B and C, the system is not orthogonal.
- When AI generates code that wires together multiple concerns (e.g., a function that queries a DB and formats HTML), split it into orthogonal layers.
- Avoid global state and singletons — they create invisible coupling between everything they touch.
3. Reversible Decisions — Keep Options Open
Prefer decisions that can be undone. The cost of change should stay low throughout the project.
Concrete rules for AI:
- Favor interfaces and abstractions over concrete implementations at integration points. Swap a library binding behind an interface rather than sprinkling its API calls everywhere.
- Document the why behind decisions, not just the what. A comment explaining "why X was chosen" equips the next developer to evaluate whether the reason still holds.
- When choosing between two viable approaches, prefer the one that is easier to reverse.
- Use feature flags, dependency injection, or adapter patterns for decisions that touch multiple subsystems.
- Keep the cost of change visible. If a decision starts feeling irreversible, that is a signal to create a flexibility point.
- For AI: when you are unsure of the best approach, build a thin scaffold that can be thrown away rather than a deep one that locks the system in.
4. Tracer Bullets — End-to-End Skeleton First
Build the full thin slice before polishing any part. Get a working system first, iterate in layers.
Concrete rules for AI:
- Implement the shortest end-to-end path first: a call that goes from user action through all layers to a visible result, even if every layer is shallow.
- Do not perfect any single module before the whole flow is functional. A polished module that connects to nothing has zero value.
- After the tracer bullet works, fill in layers: add error handling, edge cases, validation, optimization — in that order.
- Tracer bullets are not prototypes. They are the start of the production system. The skeleton stays; only the muscle changes.
- When AI suggests deep optimization before the full flow works, push back. The tracer bullet validates architecture before optimization.
- Use the tracer bullet to discover integration surprises early — schema mismatches, API gaps, configuration errors — where they are cheap to fix.
5. Broken Windows — No Decay Tolerance
Don't leave bad code unfixed. Disorder invites more disorder.
Concrete rules for AI:
- Fix technical debt the moment you encounter it, provided the fix is small and contained. A five-minute fix now saves an hour later.
- Leave code cleaner than you found it — but surgically. If a function is confusing, improve its naming or add a clarifying comment. Do not refactor the entire module.
- The "broken window" is often a pattern: inconsistent naming, dead comments, unhandled errors, skipped tests. Fixing the pattern prevents the next broken window.
- Resist the "just this once" shortcut. A single shortcut in a clean codebase is more damaging than the same shortcut in an already-messy one.
Outputs
Code that avoids duplication, keeps concerns independent, preserves reversibility, builds end-to-end before polishing, and resists decay. A codebase that stays maintainable as it grows.
Failure modes
- Over-applying DRY: unifying two things that happen to look alike but represent different concepts, creating artificial coupling.
- Orthogonality as dogma: pure separation is impossible in any real system. The goal is manageable coupling, not zero coupling.
- Using reversible decisions as an excuse to defer every decision forever. Some decisions must be made; the skill is choosing which ones to keep flexible.
- Tracer bullets mistaken for prototypes: a tracer bullet that is thrown away was not a tracer bullet — it was wasted work.
- Fixing every broken window immediately without regard to priority. Not all windows matter equally; a typo in a comment is not the same as a security hole.
- Applying principles mechanically without understanding the trade-offs. Each principle has a cost; the practitioner knows when to pay it.
Verification checklist
- Is every piece of knowledge represented exactly once (no duplication of logic, schema, or config)?
- Can each module change independently without cascading to unrelated modules?
- Have irreversible architectural decisions been flagged and documented with their rationale?
- Does the system have a working end-to-end path (tracer bullet) before deep polishing?
- Are broken windows (technical debt, shortcuts, placeholders) tracked and scheduled — or fixed immediately if small?
- Are the principles applied with judgment, not mechanically? (Trade-offs considered and documented?)
Related skills
skills/prompts/clean-code-discipline/SKILL.md— Meaningful naming, small functions, comments discipline (complements DRY and broken windows)skills/prompts/karpathy-engineering-discipline/SKILL.md— Think before coding, surgical changes (complements tracer bullets and reversible decisions)skills/prompts/anti-overengineering/SKILL.md— Simplicity first (counterweight to over-applying DRY and orthogonality)skills/prompts/software-design-philosophy/SKILL.md— Deep modules, complexity management (deepens orthogonality and coupling concepts)skills/core/goal-driven-execution/SKILL.md— Goal-driven execution with per-step checks (applies tracer bullet approach at task level)
Constitution alignment
This skill aligns with the project's prime directive of building and maintaining software quickly while preserving clarity and correctness. DRY and orthogonality directly support maintainability at scale; reversible decisions and tracer bullets support rapid iteration without fear; broken windows preserves the long-term health of the codebase. The principles are universal enough that they do not override project constraints — they adapt to any language, framework, or domain. The localization notes below reflect the Vietnamese-language considerations in the project's CLAUDE.md.
Ghi chú tiếng Việt
Năm nguyên lý: DRY (không lặp — mỗi kiến thức một chỗ), Orthogonality (độc lập — thay đổi module không lan sang module khác), Reversible Decisions (quyết định có thể đảo — giữ option luôn mở), Tracer Bullets (xương sống trước — làm full thin slice rồi mới trau chuốt), Broken Windows (cửa vỡ — không để code dở dang, sửa ngay khi thấy). Áp dụng có chọn lọc, không máy móc. Mỗi nguyên lý đều có chi phí; người thực hành giỏi biết khi nào nên trả.
Tracked via Pragmatic Programmer (Hunt & Thomas, Addison-Wesley) — ideas adapted, original wording.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

