Skip to content

Commit 90391e1

Browse files
Copilotbearguo
Copilot
and
bearguo
committed
Trim links demo to Figma/Feishu/Slack/Jira and add agent workflow guide
Co-authored-by: bearguo <20483603+bearguo@users.noreply.github.com>
1 parent ff7a01b commit 90391e1

File tree

5 files changed

+246
-80
lines changed

5 files changed

+246
-80
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
This repository is used to create technical design documents using AI Agent mode in an IDE. When a user asks you to create a technical design document, follow the guidelines below.
66

7+
> For a complete usage guide and workflow, see [`docs/agent-workflow.md`](../docs/agent-workflow.md).
8+
79
## Creating a New Technical Design Document
810

911
### Step 1: Understand the Requirement

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@
1616
> "请根据 `templates/tech-design-template.md` 模板，为 [你的功能] 创建一个技术设计文档，保存到 `docs/[功能名称]/tech-design.md`。"
1717
4. Agent 会自动生成技术设计文档并保存到 `docs/` 目录下
1818

19+
📖 **详细使用文档和工作流程**：[docs/agent-workflow.md](docs/agent-workflow.md)
20+
1921
### 目录结构
2022

2123
```
@@ -63,6 +65,8 @@ This repository is used to create technical design documents using AI Agent mode
6365
> "Please create a technical design document for [your feature] based on the `templates/tech-design-template.md` template, and save it to `docs/[feature-name]/tech-design.md`."
6466
4. The Agent will automatically generate the technical design document and save it to the `docs/` directory
6567

68+
📖 **Full usage guide and workflow**: [docs/agent-workflow.md](docs/agent-workflow.md)
69+
6670
### Directory Structure
6771

6872
```

‎docs/agent-workflow.md‎

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
# AI Agent 使用文档与工作流程
2+
3+
> 本文档面向在 IDE 中使用 AI Agent 模式（如 GitHub Copilot Agent）的工程师，介绍如何通过 Agent 快速创建、维护技术设计文档。
4+
5+
---
6+
7+
## 目录
8+
9+
1. [前置准备](#前置准备)
10+
2. [工作流程总览](#工作流程总览)
11+
3. [Step 1 — 创建模块文件夹](#step-1--创建模块文件夹)
12+
4. [Step 2 — 创建外部链接文档](#step-2--创建外部链接文档)
13+
5. [Step 3 — 创建技术设计文档](#step-3--创建技术设计文档)
14+
6. [Step 4 — 创建排期甘特图](#step-4--创建排期甘特图)
15+
7. [Step 5 — 创建 Protobuf 模型定义](#step-5--创建-protobuf-模型定义)
16+
8. [Step 6 — 更新已有文档](#step-6--更新已有文档)
17+
9. [示例 Prompt 速查表](#示例-prompt-速查表)
18+
10. [常见问题](#常见问题)
19+
20+
---
21+
22+
## 前置准备
23+
24+
| 条件 | 说明 |
25+
|------|------|
26+
| IDE | VS Code（推荐）或其他支持 GitHub Copilot 的 IDE |
27+
| 插件 | GitHub Copilot + GitHub Copilot Chat |
28+
| 模式 | 在 Copilot Chat 面板中切换到 **Agent** 模式（`@workspace` 或 `Agent` 选项） |
29+
| 仓库 | 已克隆本仓库并在 IDE 中打开 |
30+
31+
> **提示**：Agent 模式会读取 `.github/copilot-instructions.md` 作为行为指引，无需额外配置。
32+
33+
---
34+
35+
## 工作流程总览
36+
37+
```
38+
用户提需求
39+
│
40+
▼
41+
Agent 询问澄清问题（模块名、技术栈、负责人等）
42+
│
43+
▼
44+
创建模块文件夹 docs/<模块名>/
45+
│
46+
├─▶ links.md ← 外部链接（Figma / 飞书 / Slack / Jira）
47+
├─▶ tech-design.md ← 技术设计文档（必须）
48+
├─▶ schedule.md ← 排期甘特图（可选）
49+
└─▶ model.proto ← Protobuf 模型定义（可选）
50+
│
51+
▼
52+
用户审阅 → 提出修改意见 → Agent 更新文档
53+
│
54+
▼
55+
状态更新：Draft → In Review → Approved
56+
```
57+
58+
每个步骤均可单独触发，也可一次性要求 Agent 生成全套文档。
59+
60+
---
61+
62+
## Step 1 — 创建模块文件夹
63+
64+
Agent 会在 `docs/` 下自动创建以模块名命名的文件夹。文件夹名使用小写短横线命名法（kebab-case）。
65+
66+
**示例 Prompt：**
67+
```
68+
为"用户通知服务"模块创建设计文档，模块文件夹命名为 notification-service。
69+
```
70+
71+
**结果：**
72+
```
73+
docs/notification-service/
74+
```
75+
76+
---
77+
78+
## Step 2 — 创建外部链接文档
79+
80+
基于 `templates/links-template.md`，Agent 生成 `links.md` 并填入 Figma、飞书、Slack、Jira 的链接占位符。
81+
82+
**示例 Prompt：**
83+
```
84+
为 notification-service 创建 links.md，
85+
Figma 链接：https://figma.com/file/xxx，
86+
飞书文档：https://feishu.cn/docs/yyy，
87+
Slack 频道：#notification-service，
88+
Jira Epic：NOTIF-10。
89+
```
90+
91+
**生成文件：** `docs/notification-service/links.md`
92+
93+
**内容示例：**
94+
95+
| 工具 / Tool | 链接 / Link | 说明 / Description |
96+
|-------------|-------------|-------------------|
97+
| Figma | [设计稿](https://figma.com/file/xxx) | UI 设计稿 |
98+
| 飞书文档 / Feishu Doc | [需求文档](https://feishu.cn/docs/yyy) | PRD |
99+
| Slack | `#notification-service` | 主要讨论频道 |
100+
| Jira | [NOTIF-10](https://jira.example.com/browse/NOTIF-10) | Epic |
101+
102+
---
103+
104+
## Step 3 — 创建技术设计文档
105+
106+
基于 `templates/tech-design-template.md`，Agent 生成 `tech-design.md`。文档覆盖以下章节：
107+
108+
| 章节 | 说明 |
109+
|------|------|
110+
| Overview | 2-3 句话的功能概述 |
111+
| Background | 背景、现状、动机 |
112+
| Goals & Non-Goals | 明确边界 |
113+
| Design | 架构图、组件、数据模型、API、备选方案 |
114+
| Implementation Plan | 里程碑、任务拆分、工时估算 |
115+
| Testing Strategy | 单测、集成测试、E2E |
116+
| Security Considerations | 认证、鉴权、数据安全 |
117+
| Performance Considerations | 吞吐量、延迟目标 |
118+
| Rollout Plan | 灰度发布、回滚方案、监控告警 |
119+
| Open Questions | 待决事项 |
120+
121+
**示例 Prompt（简单）：**
122+
```
123+
为 notification-service 创建技术设计文档。
124+
该服务负责向用户发送站内信、邮件和推送通知，技术栈为 Go + gRPC + Kafka。
125+
```
126+
127+
**示例 Prompt（详细）：**
128+
```
129+
为 notification-service 创建技术设计文档，要求：
130+
- 作者：张三
131+
- 支持渠道：站内信、邮件（SendGrid）、Push（FCM）
132+
- 消息队列：Kafka，Topic 按渠道拆分
133+
- 数据库：PostgreSQL（存储发送记录）
134+
- 需要考虑发送限流（每用户每分钟最多 10 条）
135+
- 架构图使用 ASCII art
136+
```
137+
138+
**生成文件：** `docs/notification-service/tech-design.md`
139+
140+
> **文档过长时**：可以要求 Agent 拆分，例如：
141+
> ```
142+
> 将 tech-design.md 中的 API Design 和 Data Model 拆分到 tech-design-part2.md
143+
> ```
144+
145+
---
146+
147+
## Step 4 — 创建排期甘特图
148+
149+
基于 `templates/schedule-template.md`，Agent 生成包含 Mermaid 甘特图的 `schedule.md`。
150+
151+
**示例 Prompt：**
152+
```
153+
为 notification-service 创建排期文档，
154+
开发周期：2026-03-01 到 2026-04-30，
155+
分为三个阶段：设计（2周）、开发（4周）、测试（2周），
156+
负责人：李四（后端）、王五（QA）。
157+
```
158+
159+
**生成文件：** `docs/notification-service/schedule.md`
160+
161+
图表使用 [Mermaid 甘特图](https://mermaid.js.org/syntax/gantt.html) 语法，GitHub 和飞书均可直接渲染。
162+
163+
---
164+
165+
## Step 5 — 创建 Protobuf 模型定义
166+
167+
基于 `templates/model-template.proto`，Agent 生成 `model.proto`，定义消息体、枚举和 gRPC 服务。
168+
169+
**示例 Prompt：**
170+
```
171+
为 notification-service 创建 model.proto，
172+
package 名为 org.example.notification，
173+
需要定义：
174+
- Notification 消息（id、user_id、channel、content、status、created_at）
175+
- NotificationStatus 枚举（PENDING、SENT、FAILED）
176+
- NotificationService（Send、GetStatus、ListNotifications）
177+
```
178+
179+
**生成文件：** `docs/notification-service/model.proto`
180+
181+
---
182+
183+
## Step 6 — 更新已有文档
184+
185+
对已有文档进行修改时，Agent 会：
186+
1. 读取当前文档内容
187+
2. 仅修改相关章节（最小化变更）
188+
3. 自动递增版本号（1.0 → 1.1 小改，1.0 → 2.0 大改）
189+
190+
**示例 Prompt：**
191+
```
192+
更新 docs/notification-service/tech-design.md，
193+
在 Design 章节补充 SMS 短信渠道的支持（通过阿里云短信服务），
194+
同时在 Open Questions 中添加：SMS 是否需要支持国际号码？
195+
```
196+
197+
**更新排期：**
198+
```
199+
更新 docs/notification-service/schedule.md，
200+
SMS 渠道开发延期 1 周，上线时间顺延到 2026-05-07。
201+
```
202+
203+
---
204+
205+
## 示例 Prompt 速查表
206+
207+
| 场景 | Prompt 示例 |
208+
|------|------------|
209+
| 创建全套文档 | `为 [模块名] 创建完整的设计文档，包括 links.md、tech-design.md、schedule.md 和 model.proto` |
210+
| 只创建设计文档 | `为 [模块名] 创建技术设计文档` |
211+
| 创建链接文档 | `为 [模块名] 创建 links.md，Figma: xxx，飞书: yyy，Slack: #zzz，Jira: AAA-100` |
212+
| 创建排期 | `为 [模块名] 创建排期，开发周期 [开始日期] 到 [结束日期]` |
213+
| 创建 Proto | `为 [模块名] 创建 model.proto，定义 [消息名] 和 [服务名]` |
214+
| 更新某章节 | `更新 docs/[模块名]/tech-design.md 的 [章节名]，[修改内容]` |
215+
| 拆分长文档 | `将 docs/[模块名]/tech-design.md 的 [章节] 拆分到 tech-design-part2.md` |
216+
| 更新文档状态 | `将 docs/[模块名]/tech-design.md 的状态更新为 In Review` |
217+
218+
---
219+
220+
## 常见问题
221+
222+
**Q: Agent 生成的内容不准确怎么办？**
223+
A: 在 Prompt 中提供更详细的上下文，或者分步骤让 Agent 逐节生成后再手动合并。
224+
225+
**Q: 可以一次让 Agent 生成所有文件吗？**
226+
A: 可以。在 Prompt 中说明需要生成哪些文件，Agent 会按顺序逐一创建。
227+
228+
**Q: 架构图怎么处理？**
229+
A: 优先使用 ASCII art（在 Markdown 中可直接渲染）。如需图片，将文件存放到 `docs/<模块名>/images/` 目录，在文档中用 `![描述](images/文件名.png)` 引用。
230+
231+
**Q: Protobuf 文件需要自己编译吗？**
232+
A: `model.proto` 在本仓库中仅作为设计参考文档，不包含编译配置。实际编译集成由各服务仓库负责。
233+
234+
**Q: 文档状态流转由谁负责？**
235+
A: 由文档负责人手动更新 `Status` 字段（Draft → In Review → Approved）。Agent 不会自动变更状态，除非你明确要求。

‎docs/sample/links.md‎

Lines changed: 2 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -2,45 +2,9 @@
22

33
---
44

5-
## 设计资源 / Design Resources
6-
75
| 工具 / Tool | 链接 / Link | 说明 / Description |
86
|-------------|-------------|-------------------|
97
| Figma | [User Auth UI Design](https://figma.com/file/example) | 登录 / 注册 / MFA 界面设计稿 |
10-
| FigJam | [Auth Architecture Whiteboard](https://figma.com/board/example) | 系统架构白板 |
11-
12-
---
13-
14-
## 协作文档 / Collaboration Documents
15-
16-
| 工具 / Tool | 链接 / Link | 说明 / Description |
17-
|-------------|-------------|-------------------|
188
| 飞书文档 / Feishu Doc | [用户认证需求文档](https://example.feishu.cn/docs/example) | 产品需求文档 (PRD) |
19-
| 飞书多维表格 / Feishu Base | [任务追踪表](https://example.feishu.cn/base/example) | Sprint 任务看板 |
20-
21-
---
22-
23-
## 沟通频道 / Communication Channels
24-
25-
| 平台 / Platform | 频道 / Channel | 说明 / Description |
26-
|-----------------|---------------|-------------------|
27-
| Slack | `#auth-system` | 主要讨论频道 |
28-
| 飞书群 / Feishu Group | [用户认证项目群](https://example.feishu.cn/chat/example) | 项目日常沟通 |
29-
30-
---
31-
32-
## 需求 & 工单 / Requirements & Tickets
33-
34-
| 系统 / System | 链接 / Link | 说明 / Description |
35-
|---------------|-------------|-------------------|
36-
| Jira | [AUTH-100 Epic](https://jira.example.com/browse/AUTH-100) | 用户认证系统改造 Epic |
37-
| GitHub Issues | [Issue #42](https://github.com/org/repo/issues/42) | JWT 迁移技术 Issue |
38-
39-
---
40-
41-
## 其他 / Other
42-
43-
| 说明 / Description | 链接 / Link |
44-
|--------------------|-------------|
45-
| OAuth 2.0 RFC | https://tools.ietf.org/html/rfc6749 |
46-
| JWT RFC | https://tools.ietf.org/html/rfc7519 |
9+
| Slack | `#auth-system` | 主要讨论频道 |
10+
| Jira | [AUTH-100 Epic](https://jira.example.com/browse/AUTH-100) | 用户认证系统改造 Epic |

‎templates/links-template.md‎

Lines changed: 3 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,12 @@
11
# [Module Name] — External Links
22

33
> Collect all external references for this module in one place.
4-
> Remove sections that are not applicable.
54
65
---
76

8-
## 设计资源 / Design Resources
9-
107
| 工具 / Tool | 链接 / Link | 说明 / Description |
118
|-------------|-------------|-------------------|
129
| Figma | [打开 Figma](#) | UI/UX 设计稿 |
13-
| FigJam | [打开 FigJam](#) | 架构白板图 |
14-
15-
---
16-
17-
## 协作文档 / Collaboration Documents
18-
19-
| 工具 / Tool | 链接 / Link | 说明 / Description |
20-
|-------------|-------------|-------------------|
21-
| 飞书文档 / Feishu Doc | [打开飞书文档](#) | 需求文档 / Requirements |
22-
| 飞书多维表格 / Feishu Base | [打开多维表格](#) | 任务追踪 / Task Tracking |
23-
| Confluence | [打开 Confluence](#) | 内部 Wiki |
24-
| Notion | [打开 Notion](#) | 笔记 / Notes |
25-
26-
---
27-
28-
## 沟通频道 / Communication Channels
29-
30-
| 平台 / Platform | 频道 / Channel | 说明 / Description |
31-
|-----------------|---------------|-------------------|
32-
| Slack | `#channel-name` | 主要讨论频道 |
33-
| 飞书群 / Feishu Group | [加入群组](#) | 项目群 |
34-
35-
---
36-
37-
## 需求 & 工单 / Requirements & Tickets
38-
39-
| 系统 / System | 链接 / Link | 说明 / Description |
40-
|---------------|-------------|-------------------|
41-
| Jira | [Epic / Story](#) | 需求追踪 |
42-
| GitHub Issues | [Issue #](#) | 技术 Issue |
43-
| Linear | [Project](#) | 任务看板 |
44-
45-
---
46-
47-
## 其他 / Other
48-
49-
| 说明 / Description | 链接 / Link |
50-
|--------------------|-------------|
51-
| | |
10+
| 飞书文档 / Feishu Doc | [打开飞书文档](#) | 需求文档 / PRD |
11+
| Slack | `#channel-name` | 主要讨论频道 |
12+
| Jira | [Epic / Story](#) | 需求追踪 |

0 commit comments

Comments
 (0)