Hogar

Skill

Documentación

shipping-artifacts

phuryn/pm-skills

Documenta las aplicaciones desarrolladas con IA, incluyendo su arquitectura, permisos, secretos y mapas de cobertura de pruebas, para que puedan revisarse antes de su lanzamiento.

...Expandir todo

Tiempo actualizado 29 de septiembre de 2026

# permissions # security audit # code review # test coverage # architecture documentation # secrets management # ai code reviewability

Documentación de artefactos: los documentos que permiten revisar el código generado por IA

Objetivo

Los agentes de IA escriben código rápidamente, pero no dejan ningún registro duradero de la intención: qué se supone que debe hacer el sistema, quién está autorizado a hacer qué, dónde se almacenan los secretos, qué reglas se verifican realmente. Sin ese registro, ningún ser humano (ni ningún agente de auditoría) puede determinar si el código es seguro para su entrega. Esta habilidad define el pequeño conjunto de documentos que restablecen la revisabilidad.

Estos documentos se encuentran en /documentation/ y están escritos para dos tipos de lectores: un revisor humano y el siguiente agente de programación basado en IA. Constituyen la parte correspondiente al estado previsto de cualquier auditoría posterior: una revisión de seguridad o de rendimiento solo es válida en la medida en que pueda comparar el código con la intención prevista.

Cómo se organiza el conjunto

El conjunto no es una lista fija: se trata de un núcleo reducido más documentos condicionales que solo se añaden cuando existe la capacidad para ello.

Documentos básicos: toda aplicación revisable cuenta con estos elementos, por lo que siempre hay que elaborarlos.
Documentos condicionales: incluye uno solo si la aplicación cuenta realmente con esa capacidad. Si no es así, escribe una sola línea en architecture.md («Sin tareas programadas: no hay cron.md») en lugar de crear un documento vacío. La revisabilidad proviene de un mapa honesto, y «no hacemos X» forma parte de ese mapa.
La mayoría de los documentos se obtienen mediante ingeniería inversa a partir del código con /document-app. La única excepción es tests.md, que se deriva de los demás documentos mediante /derive-tests: es el mapa de verificación, no una descripción de un subsistema.

Sé brutalmente honesto sobre el estado actual sin caer en la paranoia. La tarea consiste en crear un mapa preciso, no en dar un visto bueno. Cada documento es breve, contiene muchas tablas y viñetas, y omite la teoría genérica.

Documentos principales

Cada entrada: archivo · objetivo en una línea · qué debe recoger · cómo lo utiliza un revisor.

architecture.md: qué es el sistema y cómo se articula.
- Debe incluir: visión general del producto + supuestos clave; pila tecnológica; cómo fluyen de principio a fin la autenticación, las sesiones y las reclamaciones; los límites de confianza (p. ej., rol de servicio frente a cliente); una breve lista de riesgos y supuestos conocidos (cada entrada respaldada por su ubicación en el código, no una lista de verificación genérica); un índice de «Documentos relacionados» con todos los demás documentos elaborados.
- Uso por parte del revisor: el documento raíz; todo lo demás se remite a partir de aquí.
flows.md: los recorridos en los que se ejercen realmente los permisos y los efectos secundarios.
- Debe incluir: cada flujo fundamental como actor + precondición + resultado de éxito; la secuencia paso a paso a través de la interfaz de usuario → servidor → datos → tareas → proveedores → agentes; la comprobación de autorización en cada paso protegido (qué reclamación/rol/ámbito, sobre qué recurso y el caso de denegación esperado); los cruces de límites de confianza (navegador → servidor, servidor → proveedor, tarea → aplicación, agente → herramienta, webhook → aplicación); los cambios de estado y los efectos secundarios que provoca cada paso (escrituras, correos electrónicos en cola, tareas activadas, llamadas salientes).
- Uso para el revisor: la visión en tiempo de ejecución que una matriz estática de permissions.md no puede mostrar: dónde y en qué orden se aplica la autorización, y dónde se puede omitir.
- Regla anti-PRD: un flujo que no afecte a los permisos, la integridad de los datos, los efectos secundarios externos, el dinero, la privacidad o la seguridad operativa no tiene cabida aquí. Se trata de un mapa de seguridad y operaciones, no de una especificación de funcionalidades.
permissions.md: quién está autorizado a hacer qué.
- Debe incluir: roles/reivindicaciones; de dónde se deriva el ámbito (token frente a base de datos); una matriz de recurso × operación × rol; qué tablas tienen seguridad a nivel de fila y cuáles se basan en comprobaciones impuestas por el código.
- Uso por parte del revisor: la línea de base con la que se compara el código en una auditoría de control de acceso. flows.md lo muestra en acción; esta es la referencia estática.
variables.md — configuración y secretos, asignados al riesgo.
- Debe incluir: una tabla con Nombre · utilizado por · ámbito (servidor/cliente) · origen · rotación · riesgo; confirmación explícita de que no se incluye ningún secreto en el lado del cliente; una lista de comprobación previa a la puesta en marcha.
- Uso por parte del revisor: la superficie de fuga de secretos/datos personales identificables y el plan de rotación durante la respuesta a incidentes.
tests.md — el mapa de verificación: qué reglas documentadas se comprueban realmente, cuáles son solo propuestas y cuáles no se comprueban mediante ningún mecanismo.
- Debe incluir, en tres secciones claramente separadas para que el mapa no muestre un «verde» engañoso:
  - Cobertura existente — pruebas que se encuentran actualmente en el repositorio, cada una vinculada a la regla a la que se refiere (para que el mapa refleje la realidad, no una lista de deseos).
  - Pruebas propuestas: casos recomendados que aún no se han escrito, marcados por tipo de prueba (unitaria/de integración automatizada · en entorno de producción supervisado · revisión manual).
  - Lagunas: reglas documentadas sin ningún tipo de verificación, clasificadas según lo que su incumplimiento pone de manifiesto.
- Cada fila incluye: caso de uso → regla → comportamiento esperado (incluido el caso de denegación o negativo) → fuente de evidencia (documentación + código) → estado (existente / propuesto / ninguno). También indica qué comprobaciones son obligatorias en la integración continua (CI) y condicionan las fusiones con la rama principal.
- Uso para los revisores: la forma operativa de «documentado == implementado»: muestra si cada regla que mencionan los demás documentos está realmente respaldada por una prueba en la actualidad, si solo es una propuesta o si no se ha verificado.
- Generado por /derive-tests (no por /document-app), ya que se deriva de los demás documentos y del conjunto de pruebas existente, en lugar de leerse directamente de un subsistema.

Documentos condicionales (incluirlos solo cuando exista la funcionalidad)

emails.md: todas las notificaciones que envía el sistema. Incluir solo si la aplicación envía correos electrónicos transaccionales o automatizados.
- Debe incluir: la ruta cola → procesador → proveedor; las plantillas y las variables que admiten; el comportamiento de reintentos y retrasos; dónde buscar cuando falla un envío.
- Uso por parte de los revisores: detectar entradas de plantillas no validadas y límites de exposición de datos de carácter personal.
cron.md — todas las tareas programadas y cómo gestionarlas de forma segura. Incluir solo si existen tareas programadas o en segundo plano.
- Debe incluir: una tabla de inventario (tarea → programación → función → secretos → límites → reintentos); cómo se mantiene idempotente cada tarea; cómo se autentifican las llamadas internas; dónde consultar las últimas ejecuciones.
- Uso por parte del revisor: detectar desencadenantes que puedan falsificarse y tareas en segundo plano sin límites.
seo.md — cómo gestiona una aplicación de página única el SEO y las vistas previas en redes sociales. Incluir solo si hay rutas públicas/indexables o dirigidas a bots.
- Debe incluir: el enfoque de las vistas previas (metadatos estáticos / prerenderización / HTML de borde); una tabla ruta → necesidades-SEO → solo-datos-públicos; cómo se depuran los metadatos dinámicos; enrutamiento para bots frente a humanos.
- Uso por parte de los revisores: detectar infracciones de la norma «solo datos públicos» e inyección de metadatos en rutas para bots.
automation.md — agentes integrados y otras vías de automatización. Incluir solo si la aplicación integra agentes de IA, flujos de trabajo de LLM, llamadas a herramientas, webhooks o automatización externa.
- Se debe especificar, por cada automatización/agente: el desencadenante + el propietario + si se ejecuta automáticamente o solo tras aprobación; las entradas que puede leer y las herramientas o API exactas a las que puede acceder (la superficie de la herramienta es en sí misma una barrera de seguridad); dónde se encuentra el control (el prompt) frente a las barreras de seguridad independientes del prompt; el contrato de salida hacia la aplicación (esquema, validación, gestión de errores); efectos secundarios propios de la aplicación frente a sugerencias propias del agente; y los controles: puertas de aprobación, registro de auditoría/cronología, límites de frecuencia, reintentos, interruptor de emergencia.
- Uso por parte del revisor: hace visibles las rutas de automatización ocultas y traza la línea divisoria entre lo que propone un agente y lo que impone la aplicación —la superficie de mayor riesgo en las aplicaciones modernas basadas en IA—.

Notas

Cada documento generado añade una referencia a sí mismo en architecture.md, en la sección «Documentos relacionados», para que el conjunto siga siendo fácil de localizar.
Omite cualquier documento condicional que no sea aplicable e indícalo en una sola línea en lugar de inventar contenido.
Mantén los ejemplos y las plantillas terminadas fuera de estos documentos: describen este sistema, no el método general.
El archivo de contexto operativo del agente (CLAUDE.md / AGENTS.md) es un artefacto distinto: se trata de instrucciones derivadas de estos documentos, no de la documentación del sistema. Se genera en la etapa de traspaso mediante /ship-check, no aquí.
El archivo tests.md lo genera /derive-tests; el resto lo genera /document-app.
No incluyas una línea con la «fecha de actualización»; el historial del archivo es la fuente de información fiable.

Ver en GitHub

---
name: shipping-artifacts
description: Documents AI-built apps with architecture, permissions, secrets, and test coverage maps to make them reviewable before shipping.
---

# Shipping Artifacts: The Docs That Make AI-Built Code Reviewable

## Purpose

AI agents write code fast, but they leave no durable record of *intent* — what the system is supposed to do, who is allowed to do what, where the secrets live, which rules are actually verified. Without that record, no human (and no auditing agent) can tell whether the code is safe to ship. This skill defines the small set of documents that restore reviewability.

These docs live in `/documentation/` and are written for two readers: a human reviewer and the next AI coding agent. They are the **intended-state** half of every later audit — a security or performance review is only as good as the intent it can compare the code against.

## How the set is organized

The set is **not** a fixed list — it is a small **core** plus **conditional** docs you add only when the capability exists.

- **Core docs** — every reviewable app has these surfaces, so always produce them.
- **Conditional docs** — include one only if the app actually has that capability. If it doesn't, write a single line in `architecture.md` ("No scheduled work — no `cron.md`.") rather than inventing an empty document. Reviewability comes from an honest map, and "we don't do X" is part of the map.
- Most docs are reverse-engineered from code by `/document-app`. The one exception is `tests.md`, which is *derived from the other docs* by `/derive-tests` — it is the verification map, not a description of a subsystem.

Be brutally honest about the current state without being paranoid. The job is an accurate map, not a clean bill of health. Each doc is short, table-and-bullet heavy, and skips generic theory.

## Core documents

Each entry: file · one-line purpose · what it must capture · how a reviewer uses it.

1. **`architecture.md`** — what the system is and how it hangs together.
   - Must capture: product overview + key assumptions; tech stack; how auth/sessions/claims flow end to end; the trust boundaries (e.g. service-role vs. client); a short **Known risks / assumptions** list (each entry backed by where it shows up in the code, not a generic checklist); a "Related Documents" index of every other doc produced.
   - Reviewer use: the root document — everything else is cross-referenced from here.

2. **`flows.md`** — the journeys where permissions and side effects are actually exercised.
   - Must capture: each load-bearing flow as actor + precondition + success outcome; the step-by-step sequence across UI → server → data → jobs → providers → agents; the **authz check at each protected step** (which claim/role/scope, on which resource, and the expected *deny* case); the **trust-boundary crossings** (browser→server, server→provider, job→app, agent→tool, webhook→app); the state changes and side effects each step causes (writes, emails queued, jobs triggered, outbound calls).
   - Reviewer use: the runtime view a static `permissions.md` matrix can't show — *where* and *in what order* authorization is enforced, and where it can be skipped.
   - **Anti-PRD rule:** a flow that doesn't touch permissions, data integrity, external side effects, money, privacy, or operational safety does not belong here. This is a security/operations map, not a feature spec.

3. **`permissions.md`** — who is allowed to do what.
   - Must capture: roles/claims; where scope is derived (token vs. DB); a resource × operation × role matrix; which tables have row-level security and which rely on code-enforced checks.
   - Reviewer use: the baseline an access-control audit compares the code against. `flows.md` shows it in motion; this is the static reference.

4. **`variables.md`** — configuration and secrets, mapped to risk.
   - Must capture: a table of Name · used-by · scope (server/client) · source · rotation · risk; explicit confirmation that no secret is bundled client-side; a pre-go-live checklist.
   - Reviewer use: the secrets/PII-leak surface and the rotation plan during incident response.

5. **`tests.md`** — the verification map: which documented rules are actually checked, which are only proposed, and which are checked by nothing.
   - Must capture, in three clearly separated sections so the map can't read falsely green:
     - **Existing coverage** — tests that are in the repo *today*, each tied to the rule it pins (so the map reflects reality, not a wish-list).
     - **Proposed tests** — recommended cases not yet written, marked by **test type** (automated unit/integration · guarded live · manual review).
     - **Gaps** — documented rules with no verification at all, ranked by what crossing them exposes.
   - Each row carries: use-case → rule → expected behavior (including the deny/negative case) → evidence source (doc + code) → status (existing / proposed / none). It also notes which checks are CI-required and gate merges to `main`.
   - Reviewer use: the operational form of "documented == implemented" — it shows whether each rule the other docs claim is actually pinned by a test today, only proposed, or unverified.
   - Produced by `/derive-tests` (not `/document-app`), because it is derived from the other docs and the existing test suite rather than read off a subsystem.

## Conditional documents (include only when the capability exists)

6. **`emails.md`** — every notification the system sends. *Include only if the app sends transactional or automated email.*
   - Must capture: the queue → processor → provider path; templates and the variables they accept; retry/backoff behavior; where to look when a send fails.
   - Reviewer use: spotting unvalidated template inputs and PII exposure boundaries.

7. **`cron.md`** — all scheduled work and how to operate it safely. *Include only if scheduled or background jobs exist.*
   - Must capture: an inventory table (job → schedule → function → secrets → limits → retry); how each job stays idempotent; how internal calls authenticate; where to see last runs.
   - Reviewer use: finding forgeable triggers and unbounded background jobs.

8. **`seo.md`** — how a single-page app handles SEO and social previews. *Include only if there are public/indexable or bot-facing routes.*
   - Must capture: the preview approach (static meta / prerender / edge HTML); a route → needs-SEO → public-data-only table; how dynamic metadata is sanitized; bot-vs-human routing.
   - Reviewer use: catching public-data-only violations and metadata injection on bot routes.

9. **`automation.md`** — embedded agents and other automation paths. *Include only if the app embeds AI agents, LLM workflows, tool-calling, webhooks, or external automation.*
   - Must capture, per automation/agent: trigger + owner + whether it runs automatically or only after approval; the inputs it may read and the **exact tools/APIs it may call** (the tool surface is itself a hard guardrail); where **steering** lives (the prompt) vs. the **non-prompt hard guardrails**; the **output contract** back to the app (schema, validation, failure handling); **app-owned side effects vs. agent-owned suggestions**; and the controls — approval gates, audit/timeline logging, rate limits, retries, kill switch.
   - Reviewer use: makes hidden automation paths visible and draws the line between what an agent *proposes* and what the app *enforces* — the highest-risk surface in modern AI-built apps.

## Notes

- Each produced doc adds a reference to itself in `architecture.md` under a "Related Documents" section, so the set stays discoverable.
- Skip any conditional document that doesn't apply, and say so in one line rather than inventing content.
- Keep examples and finished templates out of these docs — they describe *this* system, not the general method.
- The agent operating-context file (`CLAUDE.md` / `AGENTS.md`) is a *different* artifact — instructions derived from these docs, not system documentation. It is produced at the handoff step by `/ship-check`, not here.
- `tests.md` is produced by `/derive-tests`; the rest are produced by `/document-app`.
- Do not include an "updated date" line; the file's history is the source of truth.