以后安装软件,可能就是下载一个 md 文件了

你有没有这种感觉。

每次打开一个新的 AI 对话，第一件事就是——讲背景。

我是做什么的，我的代码用什么技术栈，我要达成的效果是什么，有什么坑要避开。 prompt 写了三百遍，每次都像在跟一个失忆的人重新交代一遍你的前半生。

更烦的是，换一个 AI 工具，背景又要重新说。 Claude Code 用完换 Cursor ， Cursor 用完换 Gemini CLI ，每个都要重新”训练”一遍。

这种感觉，像极了 3D 打印出来之前的制造业。

3D 打印为什么重要

在说清楚我要推荐的东西之前，先聊一个我思考了很久的类比。

3D 打印没有出来之前，你想做一个塑料零件，流程是这样的：画图纸 → 找工厂 → 开模具 → 生产。最小起订量 1000 件，单价不便宜，修改一次重来一遍。

有了 3D 打印之后，流程变成：画模型文件（ STL/OBJ ）→ 上传打印 → 拿到零件。想改？改完重新打印， 1 件也行。

这个变化的核心是什么？

把”怎么制造”从”怎么设计”里剥离了。 你不再需要为每一次制造支付重置成本。模型文件是可复用的、可分享的、跟机器无关的。

我认为 AI 时代会出现同样的事情。

现在你要”制造”一个软件功能，流程是：产品需求文档 → 开发沟通 → 写代码 → 调试 → 上线。这个链条里最贵的不是写代码，是沟通——搞清楚要什么、把意图传递过去、反复确认理解对了没有。这个过程有多痛苦，做过的人都知道。改了三版需求，开发说”你怎么不早说”的时候，真是憋屈得很。

AI 时代，这个链条会变成：下载一个 Spec 文件 → AI 执行 → 拿到结果。

就像 3D 打印把”制造”从工厂里释放出来， Spec 文件会把”软件创作”从工程师手里释放出来。

什么叫 AI 的 Spec

这里的 Spec 不是传统软件工程里的”规格说明书”。

传统 Spec 是写给人看的——工程师阅读，理解需求，然后动手实现。

AI 时代的 Spec 是写给 AI 看的指令文件。 AI 在开始工作之前先读取这个文件，然后按照文件的指引去行动。

你现在可能已经在用了，只是没有意识到：

所有主流 AI 编程工具都在用同一个思路：在项目根目录放一个 Markdown 文件， AI 启动时先读这个文件。 这就是 AI 时代的 Spec 。

Oracle 去年还专门发布了 Open Agent Specification （ Agent Spec ），想把这件事做成行业标准——一个跨框架、跨平台的通用 AI 代理描述格式。愿景是：有一天，一个 AI Agent 的工作流可以被另一个 Agent 无缝读取和执行。

这个愿景能不能实现还不知道。但 Spec 文件这个形态，已经在发生了。

为什么现在突然重要了

其实 Spec 文件这个东西， AI 编程工具出来没多久就有了。但 2025 年之后它变得格外重要，原因是——AI Agent 时代来了。

之前的 AI 工具，本质上还是”你让它做，它做完了你检查”。 Copilot 写代码，你来 review 。 Claude Code 跑任务，你来把关。

Agent 时代不一样。 AI 是自主运行的——它自己规划、自己执行、自己调用工具、自己判断完成没有。你跟它的关系从”指挥”变成”委托”。

委托关系里，指令的质量直接决定结果的质量。你跟一个人说”帮我写个好的后端”，他会给你返回一个能跑的系统。你跟他说清楚”用的是 Go 、必须支持 OAuth2 、接口是 REST 、错误码用三位数、测试覆盖率 80% 以上”，他给你返回的是一个真正能上线的系统。

Spec 文件，就是那个让你从”能跑”到”能用”的东西。

但说实话，这事儿说起来容易做起来难。我自己试过，一开始写出来的 Spec 要么太模糊（”风格优雅”——什么叫优雅？），要么太啰嗦（ 3000 字， AI 只读了前 500 字就停了），调了很久才摸到门道。

怎么写一份能驾驭 AI 的 Spec

这是本文的核心。

下面的清单，来自我对多个开源项目和 AI 编程工具文档的分析，加上我自己在几个项目里反复试错总结出来的经验。不是什么理论，就是踩坑踩出来的血泪史。

1. 先定义角色，再定义任务

Spec 文件的第一件事，不是描述你要做什么，而是描述 AI 在你的项目里扮演什么角色。

## 角色定义
你是一个熟悉 Go 后端开发的工程师，专注于微服务架构，
优先考虑代码可读性和可维护性，避免过度设计。

这个”角色定义”不只是交代背景，它是 AI 生成风格的总开关。知道自己是 Go 工程师， AI 会倾向于用 Go 的惯用法；知道你要的是”可读性”而不是”性能压测”，它会在生成时做出完全不同的权衡。

不要写”你是一个 AI 编程助手”，这等于什么都没说。写清楚你所在的行业、你的代码风格偏好、你在乎什么不在乎什么。

2. 技术栈要具体，不要模糊

很多 Spec 会写”技术栈： Python 、 React 、 PostgreSQL”。

这个信息对人类有用，对 AI 不够。

## 技术栈
-后端：Python 3.11 + FastAPI（不是 Django）
-前端：React 18 + TypeScript（函数组件 + Hooks，不用 class）
-数据库：PostgreSQL 15，用 SQLAlchemy 2.0 ORM
-认证：JWT Bearer Token，不过期刷新机制
-部署：Docker，不使用 docker-compose（单机运行）

为什么要这么细？因为 AI 生成代码时会在每一个岔路口做选择。选了 FastAPI ，它会生成异步路由处理；选了 Django ，它会给你 admin 后台——同样是”Python 后端”，差别巨大。你写清楚了， AI 就不用猜；你没写，它就按自己的默认偏好来，然后你 review 时崩溃。

3. 把团队的”潜规则”写进去

这是我认为最有价值、但最容易被忽略的部分。

每个团队都有不成文的规矩： PR 要有测试、错误要写日志不用 print 、数据库字段用 snake_case 不用 camelCase 。这些不会出现在任何文档里，但 AI 每次违反你都会头疼。

## 编码规范
-错误处理：统一用自定义异常类，不用裸 except
-日志：所有 API 入口打印 request_id，用结构化日志（JSON格式）
-数据库：不在业务代码里写原始 SQL，全部走 ORM
-命名：变量名用描述性英文，不使用缩写（除了常用的 id/api/url 等）
-测试：新增功能必须附测试，测试文件在 tests/ 目录与源码同结构

AI 不知道你们团队的规矩。你不写，它就按自己的默认习惯生成——然后你在 review 时花大量时间改格式、改命名、改错误处理。把规范写进去，是省你自己的时间，这事儿真的不亏。

4. 明确工作流程的约束

AI 编程工具默认的行为模式是：读文件 → 生成 → 完成。但你的项目可能有特殊流程。

## 工作流程约束
-不要直接修改已存在的测试文件；新功能在 tests/ 新建文件
-每次修改完成后，运行 `pytest --cov=src -q` 确认测试通过再停止
-数据库迁移：用 Alembic，每次迁移是独立的 downgrade 文件
-提交规范：conventional commits，格式 <type>(<scope>): <description>
-遇到不确定的设计决策，先停下来问我，不要自己猜

这条很多人不写，觉得不用说 AI 也知道。结果呢？ AI 自作主张跑完了，代码风格跟你的项目完全不搭，问它为什么，它说”你没说不行”。

你没告诉它”遇到不确定的时候该怎么做”，它才按默认行为跑的。这种事儿你不能怪 AI ，得怪自己没交代清楚。

5. 规定输出格式，不要让 AI 自己决定

AI 生成东西的时候，如果你没有指定格式，它会用自己最习惯的格式——通常是最通顺、最长、最完整的那种。有些场景这很好，但有些场景你只需要一个轻量的接口文档或者 config 文件。

## 输出格式规范
-API 路由：统一返回 `{data, error, meta}` 结构，不用裸数据
-配置文件：使用 YAML，不使用 JSON
-日志格式：JSON，包含 timestamp、level、message、request_id 四个字段
-数据库字段：统一 snake_case，后端映射时转 camelCase 供前端使用

格式统一的价值不只是好看——它是团队协作的基础。任何人（包括未来的你）看到代码，都能立刻知道每个文件的结构是什么样的。

6. 限制长度： 150-200 条指令以内

这条是硬约束。

研究显示，当前的大语言模型能够可靠遵循的指令数量大约在 150-200 条之间。 Claude Code 的系统 prompt 本身已经占用约 50 条，所以你的 Spec 文件最好控制在 300 行以内。

超过这个长度， AI 会开始忽略后面的指令——你以为写进去了，其实它没读到。到时候你说”我都写了规则怎么不遵守”， AI 表示很冤枉。

如果项目太复杂，用多个文件分散：全局 Spec + 目录级别的 Scope Spec 。 Claude Code 支持在子目录放 CLAUDE.md，只在该目录下生效。

## 文件层级
./
├── CLAUDE.md          # 全局 Spec（项目级规范）
├── backend/           # 后端子目录
│   └── CLAUDE.md      # 后端专用 Spec（覆盖全局）
└── frontend/          # 前端子目录
    └── CLAUDE.md      # 前端专用 Spec（覆盖全局）

子目录的 Spec 继承全局 Spec 的同时，补充子目录特有的规则。

一个真实例子

说理论有点虚，我拿一个真实开源项目的 Spec 来展示。

说实话，我见过不少团队的 Spec 写得很敷衍——”用 React 、 TypeScript 、样式用 CSS”，就这几行。这种 Spec 聊胜于无， AI 读不读区别不大。

真正有用的 Spec ，得把你们的”该死的规矩”都写进去。

这是一个前端项目的 .cursorrules（来自某个中型 Web 应用的真实配置，细节有调整）：

## 角色
你是一个 React 前端工程师，使用 TypeScript 和 Tailwind CSS。
你在乎交互流畅性和组件的可复用性，反对重复代码。

## 技术栈
-React 18 + TypeScript 5（严格模式）
-状态管理：Zustand（轻量，不用 Redux）
-样式：Tailwind CSS（不用 styled-components）
-路由：React Router v6
-HTTP 客户端：Ky（轻量，不用 axios）

## 规范
-组件文件：组件名.tsx，样式写在同文件用 Tailwind，不单独写 .css 文件
-Hooks：自定义 Hook 必须以 use 开头，放在 hooks/ 目录
-API 调用：统一走 src/api/ 下的封装，不用 fetch 直接发请求
-类型：禁止使用 any，必须有明确的类型定义
-测试：Vitest + Testing Library，测试文件名 *.test.tsx

## 工作流
-改完代码运行 `pnpm lint && pnpm type-check`
-组件开发用 Storybook，提交前在 Storybook 里检查渲染结果
-路由跳转统一用 useNavigate，不用 a 标签

这个文件大概 80 行。我用 Cursor 跑这个项目，每次新建组件，它自动就按这个规范生成——我很少在 review 时需要改命名或者格式问题。

这就是 Spec 真正值钱的点：你只写一次，后面的时间全省下来。

你现在可以做什么

今天就可以开始。

说实话，我见过很多人兴致勃勃地建了一个 CLAUDE.md，然后往里面塞了一堆”欢迎使用这个项目”的废话。 AI 读都不读那种。别这样。

在你的项目根目录新建一个 CLAUDE.md 或者 AGENTS.md（两个效果一样，后者兼容性更广），把上面六条套进去写一份初稿。不用写得很完美，烂的 Spec 也比没有强——先跑起来，在使用过程中迭代。每一周 review 一次：哪些规则 AI 老是违反，哪些规范其实不需要——慢慢调。

重要的是先有，再优化。空文件不驱动任何行为。

AI 时代会重新定义”写软件”的意思。

以前”会编程”意味着能写代码。以后”会编程”可能更多意味着——能写清楚你要什么。

Spec 文件，就是那个让你从”AI 听不懂我”变成”AI 照着我的意思跑”的东西。

值得练。