Introduction
Give developers and coding agents the same basis for engineering decisions.
Principle Driven Development (PDD) keeps current engineering judgment in your repository. Each contributor can reconstruct a decision from the rule and the code that depends on it.
If you repeatedly correct the same agent behavior, a principle can preserve the reason for that correction across sessions.
A principle in code
A comment cites the rule that a decision depends on. The citation includes the rule’s version.
// PDD-02@v1: This download checks current permission before use.
// The preview check only gives early feedback.
async function downloadExport(userId, exportId) {
await requireDownloadPermission(userId, exportId);
return readExport(exportId);
}PDD-02 Principle identifier@v1 Version of the ruleA new agent follows PDD-02@v1 to the full rule. This rule requires a permission check at the operation that uses the export.
After a meaning change to v2, the CLI reports each citation that still uses v1. A contributor reviews the code before updating its citation.
The complete system
Five parts connect the rule to daily development.
AGENTS.mdRoutes each contributor to the complete rule.The repository supplies the current judgment. Correctness does not depend on memory from an earlier person, agent, or session.
When to use PDD
- You repeatedly correct agents that add unnecessary architecture or repeat an old mistake.
- Several contributors need a common basis for a deliberate tradeoff.
- A rule change requires a review of the code that depends on it.
Start with one earned rule.A principle needs evidence and a decision that it changes. The catalog supplies examples that you can adapt to your codebase.