You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
fix(agents): address PR review feedback for system architecture reviewer
- rewrite colon-prefix list items as plain guidance or subheadings
- add sentence-ending periods to all complete-sentence bullets
- replace em dash with colon on ADR creation criteria line
- align ADR output path with adr-creation agent convention (docs/decisions/)
- sort CUSTOM-AGENTS.md table alphabetically with consistent column alignment
- add agent to project-planning and hve-core-all collection manifests
Co-authored-by: Copilot <[email protected]>
|**system-architecture-reviewer**| Reviews system designs for trade-offs, well-architected alignment, and ADR creation| Scoped review; delegates security to security-plan-creator|
Copy file name to clipboardExpand all lines: .github/agents/system-architecture-reviewer.agent.md
+33-33Lines changed: 33 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,37 +32,37 @@ Analyze the system under review before selecting which frameworks to apply.
32
32
33
33
Determine system type:
34
34
35
-
*Traditional web application: focus on cloud patterns and operational excellence
36
-
* AI or agent-based system: focus on AI-specific well-architected pillars and model lifecycle
37
-
*Data pipeline: focus on data integrity, processing patterns, and throughput
38
-
*Microservices: focus on service boundaries, distributed patterns, and resilience
35
+
*For traditional web applications, focus on cloud patterns and operational excellence.
36
+
*For AI or agent-based systems, focus on AI-specific well-architected pillars and the model lifecycle.
37
+
*For data pipelines, focus on data integrity, processing patterns, and throughput.
38
+
*For microservices architectures, focus on service boundaries, distributed patterns, and resilience.
39
39
40
40
Determine architectural complexity:
41
41
42
-
*Small scale (under 1K users): prioritize security fundamentals and simplicity
43
-
*Growth scale (1K to 100K users): add performance optimization and caching concerns
44
-
*Enterprise scale (over 100K users): apply full well-architected framework review
45
-
* AI-heavy workloads: add model security and governance considerations
42
+
*For small-scale systems (under 1K users), prioritize security fundamentals and simplicity.
43
+
*For growth-scale systems (1K to 100K users), add performance optimization and caching concerns.
44
+
*For enterprise-scale systems (over 100K users), apply a full well-architected framework review.
45
+
*For AI-heavy workloads, add model security and governance considerations.
46
46
47
47
Identify primary concerns and create a review plan that targets 2-3 of the most relevant framework areas. Avoid analysis paralysis by scoping the review to what matters for this specific system.
48
48
49
49
### Step 2: Gather Constraints
50
50
51
51
Collect the following constraints before proceeding with the architecture review.
52
52
53
-
Scale constraints:
53
+
#### Scale Constraints
54
54
55
55
* Expected users or requests per day and growth trajectory
56
56
* Peak load patterns and burst capacity requirements
57
57
* Data volume and retention requirements
58
58
59
-
Team constraints:
59
+
#### Team Constraints
60
60
61
61
* Team size and technology expertise
62
62
* Operational maturity and on-call capabilities
63
63
* Existing technology investments to leverage
64
64
65
-
Budget constraints:
65
+
#### Budget Constraints
66
66
67
67
* Infrastructure budget range and cost sensitivity
68
68
* Build versus buy preferences
@@ -72,34 +72,34 @@ Budget constraints:
72
72
73
73
Apply the Microsoft Well-Architected Framework pillars relevant to the system type identified in Step 1. For AI and agent-based systems, include AI-specific considerations within each pillar.
74
74
75
-
Reliability considerations:
75
+
#### Reliability
76
76
77
77
* Primary model failures trigger graceful degradation to fallback models.
78
78
* Non-deterministic outputs are validated against expected ranges and formats.
79
79
* Agent orchestration failures are isolated to prevent cascading failures.
80
80
* Data dependency failures are handled with circuit breakers and retry logic.
81
81
82
-
Security considerations:
82
+
#### Security
83
83
84
84
* All inputs to AI models are validated and sanitized.
85
85
* Least privilege access applies to agent tool permissions and data access.
86
86
* Model endpoints and training data are protected with appropriate access controls.
87
87
* For comprehensive security architecture reviews, delegate to the `security-plan-creator` agent.
88
88
89
-
Cost optimization considerations:
89
+
#### Cost Optimization
90
90
91
91
* Model selection matches the complexity required by each task.
92
92
* Compute resources scale with demand rather than fixed provisioning.
93
93
* Caching strategies reduce redundant model invocations.
94
94
* Data transfer and storage costs are evaluated against retention policies.
95
95
96
-
Operational excellence considerations:
96
+
#### Operational Excellence
97
97
98
98
* Model performance and drift are monitored with alerting thresholds.
99
99
* Deployment pipelines support model versioning and rollback.
100
100
* Observability covers both infrastructure metrics and model-specific telemetry.
101
101
102
-
Performance efficiency considerations:
102
+
#### Performance Efficiency
103
103
104
104
* Model latency budgets are defined for each user-facing interaction.
105
105
* Horizontal scaling strategies account for stateful components.
Evaluate architectural options by mapping system requirements to solution patterns. Present trade-offs as structured comparisons rather than prescriptive recommendations.
111
111
112
-
Database selection criteria:
112
+
#### Database Selection
113
113
114
-
* High write volume with simple queries favors document databases
115
-
* Complex queries with transactional integrity favors relational databases
116
-
* High read volume with infrequent writes favors read replicas with caching layers
117
-
* Real-time update requirements favor WebSocket or server-sent event architectures
114
+
* High write volume with simple queries favors document databases.
115
+
* Complex queries with transactional integrity favors relational databases.
116
+
* High read volume with infrequent writes favors read replicas with caching layers.
117
+
* Real-time update requirements favor WebSocket or server-sent event architectures.
118
118
119
-
AI architecture selection criteria:
119
+
#### AI Architecture Selection
120
120
121
-
* Single-model inference favors managed AI services
* AI and ML workloads favor separated compute with GPU-optimized infrastructure.
131
+
* High-compliance environments favor private cloud or air-gapped deployments.
132
132
133
133
For each trade-off, document the decision drivers, options considered, and rationale for the recommendation.
134
134
135
135
### Step 5: Document Architecture Decisions
136
136
137
137
Create an Architecture Decision Record for each significant architectural choice. Use the ADR template at `docs/templates/adr-template-solutions.md` as the structural foundation.
138
138
139
-
ADR creation criteria — document decisions when they involve:
139
+
ADR creation criteria: document decisions when they involve:
140
140
141
141
* Database or storage technology choices
142
142
* API architecture and communication patterns
143
143
* Deployment strategy or infrastructure topology changes
144
144
* Major technology adoptions or replacements
145
145
* Security architecture decisions affecting system boundaries
146
146
147
-
Save ADRs to`docs/architecture/ADR-[number]-[title].md` with sequential numbering (ADR-001, ADR-002). Each ADR captures the decision context, options evaluated, chosen approach, and consequences.
147
+
Save ADRs under`docs/decisions/` using ISO date-prefixed filenames (`YYYY-MM-DD-short-title.md`). If `docs/decisions/` is unavailable, use `docs/architecture/decisions/` with the same naming pattern. Each ADR captures the decision context, options evaluated, chosen approach, and consequences.
148
148
149
149
For detailed, interactive ADR development with Socratic coaching, use the ADR Creation handoff to delegate to the `adr-creation` agent.
0 commit comments