Heim

Skill

Dokumentation

shipping-artifacts

phuryn/pm-skills

Dokumentiert KI-basierte Anwendungen mit Architektur, Berechtigungen, Geheimnissen und Testabdeckungskarten, damit sie vor der Auslieferung überprüft werden können.

...Alle erweitern

Zeit aktualisiert 29. September 2026

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

Artefakte übermitteln: Die Dokumente, die KI-generierten Code überprüfbar machen

Zweck

KI-Agenten schreiben Code schnell, hinterlassen jedoch keine dauerhafte Dokumentation der Absichten – was das System tun soll, wer was tun darf, wo sich die Geheimnisse befinden und welche Regeln tatsächlich überprüft werden. Ohne diese Aufzeichnungen kann kein Mensch (und kein Audit-Agent) feststellen, ob der Code sicher für die Auslieferung ist. Diese Funktion definiert die kleine Sammlung von Dokumenten, die die Überprüfbarkeit wiederherstellen.

Diese Dokumente befinden sich im Verzeichnis /documentation/ und richten sich an zwei Leser: einen menschlichen Prüfer und den nächsten KI-Codierungsagenten. Sie bilden die „beabsichtigte Zustand “-Hälfte jeder späteren Prüfung – eine Sicherheits- oder Leistungsprüfung ist nur so gut wie die Absicht, mit der sie den Code abgleichen kann.

Wie die Sammlung organisiert ist

Die Sammlung ist keine feste Liste – sie besteht aus einem kleinen Kern sowie bedingten Dokumenten, die Sie nur hinzufügen, wenn die entsprechende Funktion vorhanden ist.

Kern-Dokumente – jede überprüfbare App verfügt über diese Bereiche, daher sollten sie immer erstellt werden.
Bedingte Dokumente – fügen Sie eines nur dann hinzu, wenn die App tatsächlich über diese Funktion verfügt. Ist dies nicht der Fall, schreiben Sie eine einzige Zeile in die Datei „architecture.md“ („Keine geplanten Aufgaben – kein cron.md.“), anstatt ein leeres Dokument zu erstellen. Überprüfbarkeit entsteht durch eine ehrliche Übersicht, und „Wir machen X nicht“ ist Teil dieser Übersicht.
Die meisten Dokumente werden von /document-app aus dem Code rückentwickelt. Die einzige Ausnahme bildet tests.md, das von /derive-tests aus den anderen Dokumenten abgeleitet wird – es handelt sich um die Verifikationsübersicht, nicht um eine Beschreibung eines Teilsystems.

Seid brutal ehrlich, was den aktuellen Stand angeht, ohne dabei paranoid zu sein. Die Aufgabe besteht darin, eine genaue Übersicht zu erstellen, nicht einen „Gesundheitszeugnis“ auszustellen. Jedes Dokument ist kurz, enthält viele Tabellen und Aufzählungspunkte und verzichtet auf allgemeine Theorie.

Kern-Dokumente

Jeder Eintrag: Datei · einzeiliger Zweck · was darin erfasst werden muss · wie ein Prüfer es nutzt.

architecture.md – Was das System ist und wie es zusammenhängt.
- Muss enthalten: Produktübersicht + zentrale Annahmen; Tech-Stack; wie Authentifizierung/Sitzungen/Claims von Anfang bis Ende ablaufen; die Vertrauensgrenzen (z. B. Service-Rolle vs. Client); eine kurze Liste bekannter Risiken/Annahmen (jeder Eintrag mit Verweis auf die entsprechende Stelle im Code, keine allgemeine Checkliste); ein Index „Verwandte Dokumente“ mit allen anderen erstellten Dokumenten.
- Verwendung durch den Prüfer: das Stammdokument – alles andere wird von hier aus verlinkt.
flows.md – die Abläufe, in denen Berechtigungen und Nebenwirkungen tatsächlich zum Tragen kommen.
- Muss erfasst werden: jeder tragende Ablauf als Akteur + Vorbedingung + Erfolgsergebnis; die Schritt-für-Schritt-Abfolge über UI → Server → Daten → Jobs → Anbieter → Agenten; die Autorisierungsprüfung bei jedem geschützten Schritt (welcher Anspruch/welche Rolle/welcher Geltungsbereich, für welche Ressource und der erwartete Ablehnungsfall ); die Überschreitungen von Vertrauensgrenzen (Browser → Server, Server → Anbieter, Job → App, Agent → Tool, Webhook → App); die Zustandsänderungen und Nebenwirkungen, die jeder Schritt verursacht (Schreibvorgänge, in die Warteschlange gestellte E-Mails, ausgelöste Jobs, ausgehende Aufrufe).
- Nutzen für Prüfer: die Laufzeitperspektive, die eine statische „permissions.md “-Matrix nicht zeigen kann – wo und in welcher Reihenfolge die Autorisierung durchgesetzt wird und wo sie übersprungen werden kann.
- Anti-PRD-Regel: Ein Ablauf, der keine Berechtigungen, Datenintegrität, externe Nebenwirkungen, Geld, Datenschutz oder Betriebssicherheit betrifft, gehört nicht hierher. Dies ist eine Sicherheits-/Betriebsübersicht, keine Funktionsspezifikation.
permissions.md – wer darf was tun.
- Muss erfasst werden: Rollen/Claims; wo der Geltungsbereich abgeleitet wird (Token vs. Datenbank); eine Matrix aus Ressource × Operation × Rolle; welche Tabellen über Sicherheit auf Zeilenebene verfügen und welche auf durch Code erzwungene Prüfungen angewiesen sind.
- Verwendung durch Prüfer: Die Basis, mit der ein Audit der Zugriffskontrolle den Code vergleicht. flows.md zeigt den Ablauf in Aktion; dies ist die statische Referenz.
variables.md – Konfiguration und Geheimnisse, zugeordnet zu Risiken.
- Muss enthalten: eine Tabelle mit Name · Verwendungszweck · Geltungsbereich (Server/Client) · Quelle · Rotation · Risiko; ausdrückliche Bestätigung, dass keine Geheimnisse clientseitig gebündelt sind; eine Checkliste vor der Inbetriebnahme.
- Verwendung durch Prüfer: die Angriffsfläche für Geheimnisse/PII-Lecks und der Rotationsplan während der Reaktion auf Vorfälle.
tests.md – die Verifizierungskarte: Welche dokumentierten Regeln werden tatsächlich geprüft, welche sind nur vorgeschlagen und welche werden gar nicht geprüft?
- Muss in drei klar voneinander getrennten Abschnitten erfasst werden, damit die Übersicht nicht fälschlicherweise „grün“ anzeigt:
  - Bestehende Abdeckung – Tests, die sich derzeit im Repo befinden, jeweils verknüpft mit der Regel, auf die sie verweisen (damit die Übersicht die Realität widerspiegelt und keine Wunschliste ist).
  - Vorgeschlagene Tests – empfohlene Fälle, die noch nicht geschrieben wurden, gekennzeichnet nach Testtyp (automatisierte Unit-/Integrationstests · geschützte Live-Tests · manuelle Überprüfung).
  - Lücken – dokumentierte Regeln, für die es überhaupt keine Verifizierung gibt, geordnet nach den Risiken, die bei Verstößen auftreten.
- Jede Zeile enthält: Anwendungsfall → Regel → erwartetes Verhalten (einschließlich des Verweigerungs-/Negativfalls) → Belegquelle (Dokumentation + Code) → Status (vorhanden / vorgeschlagen / keine). Außerdem wird vermerkt, welche Prüfungen für die CI erforderlich sind und das Zusammenführen in den Hauptzweig blockieren.
- Verwendung durch Prüfer: Die operative Form von „dokumentiert == implementiert“ – sie zeigt, ob jede Regel, die in den anderen Dokumenten genannt wird, heute tatsächlich durch einen Test abgesichert ist, nur vorgeschlagen wurde oder noch nicht verifiziert ist.
- Erstellt von /derive-tests (nicht /document-app), da es aus den anderen Dokumenten und der bestehenden Testsuite abgeleitet wird und nicht aus einem Subsystem ausgelesen wird.

Bedingte Dokumente (nur einbeziehen, wenn die Funktion vorhanden ist)

emails.md – jede Benachrichtigung, die das System versendet. Nur einbinden, wenn die App transaktionsbezogene oder automatisierte E-Mails versendet.
- Muss erfasst werden: der Pfad „Warteschlange → Prozessor → Anbieter“; Vorlagen und die von ihnen akzeptierten Variablen; Verhalten bei Wiederholungsversuchen und Rückzug; wo nachgeschaut werden muss, wenn ein Versand fehlschlägt.
- Verwendung durch Prüfer: Aufspüren von nicht validierten Vorlageneingaben und Grenzen der Offenlegung personenbezogener Daten.
cron.md – alle geplanten Aufgaben und deren sichere Durchführung. Nur einbinden, wenn geplante oder Hintergrundaufträge vorhanden sind.
- Muss erfasst werden: eine Bestandsübersicht (Auftrag → Zeitplan → Funktion → Geheimnisse → Grenzwerte → Wiederholungsversuche); wie jeder Auftrag idempotent bleibt; wie interne Aufrufe authentifiziert werden; wo die letzten Ausführungen eingesehen werden können.
- Verwendung durch den Prüfer: Auffinden von manipulierbaren Auslösern und unbegrenzten Hintergrundaufgaben.
seo.md – Wie eine Single-Page-App SEO und Social-Previews handhabt. Nur einbeziehen, wenn es öffentliche/indexierbare oder für Bots zugängliche Routen gibt.
- Muss erfasst werden: der Vorschauansatz (statische Meta-Tags / Prerendering / Edge-HTML); eine Tabelle „Route → SEO-Anforderungen → nur öffentliche Daten“; wie dynamische Metadaten bereinigt werden; Routingunterscheidung zwischen Bots und Menschen.
- Verwendung durch Prüfer: Aufdeckung von Verstößen gegen die „Nur-öffentliche-Daten“-Regel und Metadaten-Injektion auf Bot-Routen.
automation.md – Eingebettete Agenten und andere Automatisierungspfade. Nur einbeziehen, wenn die App KI-Agenten, LLM-Workflows, Tool-Aufrufe, Webhooks oder externe Automatisierung einbindet.
- Muss pro Automatisierung/Agent erfasst werden: Auslöser + Verantwortlicher + ob automatisch oder erst nach Freigabe ausgeführt wird; die Eingaben, die er lesen darf, und die genauen Tools/APIs, die er aufrufen darf (die Tool-Oberfläche ist selbst eine feste Schutzbarriere); wo die Steuerung stattfindet (der Prompt) im Vergleich zu den festen Schutzbarrieren außerhalb des Prompts; die Ausgabevereinbarung zurück an die App (Schema, Validierung, Fehlerbehandlung); App-eigene Nebenwirkungen im Vergleich zu Agenten-eigenen Vorschlägen; sowie die Kontrollmechanismen – Genehmigungsschranken, Audit-/Zeitachsenprotokollierung, Ratenbegrenzungen, Wiederholungsversuche, Kill-Switch.
- Nutzung durch Prüfer: Macht verborgene Automatisierungspfade sichtbar und zieht die Grenze zwischen dem, was ein Agent vorschlägt, und dem, was die App durchsetzt – die risikoreichste Schnittstelle in modernen, auf KI basierenden Apps.

Hinweise

Jedes erstellte Dokument fügt in der Datei „architecture.md“ unter dem Abschnitt „Related Documents“ einen Verweis auf sich selbst hinzu, sodass die Sammlung auffindbar bleibt.
Überspringe alle bedingten Dokumente, die nicht zutreffen, und weise in einer Zeile darauf hin, anstatt Inhalte zu erfinden.
Halten Sie Beispiele und fertige Vorlagen aus diesen Dokumenten heraus – sie beschreiben dieses System, nicht die allgemeine Methode.
Die Datei zum Betriebskontext des Agenten (CLAUDE.md / AGENTS.md) ist ein eigenständiges Artefakt – Anweisungen, die aus diesen Dokumenten abgeleitet wurden, und keine Systemdokumentation. Sie wird im Übergabeschritt von /ship-check erstellt, nicht hier.
tests.md wird von /derive-tests erstellt; der Rest wird von /document-app erstellt.
Fügen Sie keine Zeile mit dem „Aktualisierungsdatum“ ein; die Versionshistorie der Datei ist die maßgebliche Quelle.

Auf GitHub ansehen

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