Software Architect

Design scalable systems with sound trade-offs, clear boundaries, and maintainable patterns.

Security Scan

This is an instruction-only advisory skill that provides high-level software architecture guidance and does not request credentials, install software, or access system files — its behavior matches its description.

Purpose & Capability

Name and description match the SKILL.md content. The skill is instruction-only and does not request unrelated binaries, env vars, or config paths — nothing requested is disproportionate to providing architecture advice.

Instruction Scope

SKILL.md contains high-level design principles and checklists only; it does not instruct the agent to read files, access system state, call external endpoints, or exfiltrate data. The guidance is broad by design but stays within advisory scope.

Install Mechanism

No install spec or code files are present. Instruction-only skills write nothing to disk and have minimal execution surface — this is the lowest-risk install model.

Credentials

The skill requires no environment variables, credentials, or config paths. No secret access is requested or implied by the instructions.

Persistence & Privilege

always is false and the skill is user-invocable (standard). It does not request persistent system presence or modify other skills/configuration.

Assessment

This skill is low-risk and simply provides architecture advice. Before using it, avoid pasting secrets or private configuration/state into prompts. Remember the agent's recommendations are guidance — review and validate any design decisions before applying them to real systems. If you need hands-on operations (deployments, infra changes), prefer skills that explicitly declare and justify any required credentials or install steps.

Software Architecture Rules

Design Principles

• Simple until proven insufficient — complexity is a cost, not a feature
• Separate what changes from what stays stable — boundaries at change boundaries
• Design for the next 10x, not 100x — over-engineering wastes resources
• Make decisions reversible when possible — defer irreversible ones until necessary
• Constraints clarify design — embrace limitations, don't fight them early

System Boundaries

• Define clear interfaces between components — contracts enable independent evolution
• Boundaries where teams split — Conway's Law is real, design with it
• Data ownership at boundaries — one source of truth per entity
• Async communication for loose coupling — sync calls create distributed monoliths
• Fail independently — one component's failure shouldn't cascade

Trade-off Analysis

• Every decision has costs — articulate what you're giving up
• Consistency vs availability vs partition tolerance — pick two (CAP theorem)
• Performance vs maintainability — optimize hot paths, keep the rest readable
• Build vs buy — build differentiators, buy commodities
• Document the "why not" for rejected alternatives — future you needs context

Scalability

• Stateless services scale horizontally — state makes scaling hard
• Cache aggressively, invalidate carefully — caching solves and creates problems
• Database is usually the bottleneck — read replicas, sharding, or denormalization
• Queue work that can be async — users don't need to wait for everything
• Scale for expected load, prepare for 3x spikes — headroom prevents outages

Data Architecture

• Schema design constrains everything — get it right early, migrations are expensive
• Normalize for writes, denormalize for reads — optimize for access patterns
• Event sourcing when audit trail matters — reconstruct state from events
• CQRS when read/write patterns differ significantly — separate models for each
• Data gravity is real — processing moves to data, not vice versa

Reliability

• Design for failure — everything fails eventually, handle it gracefully
• Timeouts on all external calls — hung connections cascade into outages
• Circuit breakers prevent cascade failures — fail fast, recover gradually
• Idempotency for retries — duplicate messages shouldn't corrupt state
• Graceful degradation over total failure — partial functionality beats error pages

Security

• Defense in depth — multiple layers, no single point of failure
• Least privilege — minimal permissions for each component
• Encrypt in transit and at rest — assume networks and disks are hostile
• Validate at boundaries — don't trust input from outside your system
• Secrets management from day one — retrofitting is painful

Evolution

• Design for replacement, not immortality — components will be rewritten
• Incremental migration over big bang — strangler fig pattern works
• Backwards compatibility for APIs — breaking changes break trust
• Feature flags decouple deploy from release — ship dark, enable gradually
• Monitor before, during, and after changes — data beats intuition

Documentation

• Document decisions, not just structures — ADRs capture reasoning
• Diagrams at multiple zoom levels — C4 model: context, containers, components
• Keep docs near code — separate wikis go stale
• Update docs when architecture changes — wrong docs are worse than none
• Document operational aspects — runbooks, SLOs, failure modes

Communication

• Translate technical decisions to business impact — stakeholders need context
• Present options with trade-offs — don't just recommend, explain
• Listen to operators — they know what breaks
• Involve security early — bolt-on security is weak security
• Decisions need buy-in — imposed architecture breeds resentment