Architecture Brief
Create concise, executive-friendly summaries of architecture decisions and tradeoffs.
Context
You are writing architecture briefs for diverse audiences (executives, product, non-technical stakeholders). Explain decisions in business terms, not technical jargon. Emphasize impact on cost, speed, reliability.
Domain Context
Based on effective technical communication:
- Business Impact: How does architecture choice affect time-to-market, cost, reliability? Quantify where possible.
- Trade-offs: Every architecture choice sacrifices something. Explicitly state: "We chose X over Y because Z matters more."
- Risk Acknowledgment: What could go wrong? Residual risks accepted. Mitigation plans for critical risks.
- Assumptions: What's true about our context that makes this choice right? Different context, different choice.
Instructions
One-Pager Structure:
- Title: "API Gateway Architecture for Microservices"
- Problem: "Multiple services exposing APIs; no unified interface, inconsistent auth, no rate limiting"
- Decision: "Implement API Gateway (Kong/AWS API Gateway)"
- Rationale: "Centralizes auth, rate limiting, routing; 2-week implementation"
- Trade-off: "Extra hop in request path (5ms latency); operational overhead of new service"
- Success Metrics: "Consistent error responses, 99.9% uptime, < 50ms latency"
- Risks: "Gateway becomes bottleneck (mitigation: auto-scaling, load testing)"
Lead with Impact: Start with business outcome. "This choice enables us to scale to 10x users without tripling ops team."
Use Analogies: "Microservices are like specialized restaurants; API Gateway is the booking system routing customers."
Acknowledge Uncertainty: "Based on current traffic and team size. If traffic changes 10x, we'll revisit."
Make it Scannable: Bullet points, bold key decisions. Executives should understand main point in 2 minutes.
Anti-Patterns
- Too Technical: Explain implementation details, not impact. Result: non-technical readers lost. Guard: Lead with business impact; explain technical choice as supporting detail.
- No Trade-offs Acknowledged: "This is the best solution." Result: unrealistic, erodes trust. Guard: Always state what you're sacrificing; explain why.
- Vague Success Metrics: "It will be more scalable." Result: hard to measure success. Guard: Quantify: latency < 100ms, 99.99% uptime, < 5min deployment.
- No Assumption Statements: Assume everyone knows context. Result: brief is incomprehensible to new readers. Guard: Explain context explicitly.
Further Reading
- Made to Stick by Chip and Dan Heath — communicating complex ideas simply
- Decisive by Chip and Dan Heath — presenting decision frameworks
- Architecture Decision Records by Michael Nygard — documenting decisions clearly
1---2name: architecture-brief3description: Write concise executive summaries of architecture. Communicate decisions and tradeoffs to non-technical stakeholders. Use when presenting to leadership or documenting decisions.4---56# Architecture Brief78Create concise, executive-friendly summaries of architecture decisions and tradeoffs.910## Context1112You are writing architecture briefs for diverse audiences (executives, product, non-technical stakeholders). Explain decisions in business terms, not technical jargon. Emphasize impact on cost, speed, reliability.1314## Domain Context1516Based on effective technical communication:1718- **Business Impact**: How does architecture choice affect time-to-market, cost, reliability? Quantify where possible.19- **Trade-offs**: Every architecture choice sacrifices something. Explicitly state: "We chose X over Y because Z matters more."20- **Risk Acknowledgment**: What could go wrong? Residual risks accepted. Mitigation plans for critical risks.21- **Assumptions**: What's true about our context that makes this choice right? Different context, different choice.2223## Instructions24251. **One-Pager Structure**:26 - Title: "API Gateway Architecture for Microservices"27 - Problem: "Multiple services exposing APIs; no unified interface, inconsistent auth, no rate limiting"28 - Decision: "Implement API Gateway (Kong/AWS API Gateway)"29 - Rationale: "Centralizes auth, rate limiting, routing; 2-week implementation"30 - Trade-off: "Extra hop in request path (5ms latency); operational overhead of new service"31 - Success Metrics: "Consistent error responses, 99.9% uptime, < 50ms latency"32 - Risks: "Gateway becomes bottleneck (mitigation: auto-scaling, load testing)"33342. **Lead with Impact**: Start with business outcome. "This choice enables us to scale to 10x users without tripling ops team."35363. **Use Analogies**: "Microservices are like specialized restaurants; API Gateway is the booking system routing customers."37384. **Acknowledge Uncertainty**: "Based on current traffic and team size. If traffic changes 10x, we'll revisit."39405. **Make it Scannable**: Bullet points, bold key decisions. Executives should understand main point in 2 minutes.4142## Anti-Patterns4344- **Too Technical**: Explain implementation details, not impact. Result: non-technical readers lost. **Guard**: Lead with business impact; explain technical choice as supporting detail.45- **No Trade-offs Acknowledged**: "This is the best solution." Result: unrealistic, erodes trust. **Guard**: Always state what you're sacrificing; explain why.46- **Vague Success Metrics**: "It will be more scalable." Result: hard to measure success. **Guard**: Quantify: latency < 100ms, 99.99% uptime, < 5min deployment.47- **No Assumption Statements**: Assume everyone knows context. Result: brief is incomprehensible to new readers. **Guard**: Explain context explicitly.4849## Further Reading5051- _Made to Stick_ by Chip and Dan Heath — communicating complex ideas simply52- _Decisive_ by Chip and Dan Heath — presenting decision frameworks53- _Architecture Decision Records_ by Michael Nygard — documenting decisions clearly
sethdford