Research Question
How should architecture/design principles be documented so they are clear, actionable, durable, and clearly distinct from requirements, rules, and ADRs?
Note: This is about the documentation format and authoring practice for design principles — structure, wording, granularity, and placement. NOT about which specific principles a system should adopt.
Context
We maintain a layered documentation system for a Decision Pipeline that reviews Architecture Decision Records (ADRs). Documents are organized into tiers (business requirements → system requirements → external/internal design → ADRs → verification/ops).
Current state:
- "Design principles" live in our business-requirements document as a flat numbered list.
- We found the list mixes two different things: durable stances (e.g., "AI advises, humans decide") and concrete implementation rules (e.g., "reject below 40 points", "only the CEO may approve").
- Readers find the section unclear; they cannot tell a guiding principle from a testable rule.
- Solo developer, 5–15 ADRs/month, scaling toward multi-tenant SaaS; low-cognitive-load writing is a stated goal.
Gap: We lack an evidence-based template and authoring rules for writing design principles that stay distinct from requirements and ADRs.
Questions
- Entry structure: What elements make an individual design-principle entry effective (e.g., statement, rationale, implications/consequences, do/don't examples, status)? Provide a concrete recommended template or schema.
- Boundary criteria: How do established sources distinguish design principles from requirements, policies/rules, and ADRs? Give a practical test for classifying an item correctly.
- Durability & wording: How should principles be worded and scoped to stay actionable and avoid empty platitudes — including recommended count, trade-off/priority phrasing ("prefer X over Y"), and how to make them referenceable from decisions?
- Frameworks: What do recognized frameworks and standards prescribe for documenting principles (e.g., arc42, ISO/IEC/IEEE 42010, TOGAF principles catalog, AWS Well-Architected, ThoughtWorks)? Compare their approaches and note what is transferable to a small team.
Output
Structured report with:
- Executive summary (3–5 key findings)
- Per-question analysis
- A recommended design-principle entry template + a short classification checklist (principle vs requirement vs rule vs ADR)
- Priority ranking (must-have / should-have / nice-to-have) for our context
- References with URLs