Дом

Skill

Документация

shipping-artifacts

phuryn/pm-skills

Создает документацию по приложениям, разработанным с использованием ИИ, включая архитектуру, разрешения, секретные данные и карты охвата тестированием, чтобы обеспечить возможность их проверки перед выпуском.

...Расширить все

Обновлено время 29 сентября 2026 г.

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

Передача артефактов: документация, которая делает код, созданный ИИ, пригодным для рецензирования

Цель

ИИ-агенты быстро пишут код, но не оставляют надежных записей о намерениях — о том, что должна делать система, кому что разрешено, где хранятся секретные данные, какие правила действительно проверяются. Без этой записи ни один человек (и ни один агент аудита) не сможет определить, безопасно ли выпускать этот код. В данном руководстве описан небольшой набор документов, которые восстанавливают возможность проверки.

Эти документы находятся в каталоге /documentation/ и предназначены для двух читателей: человека-рецензента и следующего ИИ-агента-программиста. Они представляют собой «запланированное состояние » — половину каждого последующего аудита: эффективность проверки безопасности или производительности зависит от того, с каким замыслом можно сравнить код.

Как организован этот набор

Этот набор не является фиксированным списком — он состоит из небольшого ядра плюс условных документов, которые вы добавляете только при наличии соответствующих возможностей.

Основные документы — каждое приложение, подлежащее проверке, имеет такие аспекты, поэтому всегда создавайте их.
Условные документы — включайте их только в том случае, если приложение действительно обладает данной функциональностью. Если нет, лучше напишите одну строку в файле architecture.md («Нет запланированных задач — нет cron.md»), чем создавать пустой документ. Возможность рецензирования обеспечивается честной схемой, и фраза «мы не делаем X» является частью этой схемы.
Большинство документов создаются путем обратного инжиниринга из кода с помощью /document-app. Единственным исключением является файл tests.md, который получается из других документов с помощью /derive-tests — это карта проверки, а не описание подсистемы.

Будьте предельно честны в отношении текущего состояния, не впадая при этом в паранойю. Задача состоит в создании точной схемы, а не в предоставлении «справки о хорошем здоровье». Каждый документ должен быть кратким, содержать много таблиц и списков и обходить стороной общую теорию.

Основные документы

Каждая запись: файл · цель в одной строке · что он должен отражать · как его использует рецензент.

architecture.md — что представляет собой система и как она устроена.
- Должно отражать: обзор продукта + ключевые допущения; технологический стек; как от начала до конца протекают авторизация, сессии и утверждения; границы доверия (например, «роль службы» против «клиента»); краткий список известных рисков и допущений (каждая запись подкреплена указанием места в коде, а не общим чек-листом); указатель «Связанные документы» со списком всех остальных созданных документов.
- Использование рецензентом: это корневой документ — на всё остальное даются перекрёстные ссылки именно отсюда.
flows.md — сценарии, в которых фактически реализуются разрешения и побочные эффекты.
- Обязательно необходимо отразить: каждый основной поток в виде «участник + предварительное условие + результат успешного выполнения»; пошаговую последовательность: пользовательский интерфейс → сервер → данные → задания → провайдеры → агенты; проверку авторизации на каждом защищённом этапе (какая претензия/роль/область действия, в отношении какого ресурса, а также ожидаемый случай отказа ); пересечения границ доверия (браузер → сервер, сервер → провайдер, задание → приложение, агент → инструмент, веб-хук → приложение); изменения состояния и побочные эффекты, вызываемые каждым шагом (записи, письма в очереди, запущенные задания, исходящие вызовы).
- Использование рецензентом: представление на этапе выполнения, которое не может показать статическая матрица permissions.md — где и в каком порядке осуществляется авторизация, а где её можно пропустить.
- Правило «против PRD»: поток, не затрагивающий разрешения, целостность данных, внешние побочные эффекты, деньги, конфиденциальность или эксплуатационную безопасность, не имеет места здесь. Это карта безопасности/эксплуатации, а не спецификация функциональных возможностей.
permissions.md — кому что разрешено.
- Обязательно должны быть отражены: роли/претензии; откуда берется область действия (токен или БД); матрица «ресурс × операция × роль»; какие таблицы имеют защиту на уровне строк, а какие полагаются на проверки, обеспечиваемые кодом.
- Использование рецензентом: базовый уровень, с которым сравнивается код при аудите контроля доступа. Файл flows.md показывает это в действии; это статический справочник.
variables.md — конфигурация и секретные данные, соотнесённые с рисками.
- Обязательно должно быть отражено: таблица с названиями · использующими элементами · областью действия (сервер/клиент) · источником · сроком действия · риском; явное подтверждение того, что никакие секретные данные не встроены на стороне клиента; контрольный список перед запуском в эксплуатацию.
- Использование рецензентом: уязвимости, связанные с утечкой секретов/PII, и план ротации при реагировании на инциденты.
tests.md — карта проверки: какие задокументированные правила фактически проверяются, какие — только предлагаются, а какие не проверяются ничем.
- Необходимо отразить в трёх чётко разделённых разделах, чтобы карта не отображала ложные «зелёные» результаты:
  - Существующий охват — тесты, которые на сегодняшний день находятся в репозитории, каждый из которых привязан к правилу, на которое он ориентирован (чтобы карта отражала реальность, а не список пожеланий).
  - Предлагаемые тесты — рекомендуемые случаи, которые ещё не написаны, с пометкой по типу теста (автоматизированные модульные/интеграционные · тесты в производственной среде с защитой · ручной обзор).
  - Пробелы — задокументированные правила, для которых отсутствует какая-либо проверка, отсортированные по тому, что может выявить их нарушение.
- Каждая строка содержит: сценарий использования → правило → ожидаемое поведение (включая отрицательный случай) → источник доказательств (документация + код) → статус (существующий / предлагаемый / отсутствует). Также указывается, какие проверки требуются для CI и являются обязательными для слияния в основную ветку.
- Использование рецензентом: рабочая форма принципа «документировано == реализовано» — показывает, закреплено ли каждое правило, о котором говорится в других документах, на сегодняшний день тестом, является ли оно лишь предложенным или не проверенным.
- Создано с помощью /derive-tests (а не /document-app), поскольку оно получено на основе других документов и существующего набора тестов, а не считывается из подсистемы.

Условные документы (включать только при наличии соответствующей возможности)

emails.md — каждое уведомление, отправляемое системой. Включать только в том случае, если приложение отправляет транзакционные или автоматические электронные письма.
- Должно отражать: путь «очередь → процессор → провайдер»; шаблоны и принимаемые ими переменные; поведение при повторных попытках и отсрочке; где искать причину, если отправка завершилась сбоем.
- Использование рецензентом: выявление непроверенных входных данных шаблонов и границ раскрытия персональных данных.
cron.md — все запланированные задания и правила их безопасной эксплуатации. Включать только при наличии запланированных или фоновых заданий.
- Обязательно отразить: таблицу инвентаризации (задание → расписание → функция → секретные данные → ограничения → повторные попытки); как каждое задание сохраняет идемпотентность; как происходит аутентификация при внутренних вызовах; где можно посмотреть последние запуски.
- Использование рецензентом: поиск поддающихся подделке триггеров и фоновых заданий без ограничений.
seo.md — как одностраничное приложение обрабатывает SEO и предварительный просмотр в социальных сетях. Включать только при наличии публичных/индексируемых маршрутов или маршрутов, доступных для ботов.
- Обязательно отразить: подход к предварительному просмотру (статические метаданные / предварительный рендеринг / HTML на периферии); таблицу «маршрут → требования SEO → только публичные данные»; как очищаются динамические метаданные; маршрутизацию «бот против человека».
- Использование рецензентом: выявление нарушений правила «только общедоступные данные» и внедрения метаданных на маршрутах для ботов.
automation.md — встроенные агенты и другие пути автоматизации. Включать только в том случае, если приложение использует встроенных ИИ-агентов, рабочие процессы LLM, вызов инструментов, веб-хуки или внешнюю автоматизацию.
- Обязательно укажите для каждой автоматизации/каждого агента: триггер + владелец + работает ли она автоматически или только после утверждения; входные данные, которые он может считывать, и точные инструменты/API, которые он может вызывать (сама поверхность инструмента является жёстким ограничителем); где находится управление (промпт) по сравнению с жёсткими ограничителями, не связанными с промптом; договор о выводе данных обратно в приложение (схема, валидация, обработка ошибок); побочные эффекты, принадлежащие приложению, по сравнению с предложениями, принадлежащими агенту; а также средства контроля — этапы утверждения, аудит/регистрация событий, ограничения частоты запросов, повторные попытки, аварийный выключатель.
- Использование рецензентом: делает видимыми скрытые пути автоматизации и проводит границу между тем, что предлагает агент, и тем, что навязывает приложение — поверхностью с наибольшим риском в современных приложениях, построенных на ИИ.

Примечания

Каждый сгенерированный документ добавляет ссылку на себя в файл architecture.md в разделе «Связанные документы», благодаря чему набор документов остается доступным для поиска.
Пропускайте любые условные документы, которые не применимы, и указывайте это одной строкой, а не придумывайте содержание.
Не включайте примеры и готовые шаблоны в эти документы — они описывают именно эту систему, а не общий метод.
Файл контекста работы агента (CLAUDE.md / AGENTS.md) — это отдельный артефакт: инструкции, полученные из этих документов, а не системная документация. Он создается на этапе передачи с помощью /ship-check, а не здесь.
Файл tests.md создается командой /derive-tests; остальные — командой /document-app.
Не включайте строку с «датой обновления»; история файла является единственным достоверным источником информации.

Посмотреть на 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.