Purpose
AI assistants can support architectural work by helping analyse trade-offs, document decisions, explore design alternatives and review architectural consistency.
This document provides prompt patterns and workflows for using AI assistants in common architecture tasks.
As with all AI-assisted work, every output must be reviewed by a human architect before acting on it.
Principles for AI-Assisted Architecture
AI Handles Analysis; Humans Make Decisions
AI can analyse, compare and suggest. It cannot evaluate organisational context, team dynamics or business strategy. Architectural judgement remains a human responsibility.
AI is Best at Structured Problems
AI excels at analysing structured information: comparing alternatives, identifying patterns, generating documentation from templates. It is less reliable for novel or ambiguous architectural problems.
Context Must Include Constraints
Architecture is about trade-offs under constraints. AI needs to understand the constraints to provide useful analysis. Provide quality attribute priorities, technology constraints and organisational context.
Workflows
Trade-off Analysis
Purpose
Use AI to analyse trade-offs between architectural approaches, identifying impacts on quality attributes that might be overlooked.
Context to Provide
- The architectural decision to be made.
- Quality attribute priorities (ranked).
- Technology and organisational constraints.
- Approaches under consideration.
Prompt Pattern
I am evaluating architectural approaches for:
[problem description]
Quality attribute priorities (ranked):
1. [attribute 1]
2. [attribute 2]
3. [attribute 3]
Constraints:
- [constraint 1]
- [constraint 2]
Approach A: [brief description]
Approach B: [brief description]
For each approach, analyse:
1. How it impacts each quality attribute.
2. Key trade-offs.
3. Risks and mitigation strategies.
4. Conditions that would make this approach the right choice.
ADR Drafting
Purpose
Use AI to draft Architecture Decision Records from discussion notes, reducing the friction of documenting decisions.
Context to Provide
- The decision that was made.
- Why it was made.
- Alternatives that were considered.
- Consequences (positive and negative).
Prompt Pattern
Draft an Architecture Decision Record for the following decision:
***Context***
[describe the situation, problem and forces]
***Decision***
[what was decided]
***Alternatives Considered***
- [alternative 1]: [why rejected]
- [alternative 2]: [why rejected]
***Positive Consequences***
- [consequence 1]
- [consequence 2]
***Negative Consequences***
- [consequence 1]
- [consequence 2]
Use the ADR template format:
- Context
- Decision
- Consequences
- Alternatives Considered
- References
Link to related ADRs if relevant: [list related ADRs]
Pattern Selection
Purpose
Use AI to evaluate which architectural patterns suit a given problem context.
Context to Provide
- System description and goals.
- Current architecture (if evolving an existing system).
- Key constraints and quality attribute priorities.
- Team size and organisational structure.
Prompt Pattern
I need to choose an architectural pattern for:
[system description]
Current state: [new system / evolving existing system]
Quality attribute priorities (ranked):
1. [attribute 1]
2. [attribute 2]
Constraints:
- [constraint 1]
- [constraint 2]
Team context:
- Team size: [number]
- Organisational structure: [description]
Evaluate these patterns for suitability:
1. Layered Architecture
2. Hexagonal Architecture
3. Event-Driven Architecture
4. Microservices
For each, explain:
1. Why it fits or does not fit given the context.
2. What modifications would be needed.
3. The key risk to manage if chosen.
Architecture Review Preparation
Purpose
Use AI to prepare for architecture reviews by summarising proposals, identifying potential issues and suggesting review questions.
Context to Provide
- The ADR or RFC under review.
- Current architecture context.
- Relevant standards and principles.
Prompt Pattern
Help me prepare for an architecture review of the following proposal:
[ADR or RFC content]
Architecture context:
[current architecture summary]
Review criteria:
1. Problem alignment: Does this solve the stated problem?
2. Principle alignment: Is it consistent with our principles?
3. Quality attributes: Are trade-offs acknowledged?
4. Alternatives: Were meaningful alternatives considered?
5. Consequences: Are the consequences fully understood?
For each criterion:
1. Summarise how the proposal addresses it.
2. Suggest questions the review team should ask.
3. Identify potential blind spots.
System Design Exploration
Purpose
Use AI to explore design alternatives, generate C4 diagrams from descriptions, and identify design considerations.
Context to Provide
- System purpose and scope.
- Key entities and their relationships.
- External systems and integrations.
- Quality attribute requirements.
Prompt Pattern
I am designing a system for:
[purpose and scope]
Key entities:
- [entity 1]: [description]
- [entity 2]: [description]
External integrations:
- [system 1]: [purpose]
- [system 2]: [purpose]
Quality attribute priorities:
1. [attribute 1]
2. [attribute 2]
Based on this, help me:
1. Identify the main bounded contexts or service boundaries.
2. Describe the system context (C4 Level 1).
3. Describe the container structure (C4 Level 2).
4. Highlight key design decisions and trade-offs.
Anti-patterns
AI as Decision Maker
Letting AI make architectural decisions rather than informing human judgement. AI does not understand business context, team dynamics or organisational politics.
Ignoring Organisational Context
Architecture must consider team structure, skill sets and Conway's Law. AI cannot evaluate these factors without explicit guidance.
Over-Abstraction
AI may suggest patterns or abstractions that add complexity without commensurate benefit. Evaluate every AI suggestion against the principle of minimising accidental complexity.