> For the complete documentation index, see [llms.txt](https://zhouhao4221.gitbook.io/haiqing-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zhouhao4221.gitbook.io/haiqing-docs/04-prompt/design/architecture-design.md).

# 架构设计

为新功能或系统生成架构方案选项，供人工评估和决策。输出是多个选项，不是决定——最终架构由人工做出。

***

## 什么时候用

* 要新建一个模块或服务，不确定整体结构
* 有多种技术方向，需要梳理权衡再决定
* 现有架构遇到瓶颈，考虑重构或拆分

不适合的场景：功能边界已经明确、技术方向已经确定，那就直接进入代码生成。

## 准备什么

* **需求描述**：功能目标，用结构化格式写（参考 `workflow/requirement-structuring.md`）。越具体，方案越贴合实际
* **现有系统背景**：相关的现有模块、数据流、技术栈。这是最影响方案质量的输入——AI 不了解你的历史包袱
* **约束**：必须用的技术、团队能力边界、性能/安全要求
* **规模预期**：数据量级、并发量、团队维护能力

"现有系统背景"是最容易填得过于笼统的输入。"我们用的是微服务架构"不够——要说具体哪些服务已经存在、它们的职责边界是什么、团队对哪些技术熟悉。

## 怎么触发

**单次任务**

```
先读 04-prompt/design/architecture-design.md，
需求描述：[结构化需求]，
现有系统背景：[相关模块和技术栈]，
约束：[列出]，
规模预期：[数据量、并发、团队规模]。
请给出 2-3 个有实质差异的架构方案。
```

## 好的输出是什么样的

* 2-3 个方案有实质差异，不是同一思路的微调
* 每个方案有清晰的优势和劣势，不是只说优点
* 推荐方案有具体理由，而不只是"综合考虑推荐方案 A"
* 列出在做最终决策前需要澄清的问题（如果有）

判断方案有没有实质差异：不同方案应该在"数据存在哪里"或"谁调用谁"上有根本不同，而不只是用了不同的库。

## 常见失败模式

* **方案都是同一个思路**：约束描述不够具体，AI 没有足够的信息生成有差异的方案。把团队的真实限制（不熟悉 Kafka、数据库不能拆分等）明确写进约束
* **没有权衡**：输出只说优点，不说引入的复杂性。要求每个方案必须说"引入了什么风险或复杂性"
* **推荐理由空洞**："综合考虑方案 A 最优"——问 AI：这个场景下最关键的权衡是什么，为什么方案 A 在这个维度上更好
* **忽略团队能力**：AI 推荐了一个技术上最优但团队没人维护过的方案。约束里明确写出团队的技术熟悉程度

***

## 版本历史

* v1.0：初始版本


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://zhouhao4221.gitbook.io/haiqing-docs/04-prompt/design/architecture-design.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.