# 如何使用产品研发规范库

这份指南面向产品、设计、研发人员和 Agent，说明如何查找、判断并应用本库的研发规范。本库提供可复用的原则与实践参考，不自动构成某个具体产品的需求、技术决策或验收标准。

## 先看任务，再选规范

按当前任务选择少量相关内容，而不是从头读完整个库：

- 产品目标、范围和验收：查看“产品 → 需求与验收”。
- 页面结构、视觉和交互：查看“界面 → 设计原则”或“界面基础”。
- 业务事实、状态、权限和数据：查看“业务 → 规则与数据”。
- 项目初始化、架构、后端边界、性能、资源或协作交付：查看对应的“工程”主题。

如果一项任务跨多个领域，先选直接指导交付的文章，再补充一篇相关的横向规范。例如，新增上传体验可能同时涉及界面、业务规则、静态资源与对象存储。只读取足以指导当前决策的内容。

## 人类读者

1. 从左侧“领域 → 主题 → 文章”浏览，或用搜索查找任务中的概念和同义词。
2. 阅读文章开头的适用范围，再看具体原则、例子和限制条件。
3. 点击文章中的“Markdown 原文”可查看纯文本，便于引用、保存或交给 Agent。
4. 将通用建议映射到当前产品的用户、任务、设计系统、技术栈和团队流程；不适用的建议应说明原因，而不是为了形式照搬。

本库中的项目案例和来源说明帮助读者理解建议的来处，不代表参考项目的产品细节也适用于当前项目。

## Agent

公开站点可直接作为阅读入口：

- `/llms.txt`：按领域与主题组织的文章目录，适合先定位内容。
- `/index.json`：结构化文章目录，包含页面与 Markdown 原文地址。
- `/search-index.json`：站内搜索使用的文章索引。
- `/content/<领域>/<主题>/<文章>.md`：单篇 Markdown 原文，适合作为实际阅读内容。
- `/docs/<领域>/<主题>/<文章>/`：人类可读的网页文章。

推荐的 Agent 工作顺序：

1. 从任务中提取领域、用户任务和待决定的问题。
2. 检索 `/llms.txt` 或 `/index.json`，只选择直接相关的文章；跨领域任务再补充必要的横向规范。
3. 读取所选文章的 Markdown 原文，并查看目标项目的 `AGENTS.md`、现有实现、设计系统与文档。
4. 区分已确认的项目事实、用户要求和本库提供的通用建议。检查每条建议的适用前提；不要把案例、默认技术选型或示例流程描述成项目既定事实。
5. 按任务完成实现或分析，并使用与改动风险相称的方式验证。交付时指出实际采用了哪些规范、哪些不适用，以及重要假设或尚未验证的事项。

发生规则冲突时，先识别各规则的来源、适用范围和优先级。项目规范库是参考资料，不会自动覆盖当前会话指令、用户明确要求或目标项目约定；若冲突会改变结果或风险，向用户清楚说明后再处理。

可将下面的提示与具体任务一起发送给 Agent：

```text
请先阅读 https://docs.tzxys.cn/llms.txt，按当前任务选择最相关的规范，并读取对应的 Markdown 原文。
结合目标项目的 AGENTS.md、现有实现和用户要求判断适用性；不要把通用建议或参考案例当作已确认的项目需求。
完成任务后说明采用的规范、关键假设、验证结果和未解决事项。
当前任务：<描述任务>
目标项目：<项目目录或仓库>
验收要求：<描述结果>
```

如果 Agent 不能访问公网，将相关 Markdown 原文或仓库中的 `content/` 文章直接提供给它。不要发送只在你自己电脑上可访问的本机预览地址。

## 更新本库

Markdown 正文位于 `content/`，目录和显示顺序由 `content/catalog.json` 管理。更新文章后运行 `npm run build` 检查目录、索引和链接，再按仓库 README 的发布说明更新线上静态文件。不要直接编辑 `dist/`。