README、设计文档、接口文档
- Requirement：每个项目根目录必须有
README.md，且包含以下内容：
| 章节 | 说明 | 必要性 |
|---|
| 项目简介 | 一句话说明项目是什么、解决什么问题 | 必须 |
| 功能特性 | 核心功能列表 | 必须 |
| 技术栈 | 主要技术和框架及版本 | 必须 |
| 环境要求 | Node.js 版本、包管理器、系统要求 | 必须 |
| 快速开始 | 安装、配置、启动的完整命令 | 必须 |
| 目录结构 | 顶层目录说明 | 必须 |
| 部署说明 | 构建、部署步骤 | 必须 |
| 常见问题 | 常见错误及解决方案 | 建议 |
# 项目名称
> 一句话简介：本项目是一个用于 XXX 的 XXX 系统。
## 功能特性
- 功能一：XXX
- 功能二：XXX
## 技术栈
- 前端：React 18 + TypeScript 5 + Vite 5
- 后端：FastAPI + Python 3.11
- 数据库：PostgreSQL 15 + Redis 7
## 环境要求
- Node.js >= 18
- pnpm >= 8
- Python >= 3.11
## 快速开始
### 安装依赖
```bash
pnpm install
复制 .env.example 为 .env，填入对应配置。
pnpm dev
访问 http://localhost:3000
pnpm build
pnpm preview
- **Standard**：README 中的命令必须可直接复制执行，禁止提供需要修改的命令。
- **Standard**：环境要求和依赖版本必须与实际项目一致。
- **Caution**：禁止在 README 中包含密钥、Token 等敏感信息。
| README 只有项目名 | 新人无法上手 | 按模板补全内容 |
| 启动命令无法执行 | 误导使用者 | 命令必须可运行 |
| 包含敏感信息 | 安全风险 | 用 `.env.example` 示例 |
- **Standard**：设计文档分为三类，按场景选择：
|------|----------|------|
| 技术方案（Technical Design） | 功能开发前的技术选型和实现方案 | `docs/design/xxx-technical-design.md` |
| 架构决策记录（ADR） | 重要技术决策的记录 | `docs/adr/xxx-adr.md` |
| RFC | 重大变更或争议性方案 | `docs/rfc/xxx-rfc.md` |
- **Requirement**：涉及多模块、超过 3 人日的开发任务必须编写技术方案文档。
|------|------|------|------|
| 方案 A | ... | ... | 采用 |
| 方案 B | ... | ... | 不采用 |
|------|------|----------|
|------|--------|----------|
# ADR-XXX: 决策标题
## 状态
Accepted / Proposed / Deprecated
## 背景
面临什么问题，有哪些约束。
## 决策
做出了什么决策。
## 后果
- 正面影响
- 负面影响
- 需要跟进的事项
- Standard：设计文档必须包含方案对比，说明为什么选当前方案而非其他方案。
- Standard：设计文档必须评估风险并给出应对措施。
- Caution：设计文档必须经过评审后才能开始开发，评审记录附在文档末尾。
| 反模式 | 问题 | 建议 |
|---|
| 无技术方案直接开发 | 实现混乱、返工 | 先写方案再开发 |
| 方案只有一种没有对比 | 可能不是最优解 | 提供至少两种方案对比 |
| 无风险评估 | 上线后踩坑 | 必须评估风险 |
- Requirement：后端接口必须通过 OpenAPI/Swagger 生成文档，禁止手写 Word 或 Markdown 接口文档。
- Standard：接口文档地址统一为
/docs（Swagger UI）或 /openapi.json。
- Requirement：每个接口必须包含：
- 请求方法和路径
- 接口说明（一句话描述用途）
- 请求参数（Header、Path、Query、Body）的名称、类型、是否必填、说明
- 响应体的字段说明
- 错误码说明
- 示例请求和响应
paths:
/api/users/{id}:
get:
summary: 获取用户详情
description: 根据用户 ID 获取用户详细信息
parameters:
- name: id
in: path
required: true
description: 用户 ID
schema:
type: string
responses:
'200':
description: 成功
content:
application/json:
schema:
$ref: '#/components/schemas/User'
example:
id: "123"
name: "张三"
email: "zhangsan@example.com"
'404':
description: 用户不存在
content:
application/json:
example:
code: 404
message: "用户不存在"
- Requirement：接口变更时必须同步更新 OpenAPI 定义，禁止文档与实现不一致。
- Standard：使用注解/装饰器自动生成 OpenAPI，避免手动维护两套文档。
| 反模式 | 问题 | 建议 |
|---|
| 手写 Markdown 接口文档 | 易与代码不一致 | 用 OpenAPI 自动生成 |
| 接口无示例 | 前端难以对接 | 提供请求/响应示例 |
| 文档不更新 | 误导对接方 | 接口变更同步更新文档 |
- Requirement：代码变更涉及文档时，必须在同一个 PR 中更新文档，禁止”先改代码后补文档”。
- Standard：CI 中配置文档检查，检测到接口变更但未更新 OpenAPI 时阻断合并。
- Standard：文档统一放在
docs/ 目录下，按类型分子目录：
- Standard：技术方案文档必须经过至少 1 名同事评审，评审通过后才能进入开发。
- Standard：评审意见以评论形式记录在文档中，修改后需重新确认。
- Standard：文档应标注状态：草稿（Draft）、评审中（Reviewing）、已发布（Published）、已废弃（Deprecated）。
- Caution：废弃的文档必须标记并注明替代方案，禁止直接删除。
| 反模式 | 问题 | 建议 |
|---|
| 代码和文档分开提交 | 容易遗漏文档更新 | 同一 PR 一起提交 |
| 文档散落在各处 | 难以查找 | 统一放 docs/ 目录 |
| 废弃文档直接删除 | 历史决策丢失 | 标记废弃并保留 |
- Standard：技术文档使用中文撰写，专业术语保留英文（如 API、URL、Token）。
- Standard：中英文之间、中文与数字之间加空格。
正确：使用 React 18 构建 Web 应用。
- Requirement：中文文档使用中文标点符号（，。；：""），代码和英文术语除外。
- Standard：列表项末尾不加分号，最后一项不加句号（除非是完整句子）。
- Standard：同一概念在文档中使用统一术语，禁止混用。
| 推荐术语 | 避免使用 |
|---|
| 接口（API） | 端口、API 接口 |
| 参数（Parameter） | 入参、形参（非必要） |
| 返回值（Return value） | 返回结果、输出 |
| 部署（Deploy） | 发布、上线（视语境） |
| 配置（Configuration） | 设置（技术语境） |
- Standard：代码示例必须可复制运行，包含必要的 import 和上下文。
- Standard：代码块必须指定语言（```typescript），支持语法高亮。
- Caution：示例代码禁止包含真实密钥、Token、内部地址。
| 反模式 | 问题 | 建议 |
|---|
| 中英文无空格 | 阅读困难 | 中英文之间加空格 |
| 中英文标点混用 | 不规范 | 中文用中文标点 |
| 术语不统一 | 歧义 | 统一术语表 |
| 代码示例缺 import | 无法运行 | 补全上下文 |
沪公网安备31010702010612号