Design Decisions: The Hidden Architecture of Software Systems

Decisions Are Everywhere in Software Construction

Every day people make countless decisions, many unconsciously. In software construction — from requirements, analysis, development, to testing — engineers continuously make decisions. A rational software engineer wants those decisions to be sound and valuable. Every excellent engineer should actively think about the design decision process.

"Architecture represents the significant design decisions that shape a system, where significant is measured by cost of change." — Grady Booch

Three Dimensions to Understand Software

Understanding a complex software system can be approached through three dimensions:

Structural (static) : Discovering structures that implement functional and non-functional requirements — concurrency, communication, memory, storage, redundancy, etc.

Behavioral (dynamic) : Mining actual component interactions and interference at runtime, primarily via observability techniques.

Evolutionary : Uncovering why the software evolved into its current form. Understanding evolution starts with design decisions.

What Is a Design Decision?

A decision is "a conclusion or resolution reached after consideration." Design decisions are the significant choices that affect a software's shape and structure. As a "Meta Thinker," one must ask: what design decisions occur frequently during software construction? Discovering them requires knowing where to find them, how to mine them from existing projects (using clustering and LLMs), and how to leverage this knowledge in the AI era.

Real-World Decision-Making in Review Meetings

The author draws on years of experience in DRB (Design Review Board) and TMG (Technical Management Group) meetings, where technical proposals are evaluated from a DFX (Design for Excellence) perspective. Decisions cover:

Fault prevention, detection, and recovery strategies

Concurrency model selection

IPC communication mechanism selection

API naming conventions

Impact on surrounding systems

Total personnel cost

Server infrastructure cost

Making sound judgments is difficult because multiple constraints must be balanced:

Technical constraints : physical laws, algorithmic limits

Human constraints : team organization, skill acquisition

Economic constraints : return on investment

Legal constraints : digital rights

Ethical constraints : whether something should be done

Why Mining Design Decisions Is Hard

Organizational fragmentation : Different review bodies (security, DFX, performance) evaluate different aspects.

Lack of structured storage : Decisions live in meeting minutes, recordings, chat logs. Open-source projects fare better — mailing lists, issue discussions, and commit messages often capture the "why".

Missing tooling and discipline : Engineers rarely record decisions in a fixed format.

LLMs Enable Decision Knowledge Extraction

In the large-model era, multimodal processing and LLM summarization, extraction, and reasoning capabilities make it feasible to extract decision knowledge from historical assets. The author built a prototype tool that mines design decisions from GitHub issues. Success depends on well-designed prompts, context, and structured output formats.

Industry Templates for Documenting Architecture Decisions

Template 1: Architecture Decision Records (ADR)

Title : Short noun phrases, e.g., "ADR 1: Deployment on Ruby on Rails 3.0.10". Context : Describes forces at play — technological, political, social, project-local — in value-neutral language. Decision : States the response in full sentences, active voice: "We will …" Status : Proposed, accepted, deprecated, or superseded (with reference to replacement). Consequences : Lists all resulting impacts — positive, negative, neutral — that affect the team and project.

Template 2: Requirements Analysis & Design Guide (Chinese Practice)

Title (required) : Brief description of the architectural decision. Background (required) : Specific context or problem driving the decision, plus concise optional alternatives. Also serves as a system architecture description. Decision (required) : Concrete architectural decision and its rationale. Use affirmative, imperative language; avoid subjective, negative, ambiguous wording. Focus on Why, not How — understanding the reason is more important than the implementation. Impact (required) : Overall impact of the decision, both good and bad, to weigh whether benefits outweigh costs.

Next Steps

The follow-up article will categorize design decisions and provide concrete case studies based on practical experience.

Reference

https://zhuanlan.zhihu.com/p/2014998893839033768