步骤 0.3：生成适合受众的解释

如果受众是非技术人员**（管理层/投资者）：**

使用以下规则：

• 零未解释的技术术语。每个技术术语都附带类比。
• 结构："问题 → 解决方案 → 工作原理（简单）→ 为何重要"
• 使用现实世界的类比（见下方类比表）
• 最多 3 层深度
• 包含简化的 Mermaid 图表（使用可理解的名称框，而非技术名称）

非技术受众类比表：

如果受众是技术人员**：**

• 使用精确的术语
• 包含识别出的设计模式（使用名称：Saga、CQRS、事件溯源等）
• 指出隐含的架构决策和权衡
• 提及可以考虑的替代方案
• 包含技术组件的详细 Mermaid 图表

步骤 0.4：生成系统的 Mermaid 图表

始终生成一个图表，并根据受众调整：

对于非技术人员 — 使用描述性名称的框：

graph LR
    Usuario[👤 用户提问] --> Buscador[📚 文档搜索器]
    Buscador --> Asistente[🤖 AI 助手]
    Asistente --> Respuesta[💬 带来源的答案]

对于技术人员 — 实际组件：

graph TD
    Client[Web App / API] --> Gateway[API Gateway]
    Gateway --> Orch[Orchestrator - LangChain]
    Orch --> Retrieval[Retrieval Pipeline]
    Orch --> LLM[Claude Sonnet via API]
    Retrieval --> VDB[(Qdrant - Vector DB)]
    Retrieval --> BM25[BM25 - Keyword Search]
    LLM --> Guards[Guardrails + Citation]
    Guards --> Client

步骤 0.5：分析交付物

分析文档结构：

# 架构分析 — [项目名称]

## 这是什么？（1 段话，任何人都能理解）

## 它如何工作？（根据受众调整）
[Mermaid 图表]
[按层/组件的解释]

## 主要组件
| 组件 | 功能 | 技术 | 类比 |
|-----------|----------|-----------|---------|

## 数据流（逐步说明）
1. [步骤 1 — 使用受众语言]
2. [步骤 2...]

## 架构优势
- [设计良好的部分及原因]

## 改进机会
- [可以改进的部分及原因]

## 已识别的风险
- [技术或业务风险]

分析后，询问："你想让我基于此设计一个改进版本或新架构吗？" 如果是 → 过渡到设计模式（阶段 1）。

设计模式 — 5 阶段工作流

阶段 1        → 阶段 2            → 阶段 3        → 阶段 4          → 阶段 5
架构头脑风暴   方法选择            架构层设计       技术栈评估         架构文档

顺序执行所有阶段。每个阶段产生交付物，作为下一阶段的输入。

阶段 1：架构头脑风暴

灵感来自 Superpowers 的 Brainstorming 模式 (obra/superpowers)。

不要立即设计。首先，通过结构化的头脑风暴流程与用户一起探索问题，将模糊的想法提炼为清晰的需求。

头脑风暴规则：

• 一次一个问题 — 不要用多个问题压倒用户
• 首选多项选择 — 比开放性问题更容易回答
• 无情地应用 YAGNI — 从所有设计中移除不必要的功能
• 探索替代方案 — 在决定之前总是提出 2-3 种方法
• 增量验证 — 分部分呈现设计，在继续之前获得批准

头脑风暴流程：

探索上下文 → 澄清问题（一次一个） →
  提出 2-3 种方法 → 分部分呈现设计 →
    用户批准吗？ → 否：修订 → 是：进入阶段 2

步骤 1.1：探索项目上下文 提出这些问题，一次一个，在下一个问题前等待回答：

1. 这个解决方案解决什么业务问题？（用 2-3 句话）
2. 最终用户是谁？预期有多少用户？
3. 目前存在什么吗？选项：(a) 遗留系统，(b) 手动流程，(c) 什么都没有

步骤 1.2：AI 功能需求（一次一个问题）

1. AI 应该"做"什么？选项：(a) 回答关于自有文档的问题，(b) 生成内容，(c) 分类/提取数据，(d) 推荐，(e) 自动化操作，(f) 组合
2. 它基于什么知识运作？选项：(a) 内部文档，(b) 结构化数据/数据库，(c) 通用知识，(d) 实时信息，(e) 组合
3. 是否需要访问外部系统？（API、数据库、工具）
4. 是否需要交互间的记忆？

步骤 1.3：约束条件（一次一个问题）

1. 基础设施的大致月度预算？选项：(a) <$100，(b) $100-500，(c) $500-2000，(d) $2000+，(e) 未定义
2. 延迟要求？选项：(a) <1s 交互式，(b) <5s 可接受，(c) 批处理/异步无限制
3. 隐私要求？选项：(a) 数据可以发送到云端/API，(b) 敏感数据，偏好本地部署，(c) 严格监管 (GDPR/HIPAA)
4. 可用团队？选项：(a) 1-2 名无 ML 经验的开发者，(b) 3-5 名有一定经验的开发者，(c) 有 ML 工程师的团队
5. 时间线？选项：(a) 2-4 周内 MVP，(b) 2-3 个月内产品，(c) 6+ 个月内平台

将空白处标记为 "⚠️ 待定义"。

步骤 1.4：提出 2-3 种方法

根据回答，提出 2-3 种替代性架构方法。对于每种方法，用约 100 字描述：

• 包含什么（主要组件）
• 主要权衡（得到什么 vs 牺牲什么）
• 适合谁

呈现这些方法并等待用户选择或要求更改。根据复杂性调整每个部分：如果直接则用几句话，如果复杂则提供更多细节。

步骤 1.5：验证

在进入阶段 2 之前，向用户确认：

• "这种方法是否捕捉了你的需求？"
• "有什么遗漏或多余的吗？"

只有当用户确认后才进入阶段 2。

阶段 2：方法选择

使用决策树确定架构方法。完整细节请阅读 resources/decision-frameworks.md。

解决方案是否需要最新的或特定领域的知识？
├─ 是 → 什么类型的知识？
│   ├─ 自有文档/数据 → RAG
│   ├─ 特定领域行为 → 微调
│   └─ 两者 → 混合 (RAG + 微调)
│
├─ 否 → 是否需要执行操作？
│   ├─ 是 → 复杂度如何？
│   │   ├─ 1-3 个工具，线性流程 → 简单智能体 (ReAct)
│   │   └─ 多个步骤，分支 → 多智能体
│   └─ 否 → 提示工程 (基础 LLM 足够)
│
└─ 最佳可能结果
    └─ 混合：RAG + 微调 + 智能体

权衡评估（强制性）：

为用户的具体案例证明选择的合理性。

阶段 3：架构层设计

按层设计架构。每层的完整参考请阅读 resources/architecture-layers.md。

RAG 解决方案参考架构：

┌─────────────────────────────────────────────────────┐
│                 表示层                              │
│  Web App / Mobile / API / Chat Interface / Slack Bot │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│                 编排层                              │
│  API Gateway → Orchestrator (LangChain/LlamaIndex)  │
│  Session Manager → Memory Store → Rate Limiter       │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│                 智能层                              │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ 检索     │  │  LLM     │  │  后处理           │  │
│  │ 管道     │  │  网关    │  │  (护栏,           │  │
│  │          │  │          │  │   格式化)         │  │
│  └──────────┘  └──────────┘  └───────────────────┘  │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│                 数据与索引层                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │
│  │ 文档     │  │ 嵌入     │  │ 向量     │           │
│  │ 管道     │  │ 服务     │  │ 存储     │           │
│  │ (摄取,   │  │          │  │          │           │
│  │  分块,   │  │          │  │          │           │
│  │  清洗)   │  │          │  │          │           │
│  └──────────┘  └──────────┘  └──────────┘           │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│                 基础设施层                          │
│  Cloud Provider → Compute → Storage → Networking     │
│  Monitoring → Logging → CI/CD → Security             │
└─────────────────────────────────────────────────────┘

对于每一层，记录：

1. 组件：包含哪些部分
2. 职责：做什么和不做什么
3. 接口：如何与相邻层通信
4. 关键决策：需要为该层决定什么
5. 风险：可能出错的地方

为每个提出的架构变体生成 Mermaid 图表。

阶段 4：技术栈与评估

完整的选择矩阵请阅读 resources/tech-stack-matrices.md。

对于每个关键组件，使用加权标准评估选项：

4.1 LLM 模型

4.2 向量数据库 (如果使用 RAG)

4.3 编排框架

4.4 分块策略 (如果使用 RAG)

4.5 嵌入策略

显示每个选择的数值分数和理由。

阶段 5：架构文档

使用完全相同的结构生成：

# 架构文档 — [解决方案名称]
**日期：** [日期] | **版本：** 1.0 | **作者：** [用户]

## 1. 上下文与问题
[2-3 段：业务问题、用户、现状]

## 2. 选择的方法
[选择的方法 + 权衡表 + 理由]

## 3. 高层架构
[完整系统的 Mermaid 图表]

### 3.1 分层视图
[带组件的分层图表]

### 3.2 数据流视图
[从用户输入到响应的顺序图]

## 4. 分层详情

### 4.1 表示层
- 组件：[列表]
- 技术：[选择 + 理由]
- 接口：[暴露的 API]

### 4.2 编排层
- 组件：[列表]
- 技术：[框架 + 理由]
- 模式：[同步/异步，重试，熔断器]

### 4.3 智能层
- LLM 模型：[选择 + 带分数的理由]
- 检索管道：[策略 + 理由]
- 护栏：[应用了哪些保护措施]

### 4.4 数据与索引层
- 向量数据库：[选择 + 带分数的理由]
- 嵌入：[模型 + 维度 + 理由]
- 分块：[策略 + 大小 + 理由]
- 摄取：[文档管道，频率，格式]

### 4.5 基础设施层
- 云：[提供商 + 服务]
- 计算：[实例类型，如适用 GPU]
- 监控：[工具，关键指标]
- CI/CD：[部署流水线]

## 5. 图表

### 5.1 架构图 (Mermaid)
[完整的 C4 图或流程图]

### 5.2 顺序图 — 主流程
[Mermaid 顺序图：用户 → 前端 → 编排器 → 检索 → LLM → 响应]

### 5.3 数据摄取图
[Mermaid：来源 → 提取 → 分块 → 嵌入 → 存储]

## 6. 架构决策记录 (ADRs)

### ADR-001：[标题]
- **上下文：**[为什么需要这个决策]
- **决策：**[决定了什么]
- **评估的替代方案：**[考虑了哪些其他方案]
- **后果：**[接受的权衡]

[为每个关键决策重复]

## 7. 成本估算

| 组件 | 服务 | 月度估算成本 |
|-----------|---------|----------------------|
| LLM API | [提供商] | $[X] |
| 向量数据库 | [服务] | $[X] |
| 计算 | [实例] | $[X] |
| 存储 | [类型] | $[X] |
| **总计** | | **$[X]** |

⚠️ 估算基于[假设用量]。根据实际使用情况调整。

## 8. 风险与缓解措施

| 风险 | 可能性 | 影响 | 缓解措施 |
|--------|-------------|---------|-----------|
| | | | |

## 9. 实施路线图

### 阶段 1：MVP ([X] 周)
- [用于验证的最小组件]

### 阶段 2：生产环境 ([X] 周)
- [可扩展性，监控，安全性]

### 阶段 3：优化 ([X] 周)
- [微调，高级 RAG，持续评估]

## 10. 假设与限制
[所有标记为"待定义"的列表 + 设计限制]

护栏

分析模式

• 受众优先 — 在分析之前总是询问解释给谁听
• 强制使用类比 — 如果受众非技术，每个技术概念都必须附带类比
• 强制使用图表 — 每个分析必须包含至少 1 个根据受众调整的 Mermaid 图表
• 非技术图表中最多 7 个框
• 先问题后解决方案 — 在解释"用什么"之前先解释"为什么"
• 如果用户粘贴的内容不完整，指出需要什么来获得更好的分析

设计模式

• 始终先进行头脑风暴 — 没有头脑风暴（阶段 1）就不要设计
• 一次一个问题 — 不要用多个问题压倒用户
• 2-3 种替代方案 — 在设计之前总是提出替代方法
• YAGNI — 如果团队今天不需要，就不要设计它。指出升级路径。
• 生成有效且可渲染的 Mermaid 图表
• 显示技术栈评估的数值分数
• 用 ⚠️ 标记成本估算
• 每个 ADR 必须至少评估 2 种替代方案
• 优先考虑用户团队能够维护的解决方案
• 如果检测到过度设计（2 人团队想要多智能体），请指出
• 建议从简单开始并逐步演进（提示工程 → RAG → 微调 → 混合）

两种模式

• 如果用户没有 ML 经验，用类比解释概念
• 使用阶段 0 的类比表作为技术术语的参考
• 如果信息不足，请要求更多上下文 — 切勿编造

每周安装数

1

仓库

aguirrerjg/skills

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1

Paso 0.2: Análisis del repositorio

Con el material que el usuario comparta, extrae y organiza:

Mapa del sistema (qué piezas tiene y cómo se conectan):

• Componentes principales identificados
• Flujo de datos: ¿de dónde entra info y hacia dónde sale?
• Dependencias externas: ¿qué servicios/APIs/librerías usa?
• Stack tecnológico: lenguajes, frameworks, bases de datos

Patrón arquitectónico detectado:

• ¿Es monolito, microservicios, serverless, event-driven?
• ¿Usa RAG, agentes, fine-tuning, o combinación?
• ¿Qué patrón de orquestación sigue?

Paso 0.3: Generar explicación adaptada a la audiencia

Si audiencia es NO TÉCNICA (dirección/inversores):

Usa estas reglas:

• Cero jerga técnica sin explicar. Cada término técnico va con analogía.
• Estructura: "El problema → La solución → Cómo funciona (simple) → Por qué importa"
• Usa analogías del mundo real (ver tabla de analogías abajo)
• Máximo 3 niveles de profundidad
• Incluye diagrama Mermaid simplificado (cajas con nombres comprensibles, no técnicos)

Tabla de analogías para audiencia no técnica:

Si audiencia es TÉCNICA:

• Usa terminología precisa
• Incluye patrones de diseño identificados (con nombres: Saga, CQRS, event sourcing, etc.)
• Señala decisiones arquitectónicas implícitas y trade-offs
• Menciona alternativas que podrían considerarse
• Diagrama Mermaid detallado con componentes técnicos

Paso 0.4: Generar diagrama Mermaid del sistema

Genera SIEMPRE un diagrama, adaptado a la audiencia:

Para no técnicos — cajas con nombres descriptivos:

graph LR
    Usuario[👤 Usuario hace pregunta] --> Buscador[📚 Buscador de documentos]
    Buscador --> Asistente[🤖 Asistente IA]
    Asistente --> Respuesta[💬 Respuesta con fuentes]

Para técnicos — componentes reales:

graph TD
    Client[Web App / API] --> Gateway[API Gateway]
    Gateway --> Orch[Orchestrator - LangChain]
    Orch --> Retrieval[Retrieval Pipeline]
    Orch --> LLM[Claude Sonnet via API]
    Retrieval --> VDB[(Qdrant - Vector DB)]
    Retrieval --> BM25[BM25 - Keyword Search]
    LLM --> Guards[Guardrails + Citation]
    Guards --> Client

Paso 0.5: Entregable del análisis

Estructura del documento de análisis:

# Análisis de Arquitectura — [Nombre del Proyecto]

## ¿Qué es esto? (1 párrafo, comprensible para cualquiera)

## ¿Cómo funciona? (adaptado a audiencia)
[Diagrama Mermaid]
[Explicación por capas/componentes]

## Componentes principales
| Componente | Qué hace | Tecnología | Analogía |
|-----------|----------|-----------|---------|

## Flujo de datos (paso a paso)
1. [Paso 1 — en lenguaje de la audiencia]
2. [Paso 2...]

## Puntos fuertes de la arquitectura
- [Lo que está bien diseñado y por qué]

## Oportunidades de mejora
- [Lo que podría mejorarse y por qué]

## Riesgos identificados
- [Riesgos técnicos o de negocio]

Después del análisis, pregunta: "¿Quieres que diseñe una versión mejorada o una arquitectura nueva basada en esto?" Si SÍ → Transición a Modo DISEÑAR (Fase 1).

MODO DISEÑAR — Workflow de 5 Fases

Fase 1        → Fase 2            → Fase 3        → Fase 4          → Fase 5
Brainstorming   Selección de        Diseño de        Tech Stack        Documento de
Arquitectónico  Enfoque             Capas            y Evaluación      Arquitectura

Ejecuta TODAS las fases secuencialmente. Cada fase produce entregables que alimentan la siguiente.

FASE 1: BRAINSTORMING ARQUITECTÓNICO

Inspirado en el patrón Brainstorming de Superpowers (obra/superpowers).

NO diseñes de inmediato. Primero, explora el problema con el usuario usando un proceso estructurado de brainstorming que refine ideas vagas en requisitos claros.

Reglas del brainstorming:

• UNA pregunta a la vez — no abrumes con múltiples preguntas
• Opción múltiple preferida — más fácil de responder que preguntas abiertas
• YAGNI implacable — elimina features innecesarias de todos los diseños
• Explora alternativas — SIEMPRE propón 2-3 enfoques antes de decidir
• Validación incremental — presenta diseño por secciones, obtén aprobación antes de avanzar

Flujo del brainstorming:

Explorar contexto → Preguntas clarificadoras (1 a la vez) →
  Proponer 2-3 enfoques → Presentar diseño por secciones →
    ¿Usuario aprueba? → NO: revisar → SÍ: Avanzar a Fase 2

Paso 1.1: Explorar contexto del proyecto Haz ESTAS preguntas, UNA POR UNA, esperando respuesta antes de la siguiente:

1. ¿Qué problema de negocio resuelve esta solución? (en 2-3 frases)
2. ¿Quién es el usuario final? ¿Cuántos usuarios esperados?
3. ¿Existe algo hoy? Opciones: (a) sistema legacy, (b) proceso manual, (c) nada

Paso 1.2: Requisitos funcionales de IA (una pregunta a la vez)

1. ¿Qué debe "hacer" la IA? Opciones: (a) responder preguntas sobre docs propios, (b) generar contenido, (c) clasificar/extraer datos, (d) recomendar, (e) automatizar acciones, (f) combinación
2. ¿Sobre qué conocimiento opera? Opciones: (a) documentos internos, (b) datos estructurados/BD, (c) conocimiento general, (d) info en tiempo real, (e) combinación
3. ¿Necesita acceder a sistemas externos? (APIs, bases de datos, herramientas)
4. ¿Requiere memoria entre interacciones?

Paso 1.3: Restricciones (una pregunta a la vez)

1. ¿Presupuesto mensual aproximado para infra? Opciones: (a) <$100, (b) $100-500, (c) $500-2000, (d) $2000+, (e) no definido
2. ¿Requisitos de latencia? Opciones: (a) <1s interactivo, (b) <5s aceptable, (c) batch/async sin restricción
3. ¿Requisitos de privacidad? Opciones: (a) datos pueden ir a cloud/API, (b) datos sensibles, prefiero on-premise, (c) regulación estricta (GDPR/HIPAA)
4. ¿Equipo disponible? Opciones: (a) 1-2 devs sin experiencia ML, (b) 3-5 devs con algo de experiencia, (c) equipo con ML engineers
5. ¿Timeline? Opciones: (a) MVP en 2-4 semanas, (b) producto en 2-3 meses, (c) plataforma en 6+ meses

Marca vacíos como "⚠️ POR DEFINIR".

Paso 1.4: Proponer 2-3 enfoques

Basándote en las respuestas, propón 2-3 enfoques arquitectónicos alternativos. Para CADA enfoque describe en ~100 palabras:

• Qué incluye (componentes principales)
• Trade-off principal (qué ganas vs qué sacrificas)
• Para quién es ideal

Presenta los enfoques y ESPERA a que el usuario elija o pida cambios. Escala cada sección a su complejidad: pocas frases si es directo, más detalle si es matizado.

Paso 1.5: Validación

Antes de avanzar a Fase 2, confirma con el usuario:

• "¿Este enfoque captura lo que necesitas?"
• "¿Hay algo que falte o sobre?"

Solo avanza a Fase 2 cuando el usuario confirme.

FASE 2: SELECCIÓN DE ENFOQUE

Usa el árbol de decisión para determinar el enfoque arquitectónico. Lee resources/decision-frameworks.md para los detalles completos.

¿La solución necesita conocimiento actualizado o específico del dominio?
├─ SÍ → ¿Qué tipo de conocimiento?
│   ├─ Documentos/datos propios → RAG
│   ├─ Comportamiento específico del dominio → Fine-tuning
│   └─ Ambos → Híbrido (RAG + Fine-tuning)
│
├─ NO → ¿Necesita ejecutar acciones?
│   ├─ SÍ → ¿Complejidad?
│   │   ├─ 1-3 herramientas, flujo lineal → Agente simple (ReAct)
│   │   └─ Múltiples pasos, bifurcaciones → Multi-agente
│   └─ NO → Prompt engineering (suficiente con LLM base)
│
└─ Mejor resultado posible
    └─ Híbrido: RAG + Fine-tuning + Agentes

Evaluación de trade-offs (obligatoria):

Justifica la selección para el caso específico del usuario.

FASE 3: DISEÑO DE CAPAS ARQUITECTÓNICAS

Diseña la arquitectura por capas. Lee resources/architecture-layers.md para la referencia completa de cada capa.

Arquitectura de referencia para soluciones RAG:

┌─────────────────────────────────────────────────────┐
│                 CAPA DE PRESENTACIÓN                 │
│  Web App / Mobile / API / Chat Interface / Slack Bot │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│              CAPA DE ORQUESTACIÓN                    │
│  API Gateway → Orchestrator (LangChain/LlamaIndex)  │
│  Session Manager → Memory Store → Rate Limiter       │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│              CAPA DE INTELIGENCIA                     │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ Retrieval │  │  LLM     │  │  Post-processing  │  │
│  │ Pipeline  │  │  Gateway │  │  (guardrails,     │  │
│  │          │  │          │  │   formatting)     │  │
│  └──────────┘  └──────────┘  └───────────────────┘  │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│              CAPA DE DATOS E INDEXACIÓN               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │
│  │ Document  │  │ Embedding│  │ Vector   │           │
│  │ Pipeline  │  │ Service  │  │ Store    │           │
│  │ (ingest,  │  │          │  │          │           │
│  │  chunk,   │  │          │  │          │           │
│  │  clean)   │  │          │  │          │           │
│  └──────────┘  └──────────┘  └──────────┘           │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│              CAPA DE INFRAESTRUCTURA                  │
│  Cloud Provider → Compute → Storage → Networking     │
│  Monitoring → Logging → CI/CD → Security             │
└─────────────────────────────────────────────────────┘

Para CADA capa, documenta:

1. Componentes : Qué piezas la componen
2. Responsabilidad : Qué hace y qué NO hace
3. Interfaces : Cómo se comunica con capas adyacentes
4. Decisiones clave : Qué se debe decidir para esta capa
5. Riesgos : Qué puede salir mal

Genera diagrama Mermaid para cada variante arquitectónica propuesta.

FASE 4: TECH STACK Y EVALUACIÓN

Lee resources/tech-stack-matrices.md para las matrices de selección completas.

Para CADA componente clave, evalúa opciones con criterios ponderados:

4.1 Modelo LLM

4.2 Vector Database (si RAG)

4.3 Framework de Orquestación

4.4 Estrategia de Chunking (si RAG)

4.5 Estrategia de Embedding

MUESTRA los scores numéricos y la justificación para cada selección.

FASE 5: DOCUMENTO DE ARQUITECTURA

Genera con EXACTAMENTE esta estructura:

# Documento de Arquitectura — [Nombre de la Solución]
**Fecha:** [fecha] | **Versión:** 1.0 | **Autor:** [usuario]

## 1. Contexto y Problema
[2-3 párrafos: problema de negocio, usuarios, situación actual]

## 2. Enfoque Seleccionado
[Enfoque elegido + tabla de trade-offs + justificación]

## 3. Arquitectura de Alto Nivel
[Diagrama Mermaid del sistema completo]

### 3.1 Vista de Capas
[Diagrama por capas con componentes]

### 3.2 Vista de Flujo de Datos
[Diagrama de secuencia: desde input del usuario hasta respuesta]

## 4. Detalle por Capa

### 4.1 Capa de Presentación
- Componentes: [lista]
- Tecnología: [selección + justificación]
- Interfaces: [APIs expuestas]

### 4.2 Capa de Orquestación
- Componentes: [lista]
- Tecnología: [framework + justificación]
- Patrones: [sync/async, retry, circuit breaker]

### 4.3 Capa de Inteligencia
- Modelo LLM: [selección + justificación con scores]
- Retrieval pipeline: [estrategia + justificación]
- Guardrails: [qué protecciones se aplican]

### 4.4 Capa de Datos e Indexación
- Vector DB: [selección + justificación con scores]
- Embedding: [modelo + dimensiones + justificación]
- Chunking: [estrategia + tamaños + justificación]
- Ingesta: [pipeline de documentos, frecuencia, formatos]

### 4.5 Capa de Infraestructura
- Cloud: [proveedor + servicios]
- Compute: [tipo de instancias, GPU si aplica]
- Monitoring: [herramientas, métricas clave]
- CI/CD: [pipeline de deployment]

## 5. Diagramas

### 5.1 Diagrama de Arquitectura (Mermaid)
[Diagrama C4 o flowchart completo]

### 5.2 Diagrama de Secuencia — Flujo Principal
[Mermaid sequence diagram: user → frontend → orchestrator → retrieval → LLM → response]

### 5.3 Diagrama de Ingesta de Datos
[Mermaid: source → extract → chunk → embed → store]

## 6. Decisiones Arquitectónicas (ADRs)

### ADR-001: [Título]
- **Contexto:** [por qué se necesita esta decisión]
- **Decisión:** [qué se decidió]
- **Alternativas evaluadas:** [qué más se consideró]
- **Consecuencias:** [trade-offs aceptados]

[Repetir para cada decisión clave]

## 7. Estimación de Costos

| Componente | Servicio | Costo mensual estimado |
|-----------|---------|----------------------|
| LLM API | [proveedor] | $[X] |
| Vector DB | [servicio] | $[X] |
| Compute | [instancias] | $[X] |
| Storage | [tipo] | $[X] |
| **Total** | | **$[X]** |

⚠️ Estimaciones basadas en [volumen asumido]. Ajustar según uso real.

## 8. Riesgos y Mitigaciones

| Riesgo | Probabilidad | Impacto | Mitigación |
|--------|-------------|---------|-----------|
| | | | |

## 9. Roadmap de Implementación

### Fase 1: MVP ([X] semanas)
- [componentes mínimos para validar]

### Fase 2: Producción ([X] semanas)
- [escalabilidad, monitoring, seguridad]

### Fase 3: Optimización ([X] semanas)
- [fine-tuning, advanced RAG, evaluación continua]

## 10. Supuestos y Limitaciones
[Lista de todo marcado como "POR DEFINIR" + limitaciones del diseño]

Guardrails

Modo Analizar

• Audiencia primero — SIEMPRE pregunta para quién es la explicación antes de analizar
• Analogías obligatorias — Si la audiencia no es técnica, cada concepto técnico va con analogía
• Diagrama obligatorio — Todo análisis incluye al menos 1 diagrama Mermaid adaptado a la audiencia
• Máximo 7 cajas en diagramas para no-técnicos
• Problema antes que solución — Explica el PARA QUÉ antes del CON QUÉ
• Si el usuario pega contenido incompleto, señala qué más necesitarías para un análisis mejor

Modo Diseñar

• Brainstorming primero, SIEMPRE — No diseñes sin antes hacer brainstorming (Fase 1)
• Una pregunta a la vez — No abrumes al usuario con múltiples preguntas
• 2-3 alternativas — Siempre propón enfoques alternativos antes de diseñar
• YAGNI — Si el equipo no lo necesita hoy, no lo diseñes. Señala el upgrade path.
• Genera diagramas Mermaid válidos y renderizables
• MUESTRA los scores numéricos de evaluación de tech stack
• Marca estimaciones de costo con ⚠️
• Cada ADR debe tener al menos 2 alternativas evaluadas
• Prioriza soluciones que el equipo del usuario pueda mantener
• Si detectas sobredimensionamiento (equipo de 2 queriendo multi-agente), señálalo
• Recomienda empezar simple y evolucionar (prompt → RAG → fine-tune → hybrid)

Ambos modos

• Si el usuario no tiene experiencia en ML, explica conceptos con analogías
• Usa la tabla de analogías de la Fase 0 como referencia para términos técnicos
• Si no tienes suficiente información, pide más contexto — nunca inventes

Weekly Installs

1

Repository

aguirrerjg/skills

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1