762 lines
16 KiB
Markdown
762 lines
16 KiB
Markdown
# 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.
|