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

Code Principles 📐

Use these principles when you change repository code, scripts, or automation.

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.
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.
Ship the first valuable increment early.	Early value shortens feedback loops.	Agile Manifesto	Deliver working software as soon as it is useful and keep delivering value continuously.
Accept useful requirement changes.	Better ideas can arrive late.	Agile Manifesto	Treat late requirement changes as normal when they improve customer value.
Release working software frequently.	Frequent delivery surfaces issues sooner.	Agile Manifesto	Keep iterations short enough that users see working software at regular intervals.
Work with business daily.	Daily contact keeps intent aligned.	Agile Manifesto	Keep business and development in daily contact for decisions and feedback.
Trust motivated people.	Engaged people take better ownership.	Agile Manifesto	Build around engaged people and give them ownership of the work.
Use direct conversation for blocking topics.	Direct talk resolves blockers faster.	Agile Manifesto	Prefer face-to-face or synchronous discussion when the decision is urgent or complex.
Measure progress with working software.	Working software shows real progress.	Agile Manifesto	Use running software, not documents alone, as the main progress signal.
Keep a sustainable pace.	Sustainable pace avoids burnout.	Agile Manifesto	Set a pace the team can maintain for the long term.
Improve technical quality continuously.	Quality debt compounds if ignored.	Agile Manifesto	Invest in design and code quality on every change.
Remove unnecessary work.	Removing work leaves room for value.	Agile Manifesto	Choose the smallest solution that achieves the goal.
Let teams shape their own design.	Local teams know the best design.	Agile Manifesto	Let self-organizing teams own architecture, requirements, and implementation.
Inspect and adapt regularly.	Regular review catches process drift.	Agile Manifesto	Review the process at regular intervals and change it when it is not working.
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.