用 AI 写代码总在半路翻车？我踩出了一份从想法到上线的文档地图

这篇文章想帮你解决一个问题

你大概也试过：丢一段需求给 AI，让它写一个完整模块。

前三十行还行，三百行之后就开始崩——表名对不上、接口不一致、前后端字段错位，最后只能你自己拆开重写。

问题不是 AI 不行，是你给它的上下文不够。

这篇文章把我做一个真实 SaaS 项目时跑通的文档体系完整摊开：4 个文档目录、6 类文档、6 个 skill，告诉你每一类文档的作用、用哪个 skill 生成、彼此怎么串。读完你能拿走：一份对 AI 协作开发友好的"项目目录骨架"，下次新项目直接复制就能用。

一、为什么 AI 这么强，你还是会翻车

凌晨两点，你写了一行 prompt：

"帮我做一个租户管理模块，要能增删改查，多租户隔离。"

AI 啪啪啪输出 500 行。

跑起来发现：

• 表名叫 tenants，但你项目里的命名规范是 p_tenant
• 字段叫 tenant_name，但 PRD 里说的是"企业名称"
• 接口返回 {success: true, data: {...}}，但你统一格式是 {code, msg, success, data, time}
• 前端拿到响应不会解析

不是 AI 蠢，是你没告诉它项目里已经有的约定。

下一次你试着把 200 行规范贴进 prompt。AI 写得对了，但每个新模块都要贴 200 行——你不烦，token 也烦。

答案不是更长的 prompt，是让规范沉淀在文档里，让 AI 每次自己去读。

这套体系我跑了 6 个月，140 多张开发任务卡，几乎全靠 AI 落地。能跑通的原因只有一个——规范在文档里、AI 自己会读。

二、4 个目录、6 类文档、6 个 skill：一张地图

直接看我项目里实际的 document/ 目录长这样：

document/
├── A需求文档/           ← 想清楚做什么 + 全局风格
│   ├── [项目]_PRD.md                 总 PRD（定边界）
│   ├── [项目]_HLD_总览.md            HLD 总览（含设计风格 + 色调）→ CLD 的输入
│   ├── HLD_用户注册登录.md           ← 每个业务模块一份 HLD → HFPD 的输入
│   ├── HLD_订单管理.md
│   └── HLD_数据看板.md
│
├── B前端设计文档/       ← 让想法在屏幕上长出来
│   ├── CLD.pen                       组件库（从 HLD 总览取风格 / 色调）
│   ├── HFPD_P端.pen                  ← 每个端一份原型，按模块拼装
│   ├── HFPD_T端.pen
│   └── HFPD_C端.pen
│
├── C技术文档/           ← 把设计翻译成可落地的技术方案
│   ├── TAD_前端.md                   前端架构
│   ├── TAD_后端.md                   后端架构
│   ├── schema.sql                    数据库脚本
│   └── DevPlan.md                    开发计划（按阶段）
│
└── D开发任务卡/         ← 让 AI 真的开始写代码
    └── [模块名]/
        ├── 00_总览与附录.md
        ├── P0_基础设施.md             按阶段切片
        ├── P1_xxx.md
        └── P2_xxx.md

注意 A需求文档下的 HLD 拆成两层——这是这套体系最关键的一处分层，下面会专门讲。

每一类文档对应一个 skill（D 用通用的 /make-plan）：

看着多，其实每一步都是上一步的输出，链路顺下来不堵。

三、A需求文档：先想清楚做什么 + 定全局风格

3.1 PRD：一份总 PRD，定边界

skill：/write-prd
输出：document/A需求文档/[项目]_PRD_v[N].md

PRD 只回答三件事：做什么 / 给谁用 / 不做什么。

不写页面布局、不写按钮位置、不写接口字段——那些是 HLD、CLD、TAD 的事。

/write-prd 跑起来会先问你几个澄清问题：

• 几个端？（单端 / B+C 两端 / P+T+C 三端 / 其他）
• 多租户 SaaS 吗？
• 当前阶段是 MVP 还是正式版？
• 保密等级？

回答完，输出标准结构的 PRD：产品概述 → 用户角色与权限 → 各端功能清单 → 范围界定（本期做什么 + 本期不做什么）。

关键：【V2】【V3】这类延后标签必须显式写。AI 一看到就知道这部分本期不展开。

3.2 HLD：拆两层（总览 + 模块）

这套体系最关键的一处分层：HLD 分两层写。

第一层：HLD 总览 —— /write-hld <需求>（不带 --module）

• 输出：[项目]_HLD_总览.md
• 内容：产品整体结构 + 全局交互规范 + 设计风格与色调 + 模块清单
• 下游消费者：CLD（组件库要从这里拿色板、字体、间距、组件状态约定）

第二层：HLD 模块 —— /write-hld <需求> --module <模块名>

• 输出：HLD_<模块名>.md，一个业务模块一份
• 内容：需求摘要 + 该模块的页面清单 + 各页面布局 + 业务流程 + 字段 + 权限
• 下游消费者：HFPD（高保真原型按模块逐个拼装，每模块对应一份 HLD）

为什么要分两层？

一个 SaaS 项目实际的模块 HLD 目录通常长这样：

HLD_用户注册登录.md
HLD_角色与权限.md
HLD_订单管理.md
HLD_商品管理.md
HLD_支付与对账.md
HLD_消息通知.md
HLD_数据看板.md

每份模块 HLD 顶部都有一行：

上游设计：[项目]_HLD_总览.md（继承全局规范与设计风格）

意思是：全局规范我不重写，我只继承。这一规则让总览始终是单一权威源。

下面这张图把"PRD → 总览 → 模块 → CLD/HFPD"的依赖关系画清楚了——总览既往下喂 CLD（实箭头表读取），也被各模块 HLD 继承（虚箭头），模块 HLD 最终汇入 HFPD：

四、B前端设计文档：让想法在屏幕上长出来

4.1 CLD：读 HLD 总览，造组件库

skill：/write-cld
输入：[项目]_HLD_总览.md（只读总览，不读模块 HLD）
输出：document/B前端设计文档/CLD.pen

核心原则：只设计组件，不设计具体页面。

为什么 CLD 只读总览？因为 CLD 关心的是全局风格：

• 主色 / 辅色 / 中性色 → 从 HLD 总览的"设计风格与色调"取
• 字体 / 字号 / 行高 → 同上
• 圆角 / 阴影 / 间距 → 同上
• 组件类型（按钮、表单、表格等）→ 从总览的"全局交互规范"推断

CLD 输出的组件包括：

• 基础组件：Button、Input、Select、Checkbox、Switch、Tag…
• 布局组件：顶部导航、侧边菜单、面包屑、页面容器…
• 业务组件：列表表格、搜索筛选栏、编辑表单、弹窗、空状态…

所有颜色、字号、间距都走 Variables，不许硬编码。

这一步的价值：所有页面用同一套零件，UI 一致不靠"自觉"。

4.2 HFPD：读 HLD 模块，逐个拼页面

skill：/write-hfpd
输入：[项目]_HLD_总览.md + 各模块 HLD_<模块>.md + CLD.pen
输出：document/B前端设计文档/HFPD_<端>.pen（每个端一份）

比如一个三端 SaaS 就是三份 .pen 文件：

HFPD_运营端.pen   ← 平台运营（你方人员）
HFPD_租户端.pen   ← 租户管理员（购买 SaaS 的客户）
HFPD_用户端.pen   ← 终端用户（消费者 / 访客）

HFPD 怎么从两层 HLD 取材料？

• HLD 总览：拿端架构、模块顺序、导航菜单结构（决定原型在画布上怎么排）
• 模块 HLD：拿每个页面的字段、布局、业务流程（决定每页长什么样）

每份原型遵守的铁律：

• 从入口页开始（登录 / 首页 / 工作台），放画布第一行
• 后续模块按 HLD 总览的菜单顺序自上而下排
• 每个模块占一行，同模块的页面（列表 → 编辑 → 详情）从左到右排
• 行与行之间留一个页面高度的空白（看着不挤）
• 每个页面的导航激活状态和它所属模块匹配（别复制粘贴）

一个模块一行 = 一份模块 HLD 对应的页面。逻辑层和视觉层一一映射。

如果你想只画某一个模块，可以加 --module <模块名>，HFPD 只会读这一份模块 HLD，只拼这一段画布。

五、C技术文档：把设计翻译成可落地的方案

/write-tad 一次性产出 3 份文件：TAD 前端 + TAD 后端 + schema.sql。再加一份 DevPlan（开发计划），就齐了。

5.1 TAD：先架构、再落细

skill：/write-tad
输入：HLD 总览 + 各模块 HLD（按需）
输出：document/C技术文档/TAD_前端.md、TAD_后端.md、schema.sql

这个 skill 有个特别之处：它不会一上来生成完整文档，而是先给你一份"架构规划摘要"等你确认：

• 前端用什么框架？状态管理？
• 后端语言、框架、ORM？
• 数据库主库 + 缓存怎么选？
• 系统单体还是微服务？
• 多租户怎么隔离（共享表 + tenant_id / 独立 Schema / 独立库）？

你点头之后，它才会展开：

• 系统架构图（Mermaid）
• 技术栈清单
• 数据库设计（每个独立模块 = 一张主表 + 若干关联表，主表统一含 id / tenant_id / created_at / updated_at / deleted_at / created_by / updated_by / status）
• 接口设计（每个模块的 CRUD + 统一响应格式 {code, msg, success, data, time}）
• 多租户隔离方案、认证权限、非功能性需求

整条工作流是两段式的——先架构摘要让你点头，再落三件套：

5.2 schema.sql：建表脚本一次性出全

输出：document/C技术文档/schema.sql

TAD 跑完会同步生成全量建表 SQL。后续所有 DDL 变更走 Alembic（或对应工具），不再手改 schema.sql——它是基线。

5.3 DevPlan：把开发拆成有顺序的阶段

输出：document/C技术文档/DevPlan.md

DevPlan 不是任务清单，是阶段策略。

举个实际例子：

阶段一：基础搭建（1-2 天）
  - 复制代码骨架
  - 配置环境变量
  - 初始化数据库
  - 验证启动

阶段二：核心模块改造（1 周）
  - 重构旧模块对齐新规范
  - 不引入新功能

阶段三：新增模块（按周迭代）
  - 模块 A
  - 模块 B
  - ……

原则：先改造、再新增。基础不稳，新功能加得越多塌得越快。

六、D开发任务卡：让 AI 真的开始写代码

这是整套体系最关键的一类文档——前面所有文档加起来，是为了让这一类能写出来。

6.1 一张开发任务卡 = 一次会话能干完的端到端切片

目录结构：

D开发任务卡/
└── 订单系统/
    ├── 00_订单系统_总览与附录.md
    ├── [已完成]P0_订单基础设施.md
    ├── [已完成]P1_商品 + 价格.md
    ├── [已完成]P2_下单流程骨架.md
    ├── [已完成]P3_支付集成.md
    ├── [已完成]P4_退款 + 售后.md
    ├── [已完成]P5_监控 + 报表.md
    └── [已完成]P6_第三方对接.md

核心约定：

上面这个示例模块的实际依赖关系长这样——P0 是地基，往上每张卡都是端到端切片：

6.2 用什么 skill 生成？

实际是用 /make-plan 系列工具切的。流程：

1. 手写"00 总览"：列依赖图、命名规范、表结构规范、通用约束（多租户、响应格式、async、菜单权限等）
2. 跑 /make-plan 生成 P0-PN：把 HLD 总览 + 该模块的 HLD + TAD 一起喂给它，让它按依赖切成端到端的开发卡
3. review、调整、开干：每张卡跑 /do 或者直接新开会话执行

任务卡的颗粒度很关键：1-2 个 AI 会话能完成是黄金尺寸。
太大 → AI 跑一半失忆；太小 → 切换成本比写代码还高。

七、项目级 CLAUDE.md：给 AI 的"现场守则"

文档之外，还有一类让 AI 进入项目时自动加载的东西——CLAUDE.md。

一个典型的多端 SaaS 项目会有 5 个：

<workspace>/
├── CLAUDE.md                                      ← 工作区入口地图
└── <project-root>/                                ← 实际代码库
    ├── backend/
    │   └── CLAUDE.md                              ← 后端规范（分层 / 命名 / 多租户）
    └── frontend/packages/
        ├── admin-end/CLAUDE.md                    ← 运营端前端规范
        ├── tenant-end/CLAUDE.md                   ← 租户端前端规范
        └── user-end/CLAUDE.md                     ← 用户端前端规范

作用：AI 一进入对应目录，自动读取该目录的 CLAUDE.md，知道这里"该用什么风格"。

入口 CLAUDE.md 通常写：

• 项目一句话定位
• 目录语义（每个一级目录是干嘛的）
• "按任务类型该读什么"路由表
• 当前阶段（MVP / V1 / V2）
• 禁区（不要主动改的文件 / 目录）
• 协作风格速记

CLAUDE.md 不是百科，是入口地图。具体规则放在子目录的 CLAUDE.md 里，按需读。

写得太长 AI 反而抓不住重点。

八、六个 skill 速查表

打印出来贴在工位上，下次新项目对照着用：

九、你的项目要不要走全套？

全套适合：

• 三端及以上、多租户、商业化产品
• 团队多人协作、要交付客户
• 至少做半年以上、要长期维护

可以裁剪的场景：

但永远不能省的三类：

1. HLD 总览：没这个，CLD 风格不一致、模块 HLD 各写各的
2. TAD + schema.sql：没这个，AI 写出来的表名/接口/响应格式全是各写各的
3. 开发任务卡：没这个，AI 会话规模一旦超过它的上下文窗口，输出就开始崩

文档不是越多越好。够 AI 读、够你自己看懂明天的自己，就够了。

写在最后

我以前是那种"灵感来了立刻打开 IDE 喊 AI 写"的人。

后来栽了几次跟头才发现——AI 写代码的瓶颈不在 AI，在你能不能把意图说清楚。

而把意图说清楚最经济的方式，不是写更长的 prompt，是让规范留在文档里，AI 自己去读。

这套文档体系不是一开始就有的，是踩了几个月坑后定下来的"最小集合"——再少一份就缺信息，再多一份就在做行政工作。

文档不是为了交差，是为了让 AI 看得懂你、让明天的自己看得懂今天的自己。

如果你也在 AI 协作开发里反复"跑通 demo 却做不完整个项目"，希望这份地图能让你下次睁开 IDE 时，知道自己第一步该往哪走。

愿你做的每一个项目，都对得起花在它上面的那些深夜。🌙

作者：张少楠
最后更新：2026-05-28
适用场景：SaaS 项目 / 多端架构 / 多租户
配套 skill：/write-prd · /write-hld · /write-cld · /write-hfpd · /write-tad · /make-plan