Spec-to-Code 与 Context-to-Code 工作流¶

Prompt-to-Code 这个说法本身没有错，但它已经不够用了。2028 真正决定你上限的，不是“会不会写 prompt”，而是你能不能把需求、上下文、测试、风险和交付一起组织好。

为什么要升级这章¶

老式 prompt-to-code 的默认假设是：

• 问题边界清楚
• 代码上下文不复杂
• 只需要生成一段代码
• 不需要交付和验收

现实不是这样。真实岗位里更常见的是：

• 需求不完整
• 仓库上下文噪声很大
• 改动跨多个模块
• 必须补测试、过门禁、写说明、能回滚

所以更准确的工作流应该是：

需求澄清 -> 规格定义 -> 上下文打包 -> 任务分解 -> 代码执行 -> 自动验证 -> 人工审查 -> 交付沉淀

学习目标¶

• 把一次 AI Coding 任务变成可复用的交付流程
• 学会写 spec 而不是只写一句 prompt
• 学会压缩和组织上下文，避免 agent 失焦
• 学会把测试、评测和风险控制嵌进流程

先理解 3 种输入¶

1. Prompt¶

这是你给模型的一次性指令。

适合：

• 小函数
• 单文件修改
• 快速解释

2. Spec¶

这是工程任务说明书，告诉 agent：

• 为什么做
• 要做什么
• 不能做什么
• 以什么标准算完成

适合：

• 功能开发
• 重构
• 大范围修复

3. Context Pack¶

这是任务所需的最小上下文集合，包括：

• 目标文件
• 相邻依赖
• 接口定义
• 现有测试
• 运行命令
• 风险说明

真正高质量的 AI Coding 基本都依赖后两者。

7 步工作流¶

这 7 步不是形式主义，而是把一次 AI Coding 请求从聊天变成交付流程的骨架。

第 1 步：先把问题说清楚¶

坏输入：

把推荐模块优化一下

好输入：

目标：降低推荐请求在空 query 场景下的报错率
现象：当 query 为空字符串时，rewrite service 会抛异常
影响：线上接口偶发 500
范围：`src/rewrite`、`src/search`、相关测试
验收：空 query 返回正常结果；默认场景不回归；测试通过

你首先要做的是把任务从“模糊愿望”压成“可判定目标”。

第 2 步：写一个最小 spec¶

建议每个中等以上任务都写一页最小 spec。

模板：

## 背景
[这个问题为什么重要]

## 目标
[本次任务要达到什么结果]

## 非目标
[本次明确不做什么]

## 涉及范围
- 文件
- 模块
- 接口

## 约束
- 不改 schema
- 不新增依赖
- 保持旧接口兼容

## 验收标准
- 行为标准
- 测试标准
- 文档标准

这一步的价值在于，它天然让你和 agent 站在同一个边界上。

第 3 步：打包上下文¶

不要把整个仓库都喂进去。你应该提供“最小但足够”的上下文。

推荐结构：

## 相关文件
- `src/api/search.ts`
- `src/rewrite/service.ts`
- `tests/rewrite.test.ts`

## 当前行为
- query 为空时也会执行 rewrite
- rewrite 内部假设输入非空

## 依赖关系
- search router -> rewrite service -> metrics reporter

## 命令
- `pnpm test rewrite`
- `pnpm lint`

上下文过多的坏处¶

• 模型关注点漂移
• 错误引用旧逻辑
• 改动范围失控
• token 成本上升

第 4 步：让 agent 先做 plan，不要直接改¶

这是很多人最容易省掉的一步，但它恰恰最值钱。

你可以要求：

先不要写代码。
请输出：
1. 可能需要修改的文件
2. 根因判断
3. 改动顺序
4. 测试方案
5. 潜在风险

这一步有三个好处：

• 先看它是否理解对了
• 先看改动范围是否失控
• 先看测试策略是否靠谱

第 5 步：让 agent 按子任务执行¶

不要让它一口气做完整个复杂需求。

更推荐：

1. 先改接口或配置层
2. 再改核心逻辑
3. 再补测试
4. 最后补文档和迁移说明

推荐指令：

按以下顺序执行：
1. 新增配置开关
2. 修改 rewrite 逻辑
3. 补单测
4. 输出改动说明

每一步结束后说明：
- 改了哪些文件
- 为什么这么改
- 是否需要继续

第 6 步：把验证写进任务里¶

大多数“AI 改坏了”的根因，不是模型差，而是没有验证闭环。

至少加三类验证：

• 静态检查
• 测试执行
• 人工 diff 审查

可复用模板：

完成改动后必须执行：
- `pnpm lint`
- `pnpm test`

输出时请包含：
- 关键改动摘要
- 新增或修改的测试
- 仍然存在的风险

如果仓库有 benchmark、回归集、e2e 或 golden cases，也应该写进任务描述。

第 7 步：沉淀交付资产¶

真正值钱的不是这次改动本身，而是你把方法留下来了。

推荐沉淀：

• spec 模板
• 任务模板
• review checklist
• 常见失败案例
• 回滚/发布说明

这类资产会直接决定你能不能把“个人会用 AI”升级成“团队会用 AI”。

一个完整模板¶

下面这版适合大多数 Spec-to-Code 任务：

你现在作为仓库内的 AI 工程助手工作。

## 任务
为搜索服务增加 query rewrite 开关，并修复空 query 报错。

## 背景
当前 rewrite service 默认强制开启，空 query 会抛异常，影响线上稳定性。

## 目标
- 支持通过配置关闭 rewrite
- 空 query 不再报错
- 保持默认行为兼容

## 非目标
- 不调整排序逻辑
- 不改数据库 schema
- 不新增三方依赖

## 上下文
- `src/search/router.ts`
- `src/rewrite/service.ts`
- `src/config/search.ts`
- `tests/rewrite.test.ts`

## 要求
1. 先给出改动计划
2. 再按子步骤修改
3. 补齐必要测试
4. 执行 lint 和 test
5. 最后总结风险

3 个典型场景模板¶

下面这 3 个模板，基本覆盖了从需求落地到修 bug 再到重构的常见场景。

场景 1：缺陷修复¶

请先不要改代码。
任务：定位并修复偶发空白页问题。
请输出：
- 可能根因
- 最小复现路径
- 涉及文件
- 修复方案
- 验证方法

场景 2：功能开发¶

目标：给内部知识库增加标签过滤和最近更新排序。
范围：后端查询逻辑、前端筛选 UI、对应测试。
约束：不改现有 API 路径；兼容旧参数。
请先给 spec 和改动计划，再开始实现。

场景 3：测试补齐¶

请为 `src/recommend/ranker.ts` 补单元测试。
要求覆盖：
- 正常排序
- 空候选集
- 打分为 null
- 超时 fallback
不要修改生产逻辑，除非测试证明存在明确缺陷。

高级做法：把任务拆成两个 agent 角色¶

更强的流程不是一个 agent 干到底，而是角色分离：

• planner：澄清需求、写计划
• executor：改代码、跑验证

你自己负责最后的 reviewer 角色。

这种分工有两个明显好处：

• 计划更稳定
• 执行更聚焦

这也是很多企业级 AI Coding 平台的真实演进方向。

常见反模式¶

反模式 1：一句话塞所有要求¶

结果通常是：

• 漏需求
• 漏测试
• 漏边界

反模式 2：没有明确 non-goals¶

agent 很容易“顺手优化”，然后把无关模块也改掉。

反模式 3：没有输出格式要求¶

如果你不要求它先给计划、后给总结，它就会默认直接冲。

反模式 4：不写验证命令¶

很多模型会“自信地认为没问题”，但根本没执行有效检查。

反模式 5：不要求风险说明¶

复杂改动如果没有风险清单，review 成本会直线上升。

2028 面试里怎么表达¶

你要把“会写 prompt”升级成下面这种能力表述：

我把 AI Coding 任务标准化成 spec、context pack、plan、patch、verify 五段式。
复杂任务先规划后执行，所有改动都带测试门禁和风险说明。
这样 agent 不只是会生成代码，而是能被纳入真实交付流程。

如果你能再补一句“我沉淀了模板并给团队复用”，价值会明显更高。

建议练习¶

1. 拿你现有项目里的一个 bug，写完整 spec 和 context pack
2. 拿一个小功能，要求 agent 先给 plan 再执行
3. 拿一个旧模块，只让 agent 补测试，不动实现
4. 记录每次失败的根因，形成你自己的失败模式库

本章小结¶

• Prompt-to-Code 正在升级为 Spec-to-Code
• 高质量结果来自 规格 + 上下文 + 计划 + 验证
• 2028 的竞争力不是会不会提问，而是能不能把 agent 纳入工程流程

下一步¶

• 继续看 06-AI辅助调试与测试
• 再看 14-AI-Coding评测审查与治理
• 配合 07-实战项目 和 09-Agentic软件工程项目交付模板 落地