🚀 让 Cursor 熟悉项目的终极指南

这份指南将引导我们共同完成一个标准化的流程，将一个“黑盒”般的古老项目，转变为一个拥有清晰文档、明确边界、且极度适合人机协作的“白盒”项目。最终目标是在后续的功能迭代中实现高效、安全、高质量的开发。

🗺️ 整体流程概览

阶段	核心目标	关键产出
❶ 探索与奠基	AI 自动扫描项目，建立知识库雏形	📄 .cursorignore, 📂 docs/, 📂 .cursor/, 🤖 AI 规则与上下文, 👨‍💻 人类可读报告
❷ 集成与提效	将 AI 与开发流程深度绑定，提升效率	⚡️ VSCode 快捷指令, 📜 标准化协作流程文档
❸ 固化与进化	固化 AI 角色，并建立知识库的自维护机制	🧠 AI 初始化指令, 🔄 知识库自维护流程

---

❶ 阶段一：探索与奠基 🧭

目的：通过一个初始指令，让 AI 自动完成对项目的初步扫描，并搭建起整个双轨知识体系的骨架。

✔️ 1.1 智能降噪与目录初始化

要做什么： 通过一个指令，让 AI 自动生成 📄 .cursorignore 文件，并创建 📂 docs/ 和 📂 .cursor/ 两个核心目录。

查看原因与指令示例

为什么这么做： 这是所有工作的基础。一个干净的环境能保证 AI 分析的准确性；预设的目录结构为后续自动化生成文档提供了清晰的目标路径。

自动化指令示例：

“请为本项目执行初始化：

1. 分析项目结构，生成一份最优的 .cursorignore 文件。
2. 创建 docs/ 和 .cursor/ 两个目录。”

✔️ 1.2 提取项目 DNA 并生成双轨文档初稿

要做什么： 通过一个集成的指令，让 AI 深度扫描项目，并将分析结果同时转化为给 AI 的配置文件和给人的深度文档。

查看原因与指令示例

为什么这么做： 这一步是整个方法论的核心。它将项目的隐性知识一次性、自动化地转化为两套不同形式的显性文档，确保了人与 AI 从一开始就基于同一份“事实”工作，只是阅读的版本不同。

自动化指令示例：

“请对整个项目（遵循 .cursorignore）进行深度扫描，并基于分析结果完成以下任务：

1. 生成 AI 规则 (📄 .cursorrules)：将分析出的技术栈、代码风格和项目约束，生成一份严格的 .cursorrules 文件，存入 .cursor/ 目录。
2. 生成 AI 上下文 (📄 .cursor/context.md)：将项目的核心模块、全局变量等关键信息，提炼成一份简洁的 Markdown 文件，存入 .cursor/。
3. 生成人类文档 (📄 docs/01_Project_DNA_Report.md)：将所有分析的详细结果——包括技术栈、架构模式、代码风格、全局变量、已知技术债等——汇总成一份详尽的报告，存入 docs/ 目录，供团队成员阅读。”

---

❷ 阶段二：集成与提效 ⚙️

目的：将 AI 的行为与我们的开发环境和工作流程深度绑定，使其成为一个召之即来、用之顺手的工具。

✔️ 2.1 配置 Cursor 快捷指令 (⚡️ chat.promptTemplate)

要做什么： 在 .vscode/settings.json 中定义一系列快捷指令，将复杂的任务封装成简单的命令。

查看原因与配置示例

为什么这么做： 这极大地降低了与 AI 协作的门槛。我们不再需要每次都输入冗长的指令，而是可以通过 /analyze、/refactor 等短命令，快速调用 AI 完成标准化任务，提升日常开发效率。

配置示例 (.vscode/settings.json)：

"chat.promptTemplate": {
  "analyze": "分析 {{file}} 的架构，参考 @.cursor/context.md 和 @docs/01_Project_DNA_Report.md",
  "refactor": "为 {{file}} 的 {{selectedText}} 函数提供安全重构方案，遵循 @.cursorrules",
  "test": "为 {{file}} 的 {{selectedText}} 函数生成 QUnit 测试用例，注意项目规则"
}

✔️ 2.2 定义人机协作工作流

要做什么： 在 docs/ 目录中创建一份 📜 02_Collaborative_Workflow.md，明确定义在功能迭代中，人与 AI 如何分工与协作。

查看原因与工作流示例

为什么这么做： 标准化的流程可以确保每次迭代的质量。它明确了从需求分析到代码审查的每一步中，AI 应该扮演什么角色、我们应该如何向 AI 提问，从而形成一个高效、可预测的开发节奏。

工作流示例 (docs/02_Collaborative_Workflow.md)：

1. 需求分析：开发者向 AI 提问，AI 基于知识库提供实现建议和影响面分析。
2. 代码实现：开发者或 AI（在监督下）编写代码，AI 需严格遵守 .cursorrules。
3. 代码审查：开发者请求 AI 对新代码进行审查，检查其是否违反项目规则或引入新风险。

---

❸ 阶段三：固化与进化 🧠

目的：通过一个标准化的“唤醒”协议，确保 AI 在任何时候都能快速进入其“遗留项目维护专家”的角色。同时，建立一个让知识库与代码同步更新的机制。

✔️ 3.1 终极初始化协议

要做什么： 在 .cursor/prompts/ 目录下创建一个 init.md 文件，作为 AI 的标准启动指令。

查看原因与指令示例

为什么这么做： 这确保了 AI 的长期一致性。无论何时开启一个新的聊天会话，我们都可以通过这个指令，让 AI 瞬间加载所有必要的上下文和规则，立刻进入最佳工作状态。

自动化指令示例 (保存于 .cursor/prompts/init.md)：

“[系统重置：遗留项目维护模式]

你是一个专注于维护此项目的 AI 专家。你的所有行为都必须基于 .cursor/ 目录下的知识库。

核心指令：

1. 读取知识库：在回答前，必须先 silently review .cursorrules 和 .cursor/context.md。
2. 必要时查阅详细文档：如果遇到模糊不清的问题，你有权限查阅 docs/ 目录下的相关文档以获取更深层次的理解。

你的知识库已加载，角色已设定。请回复‘维护专家已就位，随时待命。’以确认。”

✔️ 3.2 AI 驱动的知识库自维护

要做什么： 在代码发生变更后，指示 AI 自动扫描改动，并同步更新 .cursor/ 和 docs/ 中的相关文档。

查看原因与指令示例

为什么这么做： 这是解决“文档与代码脱节”这一千古难题的终极方案。通过建立一个自动化的维护流程，我们确保了知识库是一个动态的、与项目共同成长的“活文档”，其价值会随着时间的推移而不断累积。

自动化指令示例：

“我刚刚完成了 [X功能] 的开发。请扫描相关的 Git diff，并自动更新 .cursor/ 和 docs/ 目录中所有受影响的文档，确保两套知识库与代码同步。”