| name | architect-thinking |
| description | Inject architectural thinking into technology selection, architecture decisions, and design judgments. Not a comparison table — a thinking framework that raises decision quality. Use when: technology stack selection, architecture pattern comparison, ADR creation, design review, non-trivial design decisions. Triggers: architecture selection, technology selection, design thinking, architecture decision, trade-off analysis |
Architect Thinking
Thinking framework for raising design decision quality. Record results as ADRs in docs/adr/.
Principles
1. Everything is a trade-off
No "best option" exists — only "least harmful in this context."
- State what you gain and lose for each candidate
- If you see no downsides, analysis is incomplete
- If you cannot articulate the trade-offs, you do not yet understand the problem
2. Reversible vs irreversible
Classify every decision:
- Type 1 (irreversible): DB engine, language, architecture style — deliberate, multi-perspective, ADR required
- Type 2 (reversible): Library, internal API, directory layout — 70% confidence → go. Fix later if wrong
Key question: "What does it cost to change this?" Higher cost → more deliberation.
3. Business context first
Read Product Vision (.github/instructions/product.instructions.md) before evaluating. Ask: "How does this serve user value?" If no answer, the selection may be self-indulgent.
4. Second-order effects
Predict consequences beyond the direct result:
- What happens in 6 months?
- Hiring and onboarding impact?
- Ops workload change?
- Adjacent system effects?
5. Counter cognitive biases
Check the bias checklist below before deciding.
6. Embrace uncertainty
Decide with available info — deferral has costs (blocked team, opportunity loss). For Type 1 only: investigate if research cost < deferral cost.
Bias Checklist
Run before every design judgment. If any apply, stop and re-evaluate.
| Bias | Check |
|---|
| Law of the Instrument | Choosing familiar tech without seriously evaluating alternatives? |
| IKEA Effect | Overly attached to something you built in the past? |
| Optimism Bias | Estimate too optimistic? Worst case considered? |
| Bandwagon Effect | Choosing because popular, not because it fits your context? |
| Anchoring | Anchored to first candidate or first data point? |
| Confirmation Bias | Only gathering supporting evidence? Sought disconfirming evidence? |
| Pro-Innovation Bias | Overrating new tech benefits, underrating risks? |
| Sunk Cost | Sticking with inferior option due to past investment? |
Evaluation Lenses
Evaluate from four perspectives. Prioritize lenses based on Product Vision — not all need perfect scores.
Business Owner
- ROI: Does the return justify the investment?
- Time to Market: Impact on delivery speed?
- Competitive Advantage: Does this create an edge?
- Total Cost: Licenses + infrastructure + staffing
Developer
- DX: Is day-to-day development productive?
- Learning Curve: Time until team becomes productive?
- Ecosystem: Library, tooling, community maturity?
- Debuggability: Easy to identify root causes?
Operator
- Observability: Logs, metrics, traces available?
- Incident Recovery: MTTR acceptable?
- Scalability: Realistic response to load increase?
- Security: Attack surface change? Vulnerability response track record?
End-User
- Performance: Impact on perceived speed?
- Reliability: Downtime or data loss risk?
- Accessibility: All target users can use it?
Anti-Patterns
| Pattern | Signal → Action |
|---|
| Google Envy | Unneeded scale → check actual traffic |
| Resume-Driven Development | Career motivation → ask what changes for users |
| Analysis Paralysis | Waiting for perfect info → classify Type 1/2, decide Type 2 now |
| Golden Hammer | One tool for everything → compare ≥3 alternatives |
| Speculative Requirements | "Might need someday" → YAGNI |
| Hype-Driven Development | Buzzword-driven → verify production track record |
Modularity & Boundaries
When deciding where to draw boundaries (modules, services, Bounded Contexts):
- Coupling taxonomy: Identify coupling type — static (compile-time), dynamic (runtime call), semantic (shared meaning), operational (shared infra). Minimize the costliest forms first.
- Connascence: Prefer connascence of name/type (weak) over connascence of meaning/timing/execution (strong). Refactor toward weaker forms.
- Bounded Context (DDD): Align service boundaries with linguistic boundaries. If two teams use the same word differently, that is a boundary signal.
- Cognitive load: If a team cannot hold the full context of a module in working memory, the boundary is too wide (Team Topologies).
Decomposition Decisions
Before splitting a monolith or extracting a service, answer:
- Is the pain organizational (team contention) or technical (scaling/deploy independence)?
- Can the boundary be tested with a module boundary first, before a network boundary? (Modular monolith → microservice is safer than big bang)
- What data does each side need? Shared DB is coupling in disguise.
Patterns: Strangler Fig (incremental replacement), Branch by Abstraction (parallel implementation), Tactical Forking (copy-and-diverge for speed).
Evolutionary Architecture
- Last Responsible Moment: Defer irreversible decisions until the cost of deferral exceeds the cost of deciding wrong. Do not confuse with procrastination.
- Fitness Functions: Define automated checks for architectural characteristics (e.g., "no cyclic dependencies", "P99 latency < 200ms", "no direct DB access from presentation layer"). Run in CI.
- Incremental change: Architecture evolves through small, verified steps — not big-bang rewrites. Each step must pass fitness functions.
Dependency & Build-vs-Buy Evaluation
When choosing an external dependency or SaaS vs self-build:
| Factor | Question |
|---|
| Core vs Context | Is this your competitive differentiator? Core → build. Context → buy/adopt. |
| Bus Factor | Who maintains it? 1-person OSS project = risk. |
| Escape Cost | How hard is it to replace later? High lock-in = Type 1 decision. |
| Attack Surface | Does it increase exposure? Evaluate CVE history. |
| License | Compatible with your distribution model? |
ADR Output
Record in docs/adr/. Required fields:
- Context — Why needed (include business context)
- Candidates & Evaluation — Options with trade-offs
- Decision — What and why
- Bias Check — Biases checked, how flagged ones were addressed
- Consequences — What becomes easier / harder
Reference Books
- Fundamentals of Software Architecture — Richards, Ford
- Software Architecture: The Hard Parts — Ford, Richards, Sadalage, Dehghani
- Building Evolutionary Architectures — Ford, Parsons, Kua
- Domain-Driven Design — Evans
- Thinking in Systems — Meadows
