Describe Design

核心用法

describe-design 是一款面向代码库研究的专业文档生成技能，采用五阶段工作流：从范围界定、初步探索、深度研究、文档草拟到最终定稿。用户指定待文档化的功能或系统后，该技能会自动扫描代码结构、追踪代码路径、识别组件依赖，最终输出包含架构图、组件说明、数据流描述和代码引用的完整Markdown文档。

显著优点

1. 双受众设计：文档结构兼顾人类开发者与AI Agent的阅读习惯，支持知识传承与自动化处理
2. 可视化输出：内置Mermaid图表生成（流程图、时序图），降低复杂系统理解门槛
3. 代码引用规范：采用符号级引用（函数名、类名）而非易失效的行号或代码拷贝，确保文档长期可维护
4. 探索边界清晰：明确定义"何时停止"的判断标准（能追踪happy path、能画出架构图、能说清组件交互），防止过度深入实现细节

潜在局限

• 依赖AI探索能力：深度研究阶段的效果受制于底层模型的代码理解能力
• 模板化输出：虽有"可适配"说明，但核心结构固定，对于高度特殊的架构可能需要大量手动调整
• 无实时验证：文档生成后不会自动验证代码引用是否仍有效，需人工维护

适合人群

• 技术负责人进行架构评审与文档沉淀
• 新成员快速熟悉复杂代码库
• 开源项目维护者生成标准化贡献指南
• 需要为AI Agent创建可解析代码地图的团队

常规风险

• 文档滞后风险：代码引用虽稳定，但大规模重构后符号可能更名，需版本化管理
• AI幻觉风险：探索阶段模型可能误判组件关系，建议关键文档人工复核
• 敏感信息泄露：自动探索可能触及包含密钥、凭证的配置文件，需配合代码库访问控制

核心用法

describe-design 是一个专注于代码库架构分析的文档生成 skill，通过五阶段工作流（Scope Definition → Initial Exploration → Deep Research → Document Draft → Finalize）系统性地将复杂代码转化为结构化文档。

用户只需指定目标功能或系统，skill 会自动探索代码库结构，追踪数据流，识别组件依赖，最终输出包含架构图（Mermaid）、组件说明、数据流描述和代码引用的完整 Markdown 文档。文档模板兼顾人类可读性与 AI 可解析性，支持技术文档、知识转移和架构评审等场景。

显著优点

1. 结构化方法论：Stage 3 的 "Stop Exploring" 判断标准（能追踪 happy path、能命名边界、能画架构图）有效避免过度探索或探索不足
2. 双受众设计：文档模板同时服务人类开发者（清晰描述）和 AI 代理（代码引用表格、稳定符号索引）
3. 安全默认值：文件写入前强制用户确认路径，防止意外覆盖
4. 零侵入性：纯文档类 skill，无代码执行、无网络请求、无第三方依赖
5. 可维护的引用规范：使用相对路径和符号名称（非行号），降低文档随代码重构而过时的风险

潜在局限

• 无自动化测试验证：依赖静态代码阅读，无法确认运行时行为是否与文档描述一致
• 大代码库效率：Haiku subagent 探索模式虽轻量化，但超大规模代码库仍可能耗时较长
• 动态语言挑战：Python/JavaScript 等动态语言的类型推断和依赖解析可能不如静态类型语言精确
• T3 来源限制：当前由个人开发者维护，缺乏组织级长期支持承诺

适合人群

• 技术团队需要进行架构文档化或知识沉淀
• 新成员 onboarding 需要快速理解代码结构
• 代码评审或重构前需要梳理现有设计
• 开源项目需要生成 CONTRIBUTING 指南或架构说明

常规风险

| 风险类型 | 等级 | 说明 |

|---------|------|------|

| 代码外泄 | 中 | 生成的架构文档可能暴露内部设计，建议审查后再分享 |

| 文档过时 | 低 | 遵循稳定引用规范可降低风险，但仍需定期维护 |

| 敏感文件读取 | 低 | 默认读取用户指定代码库，避免在含凭证的目录使用 |

| 来源可信度 | 中 | T3 来源，建议阅读源码或等待社区验证后再用于生产代码库 |