背景
在软件工程实践中，需求规格说明书（SRS）与设计文档是开发、测试与验收的依据，通常遵循 IEEE 830/29148 的结构规范，涵盖引言、总体描述、功能需求、外部接口需求、非功能需求等章节。但在多数研发团队中，代码合入后文档长期滞后是常态，且人工维护的文档在格式、粒度、术语一致性上难以统一。
将"代码 + 团队模板 → 标准化文档"的流程封装为 TRAE Skill，可以把个人的文档经验沉淀为团队可复用的工程资产。
方案设计
TRAE 的 Skill 本质是包含 SKILL.md 的能力单元，可附带 templates/、examples/、resources/ 等目录，仅在被触发时加载。项目级 Skill 存放于 .trae/skills/，全局级存放于 ~/.trae/skills/（Windows 为 %userprofile%/.trae/skills/）。
目录结构：
bash
纯文本
纯文本
code-to-doc/
├── SKILL.md # 核心指令
└── templates/
├── prd-template.md # 需求文档模板（参照 IEEE 830 结构）
└── design-template.md # 设计文档模板SKILL.md 的 description 字段是触发匹配的唯一依据，需明确触发条件、核心功能与排除场景：
yaml
yaml
yaml
---
name: code-to-doc
description: 当需要从现有代码生成符合团队模板的需求文档或设计文档时使用。不适用于从零开始撰写需求或缺乏代码上下文的场景。
---正文指令（节选关键部分）：
markdown
# code-to-doc
## 目标
根据用户提供的代码仓库和 templates/ 下的文档模板，生成符合团队规范的需求文档（PRD/SRS）或设计文档（DD）。
## 工作流程
### 1. 代码盘点
- 扫描用户指定的代码目录，识别语言、框架、模块边界
- 列出所有 API Controller / 路由 / 服务入口
- 识别数据模型（Entity / Model / Schema）
### 2. 分阶段生成（重要）
按以下顺序产出，每阶段完成后请用户确认再进入下一阶段：
1. **需求文档**：基于 IEEE 830 / 29148 标准结构，从代码反推功能需求、非功能需求、数据规格、接口规格
2. **概要设计**：模块划分、模块依赖关系、数据流说明、技术选型
3. **详细设计**：每个模块的数据结构设计、函数/类设计、处理流程、错误处理策略、测试要点
### 3. 模板强制约束
- 需求文档必须严格遵循 templates/prd-template.md 的章节结构与编号方式
- 设计文档必须严格遵循 templates/design-template.md 的章节结构与编号方式
- 输出格式统一为 Markdown，带目录、需求唯一编号（FR-001、NFR-001 递增）
### 4. 事实与推断分离（防 AI 瞎编）
- 从代码中明确能看出的内容 → 直接写入文档正文
- 代码无法体现、需要业务确认的内容（如某功能的产品动机、非功能需求的量化指标）→ 必须在文档中以「[待确认]」标注，并主动向用户提问，禁止臆测
### 5. 输出
- 需求文档输出到 doc/proposal.md
- 概要设计输出到 doc/high-level-design.md
- 详细设计输出到 doc/detailed-design.md 和 doc/shared-api.md模板长什么样（节选 prd-template.md）
参考 IEEE 830 标准并结合团队实际调整的结构：
shell
# 需求规格说明书（SRS）
## 1. 文档信息
- 版本历程 / 审查纪录 / 术语定义
## 2. 系统概述
- 系统背景 / 系统目标 / 使用者角色 / 系统范围
## 3. Use Case
- Use Case 清单 / Use Case 描述 / Use Case Diagram
## 4. 功能需求（FR-001 递增）
| 编号 | 功能描述 | 适用角色 | 操作流程 | 前置条件 |
## 5. 非功能需求（NFR-001 递增）
- 效能 / 安全性 / 可用性 / 合规性（全部量化并附验收标准）
## 6. 资料规格
- 资料流程图（DFD）/ ER Model / 资料字典
## 7. 批次流程
- 批次清单 / 批次流程图
## 8. 界面规格
- 外部系统界面 / API 规格正文指令遵循"使用场景 → 分步指令 → 示例"的结构，关键点包括：
- 代码静态分析：识别模块边界、API 入口、数据模型与外部依赖
- 模板强约束 ：输出严格遵循
templates/下的章节结构与编号体系 - 事实与推断分离 ：代码中可验证的内容写入正文；业务动机、量化指标等非代码可推导项，以
[待确认]标注并主动追问，避免模型臆测 - 分阶段产出：按"需求规格 → 概要设计 → 详细设计"顺序生成，每阶段经人工确认后推进
使用方式
在 TRAE 中打开目标项目，输入：
使用
code-to-doc技能，基于templates/prd-template.md，对src/目录下的订单模块代码生成需求规格说明书。
Skill 被触发后，会自动扫描代码结构、套用团队模板、标注待确认项，并输出到指定路径。同一 Skill 在不同项目、不同模块间可重复调用，输出格式与规范保持一致------这是单次 Prompt 无法保证的。
收益
| 维度 | 传统人工撰写 | Skill 化生成 |
|---|---|---|
| 格式一致性 | 依赖个人习惯 | 严格遵循团队模板 |
| 可复用性 | 每次重构 Prompt | 一次定义，全局/项目级复用 |
| 业务意图处理 | 易遗漏或臆测 | 强制 [待确认] 标注 |
| 团队沉淀 | 随人员流动流失 | 作为 Skill 资产留存与分享 |
结语
Skill 的价值不在于"让 AI 写文档"，而在于将团队的文档规范、质量标准与校验规则显式化为可执行的工程契约 。当文档模板演进时，只需更新 templates/ 下的文件，所有后续生成自动继承新规范。这种"定义一次、持续复用"的模式，正是研发效能工具化的核心思路。