SPEAR框架：驾驭AI编程的工程化脚手架与七阶段方法论-洪萨配资

1. 从混沌到秩序：为什么我们需要一个AI辅助开发的“脚手架”

如果你和我一样，在过去一两年里深度使用过Claude Code、Cursor、GitHub Copilot这类AI编程工具，那你一定经历过这种“过山车”式的心路历程：一开始是狂喜——“天哪，它居然真的能写代码！”，然后是困惑——“等等，这代码逻辑好像有点问题？”，最后往往是无奈——“算了，还是我自己重写吧，改它的bug比我自己写还累。”

这就是当前AI辅助开发的真实写照：强大但混乱。工具本身的能力日新月异，但我们的工作流却依然停留在“人肉提示工程”的原始阶段。我们丢给AI一个模糊的需求，它生成一堆看起来能跑的代码，我们手动修修补补，然后祈祷它下次别犯同样的错误。整个过程缺乏结构、没有审计、无法积累经验，更别提团队协作了。结果就是，AI成了另一个需要被管理的“不可靠的初级工程师”，而不是一个能真正提升工程效能的杠杆。

我花了大量时间在真实项目中实践各种AI工作流，踩遍了所有能踩的坑，最终意识到问题的核心：我们缺少一个专门为“人机协作”设计的、强约束的工程方法论。传统的敏捷、瀑布模型是为纯人类团队设计的；而单纯给AI一个长提示词，又过于脆弱和随意。我们需要一个介于两者之间的东西——一个能驾驭AI的创造力，又能用工程的严谨性为其兜底的框架。

这就是SPEAR框架诞生的背景。它不是另一个AI工具，而是一套基于规范驱动、审计门控、自我进化的开发方法论。你可以把它理解为你AI编程工作流的“操作系统”或“脚手架”。它不关心你用Claude还是Copilot，它关心的是如何让你和AI的协作过程变得可预测、可审计、可改进。下面，我就结合自己深度使用和贡献的经验，为你彻底拆解这套可能是目前最严谨的AI辅助开发框架。

2. SPEAR核心哲学：七阶段状态机与不可违背的“铁律”

SPEAR的整个体系建立在七个严格的、顺序执行的阶段之上，它像一个状态机，推动项目从想法走向产品。每个阶段都有明确的输入、输出和验收标准，绝对不允许跳步。这听起来有点死板，但正是这种死板，强制建立了秩序。

2.1 七阶段全景解析

我们来看看这七个阶段具体在做什么，以及为什么这样的顺序是合理的：

Ignite（点燃）：解决“问题是否正确”。这不是写需求文档，而是做“意图澄清”。在这个阶段，我们会用一系列问题轰炸自己（或产品经理）：“用户真正的痛点是什么？”“现有的解决方案为什么不够好？”“我们到底要改变用户的哪种行为？” 我自己的经验是，跳过这个阶段，后面AI写得再快，也是朝着错误的方向狂奔。SPEAR在这里内置了竞争情报扫描模板，强制要求你在定义方案前，先了解战场。
Spec（规范）：解决“方案是否清晰”。这是SPEAR最核心、也最与众不同的阶段。它采用苏格拉底式的提问法，把一个大需求拆解成一系列选择题和简答题。例如，不是写“实现用户登录”，而是通过问答明确：“认证方式采用JWT还是Session？”“密码重置流程包含哪几步？”“错误提示信息是前端定义还是后端返回？” 这个过程会产生一份机器和人都能无歧义理解的PRD（产品需求文档）。这是一个硬性门禁，Spec未通过评审，任何代码工作都不能开始。
Plan（计划）：解决“路径是否可行”。基于通过的Spec，将工作拆解为可执行的阶段。每个阶段都必须定义“健康度函数”——一种可自动衡量的成功标准（如“单元测试覆盖率>80%”、“首屏加载时间<1秒”）。同时，计划阶段会输出详细的技术选型、依赖分析和风险评估。这相当于给AI和开发者都画好了行军地图。
Execute（执行）：解决“代码是否正确”。这是AI直接参与编码的阶段，但SPEAR用“TDD铁律”给它戴上了紧箍咒。规则很简单：禁止在没有任何测试的情况下编写生产代码。每个小任务都必须遵循“红-绿-重构”循环。AI必须先写一个失败的测试（红），然后写代码让测试通过（绿），最后优化代码结构（重构）。如果发现AI先写了代码，SPEAR会要求你删除重来。此外，执行必须在独立的Git工作树中进行，确保每次变更都有干净的基线。
Audit（审计）：解决“质量是否达标”。代码写完了？别急着合并。SPEAR设置了七道并行的、独立的审计关卡，每道关都有一个虚拟的“审计官”角色（由另一个AI实例或规则引擎担任）来检查。这是最强大的安全网。我们后面会详细拆解这七个类别。
Ratchet（棘轮）：解决“下次能否更好”。这是SPEAR实现“自我进化”的秘诀。棘轮机制只允许质量标准向上调整，禁止无声下滑。例如，如果本次迭代将测试覆盖率从70%提升到了78%，棘轮会自动将合格线从70%“咔哒”一声提升到76%（78%减去2%的缓冲）。下次审计时，76%就成了新的底线。这意味着项目的代码质量像棘轮一样，只会前进，不会后退。
Productize（产品化）：解决“交付是否完整”。经过棘轮收紧后的代码，在这里进行最后的打包、文档完善、发布准备和上线检查。它确保从代码到用户可用的产品，没有遗漏的环节。

这七个阶段构成了一个完整的、闭环的、自增强的工作流。它把AI从“即兴表演者”变成了“遵循乐谱的演奏家”，而乐谱的质量又在每一次循环中变得更好。

2.2 十三条不可违背的状态机规则

为了保证流程不被破坏，SPEAR框架内部强制执行13条核心规则。这些规则是框架的“宪法”，理解它们就能理解SPEAR的脾气：

阶段顺序锁：必须严格按 I -> S -> P -> E -> A -> R -> P 顺序执行。想从Plan跳回Spec？可以，但必须走完整的变更流程并记录原因。
Spec硬门禁：没有经批准的Spec文档，Execute阶段的所有工具适配器都会拒绝工作。
TDD铁律：Execute阶段中，为任何功能编写生产代码前，必须至少有一个对应的、失败的测试用例存在。
工作树隔离：每个Execute周期必须在全新的、基于干净主分支的Git工作树中开始。
五步验证门：AI完成任何代码块后，必须执行：识别变更 -> 运行测试 -> 读取结果 -> 验证通过 -> 明确声明。禁止使用“应该可以”、“可能没问题”等模糊表述。
审计独立性：七个审计类别必须并行运行，审计者（无论是另一个AI还是脚本）不能与执行者是同一个会话或具有上下文关联。
审计一票否决：任何审计类别出现CRITICAL级别问题，整个变更必须被阻塞，退回Execute阶段。
棘轮单向性：Ratchet阶段只能提高阈值或保持不变，任何降低阈值的企图都必须经过人工复审并记录详尽理由。
子任务代理：对于复杂任务，Execute阶段必须将其拆分为子任务，并分发给独立的、专注的子代理执行，然后进行两阶段评审。
系统性调试：遇到bug必须遵循四步协议：根本原因分析 -> 模式识别 -> 假设生成 -> 修复验证。连续三次修复失败，必须升级为架构问题审查。
竞争情报集成：在Spec阶段开始前，必须运行竞争格局扫描，并将发现整合到需求定义中。
项目记忆写入：每个周期学到的经验、做出的决策、发现的模式，都必须结构化地存入项目记忆库。
健康度函数绑定：Plan阶段定义的每个健康度函数，都必须在Ratchet阶段有对应的阈值进行监控。

违反这些规则，SPEAR框架本身会抛出错误并停止流程。这听起来严厉，但正是这种严厉，保障了最终产出的可靠性。

3. 核心武器库拆解：审计、棘轮与AI适配器

了解了宏观流程，我们深入看看SPEAR里几个最具革命性的“武器”是如何工作的。

3.1 七重审计门禁：给AI代码上“全身体检”

审计阶段是SPEAR的质量防火墙。它不像传统的CI/CD那样只跑一下linter和单元测试，而是从七个完全独立的维度进行深度扫描。这七类审计是并行执行的，每一类都会产生自己的“通过/失败”裁决。

第一类：安全审计这是最严格的一类。它不仅仅运行像Semgrep、CodeQL这样的静态应用安全测试工具。它的流程是：先进行SAST扫描，对发现的中高危漏洞进行变体分析（看看代码库其他地方有没有类似模式），然后检查依赖供应链（有没有被劫持的包，许可证是否合规），最后还会用规则检查常见的OWASP Top 10漏洞模式，如硬编码的密钥、SQL注入点等。一个CRITICAL级别的安全发现（例如发现一个潜在的RCE漏洞）会直接阻塞整个发布。

第二类：依赖审计专门对付“左移”的供应链安全。它会拉取所有依赖（包括间接依赖）的清单，交叉比对多个漏洞数据库，标记出所有含CVE的包、已废弃的包、许可证存在冲突的包。我遇到过最实用的是，它会评估每个依赖的“维护风险”——如果某个关键依赖最近一年没有提交，且维护者只有一个人，它会发出HIGH级别警告，建议寻找替代方案。

第三类：性能审计在早期阶段就关注性能指标。它会分析代码复杂度（圈复杂度超过20会警告），估算前端包的体积，检查数据库查询是否N+1，评估内存使用模式。它甚至能集成到构建流程中，捕获真实的首屏加载时间或API响应时间，并与健康度函数中设定的阈值进行比较。

第四类：代码质量审计这是最像传统CI的部分，但更智能。它检查代码重复率、死代码、命名一致性、错误处理是否完备。但它独特之处在于，它会学习项目的“代码风格记忆”，如果项目历史中普遍采用try-catch处理错误，而新提交用了Promise.catch，它会提示这种不一致，而不是武断地报错。

第五类：文档审计确保代码和文档不脱节。它会检查公共API的文档覆盖率，验证README中的示例代码是否还能运行，确保变更日志被更新。对于AI生成的代码，这一点尤其重要，因为AI常常忘记更新文档。

第六类：架构审计维护架构的完整性。检查是否有违反分层架构的调用（比如UI层直接访问了数据库模型），检查循环依赖，确保设计模式的使用保持一致（例如，如果项目用了工厂模式创建所有服务，那么新服务也必须通过工厂创建）。

第七类：UI/视觉审计（杀手级特性）这是SPEAR最具创新性的一点。它通过Chrome DevTools协议启动一个真实的浏览器，加载前端应用，然后执行一系列自动化操作。它能捕获控制台错误、网络请求失败、检查无障碍访问树，甚至能进行视觉回归测试——对比UI渲染截图与基线图片的差异。这意味着，AI写的前端代码不光要编译通过，还要在浏览器里看起来是对的、用起来没错误。这个审计类别极大地弥补了AI在视觉和交互层面理解不足的缺陷。

这七份审计报告会汇总成一份总览，给出最终的“GO/NO-GO”结论。只有全部审计类别都为“GO”或仅有LOW/INFO级别的问题，变更才能进入Ratchet阶段。

3.2 棘轮机制：让项目质量“自动上坡”

棘轮是SPEAR的学习中枢。它的核心思想很简单：项目的质量标准应该像棘轮一样，只能向更严格的方向转动，防止在无意中倒退。

它是如何运作的？假设你的项目当前对“单元测试覆盖率”的阈值是70%（底线）。在本轮开发中，你引入了一个新的测试框架，非常给力，把覆盖率提升到了85%。在Ratchet阶段，棘轮引擎检测到这一指标超过了当前阈值（70%）超过5个百分点（可配置），于是它自动将阈值从70%上调到83%（85%减去2%的缓冲值）。这个新的83%会被记录到.spear/ratchet/ratchet.json中。

从此以后，任何新提交的代码，其测试覆盖率都必须不低于83%，否则审计中的“性能审计”类别就会失败。这意味着，团队偶然取得的质量提升，会被框架固化下来，成为新的底线。

棘轮管理的阈值类型包括：

地板阈值：必须保持高于此值，如测试覆盖率、文档覆盖率。
天花板阈值：必须保持低于此值，如代码圈复杂度、打包后体积、API响应时间P99。

棘轮永远不会“静默地”放松标准。如果由于某些正当理由（比如引入一个必需但测试困难的三方库）需要降低阈值，必须走一个特殊的“阈值变更请求”流程，需要详细的技术理由说明，并记录在案。这保证了质量标准的任何变动都是透明且经过深思熟虑的。

3.3 AI工具适配器：一套方法论，处处可用

SPEAR框架本身是AI工具无关的，它的核心是一套规则和流程定义。为了让不同工具的用户都能用上，它提供了“适配器”。你可以把适配器看作是把SPEAR的“普通话”翻译成各种AI工具的“方言”的翻译器。

Claude Code适配器：生成一个CLAUDE.md文件，里面包含了所有阶段的具体指令、角色定义和检查清单。你只需要在Claude Code的会话中引用这个文件，它就能以SPEAR的思维模式与你协作。
Cursor适配器：生成一个.cursorrules文件。Cursor会读取这个文件，并在你使用@命令或进行代码编辑时，自动应用SPEAR的约束，比如强制你先写测试。
GitHub Copilot适配器：提供一个copilot-instructions.md。你可以将其内容配置为Copilot的全局指令或项目级指令，让Copilot在补全和建议时，遵循TDD、代码风格等规则。
通用LLM适配器：如果你用的工具不在上述列表，这个适配器提供了一个自包含的、结构化的系统提示词。你可以把它复制粘贴到任何LLM的聊天窗口（如ChatGPT、DeepSeek），作为对话的起点。

这些适配器确保了无论团队或个人偏好哪种AI编程工具，都能统一在SPEAR方法论之下，产出的过程和工件都是一致的，极大地降低了协作成本。

4. 实战演练：手把手用SPEAR开发一个用户认证模块

理论说了这么多，我们来看一个具体的例子。假设我们要为一个Web应用开发一个用户认证模块（包括登录、注册、JWT令牌管理）。看看SPEAR如何一步步引导我们和AI完成这个任务。

4.1 Ignite & Spec 阶段：把模糊想法变成精确蓝图

首先，我们不会直接打开IDE或AI聊天窗口。我们在项目根目录下执行./spear ignite（如果安装了CLI工具）或手动在.spear/templates/spec/下复制一个prd.md模板。

在Ignite阶段，我们需要回答一系列问题：

核心问题：用户现在如何管理身份？是每次都用社交账号登录，还是每次都要找回密码？
成功的样子：用户成功登录后，多久内可以无需再次认证？安全性和便利性的平衡点在哪？
竞争格局：类似的应用（如Auth0、Firebase Auth）提供了哪些功能？我们是自建还是集成？差距在哪里？

完成Ignite后，进入Spec阶段。SPEAR的Spec代理会引导我们进行苏格拉底式对话：

Spec代理：“关于登录方式，我们需要明确：是仅用户名/密码，还是支持社交登录（Google/GitHub）？如果是混合，哪个是主要方式？”我们选择：主要使用邮箱/密码，同时提供Google OAuth作为可选。

Spec代理：“关于会话管理，采用有状态的服务器会话（Session）还是无状态的令牌（JWT）？令牌的刷新机制是怎样的？”我们选择：采用JWT，访问令牌有效期30分钟，刷新令牌有效期7天，通过专用刷新接口续期。

Spec代理：“关于错误处理，登录失败时，返回的错误信息是统一的‘认证失败’，还是区分‘用户不存在’和‘密码错误’？（注意安全权衡）”我们选择：出于安全考虑，前端统一显示‘用户名或密码错误’，后端日志可区分。

这个过程会持续进行，直到所有边界情况都被讨论到，生成一份详细的auth-spec.md文档。这份文档就是后续所有工作的“宪法”。AI在Execute阶段会严格引用这份文档里的具体决策，而不是自由发挥。

4.2 Plan & Execute 阶段：拆解任务与TDD实战

基于通过的Spec，我们进入Plan阶段。我们会把“用户认证模块”拆解成多个阶段，比如：

阶段1：后端JWT令牌生成与验证库。
阶段2：用户模型、数据库迁移、密码哈希存储。
阶段3：登录、注册、刷新令牌的RESTful API端点。
阶段4：前端登录/注册表单与API集成。
阶段5：前端令牌存储与请求拦截。

每个阶段都有明确的健康度函数，例如阶段1的健康度函数是：“JWT库的单元测试覆盖率需达到90%以上，且能通过所有RFC 7519的测试向量。”

现在，进入最关键的Execute阶段。我们打开配置了SPEAR适配器的Cursor（或Claude Code）。我们要实现阶段1的JWT库。

错误示范（传统AI用法）：我们直接对AI说：“写一个Node.js的JWT库。” AI生成了一堆sign和verify函数代码。我们手动去写测试。

SPEAR正确示范：我们启动Execute代理。它会首先检查当前阶段计划，然后强制进入TDD循环。

RED（红）：AI代理做的第一件事，是编写一个会失败的测试。它可能会生成类似下面的代码：
```
// test/jwt.test.js const { sign } = require('../src/jwt'); describe('JWT sign', () => { it('should throw error when secret is missing', () => { expect(() => sign({ userId: 123 })).toThrow('Secret is required'); }); });
```
此时运行测试，肯定是失败的，因为src/jwt.js文件甚至还不存在。这就是“红”。

GREEN（绿）：接着，AI代理去实现最简单的代码让这个测试通过。

// src/jwt.js function sign(payload, secret) { if (!secret) { throw new Error('Secret is required'); } // 简单实现，先让测试通过 return 'dummy.token'; } module.exports = { sign };

运行测试，通过了！这就是“绿”。功能虽然简陋，但行为符合预期。

REFACTOR（重构）：现在，AI代理（或我们）可以去完善sign函数，引入真正的加密算法（如HMAC SHA256），处理payload序列化、生成标准的JWT三段式结构等。每做一次重构，就运行一次测试，确保始终是“绿”。

这个“红-绿-重构”的循环，会针对每一个小功能点（如验证令牌、过期检查、不同算法支持）重复进行。SPEAR的Execute代理会严格监督这个过程，如果检测到先写了实现代码而没有对应的失败测试，它会发出警告并要求回退。

在整个Execute阶段，每完成25%、50%、75%和100%的工作量，SPEAR都会要求创建一个检查点提交，并记录任何与原始计划的偏差。这保证了进度的可见性和可控性。

4.3 Audit & Ratchet 阶段：质量检验与标准提升

当阶段1的代码提交后，预提交钩子会自动触发七类审计。

安全审计：SAST工具可能会发现我们用的jsonwebtoken库版本存在一个已知的低危CVE。审计报告标记为LOW。
依赖审计：检查确认jsonwebtoken的许可证是MIT，与项目兼容。
性能审计：代码复杂度分析通过，函数都很简单。
代码质量审计：发现有一个函数的错误处理是console.error而不是抛出异常或返回错误对象。标记为MEDIUM，建议改进。
文档审计：JWT库的公共API（sign,verify）都有JSDoc注释，通过。
架构审计：通过，代码放在src/lib/auth/下，符合项目结构。
UI/视觉审计：不适用，标记为N/A。

由于没有CRITICAL或HIGH问题，审计总体结果为“GO”，但附带两个需要处理的问题（CVE和错误处理）。我们可以选择立即修复，也可以记录在案在后续迭代中处理（但MEDIUM以上问题通常建议在本阶段解决）。

修复后，进入Ratchet阶段。假设我们阶段1的单元测试覆盖率达到了92%，超过了计划中90%的健康度函数。棘轮引擎检测到这一超过阈值的提升（>5%），于是自动将“单元测试覆盖率”的底线阈值从90%提升到了90%（因为92%-2%缓冲=90%，未超过原阈值，所以这次不提升。但如果覆盖率达到了95%，阈值就会被提升到93%）。同时，关于“错误处理应使用抛出异常模式”这一决策，会被作为一条新的代码规则，存入项目记忆库。下次AI写类似代码时，就会参考这条规则。

4.4 贯穿始终的实用技巧与避坑指南

在实际使用SPEAR几个月后，我积累了一些官方文档里不会写的经验：

技巧一：Spec阶段要“穷尽”选项，但避免“过度设计”Spec阶段的问答很容易陷入细节泥潭。我的经验是，对于核心流程（如登录主流程），必须穷举所有分支（成功、密码错误、账号被锁、网络超时）。但对于边缘功能（如“通过安全问题找回密码”），如果当前迭代不包含，就在Spec中明确写上“本阶段不实现，留待后续迭代”，并简要说明假设。这避免了AI在Execute阶段“自作聪明”地提前实现。

技巧二：善用“子代理执行”处理复杂任务当AI在Execute一个复杂任务（如“搭建完整的React路由守卫”）时表现不佳时，不要一直和它纠缠。使用SPEAR的“子代理执行”功能，将任务拆解：“子任务A：创建高阶组件withAuth”、“子任务B：在路由配置中集成withAuth”、“子任务C：编写路由守卫的单元测试”。每个子任务由一个干净的、专注的AI会话来执行，最后由主代理进行集成评审。这能显著提升复杂任务的完成质量。

技巧三：审计报告要“会看”七类审计报告信息量很大，不要被吓到。优先处理CRITICAL和HIGH。对于MEDIUM和LOW，建立一个团队规则：例如，每个迭代必须解决至少两个MEDIUM，LOW可以暂时搁置但需有跟踪票据。UI/视觉审计的报告尤其重要，它提供的浏览器截图和控制台错误列表，是前端调试的黄金线索。

技巧四：棘轮阈值设置要“循序渐进”一开始不要设置太高的阈值，否则会寸步难行。建议从行业平均水平开始（比如测试覆盖率从60%起步）。让棘轮机制随着项目成熟度自然地将标准拉高。如果一开始就设到90%，团队和AI都会感到极度挫败。

最大的坑：忽视“项目记忆”.spear/memory/目录下的文件不是日志，是宝藏。里面记录了所有重要的技术决策、发现的bug模式、有效的解决方案。在开始一个新功能或修复一个bug前，花5分钟浏览相关记忆文件，能让AI少走很多弯路。我习惯在每次迭代的Ratchet阶段后，花时间整理和提炼本次迭代的记忆，用清晰的标题归档，例如memory/auth-password-hashing-choice.md。

5. 团队协作、集成与自定义扩展

SPEAR不是一个单兵作战的工具，它在团队环境和现代工程体系中更能发挥价值。

5.1 在团队中推行SPEAR

让整个团队接受一套新的、严格的方法论是个挑战。我的建议是：

从小处试点：不要在全公司推行。先找一个有探索精神的小团队，在一个新的、非核心的中等项目上试点。
强调收益，而非规则：向团队展示SPEAR如何减少“AI胡写代码导致的深夜加班”，如何通过审计提前发现安全漏洞，如何用棘轮让代码质量“自动”提升。用事实和数据说话。
定制化适配器：如果团队主要用VS Code + Copilot，就重点配置Copilot适配器；如果用JetBrains全家桶，可以一起贡献一个通用的IDE适配器。降低使用门槛。
建立团队知识库：将.spear/memory/目录纳入团队共享知识库。定期组织“记忆回顾会”，分享各个项目中学到的最佳实践和踩过的坑。

SPEAR的仓库中提供了团队工作流升级指南，包括如何设置共享的中央Ratchet阈值服务器，如何统一管理各项目的审计规则库等。

5.2 与现有CI/CD管道集成

SPEAR不是用来替代你现有的GitLab CI、Jenkins或GitHub Actions的，而是增强它们。最自然的集成点有两个：

作为预提交钩子：SPEAR的审计钩子（尤其是安全、代码质量、依赖审计）可以集成到pre-commit或husky中，在代码提交前就拦截问题。
作为CI流水线中的一个阶段：在你的CI配置中，增加一个“SPEAR Audit”阶段。这个阶段拉取SPEAR框架，针对合并请求（Pull Request）的代码运行完整的七类审计，并将审计报告作为评论发布到PR中。这为代码评审提供了极其客观、全面的数据支持。
Ratchet作为质量门禁：在CI的“部署前”阶段，运行SPEAR的Fitness Functions，检查当前代码的关键指标是否满足棘轮设定的最新阈值。不满足则流水线失败，阻止部署。

5.3 自定义与扩展

SPEAR是一个开源框架，其设计初衷就是可扩展的。

自定义审计类别：如果你对“移动端性能”有特殊要求，可以仿照现有模板，在.spear/agents/目录下创建一个audit-mobile-performance.md代理，定义你的检查规则和严重性标准。
自定义健康度函数：除了内置的覆盖率、复杂度，你可以为你的项目定义独特的健康度函数。比如对于一个API服务，可以定义“95%的API端点响应时间<100ms”作为健康度函数，并让CI定时运行测试来采集这个指标。
开发新适配器：如果你用的AI工具不在支持列表，为其开发适配器是贡献价值极高的方式。核心是理解该工具如何接收指令，然后将SPEAR的13条规则和阶段逻辑“翻译”过去。

6. 常见问题与排查实录

即使有了完善的框架，在实际操作中还是会遇到各种问题。下面是我遇到的一些典型问题及解决方法。

Q1：AI在Execute阶段就是不按TDD来，总是先写实现代码怎么办？A1：这通常是适配器配置不彻底或AI“忘记”了上下文。首先，检查你使用的适配器文件是否被正确加载（例如，Cursor的.cursorrules是否在项目根目录）。其次，在每次开始Execute阶段时，用明确的指令重申规则：“我们将严格遵守SPEAR的TDD铁律。接下来实现[功能X]，请首先为我编写一个会失败的测试用例。” 如果AI仍然违规，立即中断，使用SPEAR的“系统性调试”协议，分析是提示不清晰还是任务太复杂需要拆解。

Q2：审计阶段耗时太长，特别是UI/视觉审计要启动浏览器，拖慢了开发节奏。A2：这是性能与质量的权衡。建议采用分层审计策略：

本地开发：在预提交钩子中只运行安全、代码质量、依赖这三类轻量级审计。
Pull Request：在CI流水线中运行全部七类审计，包括UI/视觉审计。这样既保证了提交速度，又确保了合并前的代码质量。
可以配置UI审计只针对有前端变更的PR运行，通过分析git diff来判断。

Q3：棘轮自动提升的阈值太激进，导致一个简单的修复因为测试覆盖率差0.5%而无法合并。A3：棘轮的自动提升逻辑（超过阈值5%则提升）是可以配置的。你可以在.spear/config.json中调整ratchet.auto_tighten_margin（自动收紧幅度）和ratchet.buffer_percentage（缓冲百分比）。例如，将幅度从5%调到10%，缓冲从2%调到5%，会让提升变得更“温和”。更重要的是，阈值变更请求流程就是为这种情况设计的。如果确实有合理理由（如紧急安全补丁），可以发起请求临时调整阈值，但必须附上详细说明和后续改进计划。

Q4：团队觉得Spec阶段太繁琐，写文档的时间比写代码还长。A4：这是一个观念问题。Spec阶段不是在“写文档”，而是在“做设计”。前期多花一小时厘清需求，能避免后期浪费十小时重写代码。可以向团队展示数据：统计采用SPEAR前后，每个需求因模糊、变更导致的返工次数。通常会有显著下降。另外，可以优化Spec模板，对于小型、重复性的任务（如“增加一个API字段”），可以使用简化的Spec模板，聚焦核心决策点。

Q5：SPEAR框架本身的更新如何管理？A5：SPEAR框架（.spear目录）应该被当作项目的“开发依赖”来管理。建议将你的项目.spear目录初始化为一个Git子模块（git submodule），指向SPEAR的主仓库或你维护的某个稳定版本分支。这样，你可以通过更新子模块引用来有控制地升级框架，并方便地查看框架本身的变更历史。永远不要手动编辑.spear目录下的核心文件，自定义配置应放在项目特定的配置文件中。

走到这里，你应该对SPEAR框架有了一个从哲学到实操的全面认识。它不是一个银弹，不能替代工程师的思考和判断。但它是一个极其强大的“力放大器”和“纪律执行者”。它强迫我们在AI的“魔法”面前保持工程的严谨，将看似随机的AI输出，转化为稳定、可靠、可积累的软件资产。最让我个人受益的，不是它帮我写了多少行代码，而是它帮我建立了一种与AI协作的可重复的成功模式。我不再需要每次从头开始设计提示词，不再担心AI上次犯的错这次再犯，也不再因为代码质量波动而焦虑。这一切，都源于那七个严格的阶段和十三条不容妥协的规则。如果你也受困于AI编程的混沌，不妨找一个项目，把SPEAR这套“脚手架”搭起来试试看，那种一切尽在掌控的感觉，真的很不错。