为 AI 生成的代码库补齐可审查文档集：在交接…

当需要让 AI 快速生成的（vibe-coded）应用在交付、安全审计或性能审查前变得可被人类和下一个 AI 代理审查时，用一套核心文档加按需条件文档来还原系统意图。

适用场景

解决思路

1. 在仓库根目录建立 documentation/ 目录存放文档，面向两类读者写作：人类审查者和下一个 AI 编码代理；这些文档是后续审计的「意图状态」基准。
2. 把文档集组织为「核心文档 + 条件文档」：核心文档每个可审查应用都必须产出；条件文档只在应用确实具备该能力时才加入。
3. 若某条件能力不存在，在 architecture.md 中写一行说明（如「No scheduled work — no cron.md.」），不要编造空文档；诚实的地图包含「我们不做 X」。
4. 大多数文档由 /document-app 从代码反向工程得出；唯一例外是 tests.md，它由 /derive-tests 从其他文档派生，是验证地图而非子系统描述。
5. 保持诚实：目标是准确的地图，不是健康证明；每份文档简短、以表格和要点为主，跳过通用理论。
6. 核心文档 1 —— architecture.md：捕获产品概览与关键假设、技术栈、auth/session/claims 的端到端流转、信任边界（如 service-role vs. client）、简短的 Known risks / assumptions 列表（每条须有代码出处，而非通用清单）、以及所有其他文档的 Related Documents 索引；它是根文档，其他文档都从这里交叉引用。
7. 核心文档 2 —— flows.md：把每个承重流程写成 actor + precondition + success outcome；记录 UI → server → data → jobs → providers → agents 的逐步序列；记录每个受保护步骤的 authz 检查（哪个 claim/role/scope、作用于哪个资源、以及预期的拒绝情形）；记录信任边界穿越（browser→server、server→provider、job→app、agent→tool、webhook→app）；记录每步造成的状态变更与副作用（写入、排队邮件、触发任务、外部调用）。
8. flows.md 的反 PRD 规则：不涉及权限、数据完整性、外部副作用、金钱、隐私或运营安全的流程不要写进去；这是安全/运营地图，不是功能规格。
9. 核心文档 3 —— permissions.md：捕获角色/claims、scope 的来源（token vs. DB）、资源 × 操作 × 角色矩阵、哪些表有 row-level security、哪些依赖代码强制检查；它是访问控制审计对比代码的静态基准，flows.md 展示其动态运行。
10. 核心文档 4 —— variables.md：捕获 Name · used-by · scope（server/client）· source · rotation · risk 表格；明确确认没有 secret 被打包到客户端；附上线前检查清单；用于识别 secret/PII 泄露面和事件响应时的轮换计划。
11. 核心文档 5 —— tests.md：分三个清晰分隔的部分，避免地图误读为全绿——Existing coverage（今天仓库中已有的测试，每条绑定其固定的规则）、Proposed tests（尚未编写的建议用例，按测试类型标注：automated unit/integration · guarded live · manual review）、Gaps（完全无验证的已记录规则，按被突破后的暴露程度排序）。
12. tests.md 每行携带：use-case → rule → expected behavior（含拒绝/负向情形）→ evidence source（doc + code）→ status（existing / proposed / none）；并注明哪些检查是 CI 必需、会 gate 合并到 main。
13. 条件文档 6 —— emails.md：仅当应用发送事务性或自动化邮件时包含；捕获 queue → processor → provider 路径、模板及其接受的变量、重试/退避行为、发送失败时去哪里排查；用于发现未校验的模板输入和 PII 暴露边界。
14. 条件文档 7 —— cron.md：仅当存在定时或后台任务时包含；捕获清单表（job → schedule → function → secrets → limits → retry）、每个任务如何保持幂等、内部调用如何认证、在哪里查看最近运行；用于发现可伪造的触发器和无界后台任务。
15. 条件文档 8 —— seo.md：仅当存在公开/可索引或面向 bot 的路由时包含；捕获预览方案（static meta / prerender / edge HTML）、route → needs-SEO → public-data-only 表格、动态元数据如何净化、bot 与人类的路由区分；用于发现 public-data-only 违规和 bot 路由上的元数据注入。
16. 条件文档 9 —— automation.md：仅当应用嵌入 AI 代理、LLM 工作流、tool-calling、webhook 或外部自动化时包含；对每个自动化/代理捕获：触发条件 + 负责人 + 是自动运行还是仅批准后运行；可读取的输入和可调用的确切工具/API（工具面本身就是硬护栏）；steering（提示词）与非提示词硬护栏分别在哪里；回传给应用的输出契约（schema、校验、失败处理）；应用拥有的副作用 vs. 代理拥有的建议；以及控制措施——审批门、审计/时间线日志、速率限制、重试、kill switch。
17. 每份产出的文档都在 architecture.md 的 Related Documents 一节中登记自身引用，保持文档集可发现。
18. 跳过不适用的条件文档，并用一行说明，而不是编造内容。
19. 文档中不要放示例和成品模板——它们描述的是这个系统，不是通用方法。
20. 代理操作上下文文件（CLAUDE.md / AGENTS.md）是另一种产物——是从这些文档派生的指令，不是系统文档；它在交接步骤由 /ship-check 产出，不在这里产出。
21. tests.md 由 /derive-tests 产出，其余由 /document-app 产出。
22. 不要包含「更新日期」行；文件历史本身就是事实来源。

适用边界 · 注意事项

• 应用尚未具备对应能力时，不要为条件文档（emails.md、cron.md、seo.md、automation.md）编造内容，只需在 architecture.md 中写一行说明。
• 不要把不涉及权限、数据完整性、外部副作用、金钱、隐私或运营安全的流程写进 flows.md——那是功能规格而非安全/运营地图。
• 不要把 CLAUDE.md / AGENTS.md 当作系统文档写在这里，它是由这些文档派生的代理指令，在交接步骤由 /ship-check 产出。