让AI编程助手少犯傻：实操指南+AGENTS.md配置模板

兄弟们，是不是感觉AI编程助手有时候像个“聪明的傻子”？它能一分钟给你写出一个完整的Laravel Service，但也能分分钟把 .env 文件里的数据库密码直接打印到日志里；它能秒解LeetCode困难题，但死活不知道你的项目是用Composer还是哪个版本PHP。

别问我是怎么知道的，都是血泪史。

其实问题不在AI笨，而是它像个刚入职的天才新人——智商180，但不知道公司的规矩。你每次都得跟它重复：“别动那个文件！”“跑这个测试！”“用那个Facade！”……

累不累？

今天咱们就聊两件事：
一、是怎么给AI下指令让它少犯浑
二、是怎么把这些规矩一次性写进项目里，以后不用每次都说

想直接复制AGENTS.md模板的，可以快速往下拉

一、让AI少犯傻的核心技巧

这些技巧从无数次“AI又把代码改崩了”的教训里总结的。挑几个用得上的，立马见效。

规划阶段：别让AI上来就干活

1. 先要方案，后写代码
千万别一上来就说“帮我做个博客系统”——AI会给你一个能跑但根本没法维护的“怪兽”。正确姿势是：“给我三个架构方案，从简单到完整，先别写代码，列出技术栈和数据表结构，我选一个你再动手。”

💡 示例：让AI先设计好框架的 Model 关系和路由结构，确认后再生成代码。

2. 根目录放个 SPEC.md
就写几行：这个项目要解决啥问题、核心功能有哪些、用什么框架（Yii/Laravel/ThinkPHP）、数据库是什么。AI看到这个，就像拿到了施工图纸。

3. 把大任务切成小任务
“实现用户认证系统”拆成：①设计users表结构 ②写注册接口 ③写登录接口 ④写中间件……每一步确认后再下一步。

4. 先用假数据，别急着连数据库
让AI用数组或JSON先把业务逻辑跑通，确认没问题了再连真实数据库。不然你会在数据库配置上浪费一下午，结果发现需求理解错了。

5. 设置全局规则文件
在项目根目录建个 .cursorrules 或 .clinerules，写上：“用PHP 8.1+、严格类型声明、遵循PSR-12规范、用Laravel Eloquent ORM、不使用Query Builder……”AI生成的代码风格就能跟团队保持一致。

提示词工程：把话说到AI心坎里

6. 报错信息要“带料”
别只说“报错了”，把完整的错误堆栈、相关代码、PHP版本、框架版本一起扔给AI。信息越全，AI一次定位问题的概率越高。

💡 示例：把Laravel的异常堆栈完整粘贴，包含文件和行号。

7. 用“当前 vs 目标”的结构说需求
“优化这个SQL查询，当前执行耗时2.3秒，目标降到500毫秒以内，不能改变返回数据结构。”

8. 给出输入输出的例子
让AI实现一个格式化金额函数，直接给它几个例子：formatMoney(1234.5) → "¥1,234.50"。比写100字描述都管用。

9. 给AI安个人设
“作为有10年经验的Laravel性能优化专家，帮我review这段Controller代码。”同一个问题，换个人设，回答的深度完全不一样。

10. 让AI一步步推理
“优化这个SQL查询，按步骤来：①用EXPLAIN分析执行计划 ②找出瓶颈 ③设计索引 ④重写查询 ⑤对比前后时间。”逐步推理比直接要答案靠谱得多。

上下文管理：让AI懂你的项目

11. 检查AI的知识有没有过期
先问一句：“你知道Laravel哪个版本？”如果是10.x，它可能不知道11的新特性。赶紧把官方文档关键部分贴给它。

12. 主动甩文档链接
“我要用Laravel 11的Invokable Validation规则，这是文档[粘贴]，请基于这个实现表单验证。”

13. 在Cursor里用 @Codebase 引用
直接说“@Codebase 我们User模型是怎么做的？我要实现一个类似的Profile模型”，AI会自己去读你的代码库。

14. 截图丢给AI
UI出问题了？直接把截图拖进对话框。一张图比你说“按钮偏左3像素”精准一万倍。

测试验证：别信AI的“我测过了”

15. 小步快跑，改一点测一点
千万别等AI改完10个文件再一起测。改一个文件就跑一次 php artisan test，测过了再继续。

16. 检查PHP错误日志
storage/logs/laravel.log 里藏着AI看不到的运行时错误。改完代码记得 tail -f 看一下。

17. 让AI自己写测试用例
“为这个UserService的register方法生成PHPUnit测试，覆盖：正常注册、邮箱已存在、密码太短、SQL注入尝试……”

18. 列个测试检查清单
在项目根目录放个 TEST_CHECKLIST.md，列上功能测试、性能测试、安全测试的条目，每次发布前过一遍。

生产代码：人工review不能省

19. 把AI代码当初级工程师的代码
重点看：SQL注入防了吗？XSS防了吗？有N+1查询吗？错误处理完善吗？代码可维护吗？

20. 过一遍安全检查

• 所有用户输入都经过验证了吗？（Laravel的 validate 或 Validator）
• 密码用 Hash::make() 了吗？
• 查询用Eloquent或参数绑定，杜绝直接拼接SQL。
• .env 里的密钥没暴露吧？

💡 这是PHP项目的命门，AI经常忽略，必须亲自把关。

21. 性能优化检查
让AI自己分析：“这段代码有没有N+1查询？有没有可以缓存的计算？给出优化方案和预期的性能提升。”

22. 用Git做检查点
大改动之前先 git commit -m "checkpoint: 重构前"，AI改崩了直接 git reset --hard HEAD^ 回滚。

二、把规则沉淀下来：AGENTS.md 让AI不再“失忆”

每次跟AI重复同样的话，烦不烦？其实可以把这些“项目规矩”写进 AGENTS.md，AI每次干活前会自动读它。

什么是 AGENTS.md？

它不是给人类看的README，而是专门给AI看的项目操作手册——告诉它这个仓库怎么启动、怎么测试、哪些文件不能碰、代码要写成啥样。

别写这些废话

• ❌ “遵守最佳实践”——啥是最佳实践？你倒是说清楚啊。
• ❌ 把README复制一遍——README讲的是“这是什么”，AI需要的是“怎么操作”。
• ❌ 只写“态度”不写“操作”——比如“要认真”就不如“改完代码必须跑 php artisan test”。

真正有用的内容

• 项目地图：核心目录是干啥的（app/Models、app/Http/Controllers、routes/等）。
• 常用命令：composer install、php artisan serve、php artisan test、php artisan migrate。
• 编码约定：用Laravel Eloquent、用Request类做验证、命名遵循PSR-12、使用严格类型 declare(strict_types=1)。
• 验证规则：改了Model要跑哪些测试，改了API路由要跑什么。
• 禁止事项：哪些文件不能改（比如vendor/、自动生成的ide-helper文件）、哪些操作必须先确认。
• 交付格式：最后要总结改动、列出验证命令、说明风险。

模板直接复制（PHP版）

在项目根目录新建 AGENTS.md，复制下面内容，按实际情况改：

# AGENTS.md - PHP/Laravel 项目规则

## 项目结构
- app/Models/: Eloquent 模型
- app/Http/Controllers/: 控制器
- app/Http/Requests/: 表单验证请求类
- app/Services/: 业务逻辑服务类
- routes/api.php: API 路由
- routes/web.php: Web 路由
- database/migrations/: 数据库迁移
- tests/: PHPUnit 测试

## 常用命令
- composer install
- php artisan serve
- php artisan test
- php artisan migrate
- php artisan migrate:fresh --seed
- php artisan ide-helper:generate

## 代码约定
- 使用 PHP 8.1+，开启严格类型 `declare(strict_types=1)`
- 遵循 PSR-12 编码规范
- 模型关联使用 Eloquent，不使用 Query Builder
- 表单验证使用 FormRequest 类，不在控制器里直接验证
- 业务逻辑写在 Service 类，控制器只负责调用和返回响应
- 返回统一格式：`['code' => 0, 'msg' => '', 'data' => []]`
- 所有数据库查询考虑 N+1 问题，用 `with()` 预加载

## 验证要求
- 修改 Model 或数据库迁移后运行 `php artisan test --testsuite=Feature`
- 修改 API 后手动测试接口，确认返回格式正确
- 修改验证规则后测试边界情况（必填、类型、长度等）

## 禁止事项
- 不提交 .env 或任何密钥文件
- 不在控制器里直接写 SQL 查询
- 不手改 vendor/ 目录下的任何文件
- 不重置用户已有改动
- 新增 Composer 依赖前先说明原因

## 最终回复
- 总结改动内容
- 列出需要执行的命令
- 说明可能的风险或未覆盖的测试
- 提醒是否有迁移文件需要运行

别只写一个大而全的文件

项目比较大的话，可以分层写：

• 根目录的 AGENTS.md 写全局规则（项目结构、通用命令）
• app/Services/AGENTS.md 写业务层专属规则
• tests/AGENTS.md 写测试规范

什么时候更新它？

• AI连续两次犯同一个错 → 把纠正方式写进去。
• Code Review里反复出现同类问题 → 把评审标准写进去。
• 换了PHP版本或框架版本 → 第一时间更新命令。
• 某个模块风险变高了（比如支付、权限）→ 在那个目录下加一个局部规则文件。

小技巧：先用AI工具（如Codex的 /init 命令）生成初稿，再根据你项目的实际情况手动改。

三、快速检查清单

写完 AGENTS.md 后，用这几条自检：

• 新同事看了能知道项目怎么启动和验证吗？
• 每条规则都具体到能被AI执行吗？（不是“保持优雅”，是“用declare(strict_types=1)”）
• 不同类型改动对应的测试命令写清楚了吗？
• 哪些文件不能碰、哪些操作要确认，都列出来了吗？
• PHP特有的安全问题（SQL注入、XSS、.env泄露）都涉及了吗？

最后说两句

AI编程助手不是魔法棒，它是个“智商在线但缺乏常识”的新同事。你的任务不是替它干活，而是把规则说清楚、把上下文给足、把验证做到位。

上面的技巧帮你少踩坑，AGENTS.md 帮你把经验沉淀下来——以后每次跟AI合作，它都像已经入职一个月的老员工，知道PHP项目的规矩、懂框架的流程、会自己跑测试。

今天就能动手的两件事：

1. 下次让AI写代码前，先让它给你3个方案选一个。
2. 在项目根目录新建 AGENTS.md，把模板复制进去，填上你项目的真实信息。

然后你会发现——AI还是那个AI，但干活靠谱多了。至少，它不会再往 dd() 里塞密码了。

觉得对您有帮助的，随手点个关注呗！