Useful context.
Different judgment.
- Memory differs by person, agent, and session.
- Each handoff loses or changes context.
- Agents fill decision gaps in different ways.
Result Reasonable choices drift apart.
Principle Driven Development keeps agent decisions aligned with your codebase.
PDD is a repository system for consistent engineering decisions.
Memory and AGENTS.md files help, but they do not give every contributor the same judgment.
PDD turns durable engineering judgment into versioned principles. It does not treat every repeated instruction as a principle.
One codebase many contributors
Useful context.
Current principles.
Shared judgment.
- Principles state how contributors must choose.
AGENTS.mdroutes contributors to each rule.- Citations connect rules to code and reviews.
Result Choices share one clear basis.
PDD does not force one implementation. It gives each contributor the same basis for judgment.
How it works
A principle becomes a decision system.
A principle file is only documentation. PDD connects each rule to the agents, decisions, and code that rely on it.
Find the judgment
A repeated instruction is evidence, not a principle. Capture the reason that remains useful when the context changes.
Route every contributor
List the token and summary in AGENTS.md. Link to the full rule.
Cite each dependency
Add the versioned token where code, tests, comments, or reviews depend on the rule.
Review rule changes
When a rule changes, the CLI finds old citations that need review.
Outcome
A new agent starts with the same current judgment, without memory from the previous agent.
Where principles come from
Start with examples. Add the principles your codebase earns.
The public catalog contains general principles. Use only the rules that fit your codebase.
Repeated problems and deliberate tradeoffs can reveal useful judgment. Adopt a principle only when that judgment must guide future decisions.
If a current principle already states the judgment, use it. If its meaning must change, advance it.
Useful across many codebases.
These rules cover recurring engineering and communication problems.
Earned by one codebase.
These rules capture choices about your product, architecture, data, and risks.