software-architecture-guidelines

SKILL.md

---
name: software-architecture-guidelines
description: Apply contextual software architecture guidance when analyzing system boundaries, quality requirements, communication, styles, decisions, risks, or evolution.
---

# Software Architecture Guidelines

Use this portable draft to support architecture work across software domains. It is not installed globally. The book supplies concepts and trade-offs; this guide operationalizes them as conditional checks. They are not project commands or substitutes for user intent, local governance, or known system evidence.

## Workflow

1. **Establish context and authority.** Identify the domain, system boundary, business outcomes, deployment and data constraints, team capabilities, known evidence, unknowns, and decision authority. Respect authority already delegated. Ask only for missing facts that can change the result; otherwise give a conditional recommendation.
2. **Rank drivers.** Translate stakeholder outcomes into architectural characteristics. Test each candidate against the three-part definition, decompose composite qualities, and prioritize a small set.
3. **Map boundaries and data.** Identify functional responsibilities, dependencies, transactions, data ownership, static coupling, runtime calls, and characteristics at each relevant boundary.
4. **Compare proportionally.** For a consequential choice, compare at least two viable options against the stated priorities, costs, risks, and evidence. Do not force a formal comparison for a small, reversible change.
5. **Decide with rationale.** State the recommendation or status, why it fits, accepted costs, assumptions, and what evidence would cause reconsideration. Follow delegated authority; do not invent approval gates.
6. **Specify checks.** Choose measures or fitness functions proportional to the risk. Name their scope, signal, limitations, and response.

## Core rules

- Ground recommendations in context ([context and priority rules](references/rulebook.md#context-priorities): F01) and respect delegated authority ([decision, risk, and evolution rules](references/rulebook.md#decisions-risk-evolution): D03).
- Derive and rank characteristics from measurable stakeholder outcomes ([context and priority rules](references/rulebook.md#context-priorities): F05, F06, F07, F08, F18).
- Keep responsibilities cohesive and boundaries honest about dependencies and coupling ([boundary rules](references/rulebook.md#boundaries-coupling-data): F11–F17, S03, S08; [glossary](references/glossary.md)).
- Choose communication for the work; distinguish request, command, and event, and design for failure ([communication rules](references/rulebook.md#communication-reliability): S06, S09–S13, S15, D08).
- Treat architecture styles as conditional options and compare their costs ([style rules](references/rulebook.md#style-choice): S01, S16, D06; [style guide](references/style-selection.md)).
- Record why consequential decisions exist and what would change them ([trade-offs](references/rulebook.md#context-priorities): F02; [decision records](references/rulebook.md#decisions-risk-evolution): F03).
- Make risk, uncertainty, and implementation alignment visible ([risk and evolution rules](references/rulebook.md#decisions-risk-evolution): D10, D11, D12, D13).
- Govern important constraints with checks people understand ([governance rules](references/rulebook.md#decisions-risk-evolution): F09, F10).
- Preserve team choice within the actual authority and constraints ([team and communication rules](references/rulebook.md#communication-teams): S04, D16, D17, D18).
- Apply provider-specific guidance only when the project includes a model provider ([D15 in rules.json](references/rules.json)).

## Output contract

Return: context and unknowns; recommendation and status; alternatives and costs; boundary, data, and communication implications; evidence and checks; and a reconsideration trigger. Scale detail to the consequence of the choice.

## References

For a task, load only the relevant category in [rules.json](references/rules.json) or read its section in [rulebook.md](references/rulebook.md), not both or the entire pack. Load [style-selection.md](references/style-selection.md) for the nine styles, [glossary.md](references/glossary.md) for source-based terms, and [source-map.json](references/source-map.json) to locate cited chapters. Synthetic evaluation prompts are in [evaluation-cases.json](references/evaluation-cases.json); they have not been run. Method and limitations are in [method-and-validation.md](references/method-and-validation.md).