mcpField
D
describe-design

describe-design

github.com/posit-dev开发551795 次安装今天更新
代码仓库

关于 describe-design

describe-design 是用于研究代码库并编写架构文档的引导式技能，面向开发者和 AI Agent。它按范围逐步探索、供用户审阅，并在写入最终 Markdown 文件前确认位置。

主要功能

  1. 01明确文档范围与受众
  2. 02结构化探索代码库
  3. 03追踪组件与数据流
  4. 04使用 Mermaid 绘制架构图
  5. 05写入前审阅并确认

适用场景

  1. 01说明某项功能的实现方式
  2. 02梳理组件交互与数据流
  3. 03为开发者和 AI Agent 编写架构参考

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/posit-dev/skills --skill describe-design

安装后在 Claude Code 中输入/describe-design确认已加载。

详细介绍

描述设计

研究代码库，并生成一份架构文档，说明各项功能或系统的工作方式。输出为 Markdown 文件，兼顾人类读者和未来的 AI Agent。

工作流

阶段 1：定义范围

在开始探索前，先弄清楚要记录什么：

  1. 询问要记录哪项功能、系统或组件。
  2. 明确目标受众（开发者、AI Agent 或两者）。
  3. 如果上下文中无法确定代码库位置，请确认其位置。
阶段 2：初步探索

全面探索代码库，建立整体认知。可用时，采用轻量、快速的探索方法（例如，如果你的运行环境支持子 Agent，可使用快速探索子 Agent）：

  1. 扫描目录结构并找出关键入口点。
  2. 阅读 README、配置文件和现有文档。
  3. 找出与该功能相关的主要文件和模块。
  4. 建立对代码库组织结构的整体认知。

向用户展示高层级大纲：

## Proposed Outline

1. [Component A] - Brief description
2. [Component B] - Brief description
3. [Component C] - Brief description

* Have I correctly captured the scope of the research? Reply "yes" to continue.
* Otherwise, please let me know what I've misunderstood.

用户确认范围后，进入深入研究。

阶段 3：深入研究

针对已获批准大纲中的每个组件：

  1. 从入口点追踪代码路径。
  2. 找出组件之间的依赖关系和交互方式。
  3. 记录配置选项及其定义位置。
  4. 查明数据的存储或持久化位置。
  5. 建立代码引用索引（文件路径 + 关键函数/类名称）。

尽量利用初步代码探索收集到的信息。根据需要阅读其他文件。如果阶段 2 中范围发生了较大变化，可以启用第二个代码探索子 Agent。

何时停止探索

满足以下条件时，即可开始起草：

  • 追踪正常流程 — 从入口点到完成，全程无遗漏地追踪典型请求/操作。
  • 明确边界 — 清楚说明哪些内容属于范围内，哪些属于外部。
  • 绘制图表 — 绘制架构图，不使用占位框。
  • 回答“各部分如何交互？” — 了解每个组件的输入和输出。

尚未完成的迹象：

  • 存在不确定性：“我认为这会连接到……”或“可能会调用……”
  • 引用未解决：发现了尚未检查的模块导入/调用。
  • 缺少连接：无法解释数据如何从组件 A 流向组件 B。

探索过度的迹象：

  • 没有挑选有代表性的样本，而是阅读目录中的每个文件。
  • 追踪到外部库或框架内部。
  • 探索了不会影响架构的实现细节。
阶段 4：起草文档

按照下方模板生成文档。将草稿交给用户审核，并根据反馈迭代。如果可用，可使用 AskUserQuestion 工具，就关键决策征求用户意见。

阶段 5：定稿
  1. 写入前确认文件位置。 可以根据仓库惯例提出路径（例如 docs/architecture/、ARCHITECTURE.md），但未经用户明确确认位置，绝对不要写入文件。如果用户事先提供了路径，则视为已确认。
  2. 将最终文档写入已确认的位置。

文档模板

以下模板提供了一个起点。根据所记录的功能进行调整——省略不适用的章节，添加独有方面的章节，并调整结构，以更好地服务于目标受众。

# [Feature/System Name] Architecture

## Overview

[1-2 paragraph summary of what this feature/system does and why it exists]

## Architecture Diagram

```mermaid
flowchart TD
    A[Entry Point] --> B[Component]
    B --> C[Data Store]
```

## Components

### [Component Name]

**Purpose**: [What it does]

**Location**: `path/to/file.ext`

**Key Functions**:
- `functionName()` - Brief description
- `anotherFunction()` - Brief description

**Interactions**:
- Receives input from: [Component]
- Sends output to: [Component]

## Data Flow

[Description of how data moves through the system, from input to output]

## Configuration

[How features are enabled, disabled, or configured. Include file paths and
environment variables.]

## Code References

| Component | File | Key Symbols |
|-----------|------|-------------|
| Auth | `src/auth/index.ts` | `authenticate()`, `AuthConfig` |
| Cache | `src/cache/redis.ts` | `CacheManager`, `invalidate()` |

## Glossary

| Term | Definition |
|------|------------|
| [Term] | [Project-specific definition] |

代码引用规范

使用稳定的引用，确保重构后仍然有效：

  • 路径：使用相对于仓库根目录的相对路径（src/auth/login.ts）
  • 符号：引用函数和类名，而非行号
  • 格式：使用 path/to/file.ext，并单独列出关键符号
  • 锚点：在有帮助时使用搜索模式（handleAuth function in auth/）

避免：

  • 复制代码：切勿将代码粘贴到文档中。代码很快就会过时；文档应作为指引，指向源代码。描述代码的功能，然后引用其位置。
  • 行号：每次编辑都会改变行号。
  • 绝对路径：仅使用相对于仓库的路径。

Mermaid 图表

使用 Mermaid 展示架构：

流程图用于展示组件之间的关系：

flowchart TD
    A[Client] --> B[API Gateway]
    B --> C[Service]
    C --> D[(Database)]

时序图用于展示请求流程：

sequenceDiagram
    Client->>API: Request
    API->>Service: Process
    Service-->>API: Response
    API-->>Client: Result

图表应聚焦于所记录的具体功能。避免塞入无关组件，造成图表过于拥挤。

写作指南

  • 描述，不要复制：说明代码的功能及其位置。需要实现细节的读者会查看实际源代码——源代码始终是最新的。
  • 便于浏览的结构：使用标题、表格和列表，方便快速查找。
  • 具体明确：包含实际文件路径、函数名称和配置项。
  • 服务两类受众：面向人类清晰写作；为 AI 使用一致的结构。
  • 保持最新：注明对代码状态或版本的任何假设。

评论

支持 Markdown