Agile Architecture Design: How to Avoid Over‑Engineering

1. A Classic Story

Xiao Wang is a responsible developer who always tries to make the architecture perfect.

Micro‑service split: one service per function

Introduce a message queue for asynchronous decoupling

Design a data‑sharding scheme

Reserve various extension points

Result:

Project delayed by one month

Code complexity doubled

Team complained the code is unreadable

Business side claimed requirements changed

Lesson: Over‑design is more dangerous than under‑design.

2. What Is Over‑Design?

2.1 Characteristics

1. Designing for "future"

"What if we need to support 1 million users?"
"What if we need multi‑tenancy?"
"What if we need to integrate third‑party systems?"

Result: 90% of the "what‑ifs" never happen, but code complexity actually increases.

2. Pursuing a perfect architecture

"This architecture is not elegant enough"
"This design is not generic enough"
"This implementation is not OO enough"

Result: Sacrificing usability for elegance.

3. Technical show‑off

"Let's use this hot new framework"
"Distributed transactions must use Seata"
"All services need circuit breaking"

Result: Unnecessary complexity is introduced.

2.2 Harms

Development cost increases – more time needed to implement.

Maintenance cost increases – code becomes complex and hard to understand.

Performance overhead – over‑abstraction hurts speed.

Team burden – steep learning curve.

Business delay – market launch is postponed.

3. What Is Agile Architecture?

3.1 Core Ideas

YAGNI

YAGNI = You Aren't Gonna Need It

Do not design for non‑existent requirements.

KISS

KISS = Keep It Simple, Stupid

Simpler solutions are more reliable.

MVP

MVP = Minimum Viable Product

Build the smallest usable piece first, then iterate.

3.2 Agile vs Traditional

Design philosophy: pre‑designed perfect vs need‑driven, evolving.

Time investment: large upfront vs embedded in development.

Change cost: high vs low.

Documentation: detailed vs just enough.

Risk: concentrated vs distributed.

4. Practices

4.1 Just‑In‑Time Architecture

Design only when needed.

Waterfall:  Design → Develop → Test → Release (all design up front)

Agile:  Design1 → Develop1 → Test1 → Release1
          ↓
        Design2 → Develop2 → Test2 → Release2
          ↓
        …

4.2 Sufficient Design

What "enough" means:

Supports current requirements.

Leaves reasonable extension space.

Team can understand and implement.

Avoid designing for speculative future needs.

4.3 Evolutionary Architecture

Architecture evolves through stages:

Stage 1: Monolith
Stage 2: Identify bottlenecks → split services
Stage 3: Continuous optimization → service mesh/governance

4.4 Identify "Enough" Signals

When to design extension points:

Current demand clearly requires extension.

Team has extension experience.

Extension cost is controllable.

When not to:

"Maybe needed later".

For a "perfect" architecture.

Just to show off.

4.5 Technical Debt Mindset

Acceptable debt:

Good debt:
- Compromise to ship quickly (to be repaid later)
- Trade‑off to simplify complexity (reasonable)

Bad debt:
- Ignoring known problems
- No future consideration
- Cutting corners for convenience

Regular repayment:

Allocate ~20% of each sprint to debt.

Prioritize critical debt.

Prevent debt from becoming unpayable.

4.6 Architecture Review Checklist

# Architecture Review Checklist

## Design
- [ ] Is the design overly complex?
- [ ] Are there signs of over‑design?
- [ ] Are extension points truly needed?
- [ ] Is the technology choice appropriate?

## Implementation
- [ ] Does the code follow the design?
- [ ] Are there work‑arounds that bypass design?
- [ ] Are unnecessary dependencies introduced?

4.7 Refactoring Architecture

When to refactor:

Adding new features becomes difficult.

Changing one place impacts many places.

Code is hard to understand.

Performance problems cannot be solved.

Typical timing:

During stable business periods.

When a better design is discovered.

When the tech stack needs upgrade.

5. Principles

5.1 Core Principles

Enough is enough – don’t over‑design for the future.

Solve the current problem first.

Architecture serves the needs, not the other way round.

5.2 Keep It Simple

Simple solutions are more reliable.

Simple code is easier to maintain.

Fewer bugs.

5.3 Continuous Evolution

Architecture is never finished.

Maintain evolvability.

Accept that architecture will change.

5.4 Team Fit

Architecture must match team capability.

Avoid technologies the team cannot hold.

Progress steadily.

5.5 Decision Checklist

Is it really needed now? Not "maybe later".

Can a simple solution solve it?

Can the team handle it?

Is the extension point mandatory?

Do benefits outweigh costs?

6. Summary

Key takeaways: YAGNI, KISS, MVP, evolutionary design, and "enough" design. The best architecture meets current needs, is understandable by the team, and has an acceptable cost.