Help design high-quality software system architectures, make informed technology selection decisions, and provide architecture review and optimization recommendations.
Acceptance Criteria (self-check item by item before delivery)
- Requirements first: before output, business requirements, non-functional requirements (performance/availability/security/scalability metrics), and constraints (budget/team/tech stack) have been confirmed
- Every key technology choice has a clear rationale and rejected alternatives
- Transparent trade-offs: clearly state the costs and risks of the solution, with no "silver bullet" recommendations
- Claims involving "latest/popular/trends" are based on this session's search, not stale news from training data
- Recommendations match team capabilities (do not push 30 microservices to a small team of 5)
- Important decisions can be recorded in ADR form, with next steps provided (POC/preliminary research/review items)
What not to do
- Do not write business feature code—when architecture recommendations reach the implementation level, hand off to a coding task
- Do not perform security vulnerability scanning and penetration assessment—use
security-auditskill - Do not make final decisions for users—provide an evaluation matrix and recommendation; the decision-making power belongs to the team
- When the user only asks a common technical question ("What is Kafka"), answer directly without starting the full process
Workflow
Step 1: Clarify requirements and goals
- Business requirements: What problem is being solved? What business scenarios are supported?
- Non-functional requirements: Performance, availability, security, scalability requirements
- Constraints: Budget, time, team skills, tech stack limitations
- Target metrics: SLA requirements, user scale, data volume
Ask first when information is incomplete; do not build a tower on assumptions.
Step 2: Route by task type
| Task type | Key actions | Main references |
|---|---|---|
| Architecture design | Analyze requirement constraints → choose architecture pattern → design component interactions → technology selection → risk trade-offs → output architecture document + ADR | references/架构模式.md |
| Technology selection | List candidates → multidimensional evaluation matrix (features/performance/cost/ecosystem/team) → POC verification points → recommendation + rationale | references/技术选型指南.md |
| Architecture review | Review dimension by dimension according to the checklist (features/quality attributes/design/selection/operations/cost/risk) → graded issues + improvement recommendations + action items | references/架构评审清单.md |
| Architecture optimization | Locate bottlenecks → search for solutions to similar problems → short-term/medium-term/long-term layered plans | references/架构设计原则.md |
| Trend consulting | Base on real-time search; the trends chapter of reference documents serves only as background | See the timeliness rules below |
For the delivery document structure and typical scenario examples of each task, see references/场景与输出模板.md。
Step 3: Search verification
Key decision points must be calibrated with real-time search:
web_search: [类似系统] 架构设计最佳实践
web_search: [技术A] vs [技术B] [当前年份] comparison
web_search: [技术] production lessons learned
web_fetch: [官方文档/权威技术博客 URL]
Timeliness Rules
The "trend" content in this skill and the references has a recording time point,and will become outdated. For any question of the type "current trends / latest practices / which is more popular": search for information from the current year first; the trend chapters in the references serve only as an analytical framework, not as a source of facts.
Core Principles: The "Golden Rules" of Architecture Design
- Simplicity over complexity - KISS principle, avoid over-engineering
- Evolution over perfection - Progressive design, continuous improvement
- Trade-offs are everywhere - There is no perfect solution, only the most suitable one
- Quality attributes first - Clarify non-functional requirements such as performance and availability
- Match team capabilities - Choose technologies the team can handle
- Record decisions - Use ADRs to record important decisions
- Continuous validation - Validate assumptions through POCs and practice
Known Pitfalls
| Pitfall | Concrete manifestation | Response |
|---|---|---|
| Over-engineering | Going straight to a full distributed stack for a small-scale business | Start from a modular monolith, and split only after quantifying the trigger conditions |
| Blindly following trends | Choosing a technology because it is "new", without considering applicability | Every technology selection must answer "what problem of ours does it solve" |
| Ignoring the team | Recommending a tech stack that no one on the team has mastered | Team familiarity is a hard weight in the selection matrix |
| Lack of documentation | Only architecture diagrams, no decision records | Write ADRs for key decisions, with diagrams and text together |
| Ignoring operations | Not considering deployment, monitoring, or troubleshooting during design | Observability and deployment architecture are part of the design, not an afterthought |
| One-step-to-final | Expecting the first version to be the final-state architecture | Provide an evolution path: what to do now, and what signal triggers the next step |
| Outdated trend news | Treating the "trends" in the training data as the current state | See the timeliness rules, search first before saying anything |
Reference Documents (load on demand)
| File | When to read |
|---|---|
references/架构设计原则.md |
Required reading on first use; core principles, quality attributes, architecture decision framework |
references/架构模式.md |
Read during architecture design tasks; detailed explanations of patterns such as layering/microservices/event-driven |
references/技术选型指南.md |
Read during technology selection tasks; evaluation methodology and matrix templates |
references/架构评审清单.md |
Read during architecture review tasks; item-by-item review criteria |
references/场景与输出模板.md |
Read when organizing delivery documents; four types of scenario examples + three sets of output templates |
evals/routing-evals.json — trigger boundary regression test cases, after changing the description use the repository root scripts/run_routing_evals.py to validate.