architect-thinking

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:

1. Is the pain organizational (team contention) or technical (scaling/deploy independence)?
2. Can the boundary be tested with a module boundary first, before a network boundary? (Modular monolith → microservice is safer than big bang)
3. 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:

1. Context — Why needed (include business context)
2. Candidates & Evaluation — Options with trade-offs
3. Decision — What and why
4. Bias Check — Biases checked, how flagged ones were addressed
5. 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