# Principle Driven Development catalog These principles are starting points. Adopt only the rules that tell the truth about your system. This combined file is a reading copy. For adoption, download each chosen principle from its own page and keep one definition per file. Follow the adoption steps at https://principledriven.dev/principles#adopt-a-rule. --- # PDD-01 — Use Ubiquitous Language Token: PDD-01 Version: v1 ## Rule Use Ubiquitous Language in conversations, documents, tests, interfaces, and code. Give each domain concept one stable name. Use that name in every layer. Keep the established DDD name for this pattern. The name connects the rule to the wider domain model. ### Exceptions Ordinary nouns, verbs, adjectives, and technical terms remain valid in context. Earlier uses do not reserve words or their grammatical forms. A naming objection needs misleading meaning, inconsistent names for one domain concept, or concrete ambiguity. The verb `run` can apply to both a routine and an action. External protocols keep their standard terms at the boundary. After the boundary, translate those terms into the Ubiquitous Language. If two bounded contexts use one word differently, name the context at the integration boundary. ## Rationale Different names for one concept force customers and teams to clarify what they mean. Agents can add duplicate types or invent awkward synonyms for ordinary words. Shared domain names reduce confusion without banning word reuse. ## History - v1 (2026-08-24): Published to prevent conflicting domain terms and unnecessary translation layers inside one model. --- # PDD-02 — Validate at Use Token: PDD-02 Version: v1 ## Rule Validate the relevant current facts where an artifact is used. If an artifact fails that check, refuse it. Name the validation checkpoint and the facts it guarantees. Do not depend on cleanup to preserve an earlier check. If requirements permit changes after that checkpoint, do not add safeguards just to prevent those changes. If a fact cannot change, name that fact before you omit its check. ### Exceptions If an operation requires validation at commit, enforce that requirement in addition to this rule. For mixed requirements, list those operations and their required guarantees as exceptions in the local rule. ## Rationale Agents add complex safeguards to close every timing gap. A validation checkpoint limits that work to the guarantees the application requires. ## History - v1 (2026-08-24): Published to prevent repeated timing repairs around artifacts that can become invalid before use. --- # PDD-03 — Use Simplified Technical English Token: PDD-03 Version: v1 ## Rule Use the structural rules of ASD-STE100 Simplified Technical English for technical prose. Apply these rules to agent instructions, documentation, commits, comments, reviews, errors, and release notes. If a trained reviewer does not use the official standard, do not claim formal ASD-STE100 compliance. - Procedural sentences contain no more than 20 words. - Descriptive sentences contain no more than 25 words. - Each procedural sentence contains one instruction. - Active voice names the person or system that does the action. - A required condition comes before its command. - One concept keeps one term. - Requirements use `must`. Possibilities use `can`. - Technical names, code, commands, paths, and quoted errors stay exact. - Necessary domain terms stay available as technical nouns and technical verbs. ### Exceptions If marketing copy carries no technical instruction, it can use its brand voice. Quoted text, code, identifiers, commands, and external protocol terms keep their exact form. ## Rationale Long sentences, weak requirements, and changing terms hide the intended decision. Short instructions with stable terms reduce ambiguity. ## History - v1 (2026-08-24): Published to prevent ambiguous technical instructions and inconsistent terms across repository artifacts. --- # PDD-04 — Avoid Sunk Cost Fallacy Token: PDD-04 Version: v1 ## Rule Keep work because it has current value, not because someone already spent time on it. Delete work that has no current use and no committed plan. When a real need returns, rebuild from current requirements. Git history is sufficient recovery for deleted work. The active tree must describe the current system. ### Exceptions Keep work that has a named owner, a committed delivery plan, and a near review date. Until the repository reaches a recorded removal condition, keep required compatibility code. ## Rationale Agents treat preserved drafts and unused code as approved directions. Preserved work can acquire false authority even when it has no current value. ## History - v1 (2026-08-24): Published to prevent unused work from becoming false authority for later changes. --- # PDD-05 — Cite the rule, do not copy it Token: PDD-05 Version: v1 ## Rule When code depends on a principle, cite its versioned token. State only the local fact that the code needs. Do not copy the full principle into comments. The principle file remains the authority. ### Exceptions Commit messages and merged review threads are history. They do not need citation reviews. ## Rationale Copied rule text can remain after its source changes. A pinned citation keeps the rule in one place and exposes dependent code for review. ## History - v1 (2026-08-24): Published to prevent copied rule text and unversioned citations from hiding dependencies after meaning changes. --- # PDD-06 — Make accepted risks explicit Token: PDD-06 Version: v1 ## Rule Put an `ACCEPTED-RISK:` marker beside code that accepts a known risk. State the scenario, reason, and review condition. Carry accepted risks from planning into those markers. Add this versioned principle token to the marker. One repository search must list every accepted risk. ### Exceptions There are no exceptions for accepted risks. An unmarked risk has no accepted status. ## Rationale Agents repeatedly report accepted findings or mistake accidental behavior for approved design. A local marker makes the trade and its review condition visible. ## History - v1 (2026-08-24): Published to prevent repeated risk investigation and vague comments that disguise unfinished work. --- # PDD-08 — Canonical by construction Token: PDD-08 Version: v1 ## Rule Store each reference as the exact identifier of its target object. Before storage, resolve supported labels and aliases to that identifier. Refuse unknown or ambiguous references. Keep label, alias, and case rules in one input resolver. Code that reads stored references must match their identifiers exactly, without label lookups, case conversion, or fallback searches. Preserve external protocols' required case, spelling, and byte order at their boundary. Keep display names and original input separate from the stored reference. Repair invalid stored references through an explicit migration. Define a removal condition for temporary compatibility code. ## Rationale Several stored forms force each part of the system to repeat input rules. One exact stored identifier removes those repairs. ## History - v1 (2026-10-05): Published to prevent repeated alias and case handling across readers. --- # PDD-09 — Separate operational state from history Token: PDD-09 Version: v1 ## Rule Store current operational state explicitly. Update it together with its audit entry in one database transaction. Give each status, clock, or cursor one owning writer. Keep audit history as evidence of changes. Do not infer current state from incidental event order or display text. ### Exceptions Intentional [event sourcing](https://learn.microsoft.com/en-us/azure/architecture/patterns/event-sourcing) uses a durable event stream as the source of truth. That design needs explicit replay rules, event versions, and owned projections. This principle does not require a second source of truth beside that stream. A historical report can reconstruct past state from audit evidence. It must identify the time and evidence that it uses. ## Rationale Agents infer current status from different audit events and filters. Audit retention or presentation changes then alter behavior far from the audit code. ## History - v1 (2026-10-05): Published to give current state and clocks explicit owners. --- # PDD-10 — Borrow infrastructure and own domain behavior Token: PDD-10 Version: v1 ## Rule Use maintained packages for established infrastructure problems. Keep domain rules and product behavior under your ownership. Before you fork or replace a package, try its public APIs and extension points. Before you create custom infrastructure, name the product requirement that existing packages cannot reasonably satisfy. Account for ongoing maintenance. Remove constraints that come only from the proposed implementation. ### Exceptions A concrete product requirement can justify a fork or custom mechanism. Record why supported alternatives fail and who owns future maintenance. A small domain function does not need a dependency merely because a package exists. Compare the actual complexity and cost. ## Rationale Agents invent implementation constraints and use them to justify private infrastructure forks. The team inherits maintenance without a product requirement. ## History - v1 (2026-10-05): Published to focus custom code on product requirements instead of unnecessary infrastructure forks. --- # PDD-11 — Tests earn their cost Token: PDD-11 Version: v1 ## Rule Before you add a test, name the concrete failure that it detects. Check which existing tests or trusted components already cover that failure. Choose the least costly layer that provides sufficient new confidence. Include runtime, fixtures, maintenance, flakiness, and failure investigation in that cost. Preserve tests for meaningful behavior, authorization, data integrity, and recovery. Before you remove duplicate proof, identify the protection that remains. ### Exceptions A browser or full system test can be the least costly reliable proof of a real integration failure. Security, recovery, and data integrity can require several layers. Each layer must protect a distinct failure or provide a necessary independent check. ## Rationale Agents add slow fixtures and repeated proof for every code change. The suite costs more without protecting additional behavior. ## History - v1 (2026-10-05): Published to require useful new confidence for the cost of each test. --- # PDD-12 — Keep domain decisions in one place Token: PDD-12 Version: v1 ## Rule Give each domain decision one authoritative implementation. API layers and clients must call it or use its result. Do not copy the decision's rules into each caller. Let requests express the desired result. Keep database joins and internal execution steps with the owning implementation. Expose the result, relevant failure conditions, and meaningful caller choices. Preserve request meaning across internal optimizations. ### Exceptions Clients can show previews or immediate feedback. The owning implementation must still make the final domain decision. If callers need execution control as a product feature, define that control and its effects in the API. ## Rationale Agents repeat domain rules across layers, which creates conflicting decisions and extra maintenance. One authoritative implementation keeps those decisions consistent. ## History - v1 (2026-10-05): Published to keep public requests focused on domain results. --- # PDD-13 — Refuse before the work exists Token: PDD-13 Version: v1 ## Rule Check predictable limits at the earliest boundary that has the necessary facts. Refuse invalid configuration before it creates unusable work. Keep the server authoritative. Repeat checks for current permission, expiration, and other facts that can change before use. Preserve drafts and completed answers after a refusal. Bind in-progress work to the definition revision that it started with. Do not require a destructive migration merely because a newer definition exists. ### Exceptions An early surface cannot check a fact that it does not yet know. Explain that remaining constraint before the user commits substantial effort. A security or legal requirement can prevent completion under an old revision. Refuse completion explicitly and preserve recoverable work where permitted. Early checks complement [Validate at Use](https://principledriven.dev/principles/validate-at-use). They do not replace the final authority check. ## Rationale Agents defer predictable refusals until submission or erase answers after a definition changes. Early checks and stable revisions protect user effort. ## History - v1 (2026-10-05): Published to expose predictable limits early and preserve user work after refusals. --- # PDD-14 — Mark operational boundaries Token: PDD-14 Version: v1 ## Rule Beside a deliberate capacity limit, add an `OPERATIONAL-BOUNDARY:` marker. Cite this principle's current pin. State the limit, affected workload or user, signal, and continuation. Give the signal a stable name and a real emitter. Choose the limit from actual workload evidence. Before ordinary use exceeds it, build the required capacity mechanism. Do not describe lost writes, wrong data, or a security failure as a scale boundary. Test the boundary behavior and its named signal. ## Rationale Agents add scale machinery without demand or hide routine failures behind vague limits. An observed boundary gives capacity work a concrete trigger. ## History - v1 (2026-10-05): Published to make capacity limits observable and give each limit a clear continuation. --- # PDD-15 — Write for future readers Token: PDD-15 Version: v1 ## Rule Write repository artifacts for a reader who did not see the conversation. State the current purpose and necessary decision context. Give titles a concrete behavior or problem. Make a pull request description explain the final delivered change. Distinguish observed results, planned checks, and incomplete work. Cite evidence where the reader needs it to assess the claim. In comments, state the local contract and its pinned rule. Keep the full rule in its authoritative file. ### Exceptions Temporary notes can use local shorthand while they remain temporary. Before they become durable instructions, add the context that future readers need. Simple code does not need a comment that restates its action. Add an explanation only for a hidden contract or decision. ## Rationale Agents leave task labels, conversation references, and abandoned plans as durable explanations. Later contributors then reconstruct the wrong decision. ## History - v1 (2026-10-05): Published to make durable artifacts useful without the original conversation.