backend-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Backend Documentation

后端文档

Create objective Markdown documentation for backend systems from code evidence. Generate only the document type the user selects; do not create a full documentation set unless explicitly requested.

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

Document Selection

文档选择

If the user does not specify the document type, ask them to choose one or more:

User need	Template
Architecture and backend design	`templates/architecture-design.md`
Developer onboarding	`templates/developer-onboarding.md`
Gap analysis and improvement opportunities	`templates/gap-analysis.md`
API contracts and endpoint behavior	`templates/api-contracts.md`
Bounded context map and DDD documentation	`templates/bounded-context-map.md`

If the user asks for "backend docs" without a target path, create the selected file under

docs/backend/

using the template name as the filename. If the repository has a stronger docs convention, follow that convention instead.

Argument rules:

Treat
```
--mode
```
as the selected document type.
Treat
```
--backendPath
```
as the backend path, module, bounded context, route group, or scope to inspect.
Treat
```
--outputPath
```
as the requested Markdown destination.
If
```
--mode
```
is missing, infer the document type from the user's wording or ask them to choose.

Selection rules:

Choose
```
bounded-context-map.md
```
when the request mentions bounded context, domain map, subdomain, ubiquitous language, context boundary, DDD mapping, or documentation recommendations for a domain area.
Choose
```
gap-analysis.md
```
when the main outcome is risks, smells, violations, or improvement opportunities, even if DDD is one of the lenses.
Choose
```
architecture-design.md
```
when the main outcome is how the backend is structured or why it is designed that way.
Ask a clarifying question only when two document types would produce materially different outputs and the prompt does not imply a stronger reader need.

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

用户需求	模板路径
架构与后端设计	`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
```
。
只有当两种文档类型会产生实质性不同的输出，且提示未明确读者需求时，才需要提出澄清问题。

Workflow

工作流程

Step 1: Confirm Scope

步骤1：确认范围

Identify the target backend, module, service, bounded context, or route group. If the request is broad, document only the highest-value slice first and note what remains out of scope.

Capture:

Document type and target reader.
Target path or docs convention.
Backend stack and runtime if discoverable.
Whether the document should describe current state, proposed design, or both.

确定目标后端、模块、服务、限界上下文或路由组。如果请求范围较广，请先仅记录最高价值的部分，并注明未涵盖的内容。

记录以下信息：

文档类型与目标读者。
目标路径或文档约定。
可发现的后端技术栈与运行时环境。
文档应描述当前状态、拟议设计，还是两者兼具。

Step 2: Discover Rules and Existing Docs

步骤2：发现规则与现有文档

Read

references/discovery-workflow.md

, then inspect project rules before reading implementation details.

Prioritize:

Project instructions:

AGENTS.md

CLAUDE.md

.cursor/rules/

.windsurf/rules/

CONTRIBUTING.md

Existing docs:
```
docs/
```
, ADRs, RFCs, architecture notes, onboarding docs.
Code contracts: route definitions, schemas, generated OpenAPI setup, database schemas, migrations, jobs, queues, integrations, tests.

If project rules conflict with this skill, project rules win.

阅读

references/discovery-workflow.md

，然后在查看实现细节之前先检查项目规则。

优先查看：

项目说明文档：

AGENTS.md

、

CLAUDE.md

、

.cursor/rules/

、

.windsurf/rules/

、

CONTRIBUTING.md

。

现有文档：
```
docs/
```
、ADRs、RFCs、架构说明、入职文档。
代码契约：路由定义、模式、生成的OpenAPI配置、数据库模式、迁移脚本、任务、队列、集成、测试。

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

Step 3: Gather Evidence From Code

步骤3：从代码中收集证据

Trace the backend from entry points to behavior. Use file references rather than pasting large code blocks.

Look for:

App bootstrapping, dependency injection, routing, middleware, auth, and tenancy.
Controllers, handlers, use cases, services, domain models, repositories, data access, and external clients.
API request and response schemas, error shapes, status codes, generated documentation, and client contracts.
Database tables, relationships, migrations, transactions, backfills, and unsafe migration patterns.
Background jobs, webhooks, queues, event flows, scheduled tasks, retries, idempotency, and failure handling.
Tests, observability, runbooks, feature flags, rollback paths, and operational risks.

Document facts as "Observed" and label conclusions as "Inference" when they are not directly stated in code or docs.

从入口点到行为追踪后端流程。使用文件引用而非粘贴大段代码块。

重点关注：

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

将事实记录为“已观测”，当结论未在代码或文档中直接说明时，标记为“推断”。

Step 4: Load Only Relevant References

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

Use progressive disclosure:

For documentation structure and brevity, read
```
references/documentation-principles.md
```
.
For backend evidence collection and source-skill routing, read
```
references/source-skill-map.md
```
.
For architecture, API, DDD, coupling, data, and quality checks, read
```
references/backend-quality-lenses.md
```
.
For Hono, Zod/OpenAPI, Drizzle, schema validation, generated API docs, or migration evidence, read
```
references/framework-contract-notes.md
```
.
For the selected document shape, read only the matching template in
```
templates/
```
.

采用渐进式披露方式：

为保证文档结构简洁，阅读
```
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/
```
中的对应模板。

Step 5: Write the Markdown Document

步骤5：编写Markdown文档

Use the selected template as the structure. Keep the document compact and useful to the target reader.

Each generated document should:

Start with scope, audience, and last-reviewed date.
Cite concrete code or docs evidence with file paths and line numbers when available.
Separate current state from recommendations.
Prefer tables for inventories, risks, APIs, gaps, and next actions.
Include diagrams only when they clarify relationships or runtime flow.
Mark unknowns and assumptions instead of inventing missing details.
End with a short maintenance note explaining when the document should be updated.

以所选模板为结构。保持文档简洁且对目标读者有用。

每份生成的文档应包含：

开头注明范围、受众和最后审核日期。
尽可能引用具体的代码或文档证据，包括文件路径和行号。
区分当前状态与建议内容。
优先使用表格展示清单、风险、API、差距和下一步行动。
仅在图表能明确说明关系或运行时流程时才包含图表。
标记未知内容和假设，而非编造缺失的细节。
结尾添加简短的维护说明，解释文档应何时更新。

Step 6: Validate Before Finishing

步骤6：完成前验证

Before final response:

Re-read the generated or edited document.
Check that the selected template was followed.
Check that every non-obvious claim has evidence or is labeled as inference.
Check that no unrelated templates were generated.
Check links and file paths.
If validation commands exist for docs formatting or markdown linting, run the project-preferred command.

在最终响应前：

重新阅读生成或编辑的文档。
检查是否遵循了所选模板。
检查每个非显而易见的主张是否有证据支持或标记为推断。
检查是否未生成无关模板。
检查链接和文件路径。
如果存在文档格式或Markdown校验的验证命令，请运行项目首选的命令。

Output Rules

输出规则

Write in the user's language unless the repository has a documented docs language.
Use concise technical prose. Avoid promotional language and generic claims.
Do not duplicate large source code blocks. Link to source paths instead.
Do not silently create ADRs, RFCs, or TDDs unless the user selected that form or the repository convention requires it.
Do not implement backend changes while documenting. If gaps are found, record them as recommendations.

使用用户的语言编写，除非仓库有明确的文档语言约定。
使用简洁的技术语言。避免宣传性语言和通用声明。
不要复制大段源代码。改为链接到源文件路径。
除非用户选择该格式或仓库约定要求，否则不要静默创建ADRs、RFCs或TDDs。
编写文档时不要实施后端变更。如果发现差距，将其记录为建议。

Examples

示例

Architecture and Design

架构与设计

User says: "Document the backend architecture for the billing service."

Action: Select

templates/architecture-design.md

, inspect project rules and billing code, map components and runtime flows, then write one Markdown document with current architecture, decisions, risks, and improvement opportunities.

用户说：“记录计费服务的后端架构。”

操作：选择

templates/architecture-design.md

，检查项目规则和计费代码，绘制组件和运行时流程，然后编写一份包含当前架构、决策、风险和改进机会的Markdown文档。

Onboarding

入职指南

User says: "Create onboarding docs so a new backend dev can understand this API."

Action: Select

templates/developer-onboarding.md

, identify setup commands and core flows from project docs and code, then write a practical guide that gets the reader from local setup to safe first contribution.

用户说：“创建入职文档，让新的后端开发者能理解这个API。”

操作：选择

templates/developer-onboarding.md

，从项目文档和代码中识别设置命令和核心流程，然后编写一份实用指南，帮助读者从本地环境设置到安全完成首次贡献。

Gap Analysis

差距分析

User says: "Find backend documentation gaps and architecture smells in this module."

Action: Select

templates/gap-analysis.md

, apply project rules plus DDD, coupling, API, data, and testing lenses, then produce prioritized findings with evidence, severity, and next actions.

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

操作：选择

templates/gap-analysis.md

，应用项目规则以及DDD、耦合、API、数据和测试维度，生成带有证据、严重性和下一步行动的优先级发现结果。

Bounded Context Map

限界上下文映射图

User says: "Map the auth bounded context and recommend backend docs we should add."

Action: Select

templates/bounded-context-map.md

, apply the domain-analysis, tactical-DDD, coupling, API, data, and project-rule lenses, then produce one context map with boundaries, relationships, model ownership, risks, unknowns, and documentation recommendations.

用户说：“绘制认证限界上下文，并推荐我们应添加的后端文档。”

操作：选择

templates/bounded-context-map.md

，应用领域分析、战术DDD、耦合、API、数据和项目规则维度，生成一份包含边界、关系、模型所有权、风险、未知内容和文档建议的上下文映射图。