Software Architecture Engineering
Purpose
Keep architecture coherent while software is being changed, including changes written by AI agents. This is an operational skill, not a command to redesign every project. Its reusable principles come from Fundamentals of Software Architecture, 2nd ed. (Richards and Ford, 2025); continuous agent workflows and artifacts are original extensions. No specific model, programming language, repository host, CI tool or framework is required.
Apply three laws throughout:
- Everything is a trade-off. Evaluate costs as well as benefits, weighted by actual context; re-evaluate when conditions change.
- Why matters more than how. Preserve rationale, rejected options, risks and decision owners, not just diagrams and code.
- Decisions lie on a spectrum. Reject false binaries, blanket microservice rules and architecture fashion.
Choose effort by impact
| Mode | Typical trigger | Action and expected output |
|---|---|---|
| Light | Isolated bug, formatting, local implementation with no contract/boundary effect | Inspect the relevant code and constraints; make minimal change; run relevant checks; report only material issues. No compulsory ADR. |
| Standard | Feature across modules, new integration, API/schema change, consequential refactor | Establish project context; inspect dependencies; compare realistic options; implement in increments; verify boundaries and contracts; record significant decisions. |
| Deep | New platform, service split, major migration, high-risk data/security/reliability change, architecture review | Full context and architecture analysis, alternatives, explicit data/failure modes, migration and rollback, measurable fitness functions, ADR(s), risk and approval boundaries. |
Escalate when a supposedly small edit crosses ownership boundaries, changes public contracts, alters persistence, introduces new runtime/deployment components, broadens failure impact or reveals architectural drift. De-escalate if investigation shows no meaningful architecture impact. User/project/safety instructions take precedence. Never force heavyweight reports for trivial tasks.
Required coding-agent loop
For work in an existing repository, perform this loop. See agent implementation governance for precise procedure, failure handling and parallel-agent rules.
0. Discover the current system—do not invent it
- Inspect relevant code, tests, package/build files, infrastructure, configuration, documentation, ADRs, directory layout and actual dependency paths when accessible.
- Locate any project architecture contract, e.g.
docs/architecture/CONTRACT.md, and accepted ADRs; treat them as project constraints, not immutable truths. - Record observed / supplied / assumed / unknown separately. If no code/tool access exists, say that the result is a proposal, not a verified repository analysis.
- Do not silently replace the architecture already in use with a favorite style.
1. Assess impact before editing
- Define change scope, affected business capabilities, owner modules, APIs/contracts, data responsibilities, dependencies, security boundaries, deployment units and failure paths.
- Classify the task Light / Standard / Deep and pick the smallest adequate review.
- For material decisions, derive a few prioritized architectural characteristics (e.g. security, latency, availability, scalability, elasticity, maintainability, testability, deployability, recoverability, cost) with scope, target and measurement. Separate explicit requirements from implicit, unconfirmed needs.
- Choose minimal, reversible defaults for low-risk unknowns; do not proceed on unsupported high-risk assumptions as if confirmed.
2. Preserve boundaries and compare alternatives where warranted
- Favor high cohesion and low coupling. Keep business responsibility, dependency direction, temporal coupling and data ownership explicit. Distinguish logical modules from independently deployed services.
- Check implications for operational and data architecture, not only directory structure. A shared database, transaction boundary or synchronous call can undo apparent modularity.
- For consequential changes, compare at least two feasible options using context-weighted trade-offs. Candidates may include layered, modular monolith, pipeline, microkernel, service-based, event-driven, space-based, orchestration-driven SOA, microservices or hybrids. No architecture style is the universal default.
- Distributed designs must address network failure/latency, availability, consistency, transaction boundaries, retries, idempotency, observability, security and operational cost as applicable.
- Name conditions that would reverse the decision. Use styles, distributed design and foundations selectively.
3. Plan the implementation in safe increments
- Identify expected file/module changes, contracts that must remain stable, migration order and rollback strategy where needed.
- State architecture invariants (rules that must remain true): permitted dependency direction, internal API ownership, data write authority, tenancy/authentication boundaries, backward compatibility, error handling, etc.
- Choose objective checks for those invariants before implementing. Where useful, copy/adapt project architecture contract and change-impact template; do not create project files without permission or clear task scope.
- Request or defer irreversible/high-impact decisions that require human/business authority. Do not counterfeit approvals.
4. Implement without architecture drift
- Make the smallest coherent change consistent with the current architecture. Don't split services, introduce brokers, global abstractions or new frameworks without demonstrated need.
- Keep interfaces and data ownership explicit. Do not create shortcuts through another module's internals, bypass auth/validation, silently change event schemas, or mix unrelated changes.
- If the implementation reveals a material flaw in the plan, stop and reassess the affected decision rather than concealing it with workaround code. Update ADR/contract only when justified.
- In multi-agent work, define component/file ownership, stable contracts and an integration owner. Parallel changes do not override shared architectural constraints.
5. Verify architecture, not just function
- Run relevant existing unit/integration/contract tests and build checks when available and authorized.
- Verify architecture-specific fitness functions: forbidden dependencies, cycles, module ownership, API compatibility, schema migration, idempotency, performance budgets, observability, resilience, security, deployment/rollback, as applicable.
- Compare before/after dependency structure and affected invariants. An optional stdlib import boundary checker with sample config can enforce selected Python/JS/TS import rules; it is intentionally limited and does not prove full architectural correctness.
- Label evidence PASS / FAIL / NOT RUN / NOT APPLICABLE. Do not claim tests, scalability, production readiness, security or deployments were verified without actual execution/evidence.
- If any mandatory gate fails, fix/revert, or explicitly identify the unresolved issue and decision owner. Never present a failed gate as completed work.
6. Record and communicate consequential decisions
- Create or update a concise ADR only for architecture-significant changes: title, status, context, chosen solution, why, alternatives, trade-offs, consequences, enforcement and revisit trigger. Use ADR template.
- Preserve historical decisions when superseded. Treat diagrams as communication aids, not evidence of implementation or validation.
- In final reporting, state: what changed; architecture impact; passed, failed or unrun checks; outstanding risks; and any required human decision. For Light changes, one concise paragraph usually suffices.
Design-only and audit tasks
When not editing a repository, apply steps 0–3 and 6 proportionately; produce a design, trade-off analysis, architecture brief or review without pretending anything was implemented or tested. For a full architecture audit, inventory components, data ownership, boundaries, deployment and team/infrastructure constraints; rank concrete risks with evidence; propose incremental remediations and fitness functions before recommending wholesale rewrites.
Non-negotiable safeguards
- No unverifiable facts: No invented repository inspections, test output, load levels, compliance status, costs, stakeholder approvals or measurements.
- No false universals: Neither microservices nor monoliths nor event-driven systems are inherently best. Do not split services by table/entity alone.
- No scope confusion: Logical modules, deployed units, data ownership and architecture-characteristic scope are different concepts.
- No hidden coupling: Examine shared schemas, shared libraries, temporal coupling, cross-service calls and event contracts; reusing volatile domain logic can increase coupling.
- No risk erasure: Distributed consistency, transaction handling, schema changes, failure recovery and rollback require explicit thought when relevant.
- No process theater: A completed checklist or self-assessment is not proof. Prioritize actual checks and code evidence.
- No silent architecture changes: Flag important deviations, document reasons, and keep responsibility with the human/project decision owner.
- No copyrighted book distribution: This skill is an original synthesis. Do not copy the book or its diagrams into downstream repos.
On-demand reference files
Read only the files needed for the task (paths relative to this skill directory):
- AI coding & continuous architecture governance — required for substantial repository edits, PR reviews, parallel agents and architecture-drift diagnosis.
- Foundations and architecture characteristics — requirements, coupling, cohesion, components, characteristic scope.
- Architecture styles — nine styles and selection conditions.
- Distributed systems and patterns — network reality, events, transactions, consistency, orchestration, CQRS.
- Decisions, fitness functions and risks — ADRs, governance, risk storming, diagrams.
- People, data, infrastructure and AI — teams and operational constraints.
- Source map — all 27 book chapters and distinction between book ideas and agent-specific extensions.
- Verification rubric — quality criteria for major design decisions and implementation review.
Artifacts: architecture brief, architecture contract, change impact, ADR, trade-off matrix, risk register, architecture review, boundary policy example. Worked scenario: AI coding without boundary drift. Other model/runtime instructions are optional; see portability.