shipping-artifacts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

发布工件：让AI构建代码具备可审查性的文档

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.

AI Agent编写代码的速度很快，但不会留下关于意图的持久化记录——比如系统应该实现什么功能、谁被允许执行哪些操作、密钥存储在哪里、哪些规则已被实际验证。没有这些记录，无论是人类（还是审计Agent）都无法判断代码是否可以安全发布。本技能定义了一套小型文档集，用于恢复代码的可审查性。

这些文档存储在

/documentation/

目录下，面向两类读者：人类审核人员和后续的AI编码Agent。它们是后续所有审计工作中预期状态的核心依据——安全或性能审查的质量，完全取决于能否将代码与明确的预期意图进行对比。

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.

本文档集并非固定列表——它由一个小型核心文档集加上条件性文档组成，仅当应用具备对应能力时才添加条件性文档。

核心文档——所有可审查的应用都具备这些层面的内容，因此必须生成。
条件性文档——仅当应用实际具备对应能力时才包含。如果不具备，只需在
```
architecture.md
```
中添加一行说明（“无定时任务——无需
```
cron.md
```
”），而非创建空文档。可审查性源于真实的映射，“我们不做X”也是映射的一部分。
大多数文档由
```
/document-app
```
从代码逆向生成。唯一的例外是
```
tests.md
```
，它由
```
/derive-tests
```
从其他文档推导而来——它是验证映射表，而非子系统描述。

请如实反映当前状态，无需过度担忧。我们的目标是生成准确的映射，而非一份完美的健康报告。每份文档都应简洁，大量使用表格和项目符号，避免泛泛的理论内容。

Core documents

核心文档

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

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

每个条目包含：文件 · 一行描述的用途 · 必须涵盖的内容 · 审核人员的使用方式。

architecture.md
——说明系统是什么以及各组件如何协同工作。
- 必须涵盖：产品概述+关键假设；技术栈；认证/会话/声明的端到端流转；信任边界（如服务角色与客户端的边界）；简短的已知风险/假设列表（每个条目需关联代码中的对应位置，而非通用检查清单）；所有已生成文档的“相关文档”索引。
- 审核人员用途：根文档——所有其他文档均从此处交叉引用。
flows.md
——权限与副作用实际生效的用户旅程。
- 必须涵盖：每个关键流程的参与者+前置条件+成功结果；跨UI→服务器→数据→任务→服务商→Agent的分步流程；每个受保护步骤的授权检查（使用的声明/角色/范围、针对的资源以及预期的拒绝场景）；信任边界跨越（浏览器→服务器、服务器→服务商、任务→应用、Agent→工具、Webhook→应用）；每个步骤引发的状态变更与副作用（写入操作、待发送邮件、触发任务、外部调用）。
- 审核人员用途：静态的
```
permissions.md
```
  矩阵无法呈现的运行时视图——展示授权在何处、按何种顺序执行，以及可能被跳过的环节。
- 反PRD规则：不涉及权限、数据完整性、外部副作用、资金、隐私或操作安全的流程无需纳入。这是一份安全/运维映射表，而非功能规格说明。
permissions.md
——谁被允许执行哪些操作。
- 必须涵盖：角色/声明；范围的来源（令牌 vs 数据库）；资源×操作×角色矩阵；哪些表启用了行级安全，哪些依赖代码强制执行检查。
- 审核人员用途：访问控制审计对比代码的基准。
```
flows.md
```
  展示其运行状态，本文件则是静态参考。
variables.md
——配置与密钥，按风险映射。
- 必须涵盖：包含名称·使用方·作用域（服务器/客户端）·来源·轮换机制·风险的表格；明确确认无密钥打包在客户端；发布前检查清单。
- 审核人员用途：密钥/PII泄露风险面以及事件响应期间的轮换方案。
tests.md
——验证映射表：哪些已记录的规则已被实际检查、哪些仅为提议、哪些完全未被检查。
- 必须分为三个清晰分离的部分，避免映射表出现虚假的“合规”标识：
  - 现有覆盖率——当前仓库中已存在的测试，每个测试需关联其验证的规则（确保映射表反映实际情况，而非愿望清单）。
  - 提议测试——建议添加但尚未编写的测试用例，标注测试类型（自动化单元/集成测试 · 受控线上测试 · 人工审查）。
  - 缺口——已记录但完全未验证的规则，按违规风险排序。
- 每行包含：用例→规则→预期行为（包括拒绝/负面场景）→证据来源（文档+代码）→状态（已存在/提议/无）。同时需注明哪些检查是CI强制要求的，且会阻止合并到
```
main
```
  分支。
- 审核人员用途：“文档记录 == 已实现”的可操作形式——展示其他文档中声明的每条规则当前是否已被测试验证、仅为提议，或是未经验证。
- 由
```
/derive-tests
```
  生成（而非
```
/document-app
```
  ），因为它是从其他文档和现有测试套件推导而来，而非直接从子系统读取信息。

Conditional documents (include only when the capability exists)

条件性文档（仅当应用具备对应能力时包含）

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

emails.md
——系统发送的所有通知。仅当应用发送事务性或自动化邮件时包含。
- 必须涵盖：队列→处理器→服务商的路径；模板及其接受的变量；重试/退避机制；发送失败时的排查位置。
- 审核人员用途：发现未验证的模板输入和PII暴露边界。
cron.md
——所有定时任务及其安全运维方式。仅当存在定时或后台任务时包含。
- 必须涵盖：包含任务→调度→函数→密钥→限制→重试的清单表；每个任务如何保持幂等性；内部调用的认证方式；查看最近运行记录的位置。
- 审核人员用途：查找可伪造的触发器和无限制的后台任务。
seo.md
——单页应用如何处理SEO和社交预览。仅当存在可公开索引或面向爬虫的路由时包含。
- 必须涵盖：预览方案（静态元数据/预渲染/边缘HTML）；路由→是否需要SEO→仅公开数据的表格；动态元数据的 sanitize 方式；爬虫与人类用户的路由区分逻辑。
- 审核人员用途：捕捉仅公开数据的违规情况以及爬虫路由上的元数据注入风险。
automation.md
——嵌入式Agent及其他自动化流程。仅当应用嵌入AI Agent、LLM工作流、工具调用、Webhook或外部自动化时包含。
- 针对每个自动化/Agent，必须涵盖：触发器+所有者+是否自动运行或需审批后运行；可读取的输入以及可调用的具体工具/API（工具面本身就是一道严格的防护栏）；引导逻辑（提示词）与非提示词硬防护栏的存储位置；返回应用的输出契约（ schema、验证、故障处理）；应用所属副作用 vs Agent所属建议；以及控制机制——审批 gate、审计/时间线日志、速率限制、重试、终止开关。
- 审核人员用途：让隐藏的自动化路径可见，并明确区分Agent提议的操作与应用强制执行的操作——这是现代AI构建应用中风险最高的层面。

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.

每份生成的文档需在
```
architecture.md
```
的“相关文档”部分添加自身引用，确保文档集的可发现性。
跳过所有不适用的条件性文档，并添加一行说明，而非编造内容。
请勿在这些文档中包含示例和成品模板——它们描述的是当前系统，而非通用方法。
Agent操作上下文文件（
```
CLAUDE.md
```
/
```
AGENTS.md
```
）是不同的工件——从这些文档衍生的指令，而非系统文档。它在交接步骤由
```
/ship-check
```
生成，而非在此处生成。
```
tests.md
```
由
```
/derive-tests
```
生成；其余文档由
```
/document-app
```
生成。
请勿添加“更新日期”行；文件的历史记录即为事实来源。