# MVP — Gestor de conocimiento personal práctico Documento de ejecución pensado para usar directamente con Claude Code. --- ## 1. Objetivo del MVP Construir una aplicación web local-first para gestión de conocimiento personal enfocada en **captura rápida**, **relación automática** y **recuperación útil**. No es una app de notas genérica. El MVP debe resolver bien estos casos: - guardar comandos frecuentes - guardar snippets de código - registrar decisiones técnicas - guardar recetas - guardar trámites o procedimientos - mantener inventario doméstico simple La propuesta de valor del MVP es: 1. **Guardar info rápido** con fricción mínima. 2. **Relacionarla sola** usando metadatos, enlaces sugeridos y contenido similar. 3. **Devolverla cuando importa** mediante búsqueda potente y vistas útiles. --- ## 2. Principios del producto ### 2.1 Principios funcionales - Crear una nota debe tomar menos de 10 segundos. - La búsqueda debe encontrar contenido por título, texto, tags y tipo. - La app debe sugerir relaciones sin exigir organización manual compleja. - El sistema debe ser útil desde el día 1 con pocas notas. - Debe funcionar bien para conocimiento práctico, no solo escritura larga. ### 2.2 Principios técnicos - **Local-first**: los datos viven primero en el dispositivo. - **Simple de desplegar y mantener**. - **Escalable por capas**: empezar pequeño sin bloquear futuras mejoras. - **Estructura tipada**: tipos de contenido claros. - **Extensible** para futuro tagging semántico, embeddings y sincronización. --- ## 3. Alcance del MVP ### 3.1 Incluye #### Captura - Crear nota rápida desde un input o modal. - Campos mínimos: - título - contenido - tipo - tags manuales opcionales - Crear desde plantillas simples según tipo. #### Tipos de nota del MVP - `command` - `snippet` - `decision` - `recipe` - `procedure` - `inventory` - `note` (genérico) #### Organización automática - Extracción automática de: - fecha de creación - fecha de actualización - tipo - tags sugeridos por heurística simple - Detección de notas relacionadas por: - coincidencia de tags - similitud de título - palabras clave compartidas - mismo tipo #### Recuperación - Búsqueda full-text. - Filtros por tipo y tags. - Vista de resultados ordenada por relevancia simple. - Vista de “relacionadas” dentro de cada nota. - Vista de “recientes”. #### Edición - Editar nota existente. - Eliminar nota. - Marcar favorita. - Pin opcional para destacar notas críticas. #### Persistencia - Base local con SQLite. - Exportar/importar JSON. --- ### 3.2 No incluye en el MVP - colaboración multiusuario - sincronización en la nube - permisos y autenticación compleja - edición en tiempo real - embeddings/vector DB en producción - OCR - app móvil nativa - plugins - automatizaciones complejas - parser avanzado de documentos adjuntos --- ## 4. Stack sugerido ## Frontend - **Next.js 15** con App Router - **TypeScript** - **Tailwind CSS** - **shadcn/ui** para componentes ## Backend - API routes / server actions de Next.js - **Prisma** como ORM - **SQLite** para MVP ## Búsqueda - inicialmente con consultas SQL + normalización simple - opcional: SQLite FTS si da tiempo ## Validación - **Zod** ## Estado - React server components + estado local mínimo - si hace falta: Zustand muy limitado ## Testing - **Vitest** para lógica - **Playwright** para flujo principal si alcanza ## Motivo de esta elección Este stack permite: - iterar rápido - mantener una sola codebase - ejecutar localmente fácil - migrar luego a Postgres sin rehacer todo --- ## 5. Arquitectura funcional ### 5.1 Entidades principales #### Note Campos sugeridos: - `id` - `title` - `content` - `type` - `createdAt` - `updatedAt` - `isFavorite` - `isPinned` #### Tag - `id` - `name` #### NoteTag - `noteId` - `tagId` #### RelatedNote - `id` - `sourceNoteId` - `targetNoteId` - `score` - `reason` Opcional en MVP si se prefiere calcular en runtime en vez de persistir. --- ### 5.2 Modelo de datos recomendado ```prisma model Note { id String @id @default(cuid()) title String content String type NoteType @default(note) isFavorite Boolean @default(false) isPinned Boolean @default(false) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt tags NoteTag[] } model Tag { id String @id @default(cuid()) name String @unique notes NoteTag[] } model NoteTag { noteId String tagId String note Note @relation(fields: [noteId], references: [id], onDelete: Cascade) tag Tag @relation(fields: [tagId], references: [id], onDelete: Cascade) @@id([noteId, tagId]) } enum NoteType { command snippet decision recipe procedure inventory note } ``` --- ## 6. UX mínima del MVP ### 6.1 Pantallas #### Home / Dashboard Debe mostrar: - barra de búsqueda principal - botón “Nueva nota” - sección de notas recientes - sección de favoritas o pineadas - filtros rápidos por tipo #### Lista de notas - búsqueda - filtros por tipo - filtros por tags - cards compactas con: - título - tipo - preview corta - tags - fecha de actualización #### Detalle de nota - título - tipo - contenido - tags - acciones: editar, borrar, favorita, pin - bloque “Notas relacionadas” #### Crear/editar nota - formulario simple - selector de tipo - área de contenido grande - campo de tags opcional - templates por tipo --- ### 6.2 Flujo ideal 1. Usuario abre app. 2. Escribe una nota nueva en segundos. 3. La nota se guarda localmente. 4. El sistema sugiere tags y notas relacionadas. 5. Días después el usuario la encuentra por búsqueda, filtro o relación. --- ## 7. Lógica de negocio del MVP ### 7.1 Reglas de creación Al crear una nota: - validar que título y contenido no estén vacíos - normalizar espacios - guardar tipo - parsear tags manuales si existen - generar tags sugeridos por heurística opcional ### 7.2 Heurísticas de tags sugeridos Heurística simple inicial: - extraer palabras frecuentes relevantes del título - detectar bloques de código para sugerir `code`, `bash`, `sql`, etc. - detectar patrones: - receta → `cocina` - decisión → `arquitectura`, `backend`, etc. según keywords - inventario → `hogar` No hace falta IA real en MVP. Debe ser determinístico y simple. ### 7.3 Cálculo de relacionadas Implementación simple: - +3 puntos si comparten tipo - +2 por cada tag compartido - +1 por palabra relevante compartida en título - +1 si una keyword del contenido aparece en ambas Mostrar top 5 relacionadas con score > umbral. Se puede calcular: - on-demand en el detalle de la nota, o - al guardar/editar la nota Para el MVP, **on-demand** es suficiente. ### 7.4 Búsqueda Primera versión: - buscar en `title` - buscar en `content` - buscar en nombres de tags - permitir filtro por `type` Orden sugerido: 1. coincidencia en título 2. coincidencia en tags 3. coincidencia en contenido 4. updatedAt desc --- ## 8. Templates por tipo ### command Campos base: - título - comando - explicación - contexto de uso Template de contenido sugerido: ```md ## Comando ## Qué hace ## Cuándo usarlo ## Ejemplo ``` ### snippet ```md ## Snippet ## Lenguaje ## Qué resuelve ## Notas ``` ### decision ```md ## Contexto ## Decisión ## Alternativas consideradas ## Consecuencias ``` ### recipe ```md ## Ingredientes ## Pasos ## Tiempo ## Notas ``` ### procedure ```md ## Objetivo ## Pasos ## Requisitos ## Problemas comunes ``` ### inventory ```md ## Item ## Cantidad ## Ubicación ## Notas ``` --- ## 9. Estructura de carpetas sugerida ```txt src/ app/ page.tsx notes/ page.tsx [id]/page.tsx new/page.tsx edit/[id]/page.tsx api/ notes/route.ts notes/[id]/route.ts search/route.ts components/ note-form.tsx note-card.tsx note-list.tsx search-bar.tsx related-notes.tsx filters.tsx dashboard.tsx lib/ prisma.ts db.ts search.ts related.ts tags.ts templates.ts validators.ts types/ note.ts prisma/ schema.prisma ``` --- ## 10. API / acciones mínimas ### CRUD de notas - `GET /api/notes` - `POST /api/notes` - `GET /api/notes/:id` - `PUT /api/notes/:id` - `DELETE /api/notes/:id` ### búsqueda - `GET /api/search?q=...&type=...&tag=...` ### export/import - `GET /api/export` - `POST /api/import` --- ## 11. Historias de usuario principales ### HU1 — Crear nota rápida Como usuario, quiero crear una nota en pocos segundos, para no perder información útil. Criterios de aceptación: - puedo crear una nota con título, contenido y tipo - queda persistida localmente - aparece en recientes inmediatamente ### HU2 — Buscar conocimiento guardado Como usuario, quiero encontrar una nota por texto libre, para recuperar información cuando la necesito. Criterios: - la búsqueda encuentra coincidencias en título y contenido - puedo filtrar por tipo - resultados aparecen rápido ### HU3 — Ver contenido relacionado Como usuario, quiero que el sistema me muestre notas relacionadas, para redescubrir información útil. Criterios: - cada nota muestra hasta 5 relacionadas - la relación se basa en reglas simples entendibles ### HU4 — Usar plantillas Como usuario, quiero crear notas con estructura base según el tipo, para capturar mejor cada caso. Criterios: - al elegir un tipo puedo cargar un template sugerido - puedo editar el template libremente ### HU5 — Exportar datos Como usuario, quiero exportar mis datos, para no quedar atado a la app. Criterios: - exporta a JSON válido - puedo reimportar ese JSON --- ## 12. Roadmap de implementación del MVP ### Fase 1 — Base funcional Objetivo: tener CRUD y persistencia. Entregables: - setup Next.js + Tailwind + Prisma + SQLite - schema Prisma - migraciones - CRUD básico de notas - listado y detalle - formulario crear/editar ### Fase 2 — Búsqueda y filtros Objetivo: recuperar bien. Entregables: - search por título/contenido - filtros por tipo - filtros por tags - home con recientes y favoritas ### Fase 3 — Relación automática Objetivo: conectar conocimiento. Entregables: - heurística de tags sugeridos - cálculo de relacionadas - UI de relacionadas en detalle ### Fase 4 — Pulido MVP Objetivo: dejarlo presentable y usable. Entregables: - templates por tipo - export/import JSON - validaciones - estados vacíos - seed de ejemplo --- ## 13. Definición de terminado El MVP está listo cuando: - se puede crear, editar y borrar notas - las notas se persisten en SQLite - se puede buscar por texto - se puede filtrar por tipo y tags - cada nota muestra relacionadas - existen templates por tipo - existe export/import JSON - la UI es suficientemente clara para uso diario local --- ## 14. Riesgos y cómo reducirlos ### Riesgo 1: demasiada ambición Mitigación: - no agregar sync ni IA real al MVP - priorizar velocidad de uso y recuperación ### Riesgo 2: búsqueda pobre Mitigación: - priorizar calidad de búsqueda antes de features cosméticas - evaluar SQLite FTS si la búsqueda simple queda corta ### Riesgo 3: relaciones poco útiles Mitigación: - mantener heurísticas transparentes - mostrar razones simples del match en una versión futura ### Riesgo 4: modelo demasiado genérico Mitigación: - usar tipos concretos desde el inicio - mantener `note` genérico solo como fallback --- ## 15. Mejoras post-MVP - sincronización entre dispositivos - embeddings para similitud semántica real - parser de comandos/snippets automático - extensión de navegador para guardar rápido - captura por share sheet móvil - recordatorios contextuales - grafos de relación - OCR y adjuntos - versionado de notas - vistas especializadas por tipo --- ## 16. Prompt maestro para ejecutar en Claude Code Usar este prompt como instrucción principal: ```txt Quiero que construyas un MVP funcional de una aplicación llamada “Gestor de conocimiento personal práctico”. Objetivo del producto: - guardar info rápido - relacionarla sola - devolverla cuando importa Casos de uso principales: - comandos - snippets - decisiones técnicas - recetas - trámites/procedimientos - inventario doméstico Stack requerido: - Next.js 15 con App Router - TypeScript - Tailwind CSS - shadcn/ui - Prisma - SQLite - Zod Requisitos funcionales del MVP: 1. CRUD completo de notas. 2. Tipos de nota: command, snippet, decision, recipe, procedure, inventory, note. 3. Formulario de creación/edición con título, contenido, tipo y tags opcionales. 4. Dashboard con búsqueda, recientes y favoritas/pineadas. 5. Lista de notas con filtros por tipo y tags. 6. Búsqueda por título, contenido y tags. 7. Página de detalle con notas relacionadas. 8. Templates simples por tipo. 9. Exportar e importar JSON. 10. Persistencia local usando SQLite. Reglas de relacionadas: - +3 si comparten tipo - +2 por cada tag compartido - +1 por palabra relevante compartida en el título - +1 por keyword compartida en el contenido - mostrar top 5 con score suficiente Restricciones: - No implementar autenticación. - No implementar sync cloud. - No implementar IA compleja ni vector DB. - Mantener el código limpio, modular y listo para evolucionar. Quiero que generes: 1. La estructura inicial del proyecto. 2. El schema de Prisma. 3. Los componentes principales. 4. Las rutas/páginas necesarias. 5. Las utilidades para búsqueda, tags y relacionadas. 6. Un seed de datos de ejemplo. 7. Instrucciones claras para correr el proyecto. Además: - usa buenas prácticas - separa responsabilidades - evita sobreingeniería - deja comentarios donde aporten claridad - entrega una primera versión funcional de punta a punta ``` --- ## 17. Prompt por etapas para Claude Code ### Etapa 1 — Setup base ```txt Crea el proyecto base con Next.js 15, TypeScript, Tailwind, Prisma y SQLite. Configura la estructura de carpetas, instala dependencias, crea el schema inicial de Prisma para Note, Tag y NoteTag, genera migración y deja una app corriendo con una página home básica. ``` ### Etapa 2 — CRUD ```txt Implementa el CRUD completo de notas. Debe existir listado, detalle, creación, edición y borrado. Cada nota debe tener title, content, type, tags opcionales, isFavorite e isPinned. Usa validación con Zod. ``` ### Etapa 3 — Búsqueda y filtros ```txt Implementa búsqueda por texto sobre título, contenido y tags. Agrega filtros por tipo y tags. Crea una home con notas recientes, favoritas y acceso rápido a crear nota. ``` ### Etapa 4 — Relacionadas ```txt Implementa la lógica de notas relacionadas usando reglas heurísticas simples. Muestra hasta 5 notas relacionadas en la vista de detalle. ``` ### Etapa 5 — Templates y export/import ```txt Agrega templates por tipo de nota y funciones para exportar e importar datos en JSON. Incluye manejo básico de errores y estados vacíos. ``` --- ## 18. Checklist de validación manual - [ ] La app inicia sin errores. - [ ] Se puede crear una nota. - [ ] Se puede editar una nota. - [ ] Se puede eliminar una nota. - [ ] La búsqueda encuentra texto por título. - [ ] La búsqueda encuentra texto por contenido. - [ ] Se puede filtrar por tipo. - [ ] Las tags se guardan y se pueden usar como filtro. - [ ] El detalle muestra relacionadas. - [ ] Se puede exportar JSON. - [ ] Se puede importar JSON. - [ ] Hay seed de ejemplo útil para probar. --- ## 19. Criterio de éxito del MVP El MVP será exitoso si una persona puede usarlo durante una semana para guardar y recuperar conocimiento práctico sin sentir que necesita otra herramienta para: - recordar comandos - reutilizar snippets - revisar decisiones - seguir procedimientos - consultar inventario o recetas --- ## 20. Recomendación final Para este MVP conviene optimizar en este orden: 1. velocidad de captura 2. calidad de búsqueda 3. utilidad de relacionadas 4. claridad visual 5. exportabilidad No priorizar IA antes de demostrar que la base manual + heurística ya resuelve valor real.