backend-docs

后端文档

根据代码证据，为后端系统编写客观的 Markdown 文档。只生成用户选择的文档类型；除非用户明确要求，否则不要创建完整的文档集。

文档选择

如果用户未指定文档类型，请让他们选择一种或多种：

用户需求	模板
架构与后端设计	templates/architecture-design.md
开发者入门	templates/developer-onboarding.md
差距分析与改进机会	templates/gap-analysis.md
API 契约与端点行为	templates/api-contracts.md
限界上下文图与 DDD 文档	templates/bounded-context-map.md

如果用户要求“后端文档”但未提供目标路径，请使用模板名称作为文件名，将所选文件创建在 docs/backend/ 下。如果仓库有更明确的文档规范，则遵循该规范。

参数规则：

• 将 --mode 视为所选文档类型。
• 将 --backendPath 视为要检查的后端路径、模块、限界上下文、路由组或范围。
• 将 --outputPath 视为请求的 Markdown 目标路径。
• 如果缺少 --mode，则根据用户的措辞推断文档类型，或请用户选择。

选择规则：

• 如果请求提到限界上下文、领域图、子域、统一语言、上下文边界、DDD 映射，或针对某个领域的文档建议，请选择 bounded-context-map.md。
• 如果主要目标是识别风险、异味、违规或改进机会，即使将 DDD 作为分析视角之一，也请选择 gap-analysis.md。
• 如果主要目标是说明后端的组织结构或采用该设计的原因，请选择 architecture-design.md。
• 只有当两种文档类型会产生实质不同的输出，且提示未明确体现更优先的读者需求时，才提出澄清问题。

工作流

步骤 1：确认范围

确定目标后端、模块、服务、限界上下文或路由组。如果请求范围较广，请先记录价值最高的部分，并说明哪些内容不在当前范围内。

记录：

• 文档类型与目标读者。
• 目标路径或文档规范。
• 可查明的后端技术栈与运行环境。
• 文档应描述当前状态、拟议设计，还是两者兼有。

步骤 2：了解规则与现有文档

先阅读 references/discovery-workflow.md，再检查项目规则，然后阅读实现细节。

优先检查：

1. 项目说明：AGENTS.md、CLAUDE.md、.cursor/rules/、.windsurf/rules/、CONTRIBUTING.md。
2. 现有文档：docs/、ADR、RFC、架构说明、入门文档。
3. 代码契约：路由定义、架构、生成的 OpenAPI 配置、数据库架构、迁移、作业、队列、集成、测试。

如果项目规则与此技能冲突，以项目规则为准。

步骤 3：从代码收集证据

从入口追踪后端的行为。使用文件引用，而不是粘贴大段代码。

检查：

• 应用引导、依赖注入、路由、中间件、身份验证与租户管理。
• 控制器、处理程序、用例、服务、领域模型、存储库、数据访问与外部客户端。
• API 请求与响应架构、错误格式、状态码、生成的文档与客户端契约。
• 数据库表、关系、迁移、事务、回填以及不安全的迁移模式。
• 后台作业、Webhook、队列、事件流、定时任务、重试、幂等性与故障处理。
• 测试、可观测性、运维手册、功能标志、回滚路径与运营风险。

将事实标注为“观察到”，对于代码或文档未直接说明的结论，则标注为“推断”。

步骤 4：仅加载相关参考资料

采用渐进式披露：

• 关于文档结构和简洁性，请阅读 references/documentation-principles.md。
• 关于后端证据收集和源技能路由，请阅读 references/source-skill-map.md。
• 关于架构、API、DDD、耦合、数据和质量检查，请阅读 references/backend-quality-lenses.md。
• 关于 Hono、Zod/OpenAPI、Drizzle、架构验证、生成的 API 文档或迁移证据，请阅读 references/framework-contract-notes.md。
• 关于选定的文档形式，只阅读 templates/ 中与之匹配的模板。

步骤 5：编写 Markdown 文档

使用选定的模板作为结构。文档应简洁实用，满足目标读者的需求。

每份生成的文档都应：

• 以范围、受众和最近审阅日期开篇。
• 尽可能引用具体的代码或文档证据，并注明文件路径和行号。
• 区分当前状态与建议。
• 优先使用表格列出清单、风险、API、差距和后续行动。
• 仅在有助于阐明关系或运行时流程时添加图表。
• 标明未知项和假设，不要杜撰缺失的信息。
• 以简短的维护说明收尾，解释何时应更新文档。

步骤 6：完成前进行验证

最终回复前：

• 重新阅读生成或编辑后的文档。
• 检查是否遵循选定的模板。
• 检查每项不明显的论断是否有证据支持，或已标明为推断。
• 检查是否未生成无关模板。
• 检查链接和文件路径。
• 如果有用于文档格式检查或 Markdown lint 的验证命令，请运行项目优先使用的命令。

输出规则

• 除非仓库已明确规定文档语言，否则使用用户的语言。
• 使用简洁的技术性文字。避免宣传性措辞和泛泛而谈。
• 不要重复大段源代码；改为链接到源文件路径。
• 除非用户选择了 ADR、RFC 或 TDD 形式，或仓库惯例要求如此，否则不要擅自创建这些文档。
• 编写文档时不要实施后端改动。发现差距时，将其记录为建议。

示例

架构与设计

用户说：“为计费服务编写后端架构文档。”

操作：选择 templates/architecture-design.md，检查项目规则和计费代码，梳理组件和运行时流程，然后编写一份 Markdown 文档，说明当前架构、决策、风险和改进机会。

入门指南

用户说：“创建入门文档，帮助新的后端开发人员了解此 API。”

操作：选择 templates/developer-onboarding.md，从项目文档和代码中找出设置命令和核心流程，然后编写实用指南，帮助读者完成本地设置并安全地进行首次贡献。

差距分析

用户说：“找出此模块的后端文档差距和架构异味。”

操作：选择 templates/gap-analysis.md，结合项目规则以及 DDD、耦合、API、数据和测试视角进行分析，然后按优先级列出发现，注明证据、严重程度和后续行动。

限界上下文图

用户说：“梳理 auth 限界上下文，并建议我们应补充哪些后端文档。”

操作：选择 templates/bounded-context-map.md，结合领域分析、战术 DDD、耦合、API、数据和项目规则等视角进行分析，然后生成一份上下文图，说明边界、关系、模型归属、风险、未知项和文档建议。