shipping-artifacts

交付材料：让 AI 构建的代码可供审查的文档

目的

AI Agent 编写代码很快，但不会留下关于意图的持久记录——系统应该做什么、谁有权执行哪些操作、密钥存放在哪里、哪些规则经过了实际验证。没有这份记录，人类（以及审计 Agent）都无法判断代码是否可以安全交付。本技能定义了一小套文档，用于恢复代码的可审查性。

这些文档面向两类读者：人工审查者和下一个 AI 编码 Agent。它们是后续每次审计中预期状态的组成部分——安全或性能审查的质量，取决于它能否将代码与预期状态进行比较。

位置和名称：以代码库的设置为准

本插件中的所有位置、文件名和文档格式约定都是默认设置。宿主代码库自身的设置优先。在编写任何内容之前（系统文档、覆盖率映射或审计报告），先查找以下设置：

1. Agent 指令 — AGENTS.md、CLAUDE.md，以及它们导入或指向的任何文件。它们通常会指定文档文件夹、其中的文件、每份文档的维护者，以及日期的记录方式。
2. 文档位置 — 现有的 docs/、documentation/ 或类似文件夹。
3. 现有的等效文档 — 已覆盖以下某个文件所涵盖内容的文档，无论其名称是什么（ARCHITECTURE.md、docs/security.md、docs/env.md）。应根据涵盖的内容来匹配，而不是根据文件名。
4. 现有的测试覆盖率映射 — 将行为映射到覆盖这些行为的测试的文件，例如 docs/test-coverage.md。应根据涵盖的内容来匹配：描述代码库如何进行测试的 TESTS.md 或 testing.md 属于测试方法文档，而不是覆盖率映射。
5. 报告位置 — 代码库现有的审计或审查结果存放位置。

然后：

• 遵循查找到的设置。 将文档写入代码库的文档位置；如果已有等效文档，则更新它，而不是创建平行文件；并沿用其命名和日期约定。每份文档必须包含的内容不变，只有存放位置和名称可以不同。如果 Agent 指令规定了文档的维护方式或维护者，也要遵循。
• 仅在代码库没有相关设置时使用插件默认值： 在代码库根目录的 documentation/ 中存放文档，使用下方的文件名，将覆盖率映射存放在 documentation/tests.md，将报告存放在 reports/<name>_{timestamp}.md，且不添加“更新日期”行（文件历史记录才是事实依据）。
• 说明采用了哪种设置。 输出中列出所有写入的位置和文件，并注明每项遵循的是代码库设置还是插件默认值。
• 绝不要创建仅大小写不同于现有文件名的文件——例如，在 TESTS.md 旁创建 tests.md，或在 architecture.md 旁创建 Architecture.md。在 Windows 和 macOS 上，这些是同一个文件，写入时会覆盖；在其他系统上，它们会成为两个文件，并在下次检出时发生冲突。创建文件前要进行不区分大小写的检查。如果现有文件涵盖相同内容，就使用该文件。如果涵盖的是其他内容（例如，描述测试方法而非覆盖率映射的 TESTS.md），则不要写入其中：改用代码库中真正等效的文件；如果没有，则选用一个不会产生冲突的名称。

在本插件中，architecture.md 或 tests.md 之类的名称，始终指该文档本身，无论代码库用什么名称、将其存放在何处。

该文档集的组织方式

该文档集不是固定列表，而是由一组小型核心文档和仅在具备相应能力时才添加的条件文档组成。

• 核心文档——每个可审查的应用都有这些方面，因此始终要生成。
• 条件文档——仅当应用确实具备相应能力时才纳入。如果不具备，则在 architecture.md 中写一行说明（“没有计划任务——不需要 cron.md。”），而不是凭空创建空文档。可审查性源自如实呈现架构图，而“我们不做 X”也是架构图的一部分。
• 大多数文档都由 /document-app 根据代码逆向整理。唯一的例外是 tests.md：它由 /derive-tests 根据其他文档整理而成，是验证图，而不是对某个子系统的描述。

要直面当前状态，如实说明，但不必草木皆兵。任务是准确呈现现状，而不是证明一切安好。每份文档都应简短，以表格和项目符号为主，并略去泛泛的理论。

核心文档

每项包括：默认文件名 · 一句话说明用途 · 必须记录的内容 · 审阅者如何使用。

1. architecture.md — 系统是什么，以及各部分如何协同运作。

   • 必须记录：产品概述和关键假设；技术栈；身份验证、会话和声明如何端到端流转；信任边界（例如，服务角色与客户端之间）；简短的 已知风险／假设 列表（每项都要注明其在代码中的对应位置，不能只是通用检查清单）；以及包含所有其他已生成文档的“相关文档”索引。
   • 审阅者用途：根文档——其他所有内容都从这里交叉引用。

2. flows.md — 实际会执行权限检查和产生副作用的流程。

   • 必须记录：每个关键流程的参与者、前置条件和成功结果；贯穿 UI → 服务器 → 数据 → 任务 → 提供方 → Agent 的逐步顺序；每个受保护步骤的 授权检查（使用哪个声明／角色／范围、针对哪个资源，以及预期的 拒绝 情况）；跨越信任边界的情况（浏览器→服务器、服务器→提供方、任务→应用、Agent→工具、webhook→应用）；每个步骤造成的状态变化和副作用（写入、排队发送的电子邮件、触发的任务、出站调用）。
   • 审阅者用途：展示静态 permissions.md 矩阵无法呈现的运行时视图——授权在何处、以何种顺序执行，以及哪些地方可能跳过授权检查。
   • 反 PRD 规则： 不涉及权限、数据完整性、外部副作用、资金、隐私或运行安全的流程不应列在这里。这是安全／运维地图，而非功能规格说明。

3. permissions.md — 谁可以执行哪些操作。

   • 必须记录：角色／声明；范围的来源（令牌还是数据库）；资源 × 操作 × 角色矩阵；哪些表启用了行级安全策略，哪些依赖代码强制执行检查。
   • 审阅者用途：访问控制审计对照代码检查的基准。flows.md 展示这些权限如何在流程中生效；本文档是静态参考。

4. variables.md — 配置和密钥，以及对应的风险。

   • 必须记录：名称 · 使用方 · 范围（服务器／客户端） · 来源 · 轮换方式 · 风险的表格；明确确认没有任何密钥会打包到客户端；上线前检查清单。
   • 审阅者用途：呈现密钥／PII 泄露面，以及事件响应期间的轮换计划。

5. tests.md — 验证地图：哪些已记录规则经过实际检查，哪些只是建议，哪些完全没有检查。

   • 必须分成三个明确的部分，以免地图造成一切均已通过的假象：
     • 现有覆盖 — 当前仓库中已有的测试，每项都关联到其验证的规则（确保地图反映现实，而非愿望清单）。
     • 建议测试 — 尚未编写的推荐用例，并注明测试类型（自动化单元／集成测试 · 受保护的实时测试 · 人工审查）。
     • 缺口 — 完全没有验证的已记录规则，按跨越相关边界可能造成的后果排序。
   • 每一行都包括：用例 → 规则 → 预期行为（包括拒绝／否定情况）→ 证据来源（文档 + 代码）→ 状态（现有／建议／无）。还需注明仓库门禁要求哪些检查：按仓库声明的门禁策略（例如，本地命令加人工放行）；如果未声明要求，则注明负责阻止合并到 main 的 CI 检查。
   • 审阅者用途：将“已记录 == 已实现”落实为可操作的形式——它展示其他文档声称的每条规则，今天是否已有测试验证、仅有建议，还是尚未验证。
   • 由 /derive-tests（而非 /document-app）生成，因为它是根据其他文档和现有测试套件推导出来的，而非读取某个子系统得出。

条件文档（仅在具备相应功能时纳入）

6. emails.md — 系统发送的所有通知。仅当应用会发送事务性或自动化电子邮件时纳入。

   • 必须记录：队列 → 处理器 → 提供商的路径；模板及其接受的变量；重试／退避行为；发送失败时的排查位置。
   • 审查用途：发现未经验证的模板输入和个人身份信息（PII）暴露边界。

7. cron.md — 所有计划任务及其安全运行方式。仅当存在计划任务或后台任务时纳入。

   • 必须记录：任务 → 计划 → 函数 → 密钥 → 限制 → 重试的清单表；每项任务如何保持幂等；内部调用如何进行身份验证；查看最近运行记录的位置。
   • 审查用途：发现可伪造的触发方式和不受限的后台任务。

8. seo.md — 单页应用如何处理 SEO 和社交预览。仅当存在公开／可编入索引或面向机器人的路由时纳入。

   • 必须记录：预览方案（静态元数据／预渲染／边缘 HTML）；路由 → 是否需要 SEO → 仅公开数据的表格；动态元数据如何清理；机器人与人类用户的路由方式。
   • 审查用途：发现仅公开数据方面的违规，以及机器人路由上的元数据注入。

9. automation.md — 嵌入式 Agent 和其他自动化路径。仅当应用嵌入 AI Agent、大模型工作流、工具调用、Webhook 或外部自动化时纳入。

   • 必须按每项自动化／Agent 记录：触发条件 + 负责人 + 自动运行还是仅在批准后运行；它可能读取的输入以及它可以调用的确切工具／API（工具可用范围本身就是严格的防护措施）；引导所在的位置（提示词）与非提示词硬性防护措施；返回应用的输出约定（架构、验证、失败处理）；应用负责的副作用与 Agent 负责的建议；以及各项控制措施——审批关卡、审计／时间线日志、速率限制、重试、紧急停用开关。
   • 审查用途：让隐藏的自动化路径清晰可见，并划清 Agent 提议什么与应用强制执行什么之间的界限——这是现代 AI 构建应用中风险最高的部分。

说明

• 每个生成的文档都应在 architecture.md 的“相关文档”部分（或仓库已有的文档索引）中添加指向自身的引用，以便查找整套文档。
• 跳过不适用的条件文档，并用一行说明原因，不要编造内容。
• 不要在这些文档中加入示例或完成的模板——这些文档描述的是这个系统，而不是通用方法。
• Agent 运行上下文文件（AGENTS.md 或 CLAUDE.md，以仓库结构中的规范文件为准）是另一种产物——它是根据这些文档整理出的指令，而非系统文档。它会在交接步骤由 /ship-check 生成，该步骤遵循仓库结构，不在此处生成。
• tests.md 由 /derive-tests 生成；其余文档由 /document-app 生成。
• 遵循仓库的日期约定。如果没有约定，不要添加“更新日期”行；文件历史才是事实依据。