深入了解 OpenClaw 中的 Describe Design Skill：全面指南
I’m happy to translate the article for you, but I don’t have the article’s text available. Could you please paste the content you’d like translated (excluding the source line you’ve already provided)? Once I have the text, I’ll translate it into Simplified Chinese while preserving all formatting, markdown, and technical terms.
描述设计技能的工作原理
该技能遵循结构化的五阶段工作流程，以确保文档的完整性和准确性。
第 1 阶段：范围定义
在深入代码库之前，技能会明确需要记录的内容。它会询问具体的功能、系统或组件，确定目标受众（开发者、AI 代理或两者），并确认代码库的位置。此初始步骤可使文档工作保持聚焦且相关。
第 2 阶段：初步探索
技能对代码库进行广泛的探索，以构建心理模型。这包括扫描目录结构、阅读 README 和配置文件、识别关键入口点以及定位现有文档。目标是在深入特定组件之前，先了解整体组织结构。
第 3 阶段：深入研究
范围确认后，技能对每个组件进行彻底研究。它会追踪入口点的代码路径，识别依赖关系和交互，记录配置选项，并查找数据的存储或持久化位置。随后构建包含文件路径和关键函数或类名的完整代码引用索引。
第 4 阶段：文档草稿
使用结构化模板，技能生成包含概述、架构图、组件描述、数据流解释、配置细节和代码引用的草稿文档。草稿会呈现给用户，以便根据反馈进行审阅和迭代。
第 5 阶段：最终定稿
在写入文档之前，最后阶段会确认文件位置。技能会根据仓库约定提出路径建议，但在未得到用户明确确认之前，绝不写入文件。
文档模板与结构
Describe Design 技能使用包含以下内容的完整模板：
- 概览 – 总结功能或系统的作用
- 架构图 – 使用 Mermaid 流程图语法
- 组件描述 – 目的、位置、关键功能和交互
- 数据流说明 – 展示信息在系统中的流动方式
- 配置细节 – 文件路径和环境变量
- 代码引用表 – 在重构后仍然有效的稳定引用
- 术语表 – 项目特定术语的定义
关键特性和最佳实践
- 稳定引用 – 使用相对于仓库根目录的相对路径以及函数/类名，而不是行号。
- 描述性方法 – 解释代码的功能及其所在位置，而不是直接复制代码。
- Mermaid 图表 – 使用 Mermaid 语法为流程图和时序图创建架构的可视化表示。
- 双受众设计 – 为人类读者清晰写作，同时保持对 AI 代理一致的结构。
- 最新信息 – 记录关于代码状态或版本的任何假设，以确保准确性。
何时使用 Describe Design 技能
此技能在以下情况下特别有用：
- 为新团队成员入职记录功能的工作方式。
- 为利益相关者创建架构概览。
- 为团队成员之间的知识转移解释代码结构。
- 为文档目的研究并描述系统设计。
使用此技能的好处
通过使用 Describe Design 技能，团队可以创建既服务于人类开发者又服务于 AI 代理的文档，确保架构知识得以保留并且易于获取。结构化的方法以及对稳定引用的强调，使得即使代码库随时间演变，文档仍然保持实用。
该技能帮助弥合复杂代码库与清晰、易懂文档之间的鸿沟，对从事大型或复杂项目的软件开发团队而言，是一件不可或缺的工具。
Skill location: design/SKILL.md