Vault de Buenas PrácticasBest-Practices Vault
Buenas prácticas de código que también entienden los agentes de IA.Dev best practices that AI agents can read too.
La IA escribe código plausible muy rápido, pero no siempre correcto ni seguro. Quería un único checklist, con criterio y con fuentes que se pueden verificar, que me valiera de recordatorio a mí, de instrucciones para el agente que escribe el código y de guía para revisar un proyecto ya hecho.
Todo sale de un solo fichero Markdown: 42 fichas, cada una con su ID, su severidad (crítico/alto/medio) y fuentes oficiales que se pueden comprobar (OWASP, NIST, RGPD, PCI DSS, LSSI, AEPD, 12-Factor). De ahí salen la web (una SPA de un solo fichero, con buscador, filtros y un lector modal con referencias cruzadas), la capa para agentes internos (AGENTS.md + CLAUDE.md, con un protocolo tarea → fichas) y la de agentes externos en texto plano (llms.txt / llms-full.txt).
El reto de fondo es que las webs tipo SPA esconden el contenido en JavaScript, así que un agente que abre la URL no ve nada. Lo resolví sirviendo llms.txt y llms-full.txt como ficheros de texto plano, generados desde la misma fuente y sin duplicar nada a mano. Un solo parser alimenta la web, el índice y el documento completo, así que no se pueden desincronizar.
AI writes plausible code fast, but not always correct or secure. I wanted a single checklist, with judgement and sources you can verify, that worked as a reminder for me, as instructions for the agent writing the code, and as a guide for reviewing a project that is already done.
Everything comes from one Markdown file: 42 cards, each with its ID, its severity (critical/high/medium) and official sources you can check (OWASP, NIST, GDPR, PCI DSS, and more). From there come the site (a single-file SPA with search, filters and a modal reader with cross-references), the layer for internal agents (AGENTS.md + CLAUDE.md, with a task → cards protocol) and the plain-text layer for external agents (llms.txt / llms-full.txt).
The underlying problem is that SPA sites hide their content in JavaScript, so an agent opening the URL sees nothing. I solved it by serving llms.txt and llms-full.txt as plain-text files, generated from the same source and without duplicating anything by hand. A single parser feeds the site, the index and the full document, so they cannot drift out of sync.
Qué haceWhat it does
- 42 fichas en 14 categorías, cada una con ID, severidad, tags, buenas prácticas, errores típicos y fuentes oficiales
- La web, llms.txt y llms-full.txt se regeneran con un script desde el mismo Markdown, así que no se desincronizan
- Cada severidad la cita el agente por su ID, para que después una persona pueda revisarlo
- Web sin dependencias: buscador y filtros en el cliente, y un renderizador de Markdown propio
- Sirve para dos públicos: la leen las personas y la usan como contexto los agentes de IA (los míos y los de auditoría externa)
- 42 cards across 14 categories, each with an ID, severity, tags, best practices, common mistakes and official sources
- The site, llms.txt and llms-full.txt are regenerated by a script from the same Markdown, so they never drift
- Every severity gets cited by the agent by its ID, so a person can review it afterwards
- Dependency-free site: client-side search and filters, and a hand-rolled Markdown renderer
- It serves two audiences: people read it, and AI agents use it as context (mine and external auditors)