Dt tech doc

内部技术文档 Skill

帮用户写出 Leader 能在 5 分钟内审完的技术文档。核心原则：决策层精简有重点，实现层按需展开；语言像人写的，不像 AI 生成的。

本 skill 有三条工作流，先判断走哪条：

• 用户要写新文档 → 走「A. 生成文档」
• 用户给出已有文档、明确要求改写结构或表达 → 走「B. 文档改写」
• 用户对生成的文档给出反馈（"这里不好""不要这样写""风格不对"） → 走「C. 反馈迭代」

重要：执行 A 和 B 之前，先检查 ~/.dt/learned-rules.md（用户历次反馈积累的个人偏好规则，优先级高于默认规则）：存在就读，不存在就跳过。

受众决定结构

动笔前先确认受众，受众不同，用的结构完全不同：

• 内部评审文档（给 Leader / 同事看，重点是思路和可行性）→ 用下方「决策层统一结构」
• 对外方案 / 操作指南（给外部团队、接入方看，或内外两用，重点是照着能做完）→ 用下方「对外方案结构」，不套决策层模板

内部评审文档的分层

内部文档分两层：

• 决策层（给 Leader 看）：一句话结论、背景、方案、影响范围、风险
• 实现层（给自己和 AI 工具用）：放在 ## 详细设计 之后，数据表结构、接口详细参数、伪代码等

决策层统一结构

三种文档类型共用同一套决策层章节：

# [文档名称]

## 一句话结论
（Leader 一眼知道你要干什么/推荐什么/怎么设计）

## 背景
（1-3 句话，说清楚现状问题）

## 方案
（核心思路 + 关键设计点，只写影响方向判断的）
（技术调研：这里是对比表，只列影响决策的维度）
（架构设计：这里是整体设计 + 关键设计决策）

## 影响范围
（改了什么、影响什么、需要谁配合）

## 风险
（真实风险 + 应对，不凑数）

---

## 详细设计
（实现细节放这里）

类型差异只体现在"方案"章节的内容侧重：

• 技术方案：核心思路 + 关键设计点 + 方案对比（如有）
• 技术调研：结论放最前 + 对比表 + 选择理由
• 架构设计：架构图 + 模块职责 + 关键设计决策

对外方案结构

对外接入 / 操作指南类文档（含内外两用）用这套骨架，核心是"思路薄、实操厚"：

# [方案名称]

## 整体思路
（要解决什么问题 + 核心做法一张图或一段话讲清 + 硬约束 + 本期范围）

## 方案选择
（有哪几条路、对比表、明确的选择建议；说清共用部分与差异部分）

## 交付能力清单（实操类建议）
（读者最终要交付/实现哪几项能力，每项映射到对应章节——先知道终点再看步骤）

## 共用主流程（如有）
（多方案共用的核心流程，放在各方案实操之前——实操的终点要能接上它。
逐步展开：每步做什么、调什么接口、传什么关键字段、拿回什么。
整体流程图每步标注"谁做 / 在哪做"，并区分核心流程与可选步骤）

## 方案 X 实操步骤
（每个方案一章，从零到跑通的正向步骤）

## 接口与字段参考（如有）
（完整字段表、接口清单集中放这里；步骤正文只出现当步用到的关键字段，不让字典表撑爆步骤）

## 注意事项（尽量并入步骤）
（优先以一两条"规则"式短句贴在所属步骤末尾；只有跨步骤的硬项才集中后置）

对外文档的通用化红线——只写三层事实，其余全删：

• ✅ 平台机制：接口、字段、转发规则等平台本身的行为
• ✅ 必须遵守的约定：用"需要做到什么效果"的语气写，不规定怎么实现
• ❌ 实现私货：配置存哪（.env 等）、技术栈、代码语法限制、DOM 选择器、demo 路径、测试数据，全部删掉或改成效果描述

判断标准：换一个技术栈的团队来做，这句话还成立吗？ 不成立就删或改写。

A. 生成文档

第一步：确认信息

问清楚，关键口径尽量给选项让用户选（选择题一次问完，不要开放式追问）：

• 写给谁看？（内部 Leader 评审 / 对外接入方 / 两者兼顾）——决定用哪套结构
• 这是什么类型的文档？（技术方案 / 技术调研 / 架构设计 / 对外方案·操作指南）
• 要解决什么问题？
• 你打算怎么做？（或者调研了哪些选项）
• 影响哪些模块/服务？
• 有什么风险？

如果用户已经把这些信息说清楚了，跳过提问直接写。

第二步：先出目录骨架 + 样板（长文档必做）

结构非标准或篇幅长（预计超过 3 屏）时，先给两样东西让用户确认再写全文：①目录骨架——每章一句话说明写什么；②核心步骤或核心模块的一个完整样板——让用户确认详细度和格式。骨架与样板阶段的调整成本远低于写完返工；标准短文档可跳过直接写。

第三步：生成文档

先确定输出文件路径：调用方（如 dt-think）传入的路径直接用，没有传入就问用户存到哪。文档写入该文件，不能只贴在对话里。

按受众对应的结构生成（内部评审 → 决策层统一结构；对外 / 两用 → 对外方案结构），语言严格遵循下方「语言规范」。

内部文档决策层写完后，实现层写占位提示（"待补充：XX"），除非用户提供了足够的实现细节。

第四步：交付

告诉用户文档写在了哪个文件，简要说明结构。如果用户需要调整，按反馈修改。

B. 文档改写

第一步：读取文档

读用户给的文档，判断：

• 它的受众是谁（内部评审 / 对外接入方 / 两者）、该用哪套结构（内部 → 决策层统一结构；对外 → 对外方案结构），拿不准就问用户
• 结构是否符合该受众对应的结构
• 内部文档：决策层和实现层是否分开、有没有不影响决策的内容混在决策层
• 对外文档：详略是否倒挂（关键步骤薄、风险注意事项厚）、有没有实现私货（按「对外方案结构」的通用化红线扫）

第二步：语言扫描

逐段检查下方「语言规范」中的 17 条 AI 味特征，标记命中项。

第三步：改写输出

用户给的是文件时，改写结果直接写回原文件（用户另有要求除外）；用户贴的是文本，在对话里输出完整改写结果。改写原则：

• 结构不对的，按该文档受众对应的结构重新组织；整篇重构时先出目录骨架 + 核心步骤/模块样板让用户确认，再动笔
• 内部文档：决策层混了实现细节的，移到详细设计
• 对外文档：实现私货删掉或改成效果描述；边缘内容压缩后置或并入步骤
• 语言有 AI 味的，按规范改掉
• 保住所有事实、数据、技术判断，只改表达方式
• 改完后附一段简要说明：改了哪些地方、为什么改

C. 反馈迭代

当用户对生成的文档给出反馈时（比如"这里太啰嗦了""不要用这种句式""风险写得太正式""这个词别用"），执行以下步骤：

第一步：理解反馈

从用户的反馈中提取出具体的规则。反馈可能是：

• 对某个具体表达的不满："不要用'旨在'这个词"
• 对某类风格的偏好："风险部分要更口语化"
• 对结构的调整："背景不需要写那么多"
• 对详细程度的意见："方案部分太简略了，关键设计点要多写一些"
• 发现新的 AI 味模式："AI 老是用'值得一提的是'，加到检查表里"

第二步：判断规则归属

判断这条反馈应该改哪里：

反馈类型	改哪里	举例
新的 AI 味特征	SKILL.md 的去 AI 味检查表	"加一条：不要用'值得一提的是'"
结构模板调整	SKILL.md 的决策层统一结构	"模板里要加一个'技术约束'章节"
写作原则补充	SKILL.md 的写作原则	"补一条：不要解释 Leader 已经知道的缩写"
个人用词偏好	~/.dt/learned-rules.md	"我不喜欢用'旨在'这个词"
个人风格偏好	~/.dt/learned-rules.md	"我 Leader 喜欢看对比表"
详细程度偏好	~/.dt/learned-rules.md	"背景部分我只想写一句话"

简单判断：这条规则换个人也适用吗？ 适用 → 改 SKILL.md；只适用于这个用户 → 写 ~/.dt/learned-rules.md。

第三步：提炼并写入

把反馈转化成可执行的规则。先读目标文件的已有规则：重复的不再添加，冲突的用新规则覆盖旧规则。

写入 ~/.dt/learned-rules.md（个人偏好，直接写；文件不存在则先创建，含一行标题 # 迭代积累的规则）的格式：

### [日期] [规则标题]
- **触发场景**：什么情况下应用这条规则
- **具体要求**：怎么做
- **来源**：用户原话（简要）

写入 SKILL.md 的（通用规则，影响所有后续运行）：先把提炼出的规则文本给用户看，确认后再修改对应章节（往检查表加行、往写作原则加条目、往模板加章节等）。

第四步：应用

告诉用户规则写到了哪里。如果用户的反馈是针对当前文档的，同时按新规则修改当前文档。

---

语言规范

去 AI 味检查表

以下 17 条特征，写完/改完之后逐条检查：

#	AI 味特征	例子	怎么改
1	开头总结全文	"本文档将详细阐述……"	删掉，直接进正文
2	宏大开场	"在当今微服务架构日益普及的背景下"	删掉，直接说问题
3	空洞修饰词	"高效的""强大的""灵活的""优雅的"	删掉，或用具体数据替代
4	万能连接词	"综上所述""值得注意的是""总的来说"	删掉
5	假大空的好处	"提升了系统的可维护性和可扩展性"	说具体："新增业务类型时只需加一个配置文件，不用改代码"
6	面面俱到	把每个技术点都解释一遍	只写 Leader 不知道的信息
7	末尾总结	"通过以上方案，我们实现了……"	删掉
8	过度礼貌	"感谢您的审阅""如有任何问题"	删掉
9	列举万物	列了 10 个好处、8 个特性	只留最重要的 2-3 个
10	三件套排比	"高效、稳定、可扩展"	有几个说几个，不凑三个词
11	同义词轮换	消息队列/MQ/异步消息组件 轮着叫	同一个东西全篇用同一个词
12	回避"是"	"Redis 作为缓存层承担了数据加速的职责"	直接说"Redis 是缓存"
13	"不是X而是Y"	"这不是简单的数据迁移，而是架构层面的升级"	删掉转折，直接说要做什么
14	翻译腔	"对数据进行处理""基于XX的方式"	说中文："处理数据""用XX"
15	无源权威	"业界普遍认为""最佳实践表明"	给出处或删掉
16	商业黑话	"赋能""闭环""沉淀""抓手""拉通"	说具体动作
17	过度对冲	"可能在某些场景下存在一定的性能瓶颈"	明确表态："数据超过 100 万条会慢"

写作原则

• 说人话：想象在工位上口头跟 Leader 说这个方案，怎么说就怎么写
• 有立场：明确判断，"我选方案 A，因为……"，不要两边说好话让读者自己选
• 说具体的：不说"性能更好"，说"P99 延迟从 200ms 降到 50ms"
• 省略显而易见的：Leader 知道的事情不重复，不需要解释"什么是 Redis"
• 用短句：一句话不超过 30 个字，一段不超过 4 句，能用列表就不用段落
• 步骤是主体（实操类文档）：每步四段式——目的（一句话）→ 做什么（编号动作，每个动作具体到"输入什么、做什么、输出什么"）→ 产物（文件 / 保存哪些字段 / 数据形态示例）→ 如何验证；步骤收尾可用一句"至此，XX 完成"标记阶段闭环
• 注意事项并入步骤：优先以一两条"规则"式短句贴在所属步骤末尾（如"入口参数不可信"）；只有跨步骤的硬项才集中后置，不让边缘内容比关键步骤厚

排版（中文排版硬规则）

• 中文语境用全角标点（，。、；：""（）），全角标点两侧不空格
• 中文与英文 / 数字之间空 1 个半角空格（每 2 分钟导入 256 MB）；纯中文之间不空格
• 计量 / 百分比 / 版本号 / 日期用阿拉伯数字（34.05%、v2.1）；概数、固定词语用汉字（三五天）
• 全英文括号用半角且前后各空 1 格 (DDL)；含中文用全角且前后不空格（斜杠（slash））
• 专有名词保留正确大小写（MySQL、GitHub）；API、SDK、URL、JSON 等技术缩写保留英文
• 代码、命令、字段名用 行内代码 标记