ClaudeCode项目规范 - 404 Not Found.

开发规范（Development Guidelines）#

测试协议（Testing Protocol）#

实现与测试分离
Claude 负责功能实现，用户负责测试
用户会提供测试结果与错误信息
Claude 仅在用户报告问题时介入
不要自动启动测试服务器或执行测试命令

库与文档规范（Library Documentation）#

始终先查阅官方文档：在使用任何库或包前，必须通过 Context7 获取最新版文档
文档优先级：官方文档优先于假设或过时知识
推荐工作流程：
1. 确定所需库或包
2. 使用 Context7 获取最新文档
3. 查阅 API 与最佳实践
4. 按照文档规范进行实现

语言与交流（Language and Communication）#

整个开发过程使用中文：所有回复、注释与讨论均应使用中文
代码注释：统一使用中文，保持一致性
变量/函数命名：保持英文，遵循标准命名规范
技术文档：默认使用中文编写，除非另有说明

CHANGELOG 管理（CHANGELOG Management）#

每个功能完成后都要创建摘要：每个新功能 / 需求 / 优化都必须在 CHANGELOG 中记录
按日期组织：若现有 CHANGELOG 未按日期排序，应重组为按日期格式
按时间顺序排列：后续的条目必须依时间顺序添加

条目格式示例：

1
## [YYYY-MM-DD]
2

3
### 新增 (Added)
4
- 功能描述
5

6
### 修改 (Changed)
7
- 修改描述
8

9
### 修复 (Fixed)
10
- 修复描述
11

12
### 优化 (Optimized)
13
- 优化描述

及时更新：完成任务后立即更新 CHANGELOG，不要集中补写

依赖管理（Dependency Management）#

绝对不要自动执行包管理命令（例如 pnpm install / pnpm add）
当需要新依赖时，应提供一份明确的依赖清单及对应命令
在得到用户确认前不要继续实现
用户会手动添加依赖并在完成后通知

代码复用性（Code Reusability）#

当实现可跨项目复用的功能时，应将其设计为独立模块
将通用逻辑提取到单独且文档齐全的模块中

前端组件开发（Frontend Component Development）#

绝对不要手动直接创建 shadcn/ui 组件
当需要使用 shadcn/ui 组件时，先提供所需组件的清单
等待用户通过 shadcn CLI 添加组件后再进行实现
优先使用 @/shared/ui/ 下已有的共享组件
遵循既定的路径别名： @/widgets、@/shared/ui、@/shared/lib 等

前端组件组织（Frontend Component Organization）#

单文件单组件原则：每个组件一个文件，且单个组件文件最多 300 行

复杂组件结构处理方式：

若为简单组合组件（子组件少），可采用单文件方式（如 tab.tsx）

若为复杂组合组件（子组件多），应采用文件夹组织形式并通过 index.ts 导出：

1
tab/
2
├── index.ts          # 导出所有组件
3
├── tab.tsx           # 主组件 Tab
4
├── tab-content.tsx   # 子组件 Tab.Content
5
├── tab-controls.tsx  # 子组件 Tab.Controls
6
├── context.ts        # Context 与 useXxx hooks（如需要）
7
└── types.ts          # 类型定义（如需要）

基于 Context 的组件：建立组件文件夹，包含以下文件：
- context.ts: 定义 Context 及其消费 hooks
- types.ts: 定义组件与子组件类型
- 各独立组件文件
- index.ts: 统一导出入口

NestJS模块复用性（NestJS Module Reusability）#

遵循 NestJS 的最佳实践来创建可复用模块
示例：配置管理模块、日志模块、认证模块应保持与具体项目无关

重要执行提醒（important-instruction-reminders）#

只做被要求的事，不多也不少
除非必要，否则不要创建新文件
优先编辑已有文件，而非新建文件
*绝对不要主动创建文档文件（如 .md 或 README）
仅在用户明确要求时才可创建文档文件

以下为Markdown格式项目开发规范（可以直接复制到Claude.md中）#

文件头部内容#

1
## 项目概览
2
本项目是xxxxx，详细信息请参考：@README.md
3

4
## 技术规范
5
- **编码规范**: @./docs/coding-style.md
6
- **API 文档**: @./docs/api-reference.md
7
- **可用脚本**: 请参考 @package.json 中的 "scripts" 部分。

通用基础规范#

1
## 开发规范（Development Guidelines）
2

3
### 测试协议（Testing Protocol）
4

5
* **实现与测试分离**
6
* Claude 负责功能实现，用户负责测试
7
* 用户会提供测试结果与错误信息
8
* Claude 仅在用户报告问题时介入
9
* **不要自动启动测试服务器或执行测试命令**
10

11
### 库与文档规范（Library Documentation）
12

13
* **始终先查阅官方文档**：在使用任何库或包前，必须通过 **Context7** 获取最新版文档
14
* **文档优先级**：官方文档优先于假设或过时知识
15
* **推荐工作流程**：
16

17
  1. 确定所需库或包
18
  2. 使用 Context7 获取最新文档
19
  3. 查阅 API 与最佳实践
20
  4. 按照文档规范进行实现
21

22
### 语言与交流（Language and Communication）
23

24
* **整个开发过程使用中文**：所有回复、注释与讨论均应使用中文
25
* **代码注释**：统一使用中文，保持一致性
26
* **变量/函数命名**：保持英文，遵循标准命名规范
27
* **技术文档**：默认使用中文编写，除非另有说明
28

29
### CHANGELOG 管理（CHANGELOG Management）
30

31
* **每个功能完成后都要创建摘要**：每个新功能 / 需求 / 优化都必须在 CHANGELOG 中记录
32
* **按日期组织**：若现有 CHANGELOG 未按日期排序，应重组为按日期格式
33
* **按时间顺序排列**：后续的条目必须依时间顺序添加
34
* **条目格式示例**：
35

36
  ```markdown
37
  ## [YYYY-MM-DD]
38

39
  ### 新增 (Added)
40
  - 功能描述
41

42
  ### 修改 (Changed)
43
  - 修改描述
44

45
  ### 修复 (Fixed)
46
  - 修复描述
47

48
  ### 优化 (Optimized)
49
  - 优化描述
50
  ```
51
* **及时更新**：完成任务后立即更新 CHANGELOG，不要集中补写
52

53
## 重要执行提醒（important-instruction-reminders）
54

55
* **只做被要求的事，不多也不少**
56
* **除非必要，否则不要创建新文件**
57
* **优先编辑已有文件，而非新建文件**
58
* **绝对不要主动创建文档文件（如 *.md 或 README）**
59
* **仅在用户明确要求时才可创建文档文件**

前端补充规范#

1
### 依赖管理（Dependency Management）
2

3
* **绝对不要自动执行包管理命令**（例如 `pnpm install` / `pnpm add`）
4
* 当需要新依赖时，应提供一份**明确的依赖清单及对应命令**
5
* **在得到用户确认前不要继续实现**
6
* 用户会手动添加依赖并在完成后通知
7

8
### 代码复用性（Code Reusability）
9

10
* 当实现可跨项目复用的功能时，应将其设计为**独立模块**
11
* 将通用逻辑提取到**单独且文档齐全的模块**中
12

13
### 前端组件开发（Frontend Component Development）
14

15
* **绝对不要手动直接创建 shadcn/ui 组件**
16
* 当需要使用 shadcn/ui 组件时，先提供**所需组件的清单**
17
* 等待用户通过 **shadcn CLI** 添加组件后再进行实现
18
* 优先使用 `@/shared/ui/` 下已有的共享组件
19
* 遵循既定的路径别名：
20
  `@/widgets`、`@/shared/ui`、`@/shared/lib` 等
21

22
### 前端组件组织（Frontend Component Organization）
23

24
* **单文件单组件原则**：每个组件一个文件，且单个组件文件最多 300 行
25
* **复杂组件结构处理方式**：
26

27
  * 若为简单组合组件（子组件少），可采用单文件方式（如 `tab.tsx`）
28
  * 若为复杂组合组件（子组件多），应采用文件夹组织形式并通过 `index.ts` 导出：
29

30
    ```text
31
    tab/
32
    ├── index.ts          # 导出所有组件
33
    ├── tab.tsx           # 主组件 Tab
34
    ├── tab-content.tsx   # 子组件 Tab.Content
35
    ├── tab-controls.tsx  # 子组件 Tab.Controls
36
    ├── context.ts        # Context 与 useXxx hooks（如需要）
37
    └── types.ts          # 类型定义（如需要）
38
    ```
39
* **基于 Context 的组件**：
40
  建立组件文件夹，包含以下文件：
41

42
  * `context.ts`: 定义 Context 及其消费 hooks
43
  * `types.ts`: 定义组件与子组件类型
44
  * 各独立组件文件
45
  * `index.ts`: 统一导出入口
46

47
### NestJS模块复用性（NestJS Module Reusability）
48

49
* 遵循 **NestJS** 的最佳实践来创建可复用模块
50
* 示例：配置管理模块、日志模块、认证模块应保持与具体项目无关

2025.12.03更新#

1
## AI 开发规则
2

3
### 新功能开发流程
4

5
**重要**: 在实现任何新需求时，必须遵循以下流程：
6

7
1. **设计阶段** - 首先进行详细设计
8
   - 创建设计文档，命名格式: `docs/feature-<需求名称>.md`
9
   - 文档必须包含以下内容:
10
     - **核心原理**: 功能的技术原理和设计思路
11
     - **实现步骤**: 详细的实现步骤和顺序
12
     - **文件变更清单**:
13
       - 需要修改的文件及修改内容
14
       - 需要创建的文件及其用途
15
       - 需要删除的文件及原因
16
     - **核心实现代码**: 关键代码片段和实现逻辑
17
     - **测试计划**: 如何验证功能是否正确实现
18
     - **潜在风险**: 可能遇到的问题和解决方案
19

20
2. **审核阶段** - 等待用户确认
21
   - 将设计文档提交给用户审核
22
   - 根据用户反馈修改设计文档
23
   - 只有在用户明确确认后才能进入实施阶段
24

25
3. **实施阶段** - 严格按照文档执行
26
   - 严格按照设计文档中的步骤实施
27
   - 每完成一个步骤，更新文档状态
28
   - 遇到与设计不符的情况，先暂停并咨询用户
29

30
4. **文档查询规则**
31
   - 在实现过程中涉及到需要调用第三方库时
32
   - **必须先使用 Context7 查询对应库的官方文档**
33
   - 参考官方文档的最佳实践和推荐用法
34
   - 避免使用过时或不推荐的 API
35

36
5. **完成阶段** - 更新项目文档
37
   - **更新 CHANGELOG**: 将设计文档链接添加到 `CHANGELOG.md` 对应日期下
38
   - **更新上下文文件**: 定期更新 `CLAUDE.md` 等上下文文件，防止进度丢失
39
   - 记录重要的架构变更和技术决策
40

41
6. **测试规则**
42
   - **禁止 AI 自行运行项目或测试**: 所有功能完成后，由用户来运行和测试
43
   - AI 只负责编写代码，用户负责验证和测试
44
   - 用户会告知测试结果，AI 根据反馈进行调整
45
   - 这条规则确保用户对项目运行有完全控制权
46

47
### 文档维护规则
48

49
#### 1. CHANGELOG 更新规范
50

51
每个需求实现完成后，必须在 `CHANGELOG.md` 文件中添加条目：
52

53
- **文件位置**: 项目根目录的 `CHANGELOG.md`
54
- **更新位置**: 在文件顶部添加新的日期条目（保持倒序，最新的在最上面）
55
- **条目格式**:
56
  ```markdown
57
  ## YYYY-MM-DD
58

59
  ### 新增功能
60

61
  - **[功能名称](./docs/feature-功能名称.md)**
62
    - 功能描述
63
    - 主要变更文件
64
    - 影响范围
65

66
  ### 修复
67

68
  - **[问题描述](./docs/fix-问题描述.md)**
69
    - 问题原因
70
    - 解决方案
71
    - 影响范围
72

73
  ### 优化
74

75
  - **[优化项](./docs/improve-优化项.md)**
76
    - 优化内容
77
    - 性能提升
78
    - 影响范围
79
  ```
80

81
#### 2. 上下文文件更新规范
82

83
在每个重要需求完成后，必须更新以下文件：
84

85
- **CLAUDE.md**:
86
  - 更新项目结构（如有新增目录或重要文件）
87
  - 更新核心功能说明（如有新增功能模块）
88
  - 更新最佳实践（如有新的开发规范）
89
  - 更新故障排除（如有新的常见问题）
90

91
- **README.md**:
92
  - 更新用户文档
93
  - 更新使用说明
94
  - 更新部署指南
95

96
- **docs/README.md**:
97
  - 更新设计文档索引
98
  - 记录重要的技术决策
99

100
#### 3. 更新时机
101

102
- ✅ **必须更新**: 新增功能、重大重构、架构变更
103
- ✅ **建议更新**: 性能优化、安全修复、依赖升级
104
- ⚠️ **可选更新**: 小的 bug 修复、文案调整、样式优化
105

106
### 例外情况
107

108
如果用户明确说明某个需求**不需要设计，直接实现**，则可以跳过设计阶段，直接进入实施。
109

110
### 设计文档模板
111

112
以下是设计文档的标准模板格式：
113

114
````markdown
115
# Feature: <功能名称>
116

117
## 需求描述
118
[简要描述功能需求]
119

120
## 核心原理
121
[技术原理和设计思路]
122

123
## 实现步骤
124
1. [步骤1]
125
2. [步骤2]
126
...
127

128
## 文件变更清单
129

130
### 需要创建的文件
131
- `path/to/file.ts` - [文件用途]
132

133
### 需要修改的文件
134
- `path/to/file.ts`
135
  - [修改内容1]
136
  - [修改内容2]
137

138
### 需要删除的文件
139
- `path/to/file.ts` - [删除原因]
140

141
## 核心实现代码
142

143
### 文件名: `path/to/file.ts`
144
```typescript
145
// 关键代码实现
146
```
147

148
## 依赖项
149
- [需要安装的包]
150
- [需要查询文档的库]
151

152
## 测试计划
153
1. [测试场景1]
154
2. [测试场景2]
155

156
## 潜在风险
157
- [风险1及解决方案]
158
- [风险2及解决方案]
159

160
## 实施进度
161
- [ ] 步骤1
162
- [ ] 步骤2
163
...
164
````