# Dsh Doc

创建或维护工程文档、设计决策、事故复盘、归档提案或产品迁移指南时使用，保留事实依据、实际备选方案和准确状态。

- Repository: https://github.com/qufei1993/skills-hub (1848 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add qufei1993/skills-hub --skill dsh-doc -g -a claude-code -y`
Codex: `npx skills add qufei1993/skills-hub --skill dsh-doc -g -a codex -y`
Cursor: `npx skills add qufei1993/skills-hub --skill dsh-doc -g -a cursor -y`
Gemini CLI: `npx skills add qufei1993/skills-hub --skill dsh-doc -g -a gemini-cli -y`

## Description

创建或维护工程文档、设计决策、事故复盘、归档提案或产品迁移指南时使用，保留事实依据、实际备选方案和准确状态。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 维护有用的工程文档

阅读[项目上下文](references/project-context.md)和[文档写作](references/prose.md)。创建文档前，先找到现有负责维护相关事实的位置。

1. 明确读者、任务和实际源码行为。涉及默认值、输入输出、失败恢复及兼容性时，阅读实现和真实示例。
2. 选择下面与任务有关的流程，只组合请求需要的部分。
3. 优先修改事实的现有维护文档，更新导航和指向它的链接，并在任务范围内清理矛盾的重复说明。沿用项目的文档约定和语言。
4. 验证示例、路径和链接，对照代码检查语义。格式检查不能证明事实正确或内容完整。适用时执行项目必需检查。

## 当前行为文档

说明前置条件、受支持用法、代表性示例、重要限制和失败行为。注释解释行为约定或不明显的选择，不记录修改过程。公开行为变化时，在同一次改动中更新读者实际使用的入口文档。

## 决策和事故记录

沿用项目已有记录结构。长期选择的理由若会丢失，应记录下来；普通局部修改不需要决策记录。重大漏检缺陷、重复故障或用户明确要求时编写事故记录，不要求每次修复都做复盘。

- 决策使用[决策模板](templates/decision-record.md)：问题、选定行为、真实备选方案及落选理由、影响、证据和状态。同时记录收益与代价。移除功能时保留原始需求、失去的能力和重新考虑的条件。历史缺失时不编造备选方案，新增建议与历史决定分开标注。
- 事故使用[复盘模板](templates/postmortem.md)：实际影响、已知经过、原因、现有检查为何漏检、修正和防复发措施。每项防护对应到它能检出的故障、已知的实际负责人，以及代码或测试证据；区分拟议、已实现和已验证。缺失的日期、负责人、链接或测试结果保持未知，不补造。

区分假设与已经核实的事实。当前指南不保留会话推理过程，但保留解释长期约束的理由。

## 已实施提案与归档

将提案标为已交付前，验证实际实现。核对名称、路径和机制与现状一致，同时保留历史决策。只有状态适合归档时才归档，修复指向它的链接，并注明当前维护位置或后继文档。不得悄悄删除仍有效的需求，或将历史改写为当前行为。

## 产品迁移指南

说明受影响版本和用户、新旧行为、前置条件、可执行步骤、兼容期、验证方式及回退限制。涉及持久化数据时，明确格式负责方、备份策略和迁移中断后的行为。用代表性的旧数据走真实迁移入口。不要将产品迁移与 DSH Engineering Skill 安装包更新混淆。

报告改动的维护文档、已验证行为和未解决的事实问题。翻译与发布仍是需要明确提出的独立任务。