| name | metodologia-ai-software-architecture |
| description | AI software architecture design — modules, layers, boundaries, design patterns, ADRs, quality attributes, and technical debt strategy for AI-enabled systems. This skill should be used when the user asks to "design AI system structure", "define AI module boundaries", "select AI architecture patterns", "document AI architecture decisions", "evaluate AI code architecture", or mentions AI pipelines, feature stores, model serving, drift detection, ML quality attributes, explainability architecture, or AI technical debt.
|
| model | opus |
| context | fork |
| allowed-tools | ["Read","Write","Edit","Glob","Grep","Bash"] |
AI Software Architecture: Internal Structure & Design Decisions for AI-Enabled Systems
AI software architecture defines how code is organized internally in systems that combine traditional software components with AI/ML capabilities — module boundaries spanning data pipelines, model serving, and feature stores; layer separation across the 6-layer AI stack; design patterns bridging traditional and AI-specific concerns; and the reasoning behind technical decisions. This skill produces comprehensive architecture documentation that enables teams to understand, maintain, and evolve AI-enabled systems.
Principio Rector
En sistemas de IA, la arquitectura implica dos tipos de deuda: la del codigo y la del modelo. Ignorar cualquiera de las dos garantiza degradacion silenciosa. Por eso se documenta ANTES de implementar, se valida contra quality attributes medibles (incluyendo fairness, explainability, robustness), y cada decision vive en un ADR con alternativas y trade-offs.
Filosofia de Arquitectura de Software para IA
- El modelo es un componente, no el sistema. La arquitectura de IA es 80% ingenieria de datos, serving, y monitoreo. El modelo es el nucleo analitico, pero sin la arquitectura circundante es un notebook, no un sistema de produccion.
- Quality attributes mandan — incluyendo los de IA. Performance y availability no bastan. Fairness, explainability, robustness y drift resilience son quality attributes de primera clase. Un modelo preciso pero opaco o sesgado es una bomba regulatoria.
- Drift es la deuda tecnica especifica de IA. En software tradicional, la deuda se acumula por decisiones de codigo. En IA, la deuda se acumula porque los datos cambian y el modelo no. Monitorear drift no es opcional — es higiene arquitectonica.
Inputs
The user provides a system or project name as $ARGUMENTS. Parse $1 as the system/project name used throughout all output artifacts.
Parameters:
{MODO}: piloto-auto (default) | desatendido | supervisado | paso-a-paso
- piloto-auto: Auto para analisis de estructura y patterns, HITL para ADRs y decisiones de modelo.
- desatendido: Cero interrupciones. Arquitectura documentada automaticamente. Supuestos documentados.
- supervisado: Autonomo con checkpoint en pattern selection, model topology, y ADRs.
- paso-a-paso: Confirma cada module view, pattern, ADR, y plan de evolucion.
{FORMATO}: markdown (default) | html | dual{VARIANTE}: ejecutiva (~40% — S1 module view + S3 patterns + S5 ADRs) | tecnica (full 6 sections, default)
Before generating architecture, detect the codebase context:
!find . -name "*.py" -o -name "*.ts" -o -name "*.java" -o -name "*.go" | head -30
Use detected languages, frameworks, and ML libraries (PyTorch, TensorFlow, scikit-learn, LangChain, Hugging Face) to tailor pattern recommendations and component naming.
If reference materials exist, load them:
Read ${CLAUDE_SKILL_DIR}/references/ai-architecture-stack.md
Read ${CLAUDE_SKILL_DIR}/references/ai-quality-attributes.md
Read ${CLAUDE_SKILL_DIR}/references/ai-patterns-catalog.md
When to Use
- Designing modular structure for new AI-enabled systems or major AI refactors
- Evaluating existing architecture against AI quality attributes (fairness, explainability, robustness)
- Selecting design patterns for AI systems (Feature Store, Champion-Challenger, Shadow Deployment, Drift Detection)
- Documenting architectural decisions for model selection, training strategy, inference topology
- Identifying anti-patterns and debt in AI pipelines before they compound
- Communicating AI architecture to development teams, data scientists, and stakeholders
- Planning evolution strategy for AI systems aligned with business and technical constraints
When NOT to Use
- CONOPS and operational concept for AI systems → metodologia-ai-conops
- Detailed pipeline architecture (dev/prod pipelines, CI/CD for AI) → metodologia-ai-pipeline-architecture
- Deep pattern catalog with tactics and anti-patterns → metodologia-ai-design-patterns
- Comprehensive testing strategy for AI systems → metodologia-ai-testing-strategy
- GenAI/LLM-specific architecture (RAG, agents, vector DBs) → metodologia-genai-architecture
- AWS-specific service selection and Well-Architected assessment → metodologia-aws-architecture-design
- End-to-end solution design across multiple systems → metodologia-solutions-architecture
- Enterprise portfolio alignment → metodologia-enterprise-architecture
- Infrastructure and platform design → metodologia-infrastructure-architecture
Delivery Structure: 6 Sections
S1: AI System Module View
Maps the internal module structure through the 6-layer AI architecture stack: Hardware, Data, Model, Inference, Application, Monitoring & Control.
Includes:
- Module decomposition across the 6 layers — what modules exist per layer, responsibilities, dependencies
- Dependency graph showing coupling between traditional software modules and AI-specific modules
- Layer map with clear separation and dependency direction (upper layers depend on lower layers)
- Module-to-team ownership mapping (data engineering, ML engineering, platform, product)
- Identified dependency violations and cycles — especially training-serving skew risks
Key decisions:
- Granularity: monolithic pipeline vs. decomposed stages vs. microservice-per-model
- Direction: all dependencies flow inward (Hexagonal) vs. layered flow vs. event-driven
- Shared components: feature stores, model registries, embedding caches — minimize coupling
- Cross-module contracts: data contracts between pipeline stages, model interface contracts
S2: AI Component View
Decomposes selected modules into components — what they do, interfaces exposed, dependencies. Focus on the five core production pipeline components.
Components:
- Data Cleansing: Schema validation, anomaly detection, data quality enforcement
- Data Transformation: Feature engineering, embedding generation, format conversion
- ML Model: Model registry integration, A/B testing framework, explainability hooks
- Pipeline Operations: Monitoring, alerting, self-healing, visualization
- Results Store: Prediction storage, feature attribution, audit trails, BI integration
Key decisions:
- Component interfaces: input/output contracts, versioning for stability
- Dependency injection for model swapping without pipeline changes
- Monitoring hooks: performance metrics, prediction distributions, resource utilization
S3: Design Patterns
Documents selected patterns with justification, detected anti-patterns, and alternatives. Bridges traditional and AI-specific pattern catalogs.
AI-specific patterns (Feature Store, Champion-Challenger, Shadow Deployment, Drift Detection, Explainability Wrapper, Canary Deployment, Bulkhead):
- Why chosen: which AI quality attribute it enables
- How applied: concrete examples from the system
- Implications: compute cost, operational complexity, team structure
Traditional patterns adapted for AI (Service-Oriented, Balancer, Circuit, Throttle, N-Party Voting):
- How the pattern changes when applied to AI workloads
- GPU-aware, drift-aware, or fairness-aware adaptations
Anti-patterns detected (Training-serving skew, Pipeline jungle, Dead feature columns, Undeclared consumers):
- Location in codebase, consequences if unaddressed, refactoring approach
Principle: Patterns serve quality attributes. A Feature Store without multiple consumers is overhead. Shadow Deployment without evaluation criteria is wasted compute.
S4: Quality Attribute Scenarios (ATAM + AI)
ATAM-style scenarios extended with AI-specific quality attributes: Stimulus → Response → Measure
| Quality Attribute | Example Scenario |
|---|
| Performance | Inference request completes within 200ms (p95) under 1000 concurrent users |
| Accuracy | ML model accuracy >= .88 threshold, .94 objective |
| Fairness | Model fairness across demographic groups >= 90% parity (threshold), 95% (objective) |
| Explainability | Explainability score >= 0.7 (threshold), 0.8 (objective); top-5 features explain >60% |
| Robustness | Model accuracy change under perturbation <= +/-10% (threshold), +/-5% (objective) |
| Drift Resilience | Drift detected within <1 hour (threshold), <10 minutes (objective) |
| Availability | Service remains available during model failure with <30s failover to fallback |
| Modifiability | Swapping model algorithm requires changes to <=3 modules |
| Deployability | New model version deployed in <15 min with instant rollback |
| Compliance | All model decisions have complete audit trails; governance review workflows enforced |
S5: Architecture Decision Records (ADRs)
Captures significant AI architecture decisions with context, decision, consequences, and alternatives.
AI-specific ADR topics:
- Model architecture selection (transformer vs. ensemble vs. linear)
- Training strategy (batch vs. online vs. transfer learning)
- Inference topology (real-time vs. batch vs. streaming vs. edge)
- Feature store adoption (build vs. buy vs. skip)
- Monitoring strategy (drift detection algorithm, alert thresholds)
- Multi-model strategy (single model vs. tiered vs. ensemble)
- Data pipeline architecture (batch vs. streaming vs. hybrid)
- Explainability approach (SHAP vs. LIME vs. attention-based)
ADR structure: Title, Status, Context (business + technical constraints), Decision (what + why), Consequences (positive/negative/neutral), Alternatives considered, Related decisions.
Scope: Decisions affecting multiple pipeline stages, requiring significant refactoring if changed, or trading off AI quality attributes.
S6: Debt & Evolution Plan
Identifies current architectural debt — including AI-specific debt — and a strategy for evolution.
AI-specific debt types:
- Model drift debt: Models serving stale predictions because monitoring is absent or ignored
- Training-serving skew debt: Different feature computation in training vs. production
- Pipeline jungle debt: Tangled dependencies between pipeline stages with no clear contracts
- Dead feature debt: Features computed but never used by any model
- Undeclared consumer debt: Downstream systems depending on model outputs without formal contracts
- Experiment debt: Abandoned experiments leaving orphaned code, configs, and data
- Responsible AI debt: Missing fairness audits, absent explainability mechanisms, no bias monitoring — accumulates regulatory and reputational risk
- LLMOps debt: Prompt templates without version control, untracked context window usage, no cost attribution per LLM call
Evolution strategy:
- Phased approach: debt reduction does not block feature delivery
- Strangler fig for pipeline modernization: old and new pipelines coexist during transition
- Testing coverage: increase before major refactors — especially model regression tests
- Monitoring-first: instrument before optimizing
- Team structure: align teams to pipeline boundaries (data, model, serving, ops)
Trade-off Matrix
| Decision | Enables | Constrains | When to Use |
|---|
| Monolithic Pipeline | Simple deployment, easy debugging | Tight coupling, hard to scale components independently | Early-stage, single-model systems |
| Microservice-per-Model | Independent scaling, tech diversity | Distributed complexity, network overhead | Multi-model, multi-team, high-scale |
| Feature Store | Consistency, reuse, drift monitoring | Infrastructure overhead, governance cost | Multiple models share features |
| Champion-Challenger | Data-driven updates, risk management | Doubled compute, statistical significance needed | Production model updates |
| Shadow Deployment | Real-world validation without risk | Doubled inference compute, no user signal | High-stakes, regulated predictions |
| Drift Detection | Proactive model updates, early warning | Monitoring infrastructure, threshold calibration | All production AI systems |
| Explainability Wrapper | Transparency, compliance, trust | Added latency, explanation fidelity trade-off | Regulated industries, user-facing |
| Bulkhead Isolation | Fault containment, independent scaling | Resource overhead per compartment | Multi-model serving, critical availability |
Assumptions
- System contains or will contain AI/ML components alongside traditional software
- Team includes or will include ML engineers, data engineers, and software engineers
- Quality attributes and constraints have been discussed (from prior discovery or CONOPS)
- Access to codebase for structure inspection is available
- Time is available for architecture documentation (not reverse-engineered under pressure)
- Organizational maturity allows for dedicated monitoring and governance processes
Limits
- Focuses on logical architecture, not physical deployment (see metodologia-infrastructure-architecture)
- Does not design external integration points (see metodologia-solutions-architecture)
- Does not address team structure or enterprise governance (see metodologia-enterprise-architecture)
- Does not detail pipeline implementation (see metodologia-ai-pipeline-architecture)
- Does not provide deep pattern implementation guides (see metodologia-ai-design-patterns)
- GenAI/LLM-specific patterns (RAG, agents) require metodologia-genai-architecture
Edge Cases
Greenfield AI System:
No existing structure; risk of over-engineering for hypothetical scale. Start with monolithic pipeline, defer microservice decomposition. Use ADRs for reversible decisions. Prioritize monitoring from day one.
Legacy System Adding AI:
Existing architecture not designed for AI workloads. Watch for: impedance mismatch between request-response web app and batch training pipelines, data access patterns that don't support feature engineering, deployment processes that can't handle model artifacts. Use strangler fig for gradual AI integration.
Multi-Model System:
Multiple models serving different use cases from shared data. Risk of resource contention, dependency conflicts, cascade failures. Apply Bulkhead pattern. Feature Store becomes essential. Model registry is non-optional.
Real-Time AI System:
Latency requirements constrain model complexity, feature computation, and explanation depth. May need edge inference, model compression, or prediction caching. Quality attribute trade-offs between accuracy and latency must be explicit in ADRs.
Regulated AI System (Finance, Healthcare):
Compliance requirements (audit trails, explainability, fairness) are architectural constraints, not afterthoughts. Explainability Wrapper pattern is mandatory. Data lineage tracking at every pipeline stage. Model governance workflows built into CI/CD.
Validation Gate
Before finalizing delivery, verify:
Cross-References
- metodologia-ai-conops: Provides upstream operational concept, stakeholders, and interaction spectrum
- metodologia-ai-pipeline-architecture: Receives architecture direction; designs pipeline implementation
- metodologia-ai-design-patterns: Deep pattern catalog and system tactics for AI
- metodologia-ai-testing-strategy: Testing strategy aligned to architecture quality attributes
- metodologia-genai-architecture: GenAI/LLM-specific architectural patterns (RAG, agents, vector DBs)
- metodologia-aws-architecture-design: Maps AI architecture to AWS services (Bedrock, SageMaker, OpenSearch)
- metodologia-software-architecture: Traditional software architecture (non-AI) — complementary skill
- metodologia-solutions-architecture: Integrates AI architecture into end-to-end solution design
- metodologia-infrastructure-architecture: Receives compute and storage needs; designs the platform
- metodologia-devsecops-architecture: Uses architecture decisions to design pipeline security controls
Output Format Protocol
| Format | Default | Description |
|---|
markdown | Yes | Rich Markdown + Mermaid diagrams. Token-efficient. |
html | On demand | Branded HTML (Design System). Visual impact. |
dual | On demand | Both formats. |
Default output is Markdown with embedded Mermaid diagrams. HTML generation requires explicit {FORMATO}=html parameter.
Output Artifact
Primary: A-01_AI_Software_Architecture_Deep.html — Executive summary, 6-layer module view, component cards, hybrid design patterns, AI quality attribute scenarios, ADRs, debt inventory and evolution roadmap.
Secondary: ADR repository (.md files, version-controlled), AI architecture stack diagram (Mermaid/PNG/SVG), quality attribute scenario checklist, pattern selection decision tree.
Fuente: Avila, R.D. & Ahmad, I. (2025). Architecting AI Software Systems. Packt. | Bass, L., Clements, P., & Kazman, R. (2021). Software Architecture in Practice (4th ed.). Addison-Wesley.
