computer-playbook/docs/contributing/design/principles.md

Code Principles 📐

Use these principles when you change repository code, scripts, or automation. For organisational and team-process principles, see principles.md.

Principles 📋

Follow these principles. Keep the rule column short, imperative, and as SMART as practical; use the reason column for the rationale, the principle column for the linked source name, and put the expanded wording in the details column.

Rule	Reason	Principle	Details
Consolidate duplicate logic before merging.	Duplicate behavior is easier to keep consistent.	DRY	Keep one implementation for each behavior and remove repeated logic from the touched files.
Leave touched code cleaner than you found it.	Small cleanup reduces future friction.	Boy Scout Rule	Make small, safe cleanup improvements in the files you touch when they reduce friction without expanding the scope unnecessarily.
Store each shared value once.	Shared values drift when copied.	SPOT	Put shared fixed values in one canonical source and reference them everywhere else.
Choose the simplest solution.	Simple code is easier to change.	KISS	Prefer the smallest implementation that still satisfies the requirement and remains easy to maintain.
Give each module one reason to change.	Focused modules are easier to test and replace.	SRP	Each module, class, or function MUST have exactly one responsibility so that changes to one concern do not ripple into unrelated code.
Build only what is needed now.	Unused code adds maintenance burden without value.	YAGNI	Do not implement functionality until it is required. Avoid speculative abstractions, optional hooks, and future-proofing that no current requirement justifies.
Make prompts SMART.	Clear prompts reduce ambiguity.	SMART	Write prompts that are specific, measurable, achievable, relevant, and time-bound so the agent can act on them without ambiguity.
Write the failing test first.	Failing tests confirm requirements first.	TDD	Start with a failing test, implement the minimum code, and refactor with confidence.
Prefer beautiful code.	Readable code is easier to trust.	Zen of Python	Choose code that is clean, coherent, and pleasant to read instead of code that is only clever.
Prefer explicit behavior.	Explicit behavior is easier to reason about.	Zen of Python	Make behavior visible in the code instead of relying on hidden assumptions.
Mark intentional exceptions.	Exceptions need context.	Zen of Python	Document intentional exceptions close to the relevant code so they stay visible until they can be removed.
Prefer simple code.	Simple code changes more safely.	Zen of Python	Choose the simplest solution that still does the job.
Prefer manageable complexity.	Controlled complexity keeps maintenance cost down.	Zen of Python	Keep complexity under control instead of making the solution more complicated than needed.
Prefer flat structures.	Shallow structures are easier to scan.	Zen of Python	Keep control flow and data structures shallow when a flatter shape works.
Prefer sparse structures.	Sparse layouts make intent clearer.	Zen of Python	Avoid dense packing when a clearer, more spacious layout improves understanding.
Make code readable.	Readable code speeds review and debugging.	Zen of Python	Write code so the next person can understand it quickly.
Protect the rules from exceptions.	Contained exceptions keep rules useful.	Zen of Python	Handle special cases without breaking the general rule set.
Prefer practical solutions.	Practical code works in the real repo.	Zen of Python	Choose the option that works well in practice over one that is only theoretically pure.
Fail loudly on errors.	Hidden failures cause harder incidents later.	Zen of Python	Do not let unexpected errors disappear unnoticed.
Silence errors only intentionally.	Suppressed errors need justification.	Zen of Python	Suppress errors only when you can explain why that is safe.
Refuse to guess in ambiguity.	Clarification is safer than guessing.	Zen of Python	Stop and clarify when the inputs or intent are unclear.
Choose one obvious way.	One standard path lowers cognitive load.	Zen of Python	Prefer one clear, standard path over multiple equivalent ones.
Make the obvious path obvious.	The right choice should be easiest.	Zen of Python	Shape the code so the recommended approach is the easiest to see.
Act now when action is due.	Deferred work tends to grow.	Zen of Python	Do the needed work now instead of deferring it without reason.
Wait rather than rush.	Premature action can make the result worse.	Zen of Python	Pause when acting immediately would make the result worse.
Keep hard code easy to explain.	Hard-to-explain code often hides flaws.	Zen of Python	If the code is hard to explain, rework it before merging.
Keep easy code easy to explain.	Easy-to-explain code is usually sound.	Zen of Python	If the code is easy to explain, it is likely a good idea.
Use namespaces generously.	Namespaces prevent collisions in a large repo.	Zen of Python	Group names so they do not collide and remain easy to navigate.

For code quality rules, see lint.md. For framework-specific guidance, see ansible.md and make.md.