AI 实现高质量编程 | API Platform 文档

addtoken_geek

352人浏览 · 2026-07-20 13:58:32

addtoken_geek · 2026-07-20 13:58:32 发布

AI 实现高质量编程

Overview

目标读者：开发团队、技术决策者、CTO、架构师

核心观点：AI不会自动产出好代码，本文总结了当前常用和有效的方法： 6个核心Agent技能，助你的AI真正产出高质量代码。

—

一、/grill-me：把模糊想法变成清晰方案

问题

多数人和AI对话时，说几句话就开始让AI写代码。结果往往是：AI猜错了需求，写了一半发现方向不对，推倒重来。

解决方案

grill-me 这个技能的核心只有三句话：

1. 就这个方案的每个方面，毫不留情地追问我，直到我们达成共识。

2. 沿着设计决策树的每个分支，逐一解决决策之间的依赖关系。

3. 如果某个问题可以通过查看代码库来回答，那就去查代码库，而不是问我。

实际效果

曾经遇到一个真实案例：在为课程视频编辑器添加新功能时，AI连续追问了 16个问题，复杂的特性甚至会追问 30-50个问题。这看似"麻烦"，但实际上是在用追问替代猜测，有效避免后续返工。如果所有skills，让我选择保留一个，那我肯定选择grill-me。

关键洞察

技能不需要很长，但每个字都要精准。 这个grill-me skill，比几百行的通用提示词更有用。

—

二、/to-spec：从对话到文档，把共识落地

问题

聊完之后，需求还是散落在对话记录里，没有形成可执行的文档。

解决方案

to-spec 技能会把当前对话和代码库理解，综合成一份 spec（即 PRD），并自动发布到你的 issue tracker。

关键特性：它不会再次追问你。 当你调用它时，对齐工作已经完成——它只是把已知信息整理成文，而非重新提问。

一份完整的 spec 包含以下部分： - Problem statement：什么出了问题或缺失了什么，以及为什么值得解决 - Solution：高层级的解决方案形态，不涉及实现细节 - User stories：编号列表，每条都是独立可验证的具体行为 - Implementation decisions：对话中已确定的技术选择，避免后续重新争论 - Testing decisions：功能将在哪些边界进行测试，以及"完成"的定义 - Out-of-scope items：本次变更刻意不覆盖的内容，保持范围可控 - Further notes：其他值得记录的信息

在写 spec 之前，to-spec 还会规划测试边界，寻找 deep module 机会——用小而稳定的接口隐藏大量功能。这对 AI 开发至关重要：好的接口让测试有稳定的目标，底层代码可以任意修改而无需动测试。

实际效果

一个健康运行的 to-spec 应该： - 直接开始写 spec，而不是重新提问 - 在写之前与你确认测试边界，并尽可能提出最少的边界 - 使用项目自己的领域词汇来写 spec，而非通用模板

使用时机

在变更方案和领域语言都已确定后调用。如果还未对齐，先用 /grill-me追问清楚。

关键洞察

没有文档的共识，等于没有共识。 spec 是 AI 和人类之间的"合同"，防止后续"我以为你是这个意思"的扯皮。

—

三、/to-tickets：把终点拆成路径

问题

spec 描述了"目的地"，但没有告诉你"怎么走过去"。直接让AI按spec写代码，往往会陷入"先写数据库层、再写API层、最后写前端"的水平切分陷阱。

解决方案

to-tickets 技能会把 spec（即 PRD）拆分成一组 垂直切片（tracer-bullet vertical slices） 的任务，每个任务都贯穿所有集成层（schema、API、UI、测试），而不是某一层的水平切片。

每个任务都会声明它被哪些任务阻塞（任务的依赖关系），支持两种工作方式：本地文件按依赖关系顺序执行，或在 GitHub/Linear 等追踪器中用原生 blocking links 实现并行调度。

在切片之前，to-tickets 会寻找 prefactoring（预重构） 机会——遵循"先让变更变简单，再做简单的变更"原则（Kent Beck——TDD 之父），并把这类工作排在最前面。然后它会和你确认拆分方案，确认无误后才发布。

宽重构例外：对于影响范围遍布整个代码库的宽重构（如重命名一列），采用 expand–contract 策略：先添加新实现，再分批迁移调用点，最后删除旧实现。

实际效果

以文档编辑器功能为例，拆分后的任务列表： - 任务1：文档编辑引擎 + 端到端测试（无阻塞，可立即开始） - 任务2：写入文档流程（端到端，与任务1并行） - 任务3：编辑文档流程（依赖任务1和2） - 任务4：Monaco编辑器切换（依赖任务2）

每个任务都是完整的垂直切片，完成后即可独立演示或验证。

使用时机

在有了一致的计划或已写好的 spec 后调用。如果还没有 spec，先用 /to-spec 生成。生成的 ticket 会被 implement 技能逐个执行，内部驱动 tdd（test-driven development，测试驱动开发） 先写测试再写代码。

关键洞察

垂直切片（Vertical Slice）是AI开发的最佳实践。 每个切片都是一个"tracer bullet"（追踪弹），快速验证从UI到数据库的完整链路是否通畅。

—

四、/implement：把ticket变成可工作的代码

问题

但接下来让 AI 开始编码，如何让代码避免成一团乱麻？

解决方案

implement 技能是整个工具链的执行者——它不决定"做什么"，只负责"怎么做"。

关键原则：`implement` 严格按计划执行，而不是重新打开设计。 它是"手"而不是"头"——思考在 to-spec 阶段已经完成。

implement 内部驱动 tdd 和 code-review 两个子技能，形成完整的工作循环：

# implement 执行流程
read_ticket
  ↓
run_tdd           # 测试优先开发，先写测试再写代码
  ↓
typecheck         # 每写完一小段就检查类型
  ↓
run_single_test   # 过程中只跑当前文件的测试
  ↓
run_full_test     # 最后跑一遍全套测试
  ↓
code_review       # 审查自己的实现
  ↓
commit            # 提交到当前分支

每个 ticket 在新 context 中执行，完成后清理，再开始下一个 ticket。

实际效果

一个健康运行的 implement 应该： - 严格按 ticket 描述执行，不擅自扩大或缩小范围 - 内部驱动 TDD，测试覆盖所有约定的 seam - 每个 ticket 完成后都留下可工作的代码 + 测试 + commit

使用时机

在工作已经写成 spec 或拆成 ticket 后调用。如果只是想要 test-first 的编码流程（不需要完整 spec），可以直接用 /tdd。

关键洞察

`implement` 的价值在于"不重新思考"。 设计决策已经在 to-spec 阶段确定、实现顺序在 to-tickets 阶段拆分完毕，implement 只负责把它们精确地翻译成代码。

—

五、/tdd：测试驱动开发，独立使用的轻量方案

问题

有时候你不需要完整的 spec 和 ticket 链路，只是想让 AI 写一段可靠的代码。但直接让 AI 写，边界情况、重构安全都成问题。

解决方案

tdd 是 implement 内部使用的测试驱动开发子技能，也可以独立使用——当没有完整 spec/ticket 时，直接让 AI 按 TDD 流程编码。

它强制AI遵循 红-绿-重构（Red-Green-Refactor） 循环： 1. 红：先写一个会失败的测试 2. 绿：写最少的代码让测试通过 3. 重构：在测试保护下优化代码结构

实际效果

Matt 强调：“做好TDD，是提升AI产出质量最稳定的方法。”

这个技能还强调了一个关键原则： - 错误做法（水平切片）：先写5个测试，再写5个实现 → AI容易迷失在大量未通过的测试中 - 正确做法（垂直切片）：测试1→实现1→测试2→实现2 → 每个小循环都有正反馈

使用时机

- 作为 implement 的子步骤：自动调用，无需手动操作 - 独立使用：当不需要完整 spec/ticket，只想让 AI 按 TDD 写代码时，直接输入 /tdd

关键洞察

TDD 不是给AI增加负担，而是给AI一个"安全网"。 有了测试，AI才敢大胆重构；没有测试，AI只会越写越保守、越写越烂。

—

六、/improve-codebase-architecture：让代码库对AI友好

问题

如果你的代码库本身就很烂，AI在里面也只能产出烂代码。测试边界模糊、模块耦合严重、理解一个概念要跳十几个文件——AI和人类一样会晕。

解决方案

improve-codebase-architecture 技能会主动扫描代码库，寻找以下问题：

- 理解一个概念需要跳多少文件？（认知负担） - 纯函数是否只是为了测试而提取，但真正的bug藏在调用逻辑里？ - 哪些模块耦合过紧，导致集成风险？

然后，它会提出**“深化模块”（Deepening Modules）**的建议——把浅层、碎片化的模块合并成深层、高内聚的模块，让AI更容易理解和操作。

实际效果

建议：每周做一次，或者在开发高峰期后做一次。 随着代码库质量提升，你会发现AI的产出质量也在同步提升。

关键洞察

垃圾进，垃圾出（Garbage In, Garbage Out）。 代码库的质量决定了AI产出的上限。投资代码架构，就是投资AI的生产力。

—

总结：把AI当"有怪癖的人类工程师"来管理

核心方法论可以总结为一句话：

把AI当作人类来管理——虽然没有记忆，但它们本质上只是需要流程、约束和清晰目标。

| 技能 | 解决的问题 | 核心价值 | |------|----------|----------| | /grill-me | 需求模糊 | 用追问替代猜测 | | /to-spec | 共识不落地 | 把对话变成可执行的文档 | | /to-tickets | 任务拆分混乱 | 垂直切片，快速验证 | | /implement | 缺少执行约束 | 严格按 spec 翻译成代码 | | /tdd | 代码质量不稳定 | 红-绿-重构，锁定质量 | | /improve-codebase-architecture | 代码库拖累AI | 让AI在好土壤里生长 |

—