¿Qué hace project-registry?
ES — Un skill de Claude Code que gestiona un registro personal de proyectos (
~/projects/PROJECTS.json) con bitácoras de desarrollo legibles por IA por proyecto (CLAUDE.md): listar, crear, eliminar, guardar, reanudar sesión, atribuir decisiones, verificar salud del proyecto y revertir versiones desde un único menú. El texto de la interfaz está en chino, pero los comandos funcionan tanto en chino como en inglés y todas las funciones son completamente operativas independientemente del idioma (la IA entiende ambos). Instalación:npx skills add SUNQSHENG/project-registryo/plugin marketplace add SUNQSHENG/project-registry.
Resumen
Gestiona la lista de proyectos registrados en ~/projects/PROJECTS.json, proporcionando funciones de alta, baja, modificación, consulta y estadísticas. Los proyectos se almacenan como subdirectorios <clave>/ dentro de ~/projects/, y cada proyecto incluye un README.md que documenta el contexto y el alcance.
Al operar sobre un proyecto, automáticamente se hace cd al directorio correspondiente.
Fuente de datos
~/projects/
PROJECTS.json # Registro de proyectos (única fuente autorizada)
<clave>/ # Directorio del proyecto
README.md # Descripción del contexto y alcance del proyecto (para humanos)
CLAUDE.md # Bitácora de desarrollo del proyecto (para IA, se carga automáticamente en cada sesión)
Todos los proyectos deben estar ubicados bajo ~/projects/.
Diferencia: README.md es para que desarrolladores/colaboradores vean el resumen del proyecto; CLAUDE.md es para la IA, registra decisiones, estado y contexto durante el desarrollo, asegurando que los proyectos largos no pierdan información.
Estructura de PROJECTS.json
{
"description": "Lista de proyectos — todos los proyectos se registran aquí",
"updated": "2026-03-01",
"nextSeq": 3,
"projects": [
{
"seq": 1,
"key": "pet_hospital_crm_20260301",
"name": "CRM Hospital Veterinario",
"status": "Completado",
"created": "2026-03-01"
}
]
}
Punto de entrada
Cada vez que se entra al skill, primero se hace cd ~ al directorio raíz del usuario, luego se lee PROJECTS.json para mostrar la lista y un menú simplificado (sin verificación a nivel de directorio):
📋 Lista actual de proyectos (total N)
┌─────┬──────────────────────────────┬─────────────────┬──────────────────────┬────────────┐
│ Nº │ clave │ Nombre │ Estado │ Fecha creac.│
├─────┼──────────────────────────────┼─────────────────┼──────────────────────┼────────────┤
│ 1 │ pet_hospital_crm_20260301 │ CRM Veterinario │ ✅ Completado │ 2026-03-01 │
│ 2 │ gym_members_app_20260315 │ App Gimnasio │ 🔄 En progreso │ 2026-03-15 │
└─────┴──────────────────────────────┴─────────────────┴──────────────────────┴────────────┘
> La visualización inicial no verifica directorios, solo lee el JSON. El estado de los directorios se verifica de forma masiva durante la comprobación MD.
Seleccione una acción (o diga directamente lo que necesita):
- Ingrese el **número** del proyecto (1-99) → Abre el proyecto correspondiente (ej. 12)
- 🆕 N. Nuevo proyecto
- 🗑️ D. Eliminar proyecto
- 🔍 C. Comprobación MD (verifica todos los proyectos de forma masiva)
> Otras necesidades (modificar/buscar/estadísticas/actualizar registro/guardar/salir/**comprobar proyecto**/**por qué X**) simplemente dígalas en la conversación.
> ⚠️ **Al guardar/salir se actualiza automáticamente CLAUDE.md** (regla obligatoria).
⚙️ Guía de configuración inicial (API Key opcional)
La primera vez que se accede al skill:
- Verificar si están configuradas las variables de entorno
PR_API_BASE_URL/PR_API_KEY/PR_API_MODEL(printenv) - No configuradas → Tarjeta AskUserQuestion preguntando: «¿Desea configurar una clave API para habilitar el resumen automático?»
- Configurar (recomendado) → Guiar para establecer las tres variables de entorno (el README tiene ejemplos de proveedores: DeepSeek / OpenAI / Tongyi / Ollama local)
- Saltar → Escribir en
<directorio del skill>/config.json(marcar como «saltado», no preguntar de nuevo) - Saber más → Mostrar tabla comparativa de funcionalidades
- La configuración surte efecto inmediatamente (no requiere reiniciar la sesión)
Comparativa de funcionalidades:
| Capacidad | Sin Key | Con Key |
|---|---|---|
| Seguridad de datos (copia de seguridad en segundos + commit automático al finalizar sesión) | ✅ | ✅ |
| Todas las funciones principales (registro/reanudación de sesión/atribución/reversión/verificación) | ✅ | ✅ |
| Resumen automático (destilación automática de la conversación → actualización en tiempo real de CLAUDE.md) | ❌ | ✅ |
En cualquier momento diga «configurar API» para reiniciar la guía.
🔍 Identificación automática del proyecto actual
Al entrar al skill ya se ha hecho automáticamente
cd ~. Las operaciones que requieran ubicar el proyecto (verificar/modificar/guardar/actualizar registro, etc.) identifican automáticamente el directorio actual:
1. `pwd` verifica si coincide con ~/projects/<clave>/
2. Coincide → Se selecciona automáticamente ese proyecto
3. No coincide → Selección manual (por número o clave)
🧭 Flujo de inicio de sesión (restauración de contexto)
Solo se activa para operaciones del tipo «entrar a trabajar en un proyecto»: abrir proyecto / verificar / modificar / actualizar registro / guardar / salir. Las operaciones ligeras como ver detalles, buscar, estadísticas no lo activan.
Después de entrar al proyecto y antes de ejecutar la acción, primero se revisa el contexto y luego se retoma (evita pérdida de información en proyectos largos, o no saber por dónde empezar al reingresar tras una interrupción):
- Leer el CLAUDE.md del proyecto (si existe)
- Resumir el progreso anterior: citar «estado actual / últimos avances», combinando con
git logde los commits recientes cuando sea necesario - Listar «próximos pasos» (por prioridad 1. 2. 3. …)
- Preguntar al usuario por dónde continuar (usar una tarjeta AskUserQuestion para presentar las opciones de próximos pasos), confirmar antes de actuar
Ejemplo de texto (nota al pie de la tarjeta):
📌 Resumen del último progreso: Inicialización del proyecto completada, registro creado
➡️ Próximos pasos (por prioridad):
1. Completar documento de requisitos
2. Completar lista de tareas pendientes
¿Por dónde continuar?
Para proyectos nuevos (CLAUDE.md recién creado) se puede omitir la revisión e ir directamente a la operación.
📂 Abrir proyecto
- Localizar proyecto por número o clave → Verificar que existe el directorio
~/projects/<clave>/ cdal directorio del proyecto- Activar «🧭 Flujo de inicio de sesión» (revisar último progreso → confirmar continuación)
- Una vez que el usuario comienza a trabajar dentro del proyecto, operar según sea necesario (modificar/actualizar registro/guardar/salir)
Detalles de las operaciones
📌 Regla de interacción (obligatoria): Todas las preguntas que requieran una respuesta «sí/no» o «elegir una opción» deben presentarse usando la herramienta AskUserQuestion con una tarjeta de opciones (dos o más botones de opción), está prohibido usar solo texto. Aplica a: ¿incorporar grill-with-docs?, ¿crear esqueleto de documentación?, confirmación de tipo de proyecto, confirmación de clave/contexto (según sugerencia o modificación), confirmación de eliminación, selección de continuación de sesión (por dónde continuar), etc.
🆕 Nuevo proyecto
- Preguntar nombre del proyecto + descripción del contexto, generar clave:
<abreviatura_ingles>_<YYYYMMDD> - Hacer copia de seguridad de PROJECTS.json → Crear directorio → Escribir README.md + CLAUDE.md +
.gitignore(que incluyaPROJECTS.json,backups/,*.bak,.memory/) - Registrar en PROJECTS.json (seq = nextSeq, luego nextSeq +1)
cdal directorio del proyecto,git init- Preguntar obligatoriamente si se desea incorporar el skill grill-with-docs (tarjeta AskUserQuestion: Incorporar / No incorporar):
- Aceptar → Ejecutar tres acciones concretas (no solo decir «incorporado» verbalmente):
① En la tabla «Relaciones de dependencia» de CLAUDE.md registrar:
| grill-with-docs | Incorporado | Flujo de interrogación de diseño (el usuario debe invocar /grill-with-docs manualmente) |② Agregar un recordatorio al inicio de las tareas pendientes (marcado como «manual», no como tarea ejecutable):- [ ] 📌 Recordatorio (manual): Al diseñar/planificar, escriba /grill-with-docs para iniciar la interrogación (este skill solo puede ser invocado manualmente por el usuario, la IA no puede activarlo)③ Informar claramente al usuario cómo invocarlo: «La primera vez que diseñe/planifique, escriba manualmente /grill-with-docs» - Rechazar → No registrar, no agregar a tareas pendientes, continuar normalmente
- Aceptar → Ejecutar tres acciones concretas (no solo decir «incorporado» verbalmente):
① En la tabla «Relaciones de dependencia» de CLAUDE.md registrar:
- Proyectos de código/ingeniería: Preguntar si se desea crear un esqueleto de documentación opcional (tarjeta AskUserQuestion: Crear / Saltar; ver «📁 Esqueleto de documentación opcional»); proyectos de negocio/documentación saltar este paso
La plantilla inicial de CLAUDE.md se encuentra al final.
🗑️ Eliminar proyecto
- Localizar proyecto → Listar entrada JSON + lista de archivos del directorio → Señalar riesgo irreversible
- Tras confirmación del usuario: Hacer copia de seguridad de PROJECTS.json → Eliminar entrada JSON → Eliminar directorio del proyecto → Renumerar consecutivamente los proyectos restantes desde 1 → nextSeq = max(seq) + 1
💾 Guardar proyecto
- Copia de seguridad de CLAUDE.md (en
<directorio del skill>/backups/, es decir~/.claude/skills/project-registry/backups/) - Revisar la conversación actual y agregar o actualizar en CLAUDE.md lo siguiente:
- Últimos avances y tareas completadas
- Nuevas decisiones arquitectónicas (las decisiones cotidianas se registran según el formato de «📜 Disciplina de registro de decisiones», la razón no puede omitirse)
- Actualizar lista de tareas pendientes (marcar completadas con ✅, agregar nuevas)
- Actualizar problemas conocidos
- ⚠️ Los «próximos pasos» deben listarse por prioridad (1. 2. 3.), no se pueden omitir (la próxima sesión continuará desde aquí)
- Hacer commit de los cambios de CLAUDE.md en git
- Sugerir siguiente herramienta: Según el contenido del proyecto y las tareas pendientes, sugerir posibles skills a usar (por ejemplo ppt-master / docx / xlsx / pdf, etc.), para que el usuario decida
- Después de guardar, no salir, permanecer en el directorio actual
⚠️ La actualización automática de CLAUDE.md es una regla obligatoria, no se puede saltar.
🚪 Salir del proyecto
Igual que la operación de guardar, pero el último paso es volver a ~:
- Copia de seguridad de CLAUDE.md
- Revisar la conversación actual y actualizar CLAUDE.md (incluyendo «próximos pasos» por prioridad)
- Hacer commit de los cambios en git
- Sugerir siguiente herramienta (igual que en guardar)
- Al salir, volver directamente a
~
🔍 Comprobación MD (verificación masiva del estado de CLAUDE.md de todos los proyectos)
Verifica de forma masiva si el CLAUDE.md de todos los proyectos registrados es válido (sin necesidad de selección manual):
- Recorrer todos los directorios de proyectos, verificando los siguientes 3 ítems:
- Si el directorio existe
- Si CLAUDE.md existe
- Si
.gitexiste (requisito para que CLAUDE.md sea efectivo: debe estar al mismo nivel que.git)
- Mostrar tabla resumen:
🔍 Comprobación de salud de MD (total N proyectos)
┌─────┬────────────────────────────┬─────────────────┬──────────┬──────────┬──────────┬──────────┐
│ Nº │ clave │ Nombre proyecto │ Dir existe│ CLAUDE.md│ .git │ ¿Válido?│
├─────┼────────────────────────────┼─────────────────┼──────────┼──────────┼──────────┼──────────┤
│ 1 │ pet_hospital_crm_20260301 │ CRM Veterinario │ ✅ │ ✅ │ ✅ │ ✅ │
│ 2 │ gym_members_app_20260315 │ App Gimnasio │ ✅ │ ✅ │ ✅ │ ✅ │
│ ... │ ... │ ... │ ... │ ... │ ... │ ... │
└─────┴────────────────────────────┴─────────────────┴──────────┴──────────┴──────────┴──────────┘
- Para los proyectos donde «¿Válido?» sea ❌, localizar el problema uno por uno:
- Directorio no existe → Verificar si hay residuos en el registro JSON
- CLAUDE.md faltante → Crearlo con la plantilla
.gitfaltante → Ejecutargit init
- Hacer automáticamente
cdal directorio raíz del usuario (no entrar a ningún proyecto concreto)
📁 Esqueleto de documentación opcional (proyectos de código/ingeniería)
Al crear proyectos de código, preguntar si se desea crear (proyectos de negocio/documentación saltar). Una vez creado, se complementa con CLAUDE.md: CLAUDE.md registra el estado y las decisiones, el esqueleto de documentación registra los detalles de diseño:
<directorio del proyecto>/
├── CLAUDE.md # Bitácora de desarrollo (estado/decisiones/tareas pendientes)
└── docs/
├── ARCHITECTURE.md # Descripción general de la arquitectura (opcional)
├── adr/ # Registro de decisiones arquitectónicas (opcional, se conecta con la salida ADR de grill-with-docs/domain-modeling)
└── dev/
├── README.md # Índice de funcionalidades
└── <funcionalidad>/
├── SPEC.md # Especificación de funcionalidad
└── DESIGN.md # Diseño de implementación
Principio de ligereza: solo crear cuando el usuario lo confirme, no es obligatorio ni por defecto. Conexión con grill-with-docs: grill-with-docs (interrogación + terminología + ADR) es el proceso de diseño; el esqueleto es la estructura de almacenamiento — primero interrogar a fondo, luego almacenar según el esqueleto. División del trabajo: las decisiones ligeras se registran en «Registro de decisiones arquitectónicas» de CLAUDE.md (una línea); las decisiones difíciles de revertir, con compromisos reales, se almacenan en
docs/adr/; el glosario CONTEXT.md es mantenido exclusivamente por domain-modeling, el esqueleto no lo vuelve a crear.
Cambio de directorio automático + actualización automática de CLAUDE.md
| Operación | cd | Actualización automática de CLAUDE.md |
|---|---|---|
| Nuevo | Entrar al directorio del proyecto | ✅ Creación automática de plantilla inicial |
| Verificar/modificar | Entrar al directorio del proyecto | ❌ No se actualiza automáticamente |
| Actualizar registro | Entrar al directorio del proyecto | ✅ Actualización manual |
| Guardar | Entrar al directorio del proyecto, no salir, permanecer en el directorio | ✅ Actualización automática |
| Salir/volver | Primero actualizar CLAUDE.md, luego volver a ~ | ✅ Actualización automática |
Mecanismo de seguridad
Operaciones de escritura en PROJECTS.json (nuevo, modificar, eliminar) requieren copia de seguridad previa:
Ruta de copia de seguridad: <directorio del skill>/backups/ (es decir ~/.claude/skills/<nombre-del-skill>/backups/)
Archivo de copia: PROJECTS.json.<YYYYMMDD_HHMMSS>.bak
Operaciones de escritura en CLAUDE.md (actualización de registro, actualización automática al guardar) requieren copia de seguridad previa:
Ruta de copia de seguridad: <directorio del skill>/backups/
Archivo de copia: CLAUDE.md.<YYYYMMDD_HHMMSS>.bak
Si el directorio de copias de seguridad no existe, se crea automáticamente.
Rotación automática de copias de seguridad:
Cada vez que se crea una nueva copia de seguridad, se limpian las copias antiguas por tipo de archivo, conservando las 10 más recientes de cada tipo:
Prefijo de tipo de copia:
PROJECTS.json.*.bak # Copia de la lista de proyectos, conservar 10
CLAUDE.md.*.bak # Copia de la bitácora de desarrollo, conservar 10
SKILL.md.*.bak # Copia del propio skill, conservar 10
Regla de limpieza: ordenar por la marca de tiempo YYYYMMDD_HHMMSS al final del nombre del archivo (nota: para copias con nombres especiales como CLAUDE.md.<nombre-proyecto>.<timestamp>.bak, la marca de tiempo está al final, no se puede ordenar por el nombre completo), conservar las 10 más recientes, eliminar el resto.
🔁 Guardado automático (hooks, silencioso)
Dos capas, ambas se ejecutan silenciosamente en segundo plano, con reintentos silenciosos en caso de fallo, solo afectan a los directorios de proyectos en ~/projects/.
Capa 1 Instantánea mecánica (cero dependencias, activada por defecto)
| Hook | Acción |
|---|---|
| Stop (después de cada respuesta) | Sincronizar transcripción a <proyecto>/.memory/transcript-latest.jsonl (en segundos) |
| SessionEnd (fin de sesión) | Copia de seguridad de CLAUDE.md (rotación de 10) + commit git (solo si hay cambios) |
- ⚠️ Privacidad:
.memory/contiene el texto original de la conversación — debe excluirse en .gitignore (el nuevo proyecto genera automáticamente .gitignore incluyendo.memory/), nunca debe entrar al repositorio. - Si se cierra el terminal forzosamente, SessionEnd no se activa, pero la sincronización en segundos de Stop sigue funcionando — los datos no se pierden.
Capa 3 Resumen automático (opcional, se activa al configurar API)
- Activación: Control de tasa (≥10 mensajes nuevos o ≥10 minutos) — no llama a la API en cada respuesta.
- Flujo: Leer incremento de
.memory/→ Llamar aPR_API_BASE_URL(cualquier proveedor compatible con OpenAI) → Extraer avances/decisiones/tareas pendientes/próximos pasos → Fusionar y actualizar CLAUDE.md (agregar decisiones/actualizar avances/tareas pendientes/próximos pasos). - Configuración (variables de entorno):
PR_API_BASE_URL/PR_API_KEY/PR_API_MODEL(si no se configuran, se salta automáticamente). - Privacidad: La conversación solo se envía al endpoint configurado por el usuario; la clave se lee de las variables de entorno, nunca se hardcodea.
Relación con el guardado manual
Resumen automático = frescura en tiempo real (fusión incremental); guardado manual = organización autorizada (revisión completa) — ambos son compatibles y complementarios.
📜 Disciplina de registro de decisiones (consulta obligatoria)
Todas las decisiones deben ser rastreables: «por qué se hizo así» siempre debe poder consultarse, la razón no puede omitirse.
Formato de decisiones ligeras
- [Estado] YYYY-MM-DD — <Decisión> (Razón: <Motivo>) (Efecto esperado: <Resultado>)
- Marcador de estado:
✅Ejecutado/🔄En curso/⛔Revertido/⏸️Pospuesto - Razón obligatoria: sin razón, no se registra.
- Efecto esperado opcional: si se conoce el efecto esperado al registrar, se añade (para verificar el resultado al hacer atribución).
Momento de registro (por capas)
| Tipo | Momento |
|---|---|
| Decisiones importantes (que afectan la dirección / difíciles de revertir / consumen recursos) | Confirmación inmediata durante la conversación: Claude pregunta activamente «¿Registro esta decisión?» |
| Decisiones cotidianas | Revisión y registro unificado al guardar/salir (obligatorio) |
Decisiones importantes → ADR
Decisiones difíciles de revertir, con compromisos reales, se almacenan en docs/adr/, y CLAUDE.md deja una línea de índice:
- 2026-08-08 — ADR-0001 <Título de la decisión> (Estado: ✅Ejecutado)
Estructura ADR: # ADR-000N <Título> + Estado / Fecha / Contexto / Decisión / Consecuencias.
Plantilla inicial de CLAUDE.md
# <Nombre del proyecto>
## Objetivo del proyecto
<Resumen del contexto>
## Stack tecnológico
(Por completar — Lenguaje/Framework/Base de datos/Despliegue, etc.)
## Estado actual
state: active
- Fase: Análisis de requisitos / En desarrollo / Completado
- Últimos avances: Inicialización del proyecto
## Registro de decisiones arquitectónicas
Registrar todas las decisiones importantes, formato:
- [Estado] YYYY-MM-DD — <Decisión> (Razón: <Motivo>) (Efecto esperado: <Resultado>)
(Estado: ✅Ejecutado / 🔄En curso / ⛔Revertido / ⏸️Pospuesto; razón no omitible, efecto esperado opcional)
## Alcance y funcionalidades del proyecto
(Lista de funcionalidades principales, también puede presentarse en tabla)
## Relaciones de dependencia
| Proyecto dependiente | Relación | Descripción |
|:---|---:|:---|
| <Nombre proyecto> | Dependiente / Dependencia | <Descripción específica> |
## Tareas pendientes
- [ ] Tarea pendiente 1 (desglosada a un nivel ejecutable)
## Problemas conocidos
- (Ninguno por ahora — añadir al descubrir, incluir alcance del impacto)
## Próximos pasos
- Listar por prioridad (1. 2. 3.), actualización obligatoria al guardar/salir
Al crear, rellenar al menos: objetivo del proyecto, stack tecnológico, estado actual, primeras tres tareas pendientes. El resto se va enriqueciendo durante el desarrollo.
Reglas de nomenclatura de clave
<Abreviatura_inglés/pinyin>_<YYYYMMDD>
Ejemplos:
CRM Hospital Veterinario → pet_hospital_crm_20260301
App Membresía Gimnasio → gym_members_app_20260315
- Priorizar inglés, pinyin como alternativa
- Todo en minúsculas, separado por guión bajo
- Añadir fecha al final
Reglas de gestión de números de secuencia
| Operación | Regla |
|---|---|
| Nuevo | Leer nextSeq como seq del nuevo proyecto, después de registrar nextSeq +1 |
| Eliminar | Después de eliminar, renumerar consecutivamente los proyectos restantes desde 1, nextSeq = max(seq) + 1 |
| seq | Siempre consecutivo, nunca saltar números |
🧠 Gestión de memoria (mecanismo de tres capas)
Memoria a nivel de proyecto (gestionada por el skill)
| Soporte de memoria | Qué registra | Mecanismo de gestión |
|---|---|---|
| CLAUDE.md | Estado / Decisiones y razones / Tareas pendientes / Problemas conocidos / Próximos pasos | Carga automática en cada sesión + actualización forzada al guardar + commit git + rotación de copias de seguridad |
| PROJECTS.json | Lista de proyectos registrados (seq/clave/nombre/estado/creado) | Copia de seguridad antes de operaciones de escritura |
| Historial git + backups/ | Instantáneas de versiones históricas | Se puede retroceder en cualquier momento (git show / archivos de copia) |
Ciclo de vida de la memoria
Escritura (actualización forzada al guardar/salir)
→ Carga automática (Claude Code inyecta automáticamente CLAUDE.md en cada sesión)
→ Copia de seguridad (rotación de 10 + commit git)
→ Recuperación (leer CLAUDE.md / investigación de atribución «por qué X» / retroceso en historial git)
Límites de la memoria
Registrar: Decisiones arquitectónicas y sus razones | Convenciones y estándares | Terminología del dominio | Tareas pendientes y problemas conocidos | Estado actual y dependencias | Próximos pasos
No registrar: Implementación detallada del código | Cambios rastreables por git | Discusiones temporales (el texto original de la conversación no se archiva — para consultar «qué se dijo exactamente en ese momento» usar el archivo de sesión integrado de Claude Code --resume, no está dentro de las responsabilidades de este skill)
División del trabajo con la memoria global
- Relacionado con el proyecto (avances/decisiones/por qué se definió así) → Memoria de este skill (CLAUDE.md, sigue al proyecto)
- Preferencias del usuario / hechos transversales a proyectos (como «PPT usa preferentemente ppt-master») → Memoria global de Claude Code (
~/.claude/.../memory/, mantenida por el sistema, el skill no escribe)
Mantenimiento de CLAUDE.md
CLAUDE.md es el archivo de contexto del proyecto que Claude carga automáticamente en cada conversación, registrando decisiones y avances.
Momentos de actualización (regla obligatoria): Generación automática al crear | Llamar a «actualizar registro» al final de cada conversación | Añadir en decisiones clave | Sincronizar cuando cambien los requisitos | ⚠️ Actualización automática al salir o guardar (debe ejecutarse, no se puede saltar), y los «próximos pasos» deben escribirse por prioridad
Qué registrar: Decisiones arquitectónicas y sus razones | Convenciones y estándares | Terminología del dominio | Tareas pendientes y problemas conocidos | Estado actual y dependencias | Próximos pasos
Qué no registrar: Implementación detallada del código | Cambios rastreables por git | Discusiones temporales
Condición de efectividad: Debe estar al mismo nivel que .git, nombre de archivo CLAUDE.md (todo en mayúsculas)
Al crear un nuevo proyecto, se hace automáticamente
git init. Si un directorio existente no tiene.git, informar la razón y preguntar si se desea hacergit init.
🔎 Investigación de atribución (por qué X)
Se activa cuando el usuario dice «por qué X / contexto de esta decisión / por qué se hizo así en ese momento / atribución X».
Flujo:
- Ubicar: Confirmar el objeto de investigación (proyecto + tema/punto en el tiempo)
- Recopilar evidencia: Leer «Registro de decisiones arquitectónicas» de CLAUDE.md del proyecto +
docs/adr/(si existe) + commits recientes de git log + avances/tareas pendientes - Generar informe de atribución:
- Línea de tiempo de decisiones: Decisiones relevantes ordenadas por tiempo
- Cadena de razones: Razón de cada decisión + relaciones entre decisiones (qué decisión se basa en cuál)
- Estado: ✅Ejecutado / 🔄En curso / ⛔Revertido / ⏸️Pospuesto
- Impacto posterior: Combinar con los últimos avances para determinar si se cumplieron las expectativas
- Conclusión: Responder «por qué se hizo así en ese momento», señalar si las expectativas se verificaron o no cuando sea necesario
La salida se produce dentro de la conversación; si se solicita archivarla, se almacena fuera del repositorio (~/project-audit-logs/) — el contenido de verificación/atribución contiene privacidad del proyecto, está prohibido escribirlo en el repositorio del proyecto.
📋 Verificación de proyecto (activación por lenguaje natural, no ocupa espacio en el menú)
Se activa cuando el usuario dice «verificar proyecto / chequeo / auditoría», no se añade una entrada en el menú.
Escaneo completo («verificar todos los proyectos»)
Verificación estructural (igual que comprobación MD C) + 5 ítems de contenido:
| # | Dimensión | Lógica de verificación |
|---|---|---|
| 1 | Consistencia de estado | ¿El estado en PROJECTS.json contradice los últimos avances/tareas pendientes en CLAUDE.md? |
| 2 | Estancamiento del proyecto | ¿La última actualización de CLAUDE.md (tiempo de git log) es > 14 días? → «Posible estancamiento» |
| 3 | Acumulación de tareas | Más de 10 tareas pendientes sin completar o sin avances durante mucho tiempo |
| 4 | Decisiones no implementadas | Decisión marcada como ✅Ejecutado pero sin reflejo en avances/tareas pendientes |
| 5 | Falta de próximos pasos | Sin sección de «próximos pasos» (perezoso en el flujo de guardado) |
Los elementos anómalos incluyen automáticamente pistas de atribución: retroceder las últimas N decisiones, señalando cuáles podrían estar relacionadas.
Investigación profunda de un solo proyecto («verificar proyecto XX»)
5 ítems de contenido, solo verificar el proyecto especificado.
El informe solo se muestra dentro de la conversación; si se solicita almacenarlo, guardar en ~/project-audit-logs/ (fuera del repositorio).
↩️ Reversión de versión
Se activa cuando el usuario dice «revertir / restaurar versión / retroceder / deshacer guardado». Doble canal: historial git (archivos del proyecto) + instantáneas de copia de seguridad (registro/bitácora de desarrollo).
Reglas de seguridad generales (todas las reversiones deben cumplir):
- Hacer copia de seguridad de la versión actual primero (la reversión en sí misma puede revertirse)
- Mostrar resumen de diferencias + confirmación con tarjeta AskUserQuestion (revertir / cancelar) antes de actuar
- La reversión genera un nuevo commit, no reescribe el historial git
① Reversión de CLAUDE.md (bitácora de desarrollo mal modificada/eliminada)
- Ubicar:
git log --onelinelistar commits recientes (o marcas de tiempo de backups/CLAUDE.md.*.bak) - Comparar:
git show <commit>:CLAUDE.mdcon la versión actual (enfocarse en: decisiones/tareas pendientes/próximos pasos) - Confirmar: Mostrar resumen de diferencias → Confirmación con tarjeta
- Ejecutar: Copia de seguridad de la versión actual →
git checkout <commit> -- CLAUDE.md→ Hacer commit (registrar «revertido a ») - Informar: Resumen del contenido revertido
② Reversión de archivos de proyecto (README/docs/código)
- Ubicar:
git logencontrar la versión objetivo - Comparar:
git diff <commit> -- <archivo> - Confirmar: Resumen de diferencias → Confirmación con tarjeta
- Ejecutar: Copia de seguridad de la versión actual →
git checkout <commit> -- <archivo>→ Hacer commit - Informar
③ Reversión del registro (PROJECTS.json mal eliminado/modificado)
- Ubicar:
backups/PROJECTS.json.<timestamp>.bak(las 10 más recientes, ordenadas por la marca de tiempo al final) - Comparar: diff entre actual y copia de seguridad (listar altas/bajas de proyectos)
- Confirmar: Resumen de diferencias → Confirmación con tarjeta
- Ejecutar: Copia de seguridad de la versión actual →
cp copia → PROJECTS.json→ Validar (número de proyectos/continuidad de seq) - Informar
Consejo: La reversión se combina con la «🔎 Investigación de atribución» — primero investigar «por qué se convirtió en esto», luego decidir a qué versión revertir.
Preguntas frecuentes
- PROJECTS.json no existe: Crear lista vacía con la plantilla por defecto
- Directorio ya existe: Reutilizar el directorio existente, solo registrar en JSON
- No se encuentra el proyecto al eliminar: Primero mostrar la lista para que el usuario confirme