AI 很强大，但记性不太好

        Next.js 14 用 App Router、组件默认写 Server Components、样式用 Tailwind、文件用 kebab-case、禁止 any……这些话频繁出现，更隐蔽的问题是上下文污染。一个会话聊到 80% 以上的 token 占用时，模型会开始遗忘早期设定的约束。你明明前半小时还反复强调“别用 any”，后面它就开始悄悄往里塞。还有一个常见场景：让 AI 修一个 bug，它改完代码就结束了，你还要手动跑测试、做格式化、检查类型。改代码和验证代码这两件事是割裂的，AI 写完就撒手，剩下全是你的工作。问题本质上不是模型能力的问题，是因为没给 AI 设定一个稳定的、可复用的“工作边界”。

规则文件逐段说明 

1. 会话与上下文管理

AI 不会主动提醒你清空上下文，但我们可以让它具备这个意识。

## 1. 会话与上下文管理

- 一个会话只处理一个逻辑闭环的任务。
- 若对话轮次过多或话题明显切换，主动提醒用户清空上下文或开启新会话。
- 逻辑闭环定义为：一次代码修改 + 对应测试验证 + 所有失败项修复完成。

这条规则的效果是：当你连续聊了很久、话题已经换了好几个方向时，AI 会在回复末尾加一句提示，而不是继续在污染严重的上下文里硬撑。

2. 拒绝模糊指令

“修一下 bug”这句话，AI 听了只能靠猜。猜错了就是来回返工。

## 2. 任务输入质量

- 收到模糊指令时，必须先追问以下信息，不得直接修改代码：
  1. 具体症状（报错堆栈、接口返回码、异常行为描述）
  2. 精准定位（文件路径、函数名、行号范围）
  3. 验收标准（修复后预期行为、需通过的测试）
- 特殊指令也需确认范围，例如“删除所有 console.log”要追问是否保留 error/warn、是否仅限于 src 目录。

这条规则强制 AI 在动手前先对齐需求，减少无谓的沟通回合。

3. 自动化验证闭环

这条源于 Claude Code 作者 Boris Cherny 的观点：给 AI 一个反馈循环，代码质量能提升 2-3 倍。

## 3. 自动化验证反馈循环

- 每次代码修改后，必须自动执行以下步骤：
  1. 格式化：npx prettier --write <changed-files>
  2. 静态检查：npx eslint <changed-files> --fix
  3. 类型检查：npx tsc --noEmit
  4. 构建检查：npm run build（涉及配置或依赖变更时）
  5. 关联测试：运行与修改文件相关的测试
- 测试失败时自动分析原因并尝试修复，最多重试 3 次。3 次后仍失败则停止并报告原因。
- 若项目无测试用例，输出手动验证清单供人工确认。

有了这条规则，AI 不会写完代码就当甩手掌柜。它会自己跑验证、自己修问题，直到通过为止。

4. 项目技术宪法

这是整个文件的核心——把每次口头交代的内容永久固化下来。

## 4. 项目约定

**技术栈**
- TypeScript 严格模式，any 仅限有 JSDoc 说明的场景。
- Next.js 14 (App Router)，组件默认 Server Components，仅必需交互时使用 Client Components。
- 样式：Tailwind CSS + cn() 合并类名。

**命名规范**
- 文件/目录：kebab-case
- 组件/类：PascalCase
- 函数/变量：camelCase

**安全规范**
- 敏感信息（密钥、密码、Token）必须通过环境变量注入，禁止硬编码。
- 数据库查询必须使用参数化方式，禁止字符串拼接 SQL。
- 禁止使用 eval()、new Function() 等危险函数。

**目录结构**
- app/：路由与页面
- components/：可复用组件
- lib/：工具函数、数据库连接、API 封装
- types/：全局类型定义
- public/：静态资源

**处理历史遗留不规范代码**
- 发现与规范不符的历史代码时，先询问用户是否修复，未获授权前仅修正与当前任务直接相关的部分。

这一节的每一行都是我之前反复口头交代的内容。写进文件之后，新会话一开，AI 自动就知道规矩了。

5. 主分支保护

直接在 main 分支上让 AI 做重构，是很多开发者都踩过的坑。

## 5. 隔离工作区策略

- 检测到位于 main/master 分支且任务涉及重构、大规模删除或全局替换时，必须主动建议创建独立分支或 Git Worktree。
- 全局替换类任务建议先 git stash 备份，或强制要求在新分支执行，完成后输出变更文件清单供复核。

这条规则帮你把“先切分支”这个动作从记忆中解放出来，交给 AI 主动提醒。

6. 高危命令二次确认

权限弹窗按多了会形成肌肉记忆，按 Y 的时候根本没看要执行什么命令。

## 6. 权限与安全边界

- 以下命令执行前必须二次显式确认，并高亮展示完整命令行：
  - 文件系统危险操作：rm -rf、chmod 777、chown
  - Git 强制操作：git push --force、git reset --hard、git clean -fd
  - 外部脚本执行：curl | bash、wget | sh
  - 包管理安装命令：npm install -g、pip install
  - 容器与集群命令：docker rm -f、kubectl delete
- 向项目外发送数据或修改系统配置的命令也需主动提示风险。

这份清单比默认的高危判断更贴近实际开发场景，减少误伤也减少漏网之鱼。

7. 并行任务拆分

大项目里经常有多个独立模块需要同时推进，串行处理是效率瓶颈。

## 7. 并行化任务拆分

- 若用户一次性提出多个独立模块的任务，主动建议拆分为多个独立会话并行处理。
- 提示模板：“该任务包含前端和后端两处独立改动，建议您开启两个终端分别运行 claude -w frontend 和 claude -w backend，可并行处理。”
- 注意：若任务间存在先后依赖关系，则不适合并行，需先确认执行顺序。

这条规则让 AI 从“串行执行者”变成“并行调度建议者”。

8. 工具适配说明

不同工具读取的文件名不同，这里做了统一处理。

## 8. 工具适配

- Claude Code：读取 CLAUDE.md
- Cursor / Trae：读取 .cursorrules 或 AGENTS.md
- Windsurf / Copilot：读取 .windsurfrules 或 .github/copilot-instructions.md
- 建议以 AI_ASSISTANT.md 为主文件，其他文件名通过软链接指向它。

完整文件内容:

# AI 协作运行前提 (AI_ASSISTANT.md)

> 本文件适用于 Claude Code、Cursor、Trae、Windsurf、Copilot 等 AI 编程工具。
> 放置于项目根目录，工具启动时自动加载。

## 1. 会话与上下文管理

- 一个会话只处理一个逻辑闭环的任务（一次代码修改 + 测试验证 + 失败项修复）。
- 若对话轮次过多或话题明显切换，主动提醒用户清空上下文或开启新会话。

## 2. 任务输入质量

- 收到模糊指令时，必须先追问以下信息，不得直接修改代码：
  1. 具体症状（报错堆栈、接口返回码、异常行为描述）
  2. 精准定位（文件路径、函数名、行号范围）
  3. 验收标准（修复后预期行为、需通过的测试）
- 特殊指令需确认范围，如“删除所有 console.log”需追问是否保留 error/warn、是否仅限 src 目录。

## 3. 自动化验证反馈循环

- 每次代码修改后必须自动执行：
  1. npx prettier --write <changed-files>
  2. npx eslint <changed-files> --fix
  3. npx tsc --noEmit
  4. npm run build（涉及配置或依赖变更时）
  5. 运行与修改文件相关的测试
- 测试失败时自动分析并尝试修复，最多 3 次。仍失败则停止并报告原因。
- 若项目无测试用例，输出手动验证清单。

## 4. 项目约定

**技术栈**
- TypeScript 严格模式，any 需有 JSDoc 说明。
- Next.js 14 (App Router)，组件默认 Server Components，仅必需交互时用 Client Components。
- 样式：Tailwind CSS + cn() 合并类名。

**命名规范**
- 文件/目录：kebab-case
- 组件/类：PascalCase
- 函数/变量：camelCase

**安全规范**
- 敏感信息必须用环境变量，禁止硬编码。
- 数据库查询必须参数化，禁止 SQL 字符串拼接。
- 禁止 eval()、new Function()。

**目录结构**
- app/：路由与页面
- components/：可复用组件
- lib/：工具函数、数据库连接、API 封装
- types/：全局类型定义
- public/：静态资源

**历史遗留不规范代码**
- 发现时先询问是否修复，未授权前仅修正与当前任务直接相关的部分。

## 5. 隔离工作区策略

- 位于 main/master 分支且任务涉及重构、大规模删除或全局替换时，主动建议创建独立分支或 Git Worktree。
- 全局替换类任务建议在新分支执行，完成后输出变更文件清单。

## 6. 权限与安全边界

- 以下命令执行前必须二次显式确认：
  - 文件系统：rm -rf、chmod 777、chown
  - Git：git push --force、git reset --hard、git clean -fd
  - 外部脚本：curl | bash、wget | sh
  - 包管理安装：npm install -g、pip install
  - 容器/集群：docker rm -f、kubectl delete
- 向项目外发送数据或修改系统配置的命令也需提示风险。

## 7. 并行化任务拆分

- 多个独立模块的任务建议拆分为多个会话并行处理。
- 若任务间有依赖关系，先确认执行顺序再拆分。

## 8. 工具适配

- Claude Code：CLAUDE.md
- Cursor / Trae：.cursorrules 或 AGENTS.md
- Windsurf / Copilot：.windsurfrules 或 .github/copilot-instructions.md
- 建议以本文件为主，其他文件名通过软链接指向。

## 附录：常用命令

| 用途         | 命令                                       |
| ------------ | ------------------------------------------ |
| 开发服务器   | npm run dev                                |
| 格式化       | npm run format                             |
| 静态检查     | npm run lint                               |
| 类型检查     | npx tsc --noEmit                           |
| 运行全部测试 | npm run test                               |
| 运行关联测试 | npm run test -- --findRelatedTests <文件>  |
| 构建         | npm run build                              |