我的 AI 工作流 —— project_rules.md 代码规范篇，让 AI 自省自动跑起来

本文基于 Trae Solo IDE

重点 TL;DR

通过 tsc-files 让 AI 在每轮代码生成后"自动"进行严格类型检测（"strict": true），给 AI 添加"自省"能力，让其"闭环"自动跑出高质量代码。

Project rules

入口：Trae 右上角齿轮设置 - Rules - Create project_rules.md

或直接新建文件：.trae\rules\project_rules.md，project_rules 将分两部分

## Technical Stack
- 技术栈
- 构建工具
- 包管理器

## Code Style Guidelines

### Part 1. General Coding Guidelines
### Part 2. Frontend Coding Guidelines
### Part 3. Project Coding Guidelines

我的项目 project_rules：

## Technical Stack
- **技术栈**：React v19, Ant Design v5, TypeScript v5, tailwindcss v4,
- **构建工具**：Rsbuild
- **包管理器**：pnpm (>= 9.0.0)
- **代码格式化和 lint**：Biome
- **操作系统**：Windows，但请使用 git bash 运行命令而非 powershell

## Coding Guidelines

### Part 1. General Coding Guidelines

<!--《中文文案排版指北》可选，大家酌情增加，详见文章后半部分 -->
文案请按照中文文案排版指北，先阅读这份文档 docs/README.zh-Hans.md。

#### 1. Basic Principles
- DRY (Don't Repeat Yourself) 原则：避免重复代码。
- SRP (Single Responsibility Principle) 原则：每个模块、函数或类应该只有一个职责。
- KISS (Keep It Simple, Stupid) 原则：保持代码简单、直接，避免复杂的逻辑。

#### 2. Comments & Documentation
- Only generate necessary comments. Comments should explain why, not what.
- Provide clear documentation for public APIs.
- Update comments to reflect code changes.

### Part 2. Frontend Coding Guidelines

#### 1. Code Structure
- Use functional components with hooks.
- Organize components in a feature-based folder structure.
- Use TypeScript for type safety.

#### 2. Styling
- Use tailwindcss for utility-first styling.
- Avoid inline styles; use antd components and necessary tailwindcss classes.

### Part 3. Project Coding Guidelines
1. Use pnpm instead of npm.
1. Avoid inline styles; use antd components and necessary tailwindcss classes. If necessary, please clearly state the reason in the comment.
1. Do not use react-router-dom. This project is a react-router v7 project, so please use react-router.
1. Import types with type prefix, e.g. `IMcpServerRecord`.
1. For type checking after modifications, use: `bun scripts/tsc-files.mjs --noEmit <related_files>` (checks **only relevant files**). Avoid `npx tsc ...` as it doesn't respect project type configuration and shows errors from unrelated files, generating many false positives.
1. 新代码请使用 es-toolkit 而非 lodash。老代码 lodash 类型报错请使用 `// @ts-expect-error` 注释忽略。
1. 新代码请勿使用 `dva` 的 `connect`。比如获取 `orgId`，应该使用 `useOrgId`，它基于 `@tanstack/react-query` 的 `useQuery`。如果其他全局服务端数据没有，应该如 `useOrgId` 封装新的 `useXxx`，并且在 `src/lib/prefetchGlobalServerData.tsx` 中添加预取逻辑。

[可选]
1. 每次修改完毕执行 `npx biome check --diagnostic-level=error --write <related_files>` 检查**涉及到**的文件

project_rules github 地址。

!NOTE 注意每次修改 project_rules.md 都需要告知 AI"重新阅读 .trae\rules\project_rules.md"。

上述中英文夹杂，建议全部中文，因为这份 rules 也需要团队成员阅读并执行。

重点解释

一、Basic Principles

- DRY (Don't Repeat Yourself) 原则：避免重复代码。
- SRP (Single Responsibility Principle) 原则：每个模块、函数或类应该只有一个职责。
- KISS (Keep It Simple, Stupid) 原则：保持代码简单、直接，避免复杂的逻辑。

我为什么只选择了这三条，甚至觉得有些都可删除，详见AI 每日心得------AI 是效率杠杆，而非培养对象 ，请大家酌情增加。

二、类型检查 tsc-files

tsc-files 类型检查工具。为什么要让 AI 检查类型？因为 AI 生成的代码如果类型有问题一般意味代码有 bug，而通常类型问题修复后代码 bug 也自行消除了，故类型检查是 AI 结束编码后保证代码质量，闭环的重要一个环节！

第二个为什么 ：为什么用社区的 tsc-files 而非 tsc 即 npx tsc --noEmit file1 file2，因为 tsc 不争气呀，社区 issue#27379 一直没有处理 ：即当传入文件则不会使用 tsconfig.json 导致大量误报，若同时指定 -p / --project tsconfig.json 则报错 error TS5042: Option 'project' cannot be mixed with source files on a command line.，即不能既指定文件又指定配置文件。

!TIP tsc-files 原理：底层当然也是使用 tsc，只是复制当前项目的 tsconfig.json 配置文件清空 include 新增 files 其值为仅传入的文件，这样无需通过参数指定待检测文件却能达到检测特定文件的目的，类似运行：tsc -p tsconfig.<random-chars>.json。

第三个为什么 ：社区有 tsc-files 为什么自定义 scripts/tsc-files.mjs？tsc-files 也有自己的问题。故修改如下：

• 问题修复：tsc-files 对 tsc 二进制文件路径解析不正确导致 pnpm 项目无法工作。
• 新增功能：仅显示指定文件的错误 ，若其他文件引发类型错误仍然认为类型检测成功。（tsc 会暴露其他文件问题导致 TRAE 会将 改动范围扩大化，这是不允许的！ 尤其是在大型代码库中。）

第四个为什么 ：为什么 tsgo ------ Go 语言对 TypeScript 进行全面重写 而非 tsc 因为 tsgo 速度快 ⚡，详见我的另一篇文章 tsgo 相比 tsc 确实有巨大性能提升。

!NOTE

1. 需先下载 npm i @typescript/native-preview -D
2. 大家可以对比下速度，将 github.com/legend80s/c... typescriptCompiler 改成 tsc 就可以体会到巨大的性能落差。

完整 scripts/tsc-files.mjs 代码见 tsc-files.mjs ~ github。

使用 tsc-files 案例或效果

未告知 AI 使用 tsc-files，生成代码有问题导致 rsbuild dev 报错：

[🦀] error   Build error:
[🦀] File: D:\workspace\project\src\pages\mcpServer\details\index.tsx:1:1
[🦀]   × ESModulesLinkingError: export 'mockData' (imported as 'mockData') was not found in '../service' (possible exports: IMcpSe
rverStatus, McpServerService, McpServerStatusValueEnum)
[🦀]     ╭─[23:29]
[🦀]  21 │                 // 在真实环境中，这里会调用 API 获取数据
[🦀]  22 │                 // 现在使用 mockData 模拟
[🦀]  23 │                 const data = mockData.find((item)=>item.id === id);
[🦀]     ·                              ─────────────
[🦀]  24 │                 // 如果没有找到对应 ID 的数据，使用默认数据
[🦀]  25 │                 const defaultData = {
[🦀]     ╰────

🦀 × ESModulesLinkingError: export 'mockData' (imported as 'mockData') was not found in '../service'

这是因为 service 并未导出 mockData，这种错误人类一眼就知有 TS error，因为我们的编辑器会标红，若安装了 Error Lens 插件则错误更加一目了然，但是 AI 不知道到，ta 还没有进化到直接看你编辑器的能力。

当我们加入规则让 AI 每次生成代码后都执行 tsc-files。

现在我们让 TRAE 自行进行类型检查：

截图可见 trae 执行了 bun scripts/tsc-files.mjs 并且仅对改动的代码执行，而且不止发现了一个问题。

TRAE 自动修复如下：

- import { McpServerStatusValueEnum, mockData } from '../service';
+ import { McpServerService } from '../service';

const { Title, Paragraph, Text } = Typography;

@ src/pages/mcpServer/details/index.tsx:26 @ const McpServerDetailsPage = () => {
      setLoading(true);
      try {
        // 在真实环境中，这里会调用 API 获取数据
        // 现在使用 mockData 模拟
-        const data = mockData.find(item => item.id === id);
+        // 使用service中的details方法获取数据
+        const data = await McpServerService.details({ id });

通过修复 ts 类型错误，Trae AI 甚至理解到了我们的代码意图：应该使用 service 中的 details 方法获取数据，而不是从 service 导出 mockData 然后对其操作，awsome 🤩！

三、biome check：lint & format #可选

npx biome check --diagnostic-level=error --write <related_files>

为什么 biome check 而非 eslint ：biome 速度好意味着 AI 生成代码耗费时间少，其次 biome check 兼备 format 和 lint，和 tsc-files 一样消除 lint error 也能避免 bug，同时 format 能让生成的代码 style 自动符合项目要求。

为什么使用 npx ：因为 pnpx、bunx 会下载远程 biome 而我们本地已安装 biome，速度反而慢。

为什么可选 ：这个看自己实际使用效果而定。有些问题人工修复更好否则 AI 会陷入及其复杂的代码中"不可自拔"，其次命令不是越多越好，就目前而言自执行轮数越多，Trae 可能会"罢工"让你自行停止然后开启新对话。

比如人可以通过一些指令快速消除无谓的 lint 错误：

// biome-ignore lint/security/noGlobalEval: Use 'eval' to read the JSON as regular JavaScript syntax so that comments are allowed
eval(`tsconfig = ${tsconfigContent}`);

案例说明 ：eval 会导致 biome lint 报错，因为我们都知道 eval 是"evil 👿 的"，但这里用其实是安全的，因为项目的 tsconfig.json 不可能隐藏危险的可执行代码，而且 eval 能将 tsconfig.json 里的注释自动去掉，人类一个指令 biome-ignore lint/security/noGlobalEval 即可消除 IDE 报错，但是如果让 AI 来解决可能会生成一段极度复杂的代码 🤯。

四、中文文案排版指北 #可选

先讲下为何"可选"，因为执行统一的"文案排版规范"还是比较不现实的，虽然蚂蚁等大厂在程序员之间执行比较好（可以看看 antd 的文档），但实际业务很难。就拿"空格"而言，业务文案很难做到"中英文之间需要增加空格"，但是我们自己的文章、文档或代码注释还是可以自我约束的。所以这里还是列出来吧。

其次我对"指北"内容进行了修改，大家也可以自行根据项目调整。

1 下载

mkdir docs && cd docs
curl -O https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.md

2 修改：简体中文使用非直角引号

---
原文：https://github.com/sparanoid/chinese-copywriting-guidelines/blob/master/README.zh-Hans.md 
修改：简体中文使用非直角引号。根据[百度百科](https://baike.baidu.com/item/%E5%8F%8C%E5%BC%95%E5%8F%B7/10758658)将直角引号修改成大陆中文的引号 "中国大陆地区标准：先用双引号" "，内部如需再引用，再用单引号''"
删除："工具"和"谁在这么做"
---

# 中文文案排版指北

统一中文文案、排版的相关用法，降低团队成员之间的沟通成本，增强网站气质。

Other languages:

- [英语](README.en.md)
- [繁体中文](README.md)
- [简体中文](README.zh-Hans.md)

* * *

## 空格

> "有研究显示，打字的时候不喜欢在中文和英文之间加空格的人，感情路都走得很辛苦，有七成的比例会在 34 岁的时候跟自己不爱的人结婚，而其余三成的人最后只能把遗产留给自己的猫。毕竟爱情跟书写都需要适时地留白。
>
> 与大家共勉之。"------[vinta/paranoid-auto-spacing](https://github.com/vinta/pangu.js)

### 中英文之间需要增加空格

正确：

> 在 LeanCloud 上，数据存储是围绕 `AVObject` 进行的。

错误：

> 在LeanCloud上，数据存储是围绕`AVObject`进行的。
>
> 在 LeanCloud上，数据存储是围绕`AVObject` 进行的。

完整的正确用法：

> 在 LeanCloud 上，数据存储是围绕 `AVObject` 进行的。每个 `AVObject` 都包含了与 JSON 兼容的 key-value 对应的数据。数据是 schema-free 的，你不需要在每个 `AVObject` 上提前指定存在哪些键，只要直接设定对应的 key-value 即可。

例外："豆瓣FM"等产品名词，按照官方所定义的格式书写。

### 中文与数字之间需要增加空格

正确：

> 今天出去买菜花了 5000 元。

错误：

> 今天出去买菜花了 5000元。
>
> 今天出去买菜花了5000元。

### 数字与单位之间需要增加空格

正确：

> 我家的光纤入屋宽带有 10 Gbps，SSD 一共有 20 TB

错误：

> 我家的光纤入屋宽带有 10Gbps，SSD 一共有 20TB

例外：度数／百分比与数字之间不需要增加空格：

正确：

> 角度为 90° 的角，就是直角。
>
> 新 MacBook Pro 有 15% 的 CPU 性能提升。

错误：

> 角度为 90 ° 的角，就是直角。
>
> 新 MacBook Pro 有 15 % 的 CPU 性能提升。

### 全角标点与其他字符之间不加空格

正确：

> 刚刚买了一部 iPhone，好开心！

错误：

> 刚刚买了一部 iPhone ，好开心！
>
> 刚刚买了一部 iPhone， 好开心！

### 用 `text-spacing` 来挽救？

CSS Text Module Level 4 的 [`text-spacing`](https://www.w3.org/TR/css-text-4/#text-spacing-property) 和 Microsoft 的 [`-ms-text-autospace`](https://msdn.microsoft.com/library/ms531164(v=vs.85).aspx) 可以实现自动为中英文之间增加空白。不过目前并未普及，另外在其他应用场景，例如 macOS、iOS、Windows 等用户界面目前并不存在这个特性，所以请继续保持随手加空格的习惯。

## 标点符号

### 不重复使用标点符号

虽然中国大陆的标点符号用法允许重复使用标点符号，但是这么做会破坏句子的美观性。

正确：

> 德国队竟然战胜了巴西队！
>
> 她竟然对你说"喵"？！

错误：

> 德国队竟然战胜了巴西队！！
>
> 德国队竟然战胜了巴西队！！！！！！！！
>
> 她竟然对你说"喵"？？！！
>
> 她竟然对你说"喵"？！？！？？！！

## 全角和半角

不明白什么是全角（全形）与半角（半形）符号？请查看维基百科条目[全角和半角](https://zh.wikipedia.org/wiki/%E5%85%A8%E5%BD%A2%E5%92%8C%E5%8D%8A%E5%BD%A2)。

### 使用全角中文标点

正确：

> 嗨！你知道嘛？今天前台的小妹跟我说"喵"了哎！
>
> 核磁共振成像（NMRI）是什么原理都不知道？JFGI！

错误：

> 嗨! 你知道嘛? 今天前台的小妹跟我说 "喵" 了哎！
>
> 嗨!你知道嘛?今天前台的小妹跟我说"喵"了哎！
>
> 核磁共振成像 (NMRI) 是什么原理都不知道? JFGI!
>
> 核磁共振成像(NMRI)是什么原理都不知道?JFGI!

例外：中文句子内夹有英文书籍名、报刊名时，不应借用中文书名号，应以英文斜体表示。

### 数字使用半角字符

正确：

> 这个蛋糕只卖 1000 元。

错误：

> 这个蛋糕只卖 １０００ 元。

例外：在设计稿、宣传海报中如出现极少量数字的情形时，为方便文字对齐，是可以使用全角数字的。

### 遇到完整的英文整句、特殊名词，其内容使用半角标点

正确：

> 乔布斯那句话是怎么说的？"Stay hungry, stay foolish."
>
> 推荐你阅读 *Hackers & Painters: Big Ideas from the Computer Age*，非常地有趣。

错误：

> 乔布斯那句话是怎么说的？"Stay hungry，stay foolish。"
>
> 推荐你阅读《Hackers＆Painters：Big Ideas from the Computer Age》，非常的有趣。

## 名词

### 专有名词使用正确的大小写

大小写相关用法原属于英文书写范畴，不属于本 wiki 讨论内容，在这里只对部分易错用法进行简述。

正确：

> 使用 GitHub 登录
>
> 我们的客户有 GitHub、Foursquare、Microsoft Corporation、Google、Facebook, Inc.。

错误：

> 使用 github 登录
>
> 使用 GITHUB 登录
>
> 使用 Github 登录
>
> 使用 gitHub 登录
>
> 使用 gｲんĤЦ8 登录
>
> 我们的客户有 github、foursquare、microsoft corporation、google、facebook, inc.。
>
> 我们的客户有 GITHUB、FOURSQUARE、MICROSOFT CORPORATION、GOOGLE、FACEBOOK, INC.。
>
> 我们的客户有 Github、FourSquare、MicroSoft Corporation、Google、FaceBook, Inc.。
>
> 我们的客户有 gitHub、fourSquare、microSoft Corporation、google、faceBook, Inc.。
>
> 我们的客户有 gｲんĤЦ8、ｷouЯƧquﾑгє、๓เςг๏ร๏Ŧt ς๏гק๏гคtเ๏ภn、900913、ƒ4ᄃëв๏๏к, IПᄃ.。

注意：当网页中需要配合整体视觉风格而出现全部大写／小写的情形，HTML 中请使用标淮的大小写规范进行书写；并通过 `text-transform: uppercase;`／`text-transform: lowercase;` 对表现形式进行定义。

### 不要使用不地道的缩写

正确：

> 我们需要一位熟悉 TypeScript、HTML5，至少理解一种框架（如 React、Next.js）的前端开发者。

错误：

> 我们需要一位熟悉 Ts、h5，至少理解一种框架（如 RJS、nextjs）的 FED。

## 争议

以下用法略带有个人色彩，即：无论是否遵循下述规则，从语法的角度来讲都是**正确**的。

### 链接之间增加空格

用法：

> 请 [提交一个 issue](#) 并分配给相关同事。
>
> 访问我们网站的最新动态，请 [点击这里](#) 进行订阅！

对比用法：

> 请[提交一个 issue](#)并分配给相关同事。
>
> 访问我们网站的最新动态，请[点击这里](#)进行订阅！

### 简体中文使用非直角引号

错误：

> 「老师，『有条不紊』的『紊』是什么意思？」

正确：

> "老师，'有条不紊'的'紊'是什么意思？"

3. 让 AI 记住

第一次先通过对话让 AI"短时记住"：

文案请按照中文文案排版指北，先阅读这份文档 docs/README.zh-Hans.md，给出文档所有正例和反例，等我确认你已经理解再执行代码修改。

"长期记忆"：将其纳入 project_rules.md：

文案请按照中文文案排版指北，先阅读这份文档，确认你已经理解再执行代码修改。

重点"中英文之间需要增加空格"：
- 反例："MCP服务"；正例："MCP 服务"
- 反例："确定删除MCP服务?"；正例："确定删除 MCP 服务？"

Trae 的问题

不能严格遵循指令

project_rules.md

- **操作系统**：Windows，但请使用 git bash 运行命令而非 powershell

即使明确在 project_rules 或对话中告知"以后记住请使用 git bash 运行命令而非 PowerShell "。下次运行还是用了 powershell 😓 -_-||。powershell 的缺点是有些语法不支持，比如 &&，虽然 Trae 能遇到运行错误自动纠正成 ; 但是对话轮数多起来了，达到一个阈值就会让你开启新对话，当然最重要的是生成代码的时间也会无谓增加。

Model thinking limit reached, please enter 'Continue' to get more.

AI 每日心得

不要把 AI 当成需要培养的下属，指望它通过"学习"来逐步改进。对于简单的任务，比如一行调整，最好自己动手完成。AI 是工具，它的价值在于帮我们更快完成工作，而不是被反复"调教"去处理那些琐碎、非标准化的细节------你教了这次，下次它大概率还是不会。优化模型是开发者的责任，不是使用者的任务。花时间"训练" AI 适应非标准需求，往往只是浪费时间，下次遇到同样情况，你很可能还要从头再来。

记住：AI 是效率杠杆，而非培养对象。

参考

• 我的Trae大会分享：大厂牛马压箱底的AI编程技巧（附PPT）
• Best Practices for TRAE Rules
• TRAE 规则（Rules）配置指南：个人习惯、团队规范与最佳实践
• AI 每日心得------AI 是效率杠杆，而非培养对象