/document-app 逆向工程指南：为 AI 编写的代码库生成可审查的系统文档（pm-ai-shipping）-酒店常州论坛

/document-app 逆向工程指南：为 AI 编写的代码库生成可审查的系统文档（pm-ai-shipping）

【免费下载链接】pm-skillsPM Skills Marketplace: 100+ agentic skills, commands, and plugins — from discovery to strategy, execution, launch, and growth.项目地址: https://gitcode.com/GitHub_Trending/pm/pm-skills

导读

AI 代理写代码很快，但从不留下"意图"记录——系统应该做什么、谁能做什么、密钥存在哪里、哪些规则真正被验证。/document-app是 pm-skills 仓库中pm-ai-shipping（AI Shipping Kit）插件的核心命令：它把一套 AI 编写的（vibe-coded）代码库逆向工程成评审者与审计者需要的系统文档，落在/documentation/目录下。读完本文，你将掌握该命令的调用方式、四步工作流、核心文档与条件文档的完整清单与每个文档必须捕获的内容，以及它与/derive-tests、/security-audit-static、/performance-audit-static、/ship-check之间的调用关系——这套文档是所有后续审计的"意图基线"。

命令定位：为什么 AI 编写的应用需要"可审查性"

在 pm-ai-shipping/README.md 中，这个插件的定位讲得很直白：AI 代理写代码快，但没有留下意图的记录——系统应该做什么、谁被允许做什么、密钥在哪里、哪些规则真正被验证。没有这份记录，任何人类评审者和任何审计代理都无法判断代码是否可以安全发布。/document-app正是恢复这种"可审查性"（reviewability）的第一步：它把系统文档化，然后由审计类命令去检查文档所说的与代码实际所做之间的差距——这正是通用扫描器发现不了的那类 bug，因为它们没有意图模型。

该命令的 frontmatter（document-app.md）对此做了精确概括：

description: Reverse-engineer an AI-built codebase into the system documents reviewers and auditors need — a core set (architecture, flows, permissions, variables) plus conditional docs (emails, cron, SEO, automation) when they apply argument-hint: "<repo path or area; defaults to the whole repository>"

argument-hint揭示了该命令的第一条使用规则：它接受一个可选的仓库路径或区域参数，缺省时作用于整个仓库。这与同插件其他命令（/ship-check、/derive-tests、/security-audit-static、/performance-audit-static）的参数约定完全一致。

调用方式

/document-app与插件内其他命令一样，既可以用带插件前缀的长形式，也可以用短形式。根据 pm-ai-shipping/README.md 的说明，每个命令可用/pm-ai-shipping:<command>或短/command形式触发：

# 缺省参数：文档化整个仓库 /document-app # 只文档化指定区域 /document-app supabase/functions /document-app the backend

使用要点：

参数缺省即全仓库：优先处理后端代码、认证、数据访问、后台任务，以及任何"发送、调度或暴露数据"的部分。
参数可为自然语言区域：the backend这类描述性参数会被理解为要文档化的范围，命令会据此收敛审查范围。
这是一个命令而非技能：命令（Commands）是用户触发的端到端工作流，内部会链式调用一个或多个技能（Skills）。/document-app在 Step 2 明确要求应用shipping-artifacts技能——其完整定义见 shipping-artifacts/SKILL.md，下文会深入展开。

四步工作流

Step 1：界定范围（Scope）

审计$ARGUMENTS。若参数为空，则文档化整个仓库，并优先处理以下高价值区域：

后端代码
认证（auth）
数据访问层
后台任务（background jobs）
任何会发送、调度或暴露数据的代码

这一步的价值在于：范围界定决定了文档化投入的回报率。AI 编写的应用里，权限与副作用集中在这几类代码中，它们是审计者最需要意图对照的地方。

Step 2：逆向工程文档（Reverse-Engineer the Docs）

应用shipping-artifacts技能，以代码为唯一事实来源（reading the code as the source of truth），在/documentation/目录下生成适用的文档。文档集合不是固定清单，而是"核心 + 条件"两层的结构：

核心文档（Core，始终生成）

文件	一句话定位	必须捕获的内容
`architecture.md`	系统是什么、各部分如何衔接	产品概述与关键假设、技术栈、认证/会话/claims 端到端流向、信任边界（如 service-role vs. client）、"已知风险/假设"清单（每项都要有代码出处，而非通用清单）、指向其他所有文档的 "Related Documents" 索引
`flows.md`	权限与副作用真正被行使的旅程	每个关键流程记为"参与者 + 前置条件 + 成功结果"；UI → 服务端 → 数据 → 任务 → 外部服务 → 代理的逐步序列；每个受保护步骤的授权检查（哪个 claim/role/scope、作用于哪个资源、预期的拒绝场景）；信任边界穿越点（浏览器→服务端、服务端→外部服务、任务→应用、代理→工具、webhook→应用）；每步产生的状态变更与副作用（写入、邮件入队、任务触发、外部调用）
`permissions.md`	谁被允许做什么	角色/claims；scope 从何处派生（token vs. DB）；资源 × 操作 × 角色矩阵；哪些表有行级安全（RLS）、哪些依赖代码强制检查
`variables.md`	配置与密钥，映射到风险	Name · used-by · scope（server/client）· source · rotation · risk 的表格；明确确认没有密钥被打进客户端；一份上线前检查清单

条件文档（Conditional，仅在能力存在时生成）

文件	存在条件	必须捕获的内容
`emails.md`	应用会发送事务性或自动化邮件	队列 → 处理器 → 邮件服务商的路径；模板及其接受的变量；重试/退避（retry/backoff）行为；发送失败时去哪里排查
`cron.md`	存在定时或后台任务	清单表（任务 → 调度 → 函数 → 密钥 → 限额 → 重试）；每个任务如何保持幂等；内部调用如何鉴权；去哪里查看最近运行记录
`seo.md`	存在公开可索引或面向 bot 的路由	预览方案（静态 meta / prerender / edge HTML）；route → 是否需要 SEO → 仅公开数据的表格；动态元数据如何清洗；bot 与真实用户如何分流
`automation.md`	应用内嵌 AI 代理、LLM 工作流、工具调用、webhook 或外部自动化	按自动化/代理逐项记录：触发方式 + 所有者 + 自动运行还是需审批；可读取的输入与可调用的确切工具/API 清单（工具面本身就是一道硬护栏）；steering（提示词）与非提示词硬护栏分别在哪里；返回应用侧的输出契约（schema、校验、失败处理）；应用拥有的副作用 vs 代理提出的建议；以及控制项——审批门禁、审计/时间线日志、限流、重试、紧急开关（kill switch）

诚实的映射规则（这是本命令最重要的纪律）：

对每个不适用的条件文档，在architecture.md里用一行说明，例如 "No scheduled work — nocron.md."，而不是编造一个空文档。可审查性来自诚实的映射，"我们不做 X"本身也是映射的一部分。
对当前状态保持"残酷诚实但不偏执"（brutally honest without being paranoid）——任务是画一张准确的地图，不是开一张健康证明。
每产出一份文档，就在architecture.md的 "Related Documents" 中加入指向它的引用，保证整个集合可被发现。
不要在文档里包含"updated date"行——文件的历史记录本身就是事实来源。
文档描述的是这个具体系统，把通用理论和成品模板排除在外。

tests.md的归属：测试覆盖地图（test-coverage map）由/derive-tests单独产出，而非/document-app——因为它是从其他文档和现有测试套件推导出来的验证映射，不是对某个子系统的描述。/document-app的产出是意图的一半，/derive-tests产出验证的一半，二者合起来才是 "documented == implemented"（文档化即已实现）的完整闭环。

Step 3：汇报（Report）

总结三件事：

创建或更新了什么（created or updated）；
跳过了什么以及为什么（skipped and why）；
代码过于模糊、无法自信文档化的缺口——这些正是要最先修复的东西。

Step 3 的潜台词值得强调：文档化的过程本身就是一个发现过程。如果某段代码连意图都读不出来，它就是对评审和审计的最大阻碍，应当被列为最高优先级修复项。

Step 4：提供后续步骤（Offer Next Steps）

命令结束时给出可选的后续建议，形成与其他命令的调用链：

"Want me toderive a test-coverage map(/derive-tests) so each documented rule has a verification plan?"
"Want me torun a security auditnow that the intended behavior is documented?"
"Should Icheck for performance issues— over-fetching, missing indexes, caching?"
"Want me torun/ship-checkto wire agent context and produce a full shipping packet?"

命令背后的技能支撑：shipping-artifacts

/document-app的 Step 2 直接调用 shipping-artifacts 技能。该技能是整套文档标准的权威定义，其 frontmatter 说明了适用场景：

Use when documenting a codebase for handoff, mapping user journeys and trust-boundary crossings, planning test coverage, or preparing for a security or performance audit.

技能中定义的读者模型是理解这套文档标准的关键：文档写给两类读者——人类评审者和下一个 AI 编码代理。它们构成每次后续审计的"意图状态"（intended-state）基线——安全或性能审查的质量，取决于它能拿代码去对照的那份意图文档。

技能还明确了几个容易被忽略的边界：

flows.md 的反 PRD 规则：不触碰权限、数据完整性、外部副作用、金钱、隐私或运营安全的流程，不属于 flows.md。这是安全/运营地图，不是功能规格。
tests.md 的三段式诚实结构：必须分成"现有覆盖"（今天就在仓库里的测试，每条绑定它钉住的规则）/"建议测试"（尚未编写、标注测试类型）/ "缺口"（完全没有验证的文档化规则，按跨越它们暴露的东西排序）三节，且明确"建议 ≠ 现有"——避免地图错误地显示全绿。
automation.md 是 AI 应用中风险最高的面：它让隐藏的自动化路径可见，并划清"代理提议什么"与"应用强制什么"的界限。

与审计类命令的调用关系：文档是审计的前提

/document-app在整个 AI Shipping Kit 中处于链首位置。从 ship-check.md 的六步流水线可以看到清晰的依赖关系：

Step 1 Document：确保系统文档存在且最新——缺了就运行/document-app；
Step 2 Wire agent context：从系统文档派生CLAUDE.md（及指向它的精简AGENTS.md）——这是操作指令（instructions），不是系统描述（description），与/document-app的产物是两种不同的工件；
Step 3 Security audit：运行/security-audit-static，用intended-vs-implemented技能对照permissions.md、flows.md、architecture.md找出代码偏离点；
Step 4 Performance audit：运行/performance-audit-static；
Step 5 Derive tests：运行/derive-tests把文档化规则与审计暴露的缺口变成覆盖地图；
Step 6 Compile packet：汇总成 shipping packet。

/security-audit-static（security-audit-static.md）的第 3 步同样明确写道：对照/documentation/*.md应用 intended-vs-implemented 技能，"一条被文档化但未在代码中实施的规则本身就是一条发现（finding）"；如果文档缺失，就先推荐/document-app——意图审计需要有记录在案的意图。

/derive-tests（derive-tests.md）在其"前置条件"一节也强调了同一依赖：测试是从文档推导的，所以文档在先——如果/documentation/*.md缺失或单薄，先运行/document-app；它读取得最重的是flows.md、permissions.md和automation.md。

意图 vs 实现的方法论由 intended-vs-implemented/SKILL.md 提供：lint 工具在真空中扫描代码，只能告诉你代码内部自洽，不能告诉你代码是否做了你想做的——因为它没有你的意图模型。最高价值的安全与正确性 bug 就藏在这个缺口里："一条被文档化但从未被强制实施的权限""一个任何人都能调的 cron-only 端点""一个标注 public-only 却泄漏私有数据的字段"。该方法要求每条发现同时给出：文档化意图（引用文档）+实现现实（引用代码文件与行号）+攻击者与受害者+具体修复。这也反向印证了/document-app的价值：没有先记录意图，整个审计方法论都无从谈起。

使用须知（Notes）

这些文档描述的是这个系统——把通用理论和成品模板排除在外。
写给两类读者：人类评审者和下一个 AI 编码代理。
不要加 "updated date" 行。
代理操作上下文文件（CLAUDE.md/AGENTS.md）在/ship-check交接步骤单独产出——它是由这些文档派生的指令，不是系统文档本身。仓库中的 AGENTS.md 恰好演示了这一分工：它只有一句话，指向 CLAUDE.md 作为唯一事实来源。

实战落地：在你的 AI 代码库上跑一遍

安装插件：按 pm-ai-shipping/README.md 的指引，从 pm-skills marketplace 安装并启用pm-ai-shipping插件，然后即可用/pm-ai-shipping:document-app或短形式/document-app触发。
确定范围：先只文档化最危险区域（如supabase/functions、支付服务）以验证流程，再扩大到全仓库。
检查产出：确认/documentation/下生成了architecture.md、flows.md、permissions.md、variables.md四份核心文档；对照本文的"必须捕获"清单逐项核对；确认不适用的条件文档以一行说明的形式出现在architecture.md中，且每份文档都登记进了 "Related Documents" 索引。
顺势推进：文档就位后，按 Step 4 的建议运行/derive-tests生成测试覆盖地图、/security-audit-static做意图对照审计，或用/ship-check走完整流水线拿到 reviewer-ready 的 shipping packet。

小结

/document-app用一套"核心 + 条件"的文档标准，把 AI 编写的代码库变成可审查、可对照、可交接的状态：核心四件套（architecture / flows / permissions / variables）保证每个可审查的应用都有完整的意图地图，条件四件套（emails / cron / seo / automation）保证映射的诚实性——不适用就明说，绝不编造。它产出的不是"健康证明"，而是"准确地图"；这份地图是/derive-tests、/security-audit-static、/performance-audit-static乃至最终/ship-checkshipping packet 的共同前提。对任何要对 AI 编写的代码负责的 PM 和创始人来说，这是让"到底能不能发布"这个问题第一次变得可回答的起点。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析