ARTICLE · 999805
让AI改项目不越改越乱,我固定会放这4个文件
前言
用 Codex、Claude Code 这类工具改已有项目，最容易遇到一个问题：
第一轮改得挺好，改着改着项目开始乱了。
今天新建一个目录、明天又换一种写法
同一个功能，前后用了两套组件。
原来的业务规则没看懂，直接重新写了一套。
你让它改 A，它顺手把 B、C 也动了。
很多时候不是 AI 不会写代码。
而是：
它根本不知道这个项目原来是怎么做的，也不知道哪些东西不能动。
所以现在让 AI 接手一个已有项目，我一般都会先放 4 个文件。
不复杂。
但能明显减少 AI 越改越乱的问题。
---
01｜AGENTS.md：告诉 AI“怎么干活”
第一个我一定会放：
AGENTS.md
它相当于这个项目给 AI 的：
工作规则。
比如我会写：
项目开发规则
修改功能前，先阅读现有代码，不要直接重写。
优先复用现有组件、工具类和公共方法。
不要擅自修改与当前需求无关的代码。
新增页面前，先检查是否已有相似页面。
保持现有目录结构和命名方式。
不允许为了完成当前需求，大范围重构项目。
如果需求与现有逻辑冲突，先说明问题，不要自行决定。
修改完成后，说明：
修改了哪些文件
为什么修改
是否影响原功能
如何验证
这个文件解决的是：
AI 的行为边界。
没有它，AI 会按照自己觉得“更合理”的方式改。
有了它以后，至少会知道：
这是一个已有项目，不是让我从零设计。
---
02｜PROJECT.md：告诉 AI“这个项目到底是干什么的”
第二个文件我会放：
PROJECT.md
很多人直接把代码扔给 AI。
然后说：
帮我加一个客户详情页。
但 AI 看到的只是代码。
它不知道：
这个系统给谁用、核心业务是什么
几个角色有什么区别。
这个页面为什么存在。
所以我会整理一份很短的项目说明。
例如：
项目说明
项目名称
车管家 App
项目定位
面向一线销售人员使用的业务 App，
主要用于客户跟进、销售过程管理和 AI 销售辅助。
核心用户
车管家
销售教练
门店管理人员
核心模块
客户管理
谈客记录
AI 录音分析
每日复盘
学习成长
当前技术栈
前端： React + TypeScript
UI： XXX
接口： XXX
重要说明
当前是已有线上项目
新功能优先复用已有交互和组件
不允许随意改变整体产品结构
这个文件不用写成 PRD。
控制在一两页就够了。
它解决的是：
AI 对整个项目的基本理解。
---
03｜ARCHITECTURE.md：告诉 AI“东西应该放哪里”
这是我觉得特别有用，但很多人会漏掉的一个文件。
ARCHITECTURE.md
因为 AI 特别容易干一件事：
能实现就行。
于是同一个项目里：
接口请求放三种地方。
状态管理用了两套方案。
页面组件和业务组件混在一起。
公共方法到处复制。
所以我会把项目结构简单写清楚。
比如：
项目结构说明
src/
├── pages/ 页面
├── components/ 公共组件
├── services/ 接口请求
├── hooks/ 公共 Hooks
├── utils/ 工具方法
├── types/ 类型定义
└── assets/ 静态资源
开发约定
页面级代码： 放 pages
多个页面复用的组件： 放 components
所有接口请求： 统一放 services
公共类型： 统一放 types
不要在页面中直接重复封装已有接口。
不要因为一个新需求重新建立一套目录结构。
甚至还可以告诉 AI：
哪些组件必须复用
客户卡片： components/CustomerCard
顶部导航： components/Header
状态标签： components/StatusTag
这样 AI 在新增功能的时候，会先考虑：
项目里已经有什么。
而不是每次重新造一套。
---
04｜TASK.md：告诉 AI“这一次到底改什么”
前三个文件都是长期存在的。
第四个文件我会随着每次需求更新：
TASK.md
它专门描述：
这次到底要做什么。
比如：
当前任务
需求
在客户详情页增加 AI 录音复盘入口。
修改范围
只涉及：
客户详情页
录音详情页
AI 分析结果展示
不需要修改
客户列表
登录逻辑
用户权限体系
原有客户数据结构
功能要求
客户详情页增加“录音复盘”入口
点击进入录音详情
展示播放器
展示录音原文
展示客户核心疑虑
点击疑虑可定位对应录音位置
验收标准
原客户详情功能正常
新入口可以正常进入
播放器可以使用
疑虑点击定位准确
不影响其他页面
开发要求
先阅读现有客户详情页和录音相关代码。
优先复用现有组件。
完成后列出所有修改文件。
这个文件最大的作用就是：
控制 AI 的修改范围。
很多 AI 改项目越改越乱，就是因为任务描述只有一句：
帮我把这个功能优化一下。
“优化”到什么程度？
哪些能改？
哪些不能改？
AI 根本不知道。
---
这 4 个文件分别解决什么问题？
其实非常简单：
AGENTS.md：AI 应该怎么工作
PROJECT.md：这个项目是干什么的
ARCHITECTURE.md：代码应该怎么组织
TASK.md：这一次到底改什么
组合起来就是：
项目背景
开发规则
现有结构
当前任务
---
我现在一般让 AI 按这个顺序开始
第一次接手项目，不会直接说：
开始开发。
而是：
先阅读：
AGENTS.md
PROJECT.md
ARCHITECTURE.md
TASK.md
然后阅读与当前任务相关的现有代码。
先不要修改。
请先告诉我：
你对当前项目的理解
当前需求涉及哪些文件
哪些现有组件可以复用
你的修改方案
可能影响哪些原有功能
确认方案后再开始修改。
这一步其实特别有用。
因为你可以在 AI 真正写代码之前，
先看看：
它到底有没有把项目理解对。
---
最后
以前我让 AI 改项目，经常是：
需求发过去、直接开干、发现不对、再改、越改越乱
现在我更习惯先把这 4 个文件放进去：
AGENTS.md
PROJECT.md
ARCHITECTURE.md
TASK.md
它们并不能保证 AI 一次就把代码写对。
但至少能解决一个很大的问题：
让 AI 每次修改，都知道自己是在一个已有项目里工作。
而不是每来一个需求，
都重新设计一遍项目。