用途
AI 智能体写代码很快，但不会留下关于“意图”的持久记录——系统本该做什么、谁被允许做什么、密钥存放在哪里、哪些规则真正被验证过。缺少这份记录，人类评审者和审计智能体都无法判断代码是否可以安全发布。Shipping Artifacts 正是为恢复可审查性而定义的一组文档。
这些文档面向两类读者：人类评审者和下一个 AI 编码代理。它们也是后续安全或性能审计的“意图基准”——审计质量取决于能拿代码对照的意图是否清晰。
位置与命名：优先遵循仓库自身约定
插件中的所有位置、文件名和文档格式约定都只是默认值，宿主仓库自身的设置优先。写入任何文档前，应先查找：
- 代理指令（AGENTS.md、CLAUDE.md 及其引用内容），其中常规定文档目录、文件、维护者和日期记录方式；
- 已存在的 docs/、documentation/ 等目录；
- 已有的等价文档（如 ARCHITECTURE.md、docs/security.md、docs/env.md），按内容匹配而非文件名；
- 已有的测试覆盖映射文件（如 docs/test-coverage.md）；
- 已有的审计或评审输出位置。
找到后应遵循：写入仓库的文档目录，更新已有等价文档而非新建平行文件，沿用其命名与日期约定。文档内容要求不变，变的只是位置和名称。只有当仓库没有任何约定时，才使用插件默认值：文档放在仓库根目录的 documentation/，覆盖映射放在 documentation/tests.md，报告放在 reports/<name>_{timestamp}.md，且不添加“更新日期”行（文件历史即事实来源）。
输出中需说明每份文件写到了哪里、遵循的是仓库约定还是插件默认。
禁止创建仅大小写不同的文件名（如 tests.md 与 TESTS.md、Architecture.md 与 architecture.md）。在 Windows 和 macOS 上它们是同一个文件，写入会覆盖；其他平台则会形成冲突文件。创建前应做大小写不敏感的检查。
文档组织方式
文档集不是固定清单，而是“小型核心 + 按需条件文档”。
- 核心文档：每个可审查应用都有这些面，始终生成。
- 条件文档：仅当应用确实具备该能力时才包含。不具备时，在 architecture.md 中用一行说明（例如“无定时任务——无 cron.md”），而不是编造空文档。可审查性来自诚实的地图，“我们不做 X”也是地图的一部分。
大多数文档由 document-app 技能从代码反向生成；唯一例外是 tests.md，由 derive-tests 技能从其他文档推导而来，它是验证映射而非子系统描述。
文档应如实反映当前状态而不夸大，每份文档简短、以表格和要点为主，跳过通用理论。
核心文档
architecture.md —— 系统是什么、如何组合。 需包含：产品概述与关键假设；技术栈；认证/会话/声明端到端流转；信任边界（如服务角色 vs. 客户端）；简短的已知风险/假设清单（每条须有代码依据，而非通用检查表）；所有其他产物的“相关文档”索引。评审者把它当作根文档，其余文档均由此交叉引用。
flows.md —— 权限与副作用真正被执行的旅程。 需包含：每个关键流程的参与者 + 前置条件 + 成功结果；跨 UI → 服务器 → 数据 → 作业 → 提供方 → 智能体的分步顺序；每个受保护步骤的授权检查（哪个声明/角色/范围、作用于哪个资源、预期拒绝情形）；信任边界跨越（浏览器→服务器、服务器→提供方、作业→应用、智能体→工具、webhook→应用）；每步引起的状态变更和副作用（写入、排队邮件、触发作业、出站调用）。评审者据此获得静态权限矩阵无法呈现的运行时视图。 反 PRD 规则：不涉及权限、数据完整性、外部副作用、资金、隐私或运行安全的流程不纳入本文档。
permissions.md —— 谁被允许做什么。 需包含：角色/声明；范围来源（令牌 vs. 数据库）；资源 × 操作 × 角色矩阵；哪些表有行级安全、哪些依赖代码检查。评审者将其作为访问控制审计的静态基线。
variables.md —— 配置与密钥，按风险映射。 需包含：名称 · 使用者 · 范围（服务端/客户端）· 来源 · 轮换 · 风险 的表格；明确确认没有密钥被打包到客户端；上线前检查清单。评审者据此识别密钥/PII 泄露面并在事件响应中执行轮换。
tests.md —— 验证映射：哪些已记录的规则真正被检查、哪些只是提议、哪些完全没有验证。 需分为三个明确区段，避免误读为“全绿”：
- 现有覆盖：仓库中当前的测试，各自绑定其固定的规则；
- 提议测试：尚未编写的建议用例，按测试类型标注（自动化单元/集成 · 受控实机 · 人工评审）；
- 缺口：完全没有验证的已记录规则，按越界后果排序。 每行包含：用例 → 规则 → 预期行为（含拒绝/负向情形）→ 证据来源（文档 + 代码）→ 状态（现有/提议/无）。还要注明仓库声明的门禁策略所需的检查（本地命令加人工放行，或未声明时合并到主分支的 CI 检查）。由 derive-tests 技能生成。
条件文档（仅在能力存在时包含）
emails.md —— 系统发送的所有通知。仅当应用发送事务性或自动邮件时包含。需包含：队列 → 处理器 → 提供方路径；模板及其接受的变量；重试/退避行为；发送失败时去哪里排查。
cron.md —— 所有定时工作及其安全操作方式。仅当存在定时或后台作业时包含。需包含：清单表（作业 → 计划 → 函数 → 密钥 → 限制 → 重试）；各作业如何保持幂等；内部调用如何认证；在哪里查看最近运行。
seo.md —— 单页应用如何处理 SEO 和社交预览。仅当存在公开/可索引或面向机器人的路由时包含。需包含：预览方案（静态 meta / 预渲染 / 边缘 HTML）；路由 → 是否需要 SEO → 是否仅公开数据 的表格；动态元数据如何净化；机器人 vs. 人类路由。
automation.md —— 内嵌智能体及其他自动化路径。仅当应用内嵌 AI 智能体、LLM 工作流、工具调用、webhook 或外部自动化时包含。需按自动化/智能体说明：触发器 + 所有者 + 是否自动运行或仅批准后运行；可读取的输入和可调用的确切工具/API；引导逻辑（提示词）与非提示词的硬性护栏；返回应用的输出契约（模式、校验、失败处理）；应用拥有的副作用 vs. 智能体拥有的建议；控制措施——审批门、审计/时间线日志、速率限制、重试、终止开关。
如何判断生效
从未看过代码的评审者仅凭文档就能回答：谁可以做什么、每个密钥在哪里、哪些经过测试，且每份文档与代码一致。
说明
每份生成的文档都在 architecture.md 的“相关文档”区（或仓库已有的文档索引）中添加自身的引用，使文档集保持可发现。不适用的条件文档直接跳过并用一行说明。文档中不保留示例和成品模板——它们描述本系统，而非通用方法。代理运行上下文文件（AGENTS.md 或 CLAUDE.md 中仓库规范的那个）是另一类产物，属于交接步骤（Claude Code 中输入 /ai-shipping:ship-check，Codex 中输入 $ai-shipping:ship-check）生成的指令，而非系统文档，不在此处产出。