使用建议

将本手册发送给 AI Agent，让它遵循手册规范进行开发。
新手友好方式：可以让 Agent 先阅读手册，再由它告知你需要补充哪些资料。
推荐提示词：
请先完整阅读本手册，后续开发需严格遵循手册规范。同时告诉我 你需要我补充哪些资料，我提供后，请你整理好资料后放入对应位置

先记住一句话

不管做哪一步，节奏都是一样的：先想清楚再动手，改动拆小，commit 勤一点，AI 改完一定自己看 diff，文档随手就补上。

至于怎么不让 AI 改 A 弄坏 B，其实就靠一件事：改之前先读这个模块的责任田边界，改完顺手把责任田更新掉。

---

整体七步

   → 第0步 想清范围 
   → 第1步 搭工作台(环境+Git+全局规则AGENTS.md+预留责任田)
   → 第2步 写需求文档 → 第3步 搭脚手架(写第一行代码)
   → 第4步 逐功能开发循环(开分支·写需求·拆任务·小步改·看diff·补责任田·合并)
   → 第5步 判定"搭建完成" → 第6步 按信号受控重构
   → 第7步 长期维护(回到第2步循环)

---

三块底子，先搞清楚

后面所有步骤都绕着这三样东西转，先有个整体印象：

基建	是什么	什么时候建
责任田文档 docs/modules/	每个页面/模块"管什么、边界在哪、改了会影响谁"的说明书	新项目先把机制留好、随做随补；老项目一次性补齐
全局规则 AGENTS.md	写给 AI 看的项目规矩（技术栈、组件、样式、工具、协作流程）	第 1 步就建，之后一直维护
Git 仓库	和 AI 协作时的后悔药	第 1 步就用，不要等搭完才想起来

责任田的文件名直接用中文就行，比如 采购入库单.md。Codex 读中文没任何障碍，业务同事看着也顺眼。

---

第 0 步｜先把范围想清楚（开工前花半小时，纸上写写）

AI 搭东西很快，但你范围没框死，它就会越搭越散。所以动手之前，先把"这一版到底要做什么"定下来。

需要定的就三件事：

• 圈出 MVP 范围。只做最基础、能让业务跑起来的部分。那些"以后想加的"单独记一张清单，这一版坚决不碰。
• 选好技术栈：语言、框架、UI 方案、数据怎么存。
• 把 MVP 要做的页面/模块列出来。这张清单后面会直接变成你的责任田清单。

最后落成一页纸的《项目规划》就够了，写清楚项目目标、这一版做什么、明确不做什么、页面清单、技术栈。这页纸相当于项目宪法，后面每个功能需求都不能越出它的范围。

---

第 1 步｜搭工作台：环境、Git、规则、责任田

1.1 初始化骨架

别急着自己配，先让 Codex 出个方案你过一遍：

我要做一个 [类型] 项目，技术栈 [...]。先不要写业务代码，进入计划模式：
1. 给出推荐的项目初始化方式和目录结构
2. 列出需要安装的依赖、启动/构建/测试命令
3. 告诉我哪些是基础脚手架（路由、全局样式、组件目录、配置）
等我确认后再执行初始化。

1.2 Git 从第一天就用

这点没得商量，第 1 步就要用，不是搭完再补。说白了，没有 Git 就敢放手让 AI 大改，等于裸奔——它一旦改崩，你连退回去的地方都没有。

初始化、打第一个基线：

git init
# 先建好 .gitignore（node_modules、.env、dist 等）
git add .
git commit -m "chore: 项目初始化骨架"

分支和合并的事先不用管，那是真正开始写功能时才用到的，放在 4.3 节讲。

1.3 全局规则 AGENTS.md

在根目录建一个 AGENTS.md，把项目规矩写给 AI 看。下面是个可以直接改的样板：

# 项目AI编码规范

## 1. 技术栈约束
- 前端：Vue3 + TypeScript；UI：Element Plus（必须用 src/components/common 下封装的公共组件）
- 后端：Node.js + Express

## 2. 组件使用规则
- 表单必须用封装的 FormContainer，禁止自行拼接 form 标签
- 表格必须用 TablePage，并传入统一请求方法
- 公共组件位置：src/components/common/

## 3. 样式规则
- 颜色必须用 src/styles/variables.scss 的 CSS 变量，禁止硬编码颜色
- 间距遵循 8px 栅格体系，使用全局 mixin

## 4. 工具库使用规则
- 日期：必须用 src/utils/date.ts 的 formatDate
- 权限：必须用 usePermission()，不得自行判断
- 请求：统一用 src/api/request.ts 封装后的 axios 实例

## 5. AI 协作流程
- 改任何页面前，必须先读 docs/modules/ 下对应责任田
- 必须先用 plan mode 给出修改计划和影响范围分析
- 改完必须更新对应责任田的"历史变更"表
- 每完成一个页面/模块，必须补一份责任田；未补文档视为未完成

另外，在用户级的 ~/.codex/AGENTS.md 里再加一条防误删，省得哪天它一个递归删除把你目录端了：

禁止批量删除文件或目录（不要用 rm -rf / Remove-Item -Recurse 等）。
需要删除时只能逐个明确路径删除；如需批量删除，先停下来让我手动处理。

1.4 责任田：新项目先留位，老项目直接补

新项目这时候页面都还没影，硬写责任田只能瞎编，所以先别真写，把机制搭好就行：

1. 建好目录 docs/modules/；
2. 放一份责任田模板（见附录）；
3. 在 AGENTS.md 里立规矩——每做完一个模块就补一份责任田，没补的不算做完。

这样责任田会跟着开发一份份长出来，既不空写，也不会漏。

接手老项目则相反：代码都在，直接让 Codex 读现有代码生成初稿，你审一遍校正，一次性补齐。

走完第 1 步，你手上应该有：能跑的骨架、带首个 commit 的 Git 仓库、根目录的 AGENTS.md、用户级防误删配置，还有 docs/modules/ 目录加一份责任田模板。

---

第 2 步｜需求文档怎么写

需求文档分两层，但都别写厚了，内部敏捷搞太重反而没人维护。

一层是项目级，就是第 0 步那份《项目规划》，整个项目一份。另一层是功能级，每做一个功能写一份《功能需求文档》，关键是在动手做这个功能之前写。

功能需求文档的格式，照着套就行：

# 需求：[功能名，如"用户列表页"]

## 背景
- 当前阶段：[MVP 搭建期 / 功能扩展期]　- 为什么做：[一句话]　- 类型：[新功能/Bug/UI/重构]

## 要解决的具体问题
1. [可验收的具体描述，不要写"优化""美化"]

## 相关文件 / 模块
- [提前指明涉及哪些文件，减少 AI 全项目乱找]

## 不能动的部分
- [登录逻辑 / 接口地址 / 数据结构 / 路由 / 已有组件 / 依赖版本 …… 给 AI 画边界]

## 完成标准
- [什么算做完，逐条列；这就是验收清单]

## 影响范围（让 Codex 评估后补）
- [会牵动哪些模块]

这几栏怎么写有讲究，对比一下就清楚了：

字段	写成这样没用	应该写成
要解决的问题	“优化用户页”	“用户列表加搜索框，按用户名模糊查询，回车触发”
不能动的部分	（留空）	“不改登录鉴权、不改 /api/user 返回结构、不改路由表”
完成标准	“做好就行”	“①列表分页 ②搜索可用 ③空状态有提示 ④构建无报错”

其中"不能动的部分"是最该认真填的一栏。它是防级联 bug 的关键——你不写，就等于默许 AI 顺手把别处也改了。

---

第 3 步｜第一行代码：先搭脚手架，再做页面

别一上来就奔着业务页面去。先把全局地基立起来——路由、基础布局、组件库、颜色 token、请求封装——后面每个页面才有得复用，风格也能统一。不然各页面各写各的，最后准是一团乱。

进入计划模式，先不要写业务页面，只搭全局脚手架：
1. 路由结构（按项目规划的页面清单预留路由）
2. 全局布局（导航/侧边栏/内容区）
3. 基础组件目录与通用组件（按钮、输入框、表格、卡片）
4. 颜色/间距 token 或主题文件
5. 统一的接口请求封装
要求：组件和 token 后续必须被复用，不允许各页面重复造。
给我方案，我确认后执行。

脚手架搭完、自测能跑起来，就 commit 一个基线，这是你后面所有功能的地基：

git add . && git commit -m "feat: 全局脚手架（路由/布局/基础组件/token/请求封装）"

---

第 4 步｜逐功能开发循环（核心，时间基本都花这）

每个页面、每个功能都走同一套循环，你 80% 的时间都待在这一步。

4.1 一个功能的完整流程

①开分支 → ②写功能需求文档 → ③Plan Mode 拆任务 → ④逐任务小步实现
   → ⑤自测 → ⑥看 diff → ⑦commit → ⑧补该模块责任田 → ⑨合并回 main

4.2 派活给 Codex 的模板

执行任务：[功能/任务描述]
- 先读 [相关模块] 现有代码和责任田（新建则跳过），复述本次修改边界
- 只改 [指定文件/模块]，不要碰：[不能动清单]
- 必须复用已封装的组件/token/请求封装，不引入第三方库
- 一次只做这一个任务，改完运行 [测试/构建命令]
完成后输出：改了哪些文件 / 每个文件改了什么 / 为什么 / 是否需构建 / 提醒我看 diff

举个实际例子，给"采购入库单"加一个"驳回"功能。开口第一句先逼它读规则：请先阅读 AGENTS.md 和 docs/modules/采购入库单.md。然后用 Plan 模式提需求，比如"只有已提交状态的单据才显示驳回按钮，点击弹确认框，确认后状态改为已驳回并记录原因，先别编码，先给我修改计划和影响范围分析"。它给出计划后，你重点看它有没有意识到这会影响库存查询、财务报表那些地方——漏了就当场补。最后让它改完顺手把责任田的历史变更表更新掉。

4.3 Git 分支与合并

内部和中小项目用最简单的模型就够了：

• main 始终保持能跑的稳定状态。
• 每个功能开一个 feature/功能名 分支，做完就合、合完就删。

分支的意义在于把 AI 那些"实验性大改"圈在分支里。它要是改崩了，分支一弃，main 一点没事。

一个功能从头到尾的命令长这样：

git checkout main
git checkout -b feature/user-list      # ① 切功能分支
# ② 按 4.2 喂任务让 Codex 开发
git add -p                             # ③ 逐块看 diff 再决定加不加
git commit -m "feat: 用户列表页基础结构与分页"   # 一个小任务一个 commit
git checkout main                      # ④ 自测+diff 通过后合并
git merge --no-ff feature/user-list    # --no-ff 保留合并记录便于追溯
git branch -d feature/user-list        # 删掉已合并分支

要不要走 PR，看人数。单人加 AI，PR 可以省了，本地 merge --no-ff 直接合。多人协作就走 PR，让另一个人（或者先让 Codex 自查一遍）Review 再合，main 设成受保护分支。合并前有个好习惯：把这次的 diff 丢给 Codex，让它检查有没有违反 AGENTS.md、有没有漏更新影响范围。

另外两条 Git 习惯能救命：一是让 Codex 动大改之前，先 commit 一次留个干净存档；二是真改崩了，没 commit 就 git checkout . 或 git reset --hard HEAD 退回去，已经 commit 了就 git revert <commit>。

4.4 功能做完，补责任田

为刚完成的 [模块] 生成责任田文档，放到 docs/modules/，按现状如实填写：
功能描述、入口、API 明细、依赖关系、影响范围、修改边界、注意事项、必须复用的组件/token/工具库。

第 1 步留的那个责任田机制，就是在这一刻兑现的。每做完一个功能补一张，等项目搭完，责任田也就齐了。

每个功能收尾前对照一下这张清单：

• 在独立 feature/* 分支上开发
• 动手前有功能需求文档（含"不能动"和"完成标准"）
• Plan Mode 拆成小任务并确认
• 一次只改一块，改完自测加看 diff
• commit 粒度小、信息说得清
• 该模块责任田已补
• 合并回 main，main 还能跑

---

第 5 步｜什么时候算"搭完了"

下面这几条都满足，MVP 就算搭建完成：

• 项目规划里的 MVP 页面/功能全做完，关键路径走得通
• 每个页面/模块都有责任田文档
• main 能正常启动/构建，没有遗留报错
• 之前欠的测试都补上了

然后打个版本标记，当正式基线：

git tag v1.0.0 && git push --tags   # 若有远程仓库

---

第 6 步｜要不要重构，怎么重构

6.1 别为重构而重构，看信号

重构是有触发条件的，没到那个点就别动。对照看看你现在是哪一栏：

暂时别重构	可以考虑重构了
MVP 刚跑通，需求还会大改	结构稳了，进入长期迭代期
代码能跑、暂时没扩展压力	加新功能时发现塞不进去、到处改
只是看着不顺眼	同样的逻辑/样式重复好几处
马上要上线，时间紧	风格乱，维护成本明显上来了

道理很简单：MVP 阶段代码还在大改，这时候重构等于给一个迟早要推翻的东西抛光，白费功夫还引风险。等结构稳下来、确定要长期迭代了再动，收益最大。

6.2 让 Codex 重构分两步走

最怕的就是 AI 一口气把整个项目重构了，改崩了你都不知道坏在哪。所以一定得受控。

第一步，先让它只分析、别动代码，列个清单你来挑：

请只分析、不要改代码：扫描 [指定模块/目录]，列出值得重构的点，
按类型分组（重复代码 / 可抽取公共组件 / 命名混乱 / 过长函数 / 未复用 token 等），
每条说明：在哪、问题是什么、风险大小、是否会改变外部行为。
我会从清单里挑几条让你逐条执行。

第二步，一次只批一类、一个范围，逐条改：

执行重构任务：[从清单选的一条，如"把重复的表格逻辑抽成公共组件 DataTable"]
严格遵守：
1. 不改变外部行为（输入输出、UI 表现、接口契约不变）
2. 不顺带改业务逻辑、不改公共 API、不改数据结构
3. 只动 [指定文件/模块]，不扩散到别处
4. 重构后跑 [测试/构建命令]，并说明如何手动验证行为没变
先给方案，我确认后再改。

6.3 重构时一定要跟 Codex 交代清楚

• 先 commit，或者开个 refactor/xxx 分支，留好存档，崩了能退。
• 行为不能变。重构只改代码长什么样，不改它跑出来什么结果。
• 一次只做一类。先抽组件、验证好，再统一 token，再拆长函数，别混在一起搞。
• 范围卡死，指定文件和模块，不许全局乱动。
• 必须能验证。有测试就跑测试，没测试就手动把关键路径回归一遍，必要时让它补几个单元测试，保证前后行为一致。
• 明确禁止那几件"顺手"：顺手改业务逻辑、顺手升依赖、顺手优化无关代码、一次重构整个项目。

说到底重构也就是一次改动，照样走完整循环：开分支、出方案、小步改、看 diff、测试、合并，最后别忘了更新责任田。

---

第 7 步｜进入长期维护

搭完之后，每来一个新需求就回到第 2 步那套循环：写需求、开分支、开发、补或更新责任田、合并。维护期再多盯两点：

• 动手前先让 Codex 读旧逻辑。读对应责任田加最近的改动，复述一遍边界再改。
• 改完同步更新责任田。文档过期比没文档更坑人——你以为它是对的，结果它在骗你。

---

附录一：新项目 vs 接手老项目

环节	全新项目	接手已有项目
责任田	先留位，随做随补	一次性补齐（Codex 读代码生成初稿后审校）
第一步	想清范围、搭脚手架	先让 Codex 通读，出一份"项目理解报告"核对
需求文档	项目级加功能级	同样两层，但先得有"现状理解文档"
Git	从零 init	摸清现有分支策略，跟着来
重构	搭完稳定后再说	接手初期先别大改，先读懂、补文档，再按信号动

---

附录二：责任田模板（放 docs/modules/ 下）

# 责任田：[模块/页面名]

## 功能描述
[1 句话说明这块负责什么]

## 功能清单
- 按钮/操作A：做什么
- 按钮/操作B：做什么

## 入口与出口
- 入口：从哪个菜单/按钮进来
- 出口：操作完成后跳转/关闭后回到哪里

## API 明细
- POST /api/xxx - 提交入库单
- GET /api/yyy - 获取仓库列表

## 依赖关系
- 依赖：[...]　- 被依赖：[...]
- 哪些显示字段由其他模块写入（如库存现有量由"采购入库"和"销售出库"共同影响）

## 影响范围
[改动这里可能牵动的模块/功能，如改入库单状态会影响库存查询的可用量、财务报表的应付账款]

## 修改边界
- 可以改：[...]　- 绝对不能动：[...]

## 注意事项
[历史坑、特殊逻辑]

## 约束
- 必须复用：[组件 / token / 工具库]

## 历史变更
| 日期 | 变更内容 | 修改人/AI |
|------|----------|-----------|
| 2026-06-27 | 初始版本 | 张三 |

---

最后用一段话把整件事串起来：先定范围，再搭好工作台（Git、AGENTS.md 规则、留好责任田机制），接着搭脚手架。然后每个功能都走同一套——开分支、写需求、拆任务、小步改、看 diff、补责任田、合并。等结构稳了，按信号受控地重构。往后维护，记住改之前读责任田、改之后更新责任田就行。