Back to Details

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 APICache for lookup
Validation rulesException mapping
Event-driven state syncKafka 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监听器配置
功能命名应基于行为，而非实现机制：
  • 推荐：
    resource-lookup
    , 
    hold-request-validation
    , 
    tenant-sync-processing
  • 不推荐：
    resource-cache
    , 
    validation-refactor
    , 
    kafka-handler

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>

<Human Title>

What it does

功能说明

<2-3 sentences describing observable behavior from an external perspective.>
<2-3句话，从外部视角描述可观察的行为。>

Why it exists

存在意义

<Business rationale: what problem it solves and why this behavior matters.>
<业务合理性：解决了什么问题，以及该行为为何重要。>

Entry point(s)

入口点

<Choose the relevant entry point representation(s). Omit only if the feature has no clear entry point.>
<选择相关的入口点表示形式。仅当功能没有明确入口点时才省略。>

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)

缓存（如适用）

<Document caching only when it affects externally observable behavior or operational correctness in a cluster.>
<仅当缓存影响外部可观察行为或集群中的操作正确性时才记录。>

Configuration (if applicable)

配置（如适用）

VariablePurpose
<property.key or ENV_VAR><What it controls in this feature>
变量用途
<property.key or ENV_VAR><该变量在本功能中的作用>

Dependencies and interactions (if applicable)

依赖与交互（如适用）

<Only feature-relevant, evidenced external interactions.>

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
）

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