mcpField
D
document-feature

document-feature

github.com/folio-org开发362 次安装6 天前更新
代码仓库

关于 document-feature

面向后端开发者的文档技能，可根据代码变更编写以行为为核心的功能文档。它要求内容有仓库证据支持，并规范功能文档及索引的结构。

主要功能

  1. 01识别外部可观察的功能
  2. 02要求声明有仓库证据
  3. 03创建功能文档和索引
  4. 04规范前置元数据与章节顺序
  5. 05标记模糊的功能边界

适用场景

  1. 01记录新实现的后端功能
  2. 02判断变更是否需要功能文档
  3. 03更新模块功能索引
  4. 04避免无依据地描述端点或集成

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/folio-org/folio-eureka-ai-dev --skill document-feature

安装后在 Claude Code 中输入/document-feature确认已加载。

附带文件references/entry-point-templates.mdreferences/workflow.md

详细介绍

原文在翻译后有更新，译文可能不是最新。

文档功能

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

范围和假设（本技能有意限定范围）

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

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

如果仓库不符合这些特征，请尽力处理，但仍须遵循证据规则。

不可妥协的要求

功能 = 可观察行为

**功能是外部使用者可以观察或交互的内容。**实现机制是功能的组成部分。

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

功能名称应体现行为，而不是机制：

  • 合适：resource-lookup、hold-request-validation、tenant-sync-processing
  • 不合适：resource-cache、validation-refactor、kafka-handler
仅依据证据规则（禁止猜测）

仅记录可通过仓库证据确认的端点、主题、配置和集成：

  • OpenAPI 规范（包含 openapi: 或 swagger: 的 *.yml/*.yaml 文件）
  • 应用配置（application.yml、application.yaml、application.properties）
  • 代码证据（注解、常量、命名明确的配置键）
  • README 或其他已纳入版本控制的文档

无法证明的内容应省略。不要推断“可能存在”的依赖项。

问题
  • 立即编写或更新文档。
  • 仅在功能边界或名称确实模糊不清时，提出恰好一个有针对性的问题。
  • 如果变更显然只是重构、格式调整或仅涉及测试，且没有可观察的行为变化：停止并报告无需更新功能文档。

输出

对于每项受影响的功能：

  • docs/features/<feature_id>.md（如目录不存在，则创建目录）
  • docs/features.md 索引（如不存在，则创建；如已存在，则按现有风格进行最小更新）

功能文档前置元数据

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

  • feature_id：必须与文件名（不含 .md）一致
  • title：符合标题大小写格式的易读标题
  • updated：YYYY-MM-DD（使用今天的日期）

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

如果现有文档的 feature_id 与文件名不一致：请将 feature_id 更新为与文件名一致（不要重命名文件）。

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

每份功能文档都应放在 docs/features/<feature_id>.md，并使用以下模板。

---
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.>

## 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>

## 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)
| Variable | Purpose |
|----------|---------|
| <property.key or ENV_VAR> | <What it controls in this feature> |

## Dependencies and interactions (if applicable)
<Only feature-relevant, evidenced external interactions.>

有关入口点格式模板（REST、Kafka Consumer、定时任务、内部事件），请参阅 references/entry-point-templates.md。

索引文件（docs/features.md）

如果 docs/features.md 不存在，请创建最简索引：

# Module Features

This module provides the following features:

| Feature | Description |
|---------|-------------|
| [<Human Title>](features/<feature_id>.md) | <One-sentence behavioral description> |

如果文件已存在但格式不同，请按现有风格进行最小更新（不要重写或统一格式）。

有关详细工作流程步骤（预检、功能识别、入口点、行为提取、配置、依赖项），请参阅 references/workflow.md。

快速检查

  • 功能名称体现行为（而不是缓存、事件或实现方式）。
  • 提及的每个端点、主题、配置和集成都有证据支持。
  • 各章节顺序固定；省略不适用的章节。

评论

支持 Markdown