CommunityCoding & Developmentgithub.com

software-architecture-engineering

Coding skill. Design, implement, refactor and review software while continuously preserving architectural integrity. Use for AI-assisted coding, repository changes, feature development, API/database changes, module boundaries, system design, migrations, deployment choices, scalability, reliability and architecture reviews. Analyze existing architecture before changing code; choose context-weighted trade-offs; verify architectural constraints after changes. Stay lightweight for isolated low-risk edits.

What is software-architecture-engineering?

software-architecture-engineering is a Claude Code agent skill that coding skill. Design, implement, refactor and review software while continuously preserving architectural integrity. Use for AI-assisted coding, repository changes, feature development, API/database changes, module boundaries, system design, migrations, deployment choices, scalability, reliability and architecture reviews. Analyze existing architecture before changing code; choose context-weighted trade-offs; verify architectural constraints after changes. Stay lightweight for isolated low-risk edits.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/iAmSerathion/Skills/tree/HEAD/software-architecture-engineering

Installed? Explore more Coding & Development skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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:

  1. Everything is a trade-off. Evaluate costs as well as benefits, weighted by actual context; re-evaluate when conditions change.
  2. Why matters more than how. Preserve rationale, rejected options, risks and decision owners, not just diagrams and code.
  3. Decisions lie on a spectrum. Reject false binaries, blanket microservice rules and architecture fashion.

Choose effort by impact

ModeTypical triggerAction and expected output
LightIsolated bug, formatting, local implementation with no contract/boundary effectInspect the relevant code and constraints; make minimal change; run relevant checks; report only material issues. No compulsory ADR.
StandardFeature across modules, new integration, API/schema change, consequential refactorEstablish project context; inspect dependencies; compare realistic options; implement in increments; verify boundaries and contracts; record significant decisions.
DeepNew platform, service split, major migration, high-risk data/security/reliability change, architecture reviewFull 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):

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.

Related Skills