夜雨聆风传统开发的第一步是搭建项目骨架。AI辅助开发的第一步，是写一份AI能看懂的项目说明书。
在第一篇文章里，我提到整个司南投研系统是由一份需求文档驱动的。每次让AI开发新功能，我只用一句话：“请对照需求文档v3.0的第X节，完成XX模块的开发。”
很多读者问：这份文档到底长什么样？AI真的能完全理解并执行吗？
这篇文章就来讲讲，我是如何从零构建这份“AI可读”的需求文档的。
为什么一份文档能驱动整个开发流程？
传统的软件开发流程是：需求评审 → 技术方案 → 详细设计 → 编码 → 测试 → 交付。每个环节都需要不同角色的人参与，信息在传递过程中不断损耗。
AI辅助开发颠覆了这个流程。因为AI可以同时扮演架构师、程序员、测试工程师的角色，你只需要把“做什么”和“做到什么标准”讲清楚，AI就能在各个环节之间无缝切换。
但这里有一个关键前提：你讲得足够清楚。
如果需求是模糊的——“做一个量化交易系统”——AI给出的结果也会是模糊的。只有把需求细化到AI可以“按图施工”的程度，才能真正实现文档驱动开发。
CLAUDE.md：AI的“项目记忆”
Claude Code有一个强大的功能：你可以在项目根目录放一个CLAUDE.md文件，AI在每次对话开始时会自动读取它，把它作为理解项目意图的基础。
我的CLAUDE.md包含以下核心内容：
1. 项目概述（一句话说清楚这是什么）
“司南投研系统是一个面向个人投资者的智能量化投研平台，核心能力包括全市场动态扫描、历史数据回测、策略自适应优化、模拟资金账户管理、复盘统计。”
2. 技术栈（精确到版本号）
后端：Python 3.12+ / FastAPI / SQLAlchemy 2.0+ / MySQL 8.0+ / Redis 7+ / Celery 5.4+
前端：React 19+ / TypeScript / Vite / Tailwind CSS 4+ / shadcn/ui / AG Grid
为什么要精确到版本号？因为AI会默认使用它训练数据中最常见的版本，而这个版本可能已经过时。明确版本号可以避免兼容性问题。
3. 当前开发状态（已完成/进行中/待开发）
这是一个动态更新的表格，每次完成一个模块就更新一次。这样AI在接手新任务时，知道哪些模块已经完成、哪些代码可以直接复用。
4. 代码规范与约定
这是最关键的部分。它告诉AI什么可以做、什么绝对不能做。例如：
“金融操作必须使用数据库事务和行级锁（SELECT...FOR UPDATE）” “API路由统一使用/api/v1/前缀” “所有敏感信息通过环境变量注入，严禁硬编码”
这些不是建议，是红线。AI生成代码时会严格遵守这些约定，而不是自由发挥。
5. 前端视觉设计规范
这是最容易被忽略但实际最重要的部分。如果不说清楚，AI默认生成的前端就是黑白骨架——没有任何样式。
我在CLAUDE.md里用整整一个章节定义了色彩体系（背景bg-gray-950、卡片bg-gray-900、涨green-400、跌red-400）、字体（Inter + JetBrains Mono）、图表规范（网格线颜色、Tooltip样式）、甚至信号列表的边框颜色。AI拿到这份规范，就能生成符合专业量化终端风格的界面。
需求文档v3.0：66项功能需求的完整蓝图
如果说CLAUDE.md是项目的“身份证”，需求文档就是项目的“建筑蓝图”。
这份文档经历了多次迭代——从v1.0到v3.0，每次迭代都增加新的功能需求、完善架构设计、补充测试方案。最终版本包含：
- 66项功能需求（F-01至F-63）
：从用户注册登录（F-01~F-07）到程序化交易合规报告（F-61），每一项都有编号、功能描述和验收标准 - 完整的技术选型决策记录
：为什么选React而不是Vue？为什么选FastAPI而不是Go？每一项决策都有对比分析和最终理由 - 数据库设计
：核心表结构、索引设计、分区策略（历史行情按月分区、审计日志按季度分区） - API端点规范
：统一响应格式、错误码定义、分页参数 - 测试方案
：覆盖功能测试、性能测试、安全测试、混沌工程测试 - 风险矩阵与应急预案
：7项核心风险的检测方式、恢复步骤和预估恢复时间
这份文档的撰写过程，本身就是“人机协作”的范例
你可能好奇：这么长一份文档，是我一个人逐字逐句写的吗？
答案是：核心设计决策全部来自我，但文档的结构化整理、格式规范化、一致性检查，AI帮了很大的忙。
具体的协作流程是：
- 我提出需求
：基于我对量化交易的理解，列出系统需要具备的功能——三层扫描、风控校验、模拟交易、复盘统计等 - AI整理成结构化列表
：我把这些需求口述给AI，AI帮我整理成带编号的功能清单（F-01至F-63），并补充它基于行业经验推断的细节描述 - 我审核、补充、调整优先级
：AI整理的功能列表中有不少需要修正的地方——例如AI把“候选池规模”建议为300只，我根据实际性能测试修正为20只+自选股。这个过程来回了好几轮 - AI编写架构设计初稿
：我确定了技术栈和模块划分后，AI帮我生成了数据库表结构、API端点规范、部署架构等章节的初稿 - 我再次审核，补充关键内容
：AI的初稿缺少测试方案、风险矩阵等工程化内容，我补充了完整的测试策略、混沌工程测试、应急预案等章节 - AI做系统性的多维度检查
：我让AI逐项对照需求文档，检查是否有遗漏、矛盾、模糊表述 - 我最终确认
整个过程花了多轮迭代。AI帮我节省的时间主要在于：格式整理、重复性检查、跨章节一致性验证。但所有关键决策——架构设计、策略逻辑、安全规则——都是我来做的。
这就是“文档驱动开发”的精髓：AI是你的高效执行者，但指挥棒始终在你手里。
一个具体的例子
当我想让AI完善配置功能时，我的指令是：
“委托frontend-dark-theme-builder和fastapi-endpoint-builder共同对照需求文档v3.0，检查/settings页面是否包含以下可配置项：初始资金(10万)、单只仓位上限(25%)、总仓位上限(80%)、硬止损(-8%)……”
AI会：读取文档→找到对应功能需求（F-08~F-12）→检查前端页面和后端API→列出缺失清单→逐项修复。
整个过程中，我不需要解释什么是“硬止损”，不需要告诉AI止损的默认值是多少，也不需要描述前端页面应该用什么组件。这些信息全部在文档里。
写好一份需求文档是AI辅助开发中最被低估的能力。它不是“额外的工作”，而是投资——前期多花1小时完善文档，后期能节省10小时的返工和调试时间。
下一篇预告：《三层扫描体系设计：从4000只股票到20只候选》
