Mapa del sistema
Módulos, funcionalidades, glosario y decisiones en Markdown plano, navegable en Obsidian, VitePress o GitHub.
CLI open source · Rust · local-first
Excava cualquier proyecto.
Documéntalo con evidencia.
archeology-doc (adoc) inspecciona proyectos nuevos o legacy y, con el agente de IA que ya usas, genera una base de conocimiento navegable, documentación, hallazgos y contexto para agentes. Cada afirmación cita su fuente ruta:línea.
$ curl -fsSL https://archeology-doc.com/download/install.sh | shQué te da archeology-doc
Contradicciones y riesgos
Hallazgos por severidad: documentación desactualizada, reglas duplicadas, configuración en conflicto, código muerto.
Huecos de testing
Funcionalidades ↔ tests, escenarios cubiertos y faltantes, tests desactivados o vacíos.
Contexto para agentes
AGENTS.md, memoria persistente y skills: cada sesión de IA empieza sabiendo qué hay y dónde.
Specs con OpenSpec
Cumplimiento de requisitos contra el código y cambios abandonados señalados en review, status y check.
Verificable
adoc check valida evidencias, enlaces y notas desactualizadas; ideal para CI.
Cómo funciona
Lo determinista lo calcula Rust; la interpretación la hace tu agente; adoc orquesta y valida.
-
1
adoc scanInventario sin IA: lenguajes, módulos, tests, CI, historial git y OpenSpec. Respeta
.gitignorey excluye secretos. -
2
adoc planDivide el trabajo en tareas acotadas según el tamaño del proyecto: pocas tareas en uno pequeño, más en uno grande.
-
3
adoc inspectTu agente ejecuta cada tarea. Solo se marca hecha si produjo lo pedido con evidencias válidas.
-
4
adoc previewSitio con dashboard: estado, hallazgos, preguntas para el equipo y FAQ. O un reporte HTML único.
-
5
adoc syncCuando el código cambia, marca las notas afectadas como desactualizadas y reabre solo esas tareas.
Instalar
Un comando según tu sistema: descarga el binario de tu plataforma, verifica su SHA-256 y lo deja en el PATH. No necesitas Rust. Node 18+ solo para el sitio VitePress y la extensión.
Terminal
$ curl -fsSL https://archeology-doc.com/download/install.sh | sho descarga el binario
Descargado desde el navegador, macOS lo marca en cuarentena: xattr -d com.apple.quarantine adoc archeology-doc y muévelos a ~/.local/bin. Con el comando de terminal no hace falta.
Terminal
$ curl -fsSL https://archeology-doc.com/download/install.sh | sho descarga el binario
Binarios para glibc 2.28 o superior (Debian 10, Ubuntu 18.10, RHEL 8 y posteriores).
PowerShell
> irm https://archeology-doc.com/download/install.ps1 | iexo descarga el binario
El instalador lo deja en %LOCALAPPDATA%\Programs\archeology-doc\bin y lo añade a tu PATH, sin permisos de administrador. En Windows ARM64 funciona con la emulación x64.
# Necesita Rust (rustup.rs). Instala `adoc` en ~/.cargo/bin
git clone https://github.com/jsoncr/archeology-doc.git
cd archeology-doc
installers/install.sh
# o directamente con cargo
cargo install --path crates/archeology-cli --lockedExtensión de VS Code
$ code --install-extension jcruz.archeology-docEl .vsix sirve para instalar sin conexión y en editores que no usan el Marketplace de Microsoft (Cursor, Windsurf): code --install-extension archeology-doc.vsix.
Extras
# Con VitePress compartido y la extensión de VS Code
curl -fsSL https://archeology-doc.com/download/install.sh | sh -s -- --with-vitepress --with-vscode
# Verifica requisitos: git, Node, VitePress, OpenSpec y agentes
adoc doctor
# Solo comprueba si hay una versión nueva
adoc upgrade --check
# Descarga e instala la versión nueva automáticamente
adoc upgradeMantente al día: adoc upgrade busca una versión nueva y se actualiza automáticamente; adoc upgrade --check solo comprueba, sin cambiar nada.
Se instalan dos binarios equivalentes: adoc (corto) y archeology-doc. Para desinstalar: adoc uninstall (con --purge borra también ~/.archeology-doc; los archivos de tus proyectos no se tocan).
Todas las descargas
| Archivo | Plataforma | Tamaño | SHA-256 |
|---|---|---|---|
| Lista disponible cuando se publique una versión. | |||
Verifica una descarga con shasum -a 256 <archivo> (macOS/Linux) o Get-FileHash <archivo> (PowerShell) y compárala con SHA256SUMS.
Primeros pasos
En la carpeta de tu proyecto:
cd mi-proyecto
adoc init # config + estructura
adoc agent use claude # o devin, codex, gemini…
adoc scan # inventario determinista
adoc plan # tareas según el tamaño
adoc inspect # el agente documenta
adoc status # dónde estás y qué sigue
adoc preview # ver el resultadoDía a día
adoc status | Resumen: progreso, tareas pendientes y el siguiente paso (--format json para integraciones) |
adoc review | Progreso, hallazgos, funcionalidades sin tests |
adoc check | Lista de lo hecho y lo que falta, con pistas para arreglarlo (código de salida para CI) |
adoc sync | Muestra archivos cambiados y sin cubrir, marca notas desactualizadas y reabre sus tareas |
adoc inspect --resume | Reintenta tareas fallidas o interrumpidas |
adoc task answer T-014 "…" | Responde a un agente que preguntó |
adoc task run T-014 -i | Sesión interactiva con el agente |
adoc ask "¿…?" | Pregunta sobre el proyecto → FAQ |
adoc graph | Grafo de conocimiento interactivo en el navegador; --json lo imprime como JSON |
adoc report | Reporte HTML único para compartir |
Proyectos, agentes y ajustes
adoc projects list | Todos tus proyectos y su progreso |
adoc projects delete <nombre> | Quita un proyecto del registro; con -d borra también sus archivos generados |
adoc agent use claude --model opus | Agente y modelo del proyecto |
adoc config set language es | Idioma de la interfaz: en o es |
Mantenimiento
adoc doctor | Verifica git, Node, VitePress, OpenSpec y agentes |
adoc upgrade --check | Solo comprueba si hay una versión nueva |
adoc upgrade | Descarga e instala la última versión |
adoc uninstall | Quita adoc; --purge borra también ~/.archeology-doc |
Trabaja con tu agente
Agnóstico: cambia de agente o de modelo cuando quieras. Sin CLI, exporta las tareas para hacerlas a mano.
Claude CodeDevinCodexGemini CLIQwen Code
OpenCodeCursorGitHub CopilotAmpgooseAider
adoc agent list # disponibles; * = activo
adoc agent use devin --model opus # agente y modelo del proyecto
adoc inspect --agent codex # solo para esta corridaExtensión para VS Code
Todo lo generado, a la vista mientras programas. Funciona también en Cursor, Windsurf y Devin Desktop.
- Tareas por estado con botón ▶ para ejecutarlas
- Hallazgos con salto a la línea de evidencia
- Grafo del conocimiento, como en Obsidian
- Preguntas del agente y del equipo, y FAQ
- Marcas en el editor en el código citado
- Progreso y agente activo en la barra de estado
Qué queda en tu proyecto
Solo resultados, en Markdown. El estado de trabajo vive fuera del repositorio.
mi-proyecto/
├── archeology-doc.toml # config + ID
├── AGENTS.md # contexto para agentes
├── knowledge/ # vault Obsidian
│ ├── 00-overview.md
│ ├── modules/ features/ findings/
│ ├── tests/ glossary/ faq/
│ └── memory/
├── docs/ # sitio VitePress
└── llms.txtPrincipios
- Evidencia ante todo: cada afirmación cita
ruta:línea - No destructivo: nunca modifica tu código; respeta tus ediciones
- Local-first: nada sale de tu máquina salvo lo que envíe tu agente
- Incremental: tareas pequeñas, reanudables, por módulos
- Estándares: Markdown, OpenSpec, AGENTS.md, Obsidian y VitePress
Los datos sensibles quedan fuera
archeology-doc nunca lee archivos de secretos y le indica a tu agente que tampoco lo haga. Esto se omite por defecto:
Se omiten los archivos de secretos
.env*, *.pem, *.key, credentials*, llaves SSH (id_rsa, id_ed25519…), almacenes de claves (*.p12, *.pfx, *.jks), .npmrc, .netrc, .git-credentials, *.tfvars, *.tfstate, secrets.*. Nunca llegan al inventario ni a los prompts.
No se puede desactivar
La configuración de un repositorio puede añadir patrones ([scan] secrets_patterns), pero nunca quitar los predefinidos.
Reglas para el agente
Cada tarea le indica al agente que no lea ni cite esos archivos, y que nunca copie claves, tokens, contraseñas ni cadenas de conexión en las notas: solo que existen y dónde.
Respeta .gitignore
Además de vendor/, node_modules/, target/, dist/ y los archivos minificados. Añade los tuyos con [paths] exclude. No se siguen los enlaces simbólicos.
El estado de trabajo, fuera del repo
Tareas, logs y aprobaciones viven en ~/.archeology-doc/, no en tu repositorio, y adoc nunca escribe a través de un enlace que apunte fuera del proyecto.
Tu código no se sube
adoc solo usa la red para buscar actualizaciones (adoc upgrade, adoc doctor; se desactiva con ADOC_NO_UPDATE_CHECK=1). El agente que elijas habla con su propio proveedor. Los adaptadores de terceros necesitan tu aprobación (adoc agent trust).
# archeology-doc.toml: se suma a las reglas predefinidas
[scan]
secrets_patterns = ["*.vault", "config/prod.*"]
[paths]
exclude = ["**/fixtures/**", "legacy/generated/**"]La detección es por nombre de archivo: un secreto escrito directamente en el código fuente sí puede llegar al agente. Se le indica que no lo copie, pero conviene rotarlo y moverlo a un archivo excluido.
Código abierto
Todo el proyecto está en GitHub bajo licencia MIT: úsalo, modifícalo y compártelo libremente.
CLI en Rust
crates/: la CLI adoc y los crates core, scan, agents, OpenSpec y registry.
Extensión de VS Code
extension/: tareas, hallazgos, grafo de conocimiento y preguntas dentro del editor.
Instaladores
install.sh e install.ps1: instalación con un comando en macOS, Linux y Windows, con verificación SHA-256.
Plantillas
templates/: las notas Markdown y los prompts que completan los agentes, en inglés y español.
Cómo contribuir
- 1
Haz un fork del repositorio y crea una rama para tu cambio.
- 2
Ejecuta
cargo test --workspace(ynpm run compileenextension/si la tocas). - 3
Abre un pull request que explique qué cambia y por qué. Para ideas grandes, abre antes un issue.
Compilar desde el código
# CLI (necesita Rust)
git clone https://github.com/jsoncr/archeology-doc
cd archeology-doc
cargo install --path crates/archeology-cli
# Extensión de VS Code (necesita Node 18+) → .vsix
cd extension
npm ci
npm run packagePreguntas frecuentes
¿Qué es archeology-doc?
Una herramienta de línea de comandos open source (adoc), escrita en Rust, que documenta código nuevo o legacy con el agente de IA que ya usas. Genera una base de conocimiento en Markdown, documentación VitePress, hallazgos y un AGENTS.md con contexto para agentes, y cada afirmación cita su fuente como ruta:línea.
¿Con qué agentes de IA funciona?
Claude Code, Codex, Devin, Gemini CLI, Qwen Code, OpenCode, Cursor, GitHub Copilot, Amp, goose y Aider. Cambia de agente o de modelo con adoc agent use; sin un agente de CLI, adoc agent use manual exporta las tareas para hacerlas a mano.
¿Sube mi código o lee mis secretos?
No. adoc se ejecuta en tu máquina y solo usa la red para buscar actualizaciones (se desactiva con ADOC_NO_UPDATE_CHECK=1); el agente que elijas habla con su propio proveedor, como ya lo hace. Los archivos de secretos como .env*, *.pem o las llaves SSH se omiten y nunca llegan a los prompts. Mira qué se deja fuera.
¿Qué lenguajes de programación y frameworks soporta?
Es agnóstico al lenguaje: adoc scan detecta los lenguajes, módulos, tests y CI del repositorio, y tu agente lee el código directamente. Sirve para proyectos nuevos o legacy, pequeños o grandes.
¿Es gratis?
Sí. archeology-doc es gratuito y open source bajo licencia MIT. El único costo es el uso de tu agente de IA, si tu proveedor lo cobra.
¿Hay extensión para VS Code?
Sí: instala archeology-doc desde el Visual Studio Marketplace (jcruz.archeology-doc) o descarga el .vsix. Muestra tareas, hallazgos, el grafo de conocimiento y las preguntas en VS Code, Cursor, Windsurf y Devin Desktop.
¿Cómo lo actualizo?
Ejecuta adoc upgrade: descarga la última versión, verifica su SHA-256 y sustituye los binarios. adoc upgrade --check solo te dice si hay una versión nueva.