Principle catalog
Start with useful examples of judgment that your codebase can earn.
Each page helps you recognize a costly behavior and understand the corrective rule. Install its compact agent file through the CLI or download it.
These are candidates for adoption. They do not govern your repository until you adopt them under its own protocol.
Available principles
14 principles
Use Ubiquitous Language
Customers and teams spend less time clarifying names and more time solving the problem.
ModelingValidate at Use
Stop adding cleanup jobs and locks just to keep an earlier check valid.
ReliabilityUse Simplified Technical English
People and agents get one meaning from instructions, commits, comments, reviews, errors, and documentation.
CommunicationAvoid Sunk Cost Fallacy
Unused code and documentation no longer mislead agents as they plan future changes.
SimplicityCite the rule, do not copy it
A meaning change produces a complete list of code that needs a new review.
GovernanceMake accepted risks explicit
A future reader can understand the trade without repeating old investigation or treating an oversight as policy.
GovernanceCanonical by construction
Every part of the system can use the same stored identifier without its own lookup or case fixes.
ModelingSeparate operational state from history
Current behavior stays stable after changes to audit events, retention, or display rules.
ReliabilityBorrow infrastructure and own domain behavior
The team spends maintenance effort on behavior that makes its product useful.
SimplicityTests earn their cost
Checks protect meaningful behavior while the suite stays fast and useful.
SimplicityKeep domain decisions in one place
Product decisions stay consistent without separate rule implementations in the backend, API layer, and frontend.
ModelingRefuse before the work exists
Users learn about known limits before they invest effort, and completed work survives changes around it.
ProductMark operational boundaries
The team can defer scale work with evidence that shows when the deferral must end.
GovernanceWrite for future readers
A new contributor or agent can reconstruct the change from durable repository evidence.
CommunicationAdopt a rule
Each principle needs repository evidence and a decision that it changes. Start with the rules that your codebase has earned.
The combined download is a reading copy. Each principle's page has a CLI command and an individual Markdown download.
- Read every current principle in your repository.
- If a current rule covers the decision, use that rule or advance its version.
- Follow your repository's admission protocol before adding a token.
- Run the chosen principle's installation command. The CLI assigns its local token and updates your agent index.
- Adapt the Rule and its exceptions to your codebase. Record local evidence in a short Rationale.
- Cite the pin where code or review decisions depend on the rule.
- Run
pdd check. - Add the check to CI.
For manual adoption, assign an unused local token and save one definition per file. Update its headers, History, and agent index together.
The setup guide supplies the review rules and explains each part. CLI configuration defines your prefix, principle directory, and agent indexes.