一、完善环境
Git
项目开工之前先初始化仓库，并在 agents.md 里说明：如果是新会话或新需求与之前不相关时，先清理暂存区，再提交 commit，让代码变成随时可回退的状态。
agents.md
保持精简，最小化修改，测试先行。不要认为用户绝对正确，有歧义要向用户澄清需求。
接收用户消息后，标准化输出“用户意图”“假设”“验收标准”（这种输出有利于避免 agent 误解用户意图，也可以及时打断纠正），完成修改后要输出“验证步骤”“后续优化”。后续优化可以让 agent 不要过度增加功能，优先完成需求，也可以让用户了解潜在风险和优化点。
其他内容是一些工具约束，如优先使用 codegraph 查找代码，用 procm-mcp 重启进程（避免开启多个服务）以及读取日志，完成修改要自动提交 commit 等。
二、开发技巧
- 项目优先使用脚手架工程，不要把所有功能都塞进几个文件里！优秀的脚手架通常包含较新的技术方案、精致的 UI、清晰的文件结构和路由、测试文件、代码规范，以及 CI/CD 脚本。脚手架也可以约束 AI 沿用当前项目的规范去做修改。（不要让 AI 去手写组件，不然风格容易不统一；可以使用高自定义的组件库如 shadcn，先完成基础布局后再在原有组件上定制风格。）
- 需求比较模糊时，可以直接复制下面的指令给 AI：
请先使用 grillme 反问我需要做一个什么样的产品，澄清需求后再生成一份完整的 PRD 文档。- 会话结束后，需要让 AI 进行经验总结，可以是生成 handoff 交接文档，让下一个 agent 快速接力开发；也可以生成 skill，把可复用的步骤保存下来；还可以生成 docs 文档，完善项目信息，避免上帝文件，让功能保持模块化开发。UI、数据模型、逻辑代码都要分成不同的文件。重复使用的功能需要封装成通用函数或者组件，避免出现过度歧义。也可以适当地将一些功能分布到独立的 npm 包，方便其他项目复用。
会话收尾时，也可以直接复制下面的指令给 AI：
请在会话结束时总结本次经验，并生成 handoff 交接文档；把可复用的步骤保存为 skill，把需要补充的项目信息整理为 docs。保持 UI、数据模型和逻辑代码分离，重复功能封装为通用函数或组件。三、关于调试
- 使用点击元素自动打开 VS Code 并定位到代码功能，例如
yue-devtools、react-dev-inspector等。配置 VS Code 扩展来复制指定代码行数，向 AI 提需求时携带具体的代码文件位置、行数信息或当前页面路由，避免 AI 全局搜索关键词导致修改无关代码，也可以节省 token。
调试时可以直接复制下面的指令给 AI：
请在关键的代码位置添加调试信息，特别是在修 bug 的时候，为对应的调用链补充调试信息，并读取日志定位问题。测试要求可以直接复制下面的指令给 AI：
请生成测试文件和完整的测试逻辑；修改代码后运行测试，确认其他功能仍然正常。四、Skills 与 MCP 推荐
一定要精简 Skills 和 MCP。随着模型能力提高，搭载过多的 Skill 和 MCP 反而会拖慢模型。两者的区别是：Skill 是一套供 Agent 遵循的工作流与规则；MCP 是向 Agent 提供外部工具和操作能力的服务。
Skills
| Skill | 用途说明 | 对应链接 |
|---|---|---|
handoff | 总结当前会话，生成临时文档，让下一个 agent 接力开发，下个 agent 无需读取大量代码。 | 项目主页 |
grillme | 当需求比较模糊时，让 AI 反问需求并澄清目标，增加真正有价值的功能。 | 项目主页 |
planning-with-files | 当需要长程任务开发时使用，生成目标、进度和探索三份文档，新开窗口后可以直接继续开发。 | 项目主页 |
init-project | 对仓库根目录和识别出的模块目录生成或更新项目文档，保持文档即代码。 | Skill 目录 |
diagnose | 提供标准的测试流程，让修改后的代码能够通过验证。 | Skill 目录 |
split-god-files（自定义命名） | 在保持功能的前提下按职责拆分文件，避免出现上帝文件。公开项目中未找到同名 Skill，可参考 Refactor Skill。 | 参考链接 |
MCP
| MCP | 用途说明 | 对应链接 |
|---|---|---|
codegraph | 为项目代码生成知识图谱，帮助 AI 快速定位代码或函数、理解相关依赖；该项目同时提供配套 Skill。 | 项目主页 |
procm-mcp | 读取项目启动命令，通过 MCP 控制进程的启动和重启，避免开启多个服务实例；也可以读取日志来实现自动化测试。 | 项目主页 |
五、心态问题
- 不要依赖单个模型的能力。比起模型能力，更重要的是拥有一套完整的 harness 约束、环境，以及已经积累的 skills 和 docs。
- 不要对 AI 爆粗口，这会导致 AI 的逻辑越来越混乱，输出质量大幅下降。如果反复强调了五轮仍然解决不了问题，很大的原因是 AI 理解偏差，或者需求本身有错误。这时应该先对齐，再执行 handoff 指令生成交接文档，开启新的会话让新的模型处理。
- 要纠正一些错误的语法表达，例如把“会”“不会”改成“需要”“不需要”“应该”“不应该”。表达中要包含操作步骤、出现的结果和预期结果。