docs-maintainer

Files (1)

• SKILL.md

SKILL.md (first lines)

# 目标

保持项目文档可发现、可验证，并与代码、接口和已确认的业务规则保持同一语义。当前需维护的项目为 `fms-ui`、`fms-rear`、`lasen-ui`、`lasen-rear`。

# 工作流程

## 1. 发现项目文档

1. 先读取目标项目根目录，确认是否存在 `docs/`。
2. 读取 `docs/README.md`，遵循其中的维护约定、目录索引和命名规则；同时读取项目根目录 `README.md` 中与文档有关的约定。
3. 文档或索引缺失时，先记录问题。只有项目约定允许或用户明确要求时才新建目录、索引或文档，不凭空引入目录结构。
4. 所有文档读取和写入都必须显式使用 UTF-8。

## 2. 判断文档类型和唯一来源

按 Diátaxis 思路判断文档用途：

- **教程**：帮助新读者完成学习路径；
- **操作指南**：帮助已有使用者完成具体任务；
- **参考文档**：准确描述接口、字段、配置和约束；
- **原理说明**：解释背景、机制、设计取舍和限制。

业务规则、接口契约和字段定义只维护在一个正式文档中。任务记录、提交说明和变更记录只保存本次变更证据，并引用正式文档，不复制一份长期规则。

## 3. 建立受影响文档清单

在修改文档前，先根据变更范围检查：

- 受影响模块的 `docs/` 文档和索引；
- 项目 README、接口说明、字段/配置参考和示例；
- 变更记录或版本说明（仅在项目约定要求时更新）；
- 文档中的代码路径、接口名、字段名、命令、链接和目录项。

形成一份受影响文档清单。对每个文件标记“需要更新”“确认无需更新”或“待用户确认”，并说明判断依据，避免只凭文件名漏改文档。

## 4. 同步内容

1. 先更新正式文档，再在任务或交接记录中引用它；不要在多个文档维护同一条业务规则。
2. 代码、接口和文档中的名称、字段、示例、前置条件、异常行为和限制必须保持一致。
3. 外部事实或技术用法优先引用官方、一手来源；保留链接或版本信息，避免无法追溯的泛化结论。
4. 文档只描述已确认的行为。对未验证的推断、不确定的兼容性或待决策内容明确标注，不写成既定事实。
5. 删除无效或重复测试类时，在验证记录中说明删除原因、替代覆盖和剩余风险；不要把删除原因藏在文档改动里。

## 5. 文档质量门禁

根据项目现有脚本执行可用检查；至少完成与本次变更匹配的检查：

- 内部链接、锚点和相对路径可解析；
- 标题层级、目录索引和文件命名符合项目约定；
- 代码、命令和接口示例中的名称与当前实现一致；
- 字段、参数、返回值、默认值和必填性没有互相矛盾；
- 引用、更新时间或版本信息按项目约定维护；
- `git diff` 中没有无关文档、临时文件、重复规则或敏感信息。

纯 Markdown 文档至少执行链接或格式检查；涉及 DOCX、PDF 等有版式的产物时，必须渲染后检查页面，不以文本抽取代替视觉验证。

## 6. 收尾和输出

文档同步后重新检查代码与文档差异，再执行任务校验或项目校验；先处理检查发现的问题，再报告完成情况。输出必须包含：

- 实际更新的 `docs` 文件及每个文件的变更目的；
- 执行过的检查及结果；
- 确认无需更新或仍待确认的文档；
- 缺失目录、索引失真、未验证内容或剩余风险。

不要把“已检查”写成“已通过”，除非有本次执行的命令或可核验的证据支持。

From GFigting/carry-god, MIT.

More from GFigting/carry-god