Maison

Skill

Documentation

shipping-artifacts

phuryn/pm-skills

Documentation des applications développées par IA, comprenant leur architecture, leurs autorisations, leurs secrets et leurs cartes de couverture de test, afin de permettre leur vérification avant leur mise en production.

...Développer tout

Heure mise à jour 29 septembre 2026

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

Documentation des artefacts : les documents qui permettent de réviser le code généré par l'IA

Objectif

Les agents IA écrivent du code rapidement, mais ils ne laissent aucune trace durable de leurs intentions: ce que le système est censé faire, qui est autorisé à faire quoi, où se trouvent les informations confidentielles, quelles règles sont réellement vérifiées. Sans cette trace, aucun humain (ni aucun agent d’audit) ne peut déterminer si le code peut être déployé en toute sécurité. Cette compétence définit le petit ensemble de documents qui rétablissent la vérifiabilité.

Ces documents se trouvent dans le répertoire /documentation/ et s’adressent à deux types de lecteurs : un réviseur humain et le prochain agent de codage IA. Ils constituent la partie « état prévu » de tout audit ultérieur — la qualité d’un audit de sécurité ou de performance dépend de la clarté de l’intention à laquelle le code peut être comparé.

Comment cet ensemble est-il organisé ?

Cet ensemble n’ est pas une liste figée : il s’agit d’un noyau restreint complété par des documents conditionnels que vous n’ajoutez que lorsque la fonctionnalité existe.

Documents de base — toute application pouvant faire l’objet d’une révision comporte ces éléments ; veillez donc à toujours les produire.
Documents conditionnels — n’en incluez un que si l’application dispose réellement de cette fonctionnalité. Si ce n’est pas le cas, écrivez une seule ligne dans architecture.md (« Pas de tâche planifiée — pas de cron.md. ») plutôt que de créer un document vide. La révisabilité découle d’une cartographie honnête, et « nous ne faisons pas X » fait partie de cette cartographie.
La plupart des documents sont générés à partir du code par /document-app. La seule exception est tests.md, qui est dérivé des autres documents par /derive-tests — il s’agit de la carte de vérification, et non d’une description d’un sous-système.

Soyez d’une honnêteté brutale quant à l’état actuel sans pour autant céder à la paranoïa. La tâche consiste à établir une cartographie précise, et non à délivrer un certificat de bonne santé. Chaque document est court, riche en tableaux et en puces, et fait l’impasse sur la théorie générique.

Documents principaux

Chaque entrée : fichier · objectif en une ligne · ce qu’elle doit couvrir · comment un relecteur l’utilise.

architecture.md — en quoi consiste le système et comment il s’articule.
- Doit couvrir : présentation du produit + hypothèses clés ; pile technologique ; flux de l’authentification, des sessions et des revendications de bout en bout ; les limites de confiance (par ex. rôle de service vs client) ; une brève liste des risques connus et des hypothèses (chaque élément étant étayé par son emplacement dans le code, et non par une simple liste de contrôle générique) ; un index « Documents associés » répertoriant tous les autres documents produits.
- Utilisation par le réviseur : le document racine — tout le reste est référencé à partir de celui-ci.
flows.md — les parcours au cours desquels les autorisations et les effets secondaires sont effectivement exercés.
- Éléments à inclure impérativement : chaque flux porteur défini par un acteur + une condition préalable + un résultat positif ; la séquence étape par étape : interface utilisateur → serveur → données → tâches → fournisseurs → agents ; le contrôle d’autorisation à chaque étape protégée (quelle revendication/quel rôle/quelle portée, sur quelle ressource, et le cas de refus attendu) ; les franchissements de frontières de confiance (navigateur → serveur, serveur → fournisseur, tâche → application, agent → outil, webhook → application) ; les changements d’état et les effets secondaires provoqués par chaque étape (écritures, e-mails mis en file d’attente, tâches déclenchées, appels sortants).
- Utilisation par le réviseur : la vue d’exécution qu’une matrice statique permissions.md ne peut pas montrer — où et dans quel ordre l’autorisation est appliquée, et où elle peut être ignorée.
- Règle anti-PRD : un flux qui ne touche pas aux autorisations, à l’intégrité des données, aux effets secondaires externes, à l’argent, à la confidentialité ou à la sécurité opérationnelle n’a pas sa place ici. Il s’agit d’une carte de sécurité/d’exploitation, et non d’un cahier des charges fonctionnel.
permissions.md — qui est autorisé à faire quoi.
- Éléments à inclure impérativement : rôles/revendications ; d’où provient la portée (jeton ou base de données) ; une matrice ressource × opération × rôle ; quelles tables disposent d’une sécurité au niveau des lignes et lesquelles s’appuient sur des vérifications imposées par le code.
- Utilisation par les réviseurs : la base de référence à laquelle un audit de contrôle d’accès compare le code. Le fichier flows.md montre le processus en action ; il s’agit ici de la référence statique.
variables.md — configuration et secrets, mis en correspondance avec les risques.
- Éléments à inclure : un tableau indiquant Nom · utilisé par · portée (serveur/client) · source · rotation · risque ; confirmation explicite qu’aucun secret n’est intégré côté client ; une liste de contrôle avant la mise en production.
- Utilisation par les réviseurs : la surface d’exposition aux fuites de secrets/données à caractère personnel et le plan de rotation pendant la réponse aux incidents.
tests.md — la carte de vérification : quelles règles documentées sont réellement vérifiées, lesquelles ne sont que proposées, et lesquelles ne font l’objet d’aucune vérification.
- Doit inclure, dans trois sections clairement distinctes afin que la carte ne donne pas de faux positifs :
  - Couverture existante — les tests actuellement présents dans le dépôt, chacun étant lié à la règle à laquelle il se rapporte (afin que la carte reflète la réalité, et non une liste de souhaits).
  - Tests proposés — cas recommandés mais pas encore écrits, classés par type de test (test unitaire/d’intégration automatisé · test en production surveillé · revue manuelle).
  - Lacunes — règles documentées ne faisant l’objet d’aucune vérification, classées en fonction des risques que leur non-respect fait apparaître.
- Chaque ligne contient : cas d’utilisation → règle → comportement attendu (y compris le cas de refus/négatif) → source de preuve (documentation + code) → statut (existant / proposé / aucun). Elle indique également quelles vérifications sont requises par l’intégration continue (CI) et conditionnent les fusions vers la branche principale.
- Utilisation par les relecteurs : la forme opérationnelle de « documenté == implémenté » — cela indique si chaque règle mentionnée dans les autres documents est aujourd’hui effectivement validée par un test, si elle est seulement proposée, ou si elle n’est pas vérifiée.
- Généré par /derive-tests (et non par /document-app), car il est dérivé des autres documents et de la suite de tests existante plutôt que d’être extrait d’un sous-système.

Documents conditionnels (à inclure uniquement lorsque la fonctionnalité existe)

emails.md — toutes les notifications envoyées par le système. À inclure uniquement si l’application envoie des e-mails transactionnels ou automatisés.
- Doit inclure : le chemin file d’attente → processeur → fournisseur ; les modèles et les variables qu’ils acceptent ; le comportement de réessai/retrait ; où chercher lorsqu’un envoi échoue.
- Utilisation par les relecteurs : repérer les entrées de modèles non validées et les limites d’exposition des données à caractère personnel.
cron.md — toutes les tâches planifiées et comment les exécuter en toute sécurité. À inclure uniquement si des tâches planifiées ou en arrière-plan existent.
- Éléments à inclure : un tableau d’inventaire (tâche → planification → fonction → secrets → limites → nouvelle tentative) ; comment chaque tâche reste idempotente ; comment s’effectue l’authentification des appels internes ; où consulter les dernières exécutions.
- Utilisation par le réviseur : identification des déclencheurs susceptibles d’être falsifiés et des tâches en arrière-plan sans limite.
seo.md — comment une application monopage gère le référencement naturel (SEO) et les aperçus sur les réseaux sociaux. À inclure uniquement s’il existe des routes publiques/indexables ou destinées aux robots d’indexation.
- Éléments à inclure : l’approche d’aperçu (métadonnées statiques / pré-rendu / HTML en périphérie) ; un tableau route → besoins-SEO → données-publiques-uniquement ; comment les métadonnées dynamiques sont nettoyées ; le routage bot vs humain.
- Utilisation par les réviseurs : détecter les violations du principe « données publiques uniquement » et l’injection de métadonnées sur les routes destinées aux robots.
automation.md — agents intégrés et autres voies d’automatisation. À inclure uniquement si l’application intègre des agents IA, des workflows LLM, l’appel d’outils, des webhooks ou une automatisation externe.
- Doit recenser, pour chaque automatisation/agent : le déclencheur + le propriétaire + s’il s’exécute automatiquement ou uniquement après validation ; les entrées qu’il peut lire et les outils/API précis qu’il peut appeler (la surface d’outils constitue en soi une barrière de sécurité stricte) ; où se situe le pilotage (l’invite) par rapport aux barrières de sécurité strictes hors invite; le contrat de sortie renvoyé à l’application (schéma, validation, gestion des échecs) ; les effets secondaires propres à l’application par opposition aux suggestions propres à l’agent ; et les contrôles — portes d’approbation, journalisation d’audit/chronologique, limites de débit, tentatives de réessai, interrupteur d’arrêt d’urgence.
- Utilisation par les réviseurs : rend visibles les chemins d’automatisation cachés et trace la ligne de démarcation entre ce que propose un agent et ce que l’application impose — la surface présentant le plus grand risque dans les applications modernes basées sur l’IA.

Remarques

Chaque document produit ajoute une référence à lui-même dans le fichier architecture.md, dans la section « Documents associés », afin que l’ensemble reste accessible.
Ignorez tout document conditionnel qui ne s’applique pas, et indiquez-le en une ligne plutôt que d’inventer du contenu.
Ne pas inclure d’exemples ni de modèles finis dans ces documents — ils décrivent ce système, pas la méthode générale.
Le fichier de contexte d’exécution de l’agent (CLAUDE.md / AGENTS.md) est un artefact distinct: il s’agit d’instructions dérivées de ces documents, et non de la documentation du système. Il est généré lors de l’étape de transfert par /ship-check, et non ici.
Le fichier tests.md est généré par la commande /derive-tests; les autres sont générés par /document-app.
N’incluez pas de ligne « date de mise à jour » ; l’historique du fichier fait foi.

Voir sur 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.