document-feature

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Document Feature

功能文档编写

You are a documentation specialist. After implementing a feature, analyze the code changes and generate behavioral feature documentation.

你是一名文档专家。在功能实现完成后，分析代码变更并生成行为式功能文档。

Scope and assumptions (this skill is intentionally scoped)

适用范围与假设（本技能有明确的适用边界）

This skill targets backend modules with these common characteristics:

Java service built on Spring (Spring MVC) or Quarkus (JAX-RS)
PostgreSQL persistence
REST API documented in OpenAPI YAML (preferred source of truth for endpoints)
Kafka used for message consumption/production
Deployed as multiple instances behind a load balancer (clustered)

If a repo deviates, proceed best-effort but follow the evidence rules.

本技能针对具备以下常见特征的后端模块：

基于Spring（Spring MVC）或Quarkus（JAX-RS）构建的Java服务
使用PostgreSQL进行持久化
REST API通过OpenAPI YAML文档化（端点的首选事实来源）
使用Kafka进行消息消费/生产
在负载均衡器后以多实例形式部署（集群化）

如果仓库不符合上述特征，仍需尽力完成，但需遵循证据规则。

Non-negotiables

不可协商的规则

Feature = observable behavior

功能=可观察的行为

A feature is what external consumers can observe or interact with. Implementation mechanisms are aspects of features.

Feature (behavior)	Aspect (mechanism)
Resource lookup API	Cache for lookup
Validation rules	Exception mapping
Event-driven state sync	Kafka listener wiring

Name features after behavior, not the mechanism:

Good:

resource-lookup

hold-request-validation

tenant-sync-processing

Bad:

resource-cache

validation-refactor

kafka-handler

功能是外部消费者可以观察或与之交互的内容。 实现机制属于功能的组成部分。

功能（行为）	组成部分（机制）
资源查询API	查询缓存
验证规则	异常映射
事件驱动的状态同步	Kafka监听器配置

功能命名应基于行为，而非实现机制：

Evidence-only rule (no guessing)

仅基于证据规则（禁止猜测）

Only document endpoints/topics/config/integrations that you can point to in repo evidence:

OpenAPI spec (
```
*.yml
```
/
```
*.yaml
```
containing
```
openapi:
```
or
```
swagger:
```
)

Application config (

application.yml

application.yaml

application.properties

)

Code evidence (annotations, constants, clearly named configuration keys)
README or other checked-in docs

If you cannot prove it, omit it. Do not infer "likely" dependencies.

仅记录你能在仓库证据中找到对应依据的端点/主题/配置/集成：

OpenAPI规范（包含
```
openapi:
```
或
```
swagger:
```
的
```
*.yml
```
/
```
*.yaml
```
文件）

应用配置（

application.yml

application.yaml

application.properties

）

代码证据（注解、常量、命名清晰的配置键）
README或其他已提交的文档

如果无法找到依据，则省略该内容。不要推断"可能存在"的依赖。

Questions

问题处理

Write/update docs immediately.
Ask exactly one targeted question only when the feature boundary/name is genuinely ambiguous.
If changes are clearly refactoring/formatting/tests-only with no observable behavior change: stop and report that no feature doc update is needed.

立即编写/更新文档。
仅当功能边界/名称确实存在歧义时，提出恰好一个针对性问题。
如果变更明显是重构/格式化/仅测试代码，未带来可观察的行为变化：停止操作并报告无需更新功能文档。

Outputs

输出结果

For each feature affected:

```
docs/features/<feature_id>.md
```
(create directories if missing)
```
docs/features.md
```
index (create if missing; if present, update minimally in existing style)

对于每个受影响的功能：

```
docs/features/<feature_id>.md
```
（若目录不存在则创建）
```
docs/features.md
```
索引文件（若不存在则创建；若已存在，只需按照现有格式进行最小化更新）

Feature doc frontmatter

功能文档前置元数据

Feature docs must include exactly these required frontmatter fields:

```
feature_id
```
: must equal the file name (without
```
.md
```
)
```
title
```
: human-readable Title Case
```
updated
```
:
```
YYYY-MM-DD
```
(use today)

Existing docs may have extra frontmatter keys; preserve them. Do not add new keys (for example, do not introduce

owners

If an existing doc's

feature_id

does not match the filename: update

feature_id

to match the filename (do not rename files).

功能文档必须包含以下必填的前置元数据字段：

```
feature_id
```
: 必须与文件名（不含
```
.md
```
后缀）一致
```
title
```
: 易读的标题格式（每个单词首字母大写）
```
updated
```
:
```
YYYY-MM-DD
```
格式（使用当前日期）

现有文档可能包含额外的前置元数据键；请保留这些键。不要添加新的键（例如，不要引入

owners

字段）。

如果现有文档的

feature_id

与文件名不匹配：更新

feature_id

使其与文件名一致（不要重命名文件）。

Documentation structure (fixed order; omit non-applicable sections)

文档结构（固定顺序；省略不适用的章节）

Each feature document lives at

docs/features/<feature_id>.md

using this template.

markdown

---
feature_id: <kebab-case-id>
title: <Human Title>
updated: <YYYY-MM-DD>
---

每个功能文档存储在

docs/features/<feature_id>.md

，使用以下模板：

markdown

---
feature_id: <kebab-case-id>
title: <Human Title>
updated: <YYYY-MM-DD>
---

<Human Title>

What it does

功能说明

<2-3 sentences describing observable behavior from an external perspective.>

<2-3句话，从外部视角描述可观察的行为。>

Why it exists

存在意义

<业务合理性：解决了什么问题，以及该行为为何重要。>

Entry point(s)

入口点

<选择相关的入口点表示形式。仅当功能没有明确入口点时才省略。>

Business rules and constraints

业务规则与约束

<Rule 1 in plain language>
<Rule 2>

<规则1，用平实语言描述>
<规则2>

Error behavior (if applicable)

错误行为（如适用）

<Externally visible error conditions and outcomes: status codes, validation failures, retry/idempotency expectations.>

<外部可见的错误条件与结果：状态码、验证失败、重试/幂等性预期。>

Caching (if applicable)

缓存（如适用）

<仅当缓存影响外部可观察行为或集群中的操作正确性时才记录。>

Configuration (if applicable)

配置（如适用）

Variable	Purpose
<property.key or ENV_VAR>	<What it controls in this feature>

变量	用途
<property.key or ENV_VAR>	<该变量在本功能中的作用>

Dependencies and interactions (if applicable)

依赖与交互（如适用）


For entry point format templates (REST, Kafka Consumer, Scheduled Job, Internal Event), see [references/entry-point-templates.md](references/entry-point-templates.md).

<仅记录与功能相关、有证据支持的外部交互。>


入口点格式模板（REST、Kafka消费者、定时任务、内部事件）请参考[references/entry-point-templates.md](references/entry-point-templates.md)。

The index file (

docs/features.md

)

索引文件（

docs/features.md

）

docs/features.md

does not exist, create a minimal index:

markdown

undefined

如果

docs/features.md

不存在，创建一个最简索引：

markdown

undefined

Module Features

模块功能

This module provides the following features:

Feature	Description
<Human Title>	<One-sentence behavioral description>


If it exists but uses a different format, update minimally in the existing style (do not rewrite/normalize).

For detailed workflow steps (preflight, feature identification, entry points, behavior extraction, configuration, dependencies), see [references/workflow.md](references/workflow.md).

本模块提供以下功能：

功能	描述
<Human Title>	<一句话行为描述>


如果该文件已存在但使用不同格式，只需按照现有格式进行最小化更新（不要重写/标准化格式）。

Quick sanity checks

快速检查清单

Feature names reflect behavior (not caching/events/implementation).
Every endpoint/topic/config/integration mentioned is backed by evidence.
Sections are in fixed order; non-applicable sections are omitted.

功能名称反映行为（而非缓存/事件/实现细节）。
提及的每个端点/主题/配置/集成都有证据支持。
章节按固定顺序排列；省略不适用的章节。

document-feature

Original

Translation

Document Feature

功能文档编写

Scope and assumptions (this skill is intentionally scoped)

适用范围与假设（本技能有明确的适用边界）

Non-negotiables

不可协商的规则

Feature = observable behavior

功能=可观察的行为

Evidence-only rule (no guessing)

仅基于证据规则（禁止猜测）

Questions

问题处理

Outputs

输出结果

Feature doc frontmatter

功能文档前置元数据

Documentation structure (fixed order; omit non-applicable sections)

文档结构（固定顺序；省略不适用的章节）

<Human Title>

<Human Title>

What it does

功能说明

Why it exists

存在意义

Entry point(s)

入口点

Business rules and constraints

业务规则与约束

Error behavior (if applicable)

错误行为（如适用）

Caching (if applicable)

缓存（如适用）

Configuration (if applicable)

配置（如适用）

Dependencies and interactions (if applicable)

依赖与交互（如适用）

The index file (docs/features.md)

索引文件（docs/features.md）

Module Features

模块功能

Quick sanity checks

快速检查清单

The index file (
`docs/features.md`
)

索引文件（
`docs/features.md`
）