AI 编程时代，项目应该提前搭好哪些基础 AI-Ready Project Foundation: What to Set Up Before Coding with Agents

用 AI 写代码这件事，很多人的体验是这样的：

第一次用，惊艳。第十次用，开始感到摩擦。Agent 读了半天文件，还是搞错了调用关系；提交代码要自己想 commit message，想半天写出来自己都觉得敷衍；改了个功能，不知道有没有影响到其他地方……

问题不在 AI 不够聪明，而在于项目本身没有为 AI 协作做好准备。

---

一、给 Agent 一份「项目地图」 | Agent-Readable Project Index

问题：每次对话都是冷启动

每次启动一个新的 AI 对话，Agent 对你的项目一无所知。它需要自己去读文件、猜结构、理清关系——这个过程耗费大量 token，推理速度慢，而且极容易出错。更糟的是，它今天理解的内容，明天对话重开又得来一遍。

一个中型项目（~50 个文件）没有索引文档时，Agent 光是「搞清楚这个项目是什么」就要消耗 3000–8000 token，而且理解往往是片面的。

收益对比

维度	无项目索引	有项目索引（CLAUDE.md）
冷启动耗时	每次对话 3–10 分钟	< 30 秒
Token 消耗（首轮）	3000–8000 token	500–1500 token
定位错误率	高，Agent 经常找错文件	明显降低
跨对话一致性	差，每次理解可能不同	稳定
新成员/新 Agent 上手	需要人工解释	读文档即可
维护成本	—	极低，有架构变更时更新

怎么做

在项目根目录维护一份 CLAUDE.md（也可叫 AGENT.md），作为 Agent 的快速上手文档，包含以下内容：

① 项目入口与目录结构

项目根目录
├── src/api/        # HTTP 路由层，入口是 app.ts
├── src/services/   # 核心业务逻辑，每个服务对应一个领域
├── src/models/     # 数据库模型定义（Prisma）
└── src/utils/      # 工具函数，无副作用

② 核心数据结构：关键类型定义在哪里，业务上最重要的实体是什么，它们之间什么关系。

③ 主要执行流程：一个典型请求从入口到响应经过哪些层，有没有消息队列、定时任务等异步流程。

④ 复杂模块的子文档索引：如果某个模块足够复杂（如支付、权限、推荐算法），单独维护 docs/payment.md，在主文档里索引它。Agent 修改这部分时按需加载，不用把整个项目都塞进上下文。

在 CLAUDE.md 里加一个索引段落，例如：

• docs/payment.md — 订单创建、支付回调、退款逻辑
• docs/auth.md — RBAC 模型、中间件说明
• docs/recommendation.md — 推荐算法流程、AB 实验入口

---

二、Git Flow 交给 AI 打理 | AI-Powered Git Workflow

问题：提交是高频的注意力消耗

写完代码，最后一步是提交。这一步听起来简单，但积累起来是不小的效率损耗：

commit message 要怎么写？改了好几个文件，一句话说不清楚。这次改动有没有引入风险，自己刚写完代码盲区最大。PR description 要填什么，每次都对着空白文本框发呆。Review comment 来了几条，来回切换上下文很烦。

对一个每天提交 3–5 次的开发者，这些「小摩擦」每天累计可能消耗 30–60 分钟的有效注意力——不是在写代码，而是在处理写代码的行政事务。

收益对比

环节	手动方式	AI Git Flow
写 commit message	2–5 分钟，质量参差	10 秒，格式规范
提交前风险排查	靠经验，有盲区	自动扫描，输出风险清单
创建 PR/MR	5–10 分钟填写描述	1 分钟确认并发布
处理 Review comment	逐条手动定位修改	批量读取，自动修复可处理项
commit 历史可读性	「fix bug」「update」	规范消息，3 个月后仍可溯源
分支命名	随意，混乱	feat/xxx、fix/xxx 自动规范

怎么做

配置一套 Git Flow Skill，AI 接管以下环节：

① 自动生成 commit message：AI 读取 git diff，按 Conventional Commits 或自定义格式生成消息，附带改动摘要。你确认或微调，一键提交。

② 提交前自动 Review：提交之前扫一遍改动——有没有遗漏的 TODO、硬编码配置、可能影响其他模块的副作用、测试是否覆盖。输出简短风险清单，不是直接放行。

③ 一键创建 PR/MR：根据 commit 历史自动生成 PR 标题、改动描述、测试方法，发到 GitHub/GitLab。

④ 读取 Review Comment 并修复：AI 读取评审意见，逐条分析哪些可自动处理，哪些需要人工判断，批量修改后提交新 commit。

⑤ 分支命名与版本管理：按规范自动命名分支，避免出现 fix-final-2-真的最终版 这种情况。

---

更大的视角

这两件事背后有同一个逻辑：

基础建设	一次性投入	每次对话收益	长期收益
项目索引文档	2–4 小时	节省 5–10 分钟冷启动	项目越复杂收益越大
AI Git Flow	1–2 小时配置	节省 20–40 分钟/天	commit 历史持续积累可读性

代码质量是结果，好的基础设施是原因。先把地基打好，之后每一次 AI 协作都会回报你这份投入。