1. 项目概述一个由AI驱动的自主功能交付系统最近在探索如何将AI智能体真正落地到实际的软件交付流程中我深度体验了一个名为“speckit-agents”的开源项目。这个项目构建了一个由“产品经理PM智能体”和“开发者Dev智能体”组成的协作团队它们能够通过一个自托管的聊天平台Mattermost进行沟通并基于结构化的产品需求文档PRD自主地完成从需求分析、规格制定到代码实现、提交PR的全流程。简单来说它试图让AI扮演一个微型开发团队的角色而人类则作为监督者和决策者在关键节点进行审批和干预。这个项目的核心价值在于它并非一个孤立的代码生成工具而是一个完整的、可观测的、人机协同的工作流系统。对于中小型团队或个人开发者而言它可以自动化处理那些重复性高、定义明确的开发任务比如根据PRD添加一个新功能、修复一个已知的Bug或者为现有代码库补充单元测试。项目巧妙地利用了GitHub开源的Spec Kit工具来提供结构化的开发规范并通过Mattermost一个类似Slack的开源聊天工具作为人机交互的界面使得整个流程透明且可控。如果你对AI智能体编排、自动化开发流水线或者如何将大语言模型LLM与现有开发工具链深度集成感兴趣那么这个项目提供了一个非常具体且可操作的范本。2. 核心架构与工作流拆解2.1 双智能体协作模型PM与Dev的角色定义在这个系统中两个智能体被赋予了明确的角色和职责模拟了一个微型产品团队的协作模式。产品经理PM智能体是整个流程的发起者和需求把关人。它的核心职责是持续阅读并理解项目根目录下的PRD.md产品需求文档。这份文档通常以用户故事User Story或功能列表的形式编写例如“作为一个用户我希望能够通过邮箱注册和登录”。PM智能体会分析PRD找出其中优先级最高且尚未被实现的功能点然后通过Mattermost聊天频道向人类操作员“提出建议”。它的思考过程类似于“根据PRD下一个高价值、低复杂度的功能是‘用户邮箱登录’我建议现在开始实施。”开发者Dev智能体则是具体的执行者。一旦PM的建议获得人类批准Dev智能体就会接管工作。它严格遵循Spec Kit定义的四阶段结构化工作流来完成任务。这个工作流强制进行“先设计后编码”确保了输出的代码不是随意生成的而是有规划、可验证的。Dev智能体在编码过程中如果遇到PRD中未明确的细节比如“密码重置邮件的模板应该是什么样子”它会主动在聊天中向PM智能体提问。PM智能体则会基于PRD的上下文进行回答模拟了现实中开发向产品确认需求的场景。这种角色分离的设计非常精妙。它避免了让单个“全能”智能体去处理从宏观策略到微观实现的所有问题而是通过分工让每个智能体更专注也使得整个流程更易于人类理解和控制。你可以清晰地看到“产品决策”和“技术实现”两个环节是如何分离又协作的。2.2 基于Spec Kit的结构化实现流水线Spec Kit是本项目Dev智能体的“核心生产工具”。它不是一个AI模型而是一套由GitHub发布的、基于Claude Code CLI的命令行工具集旨在为AI辅助编码提供标准化的流程。Dev智能体对它的调用是完全自动化的其工作流包含四个不可跳跃的步骤/speckit.specify制定规格这是第一步也是防止AI“信口开河”的关键。针对批准的功能如“添加用户登录”Dev智能体会运行此命令生成一个详细的SPEC.md文件。这个文件会明确功能的范围、输入输出、API接口设计、数据结构、边界条件以及非功能性要求如性能、安全。这相当于在写代码之前先产出一份技术设计文档。/speckit.plan制定计划基于上一步的规格文档AI会制定具体的实施计划并输出PLAN.md。这份计划会拆解任务例如1创建用户模型User Model2实现认证控制器Auth Controller3设计登录和注册的API端点4编写相关的数据库迁移脚本。计划中还会预估可能的风险和依赖。/speckit.tasks生成任务将计划进一步细化为可执行的具体任务项生成TASKS.md。每个任务都非常具体例如“在app/models/user.py中创建User类包含email唯一索引、password_hash字段”。“在app/routes/auth.py中实现POST /api/auth/register端点”。这个文件是AI后续执行操作的直接清单。/speckit.implement执行实现这是最终的执行阶段。AI会逐条读取TASKS.md中的任务在代码库中执行相应的创建、修改、删除文件等操作并尝试运行简单的命令如运行测试、启动服务来验证更改是否有效。这个流程强制AI进行“慢思考”先设计再编码极大地提高了生成代码的相关性和质量。项目speckit-agents的价值就在于将这套本地命令行工具封装成了一个可以通过聊天命令触发、在独立工作区运行、并能与人类交互的自动化服务。2.3 人机交互与状态管理Mattermost与Redis的作用自动化流程离不开可靠的人机交互和状态持久化本项目在这方面也做了扎实的工程化设计。Mattermost作为交互中枢项目选择自托管的Mattermost而非Slack等SaaS产品主要出于对数据隐私和定制化的考虑。在Mattermost中你需要为PM和Dev智能体分别创建两个机器人账号Bot。整个协作都在一个指定的频道中进行所有对话、指令、审批和问答都发生在这里。人类操作员可以像与同事聊天一样通过简单的命令进行控制product-manager /suggest主动命令PM智能体建议下一个功能。approve/reject对PM的建议或Dev的中间产出进行批准或拒绝。直接某个智能体提问例如在Dev实现过程中你可以问“developer 为什么选择JWT而不是Session”这种基于聊天工具的交互使得监督变得非常自然和低门槛。你不需要登录某个复杂的运维面板只需要打开日常使用的聊天工具就能掌握一切。Redis保障流程可靠性软件开发流程可能是漫长的中间可能遇到网络问题、AI服务不稳定或需要人工长时间评审。因此流程的状态必须被持久化。项目使用Redis来存储工作流的状态机信息。例如当前流程是处于“PM建议中”、“等待人类批准”、“Dev正在制定规格”还是“实现完成等待合并”。orchestrator.py这个核心的“编排器”模块其本质就是一个有状态的状态机它所有的状态变迁都记录在Redis中。这带来了两个关键好处一是支持--resume参数当进程意外中断后可以从断点恢复不会丢失工作二是为未来的扩展打下了基础比如可以实现多个工作流并行、任务队列等。3. 从零开始部署与配置实战3.1 基础环境与依赖准备在开始部署前你需要准备好以下基础设施和工具。我的建议是即使你只是想体验也尽量在Linux或macOS的开发环境下进行Windows可能会在依赖安装和脚本运行上遇到更多挑战。Python环境确保系统已安装Python 3.10或更高版本。推荐使用pyenv来管理多版本Python避免污染系统环境。项目管理工具uv这是一个用Rust写的、速度极快的Python包管理器和安装器类似于pip和poetry的结合体。项目用它来管理依赖和虚拟环境。安装非常简单一行命令curl -LsSf https://astral.sh/uv/install.sh | sh。安装后uv命令应该就可以用了。Claude Code CLI这是整个项目的“大脑”。你需要一个ClaudeAnthropic的账号并按照官方指南安装和认证Claude Code CLI。认证成功后在终端运行claude命令应该能启动交互式会话。关键点确保你的API额度充足因为整个流程会进行多次、长时间的模型对话消耗的Token不少。GitHub CLI (gh)因为最终Dev智能体会创建Pull Request所以需要gh命令行工具已安装且通过gh auth login完成了认证。这样AI才能以你的身份向仓库提交PR。Mattermost服务器这是最大的前置条件。你需要一个正在运行的Mattermost实例。可以从官网下载团队版进行自托管也可以使用Docker快速启动一个测试实例。你需要知道它的访问地址如http://localhost:8065并拥有一个管理员账号以便后续创建机器人用户和获取访问令牌。Redis可选但强烈推荐用于状态持久化。可以通过Docker快速启动docker run -d -p 6379:6379 redis:alpine。如果暂时不想用项目也有基于文件的状态管理回退方案但在多进程或需要可靠恢复的场景下Redis是必选项。注意环境准备阶段最容易出问题的是Claude Code CLI的认证和网络连通性。请务必在终端中手动测试claude命令可以正常与模型对话并确保你的网络环境能够稳定访问Claude的API服务。Mattermost的安装和配置也需要一些耐心建议先单独把它调通。3.2 项目初始化与核心配置详解完成基础环境准备后就可以开始配置项目本身了。# 1. 克隆代码库 git clone https://github.com/sbhavani/speckit-agents.git cd speckit-agients # 2. 使用uv创建虚拟环境并安装所有依赖包括开发依赖 uv sync --dev # 这步可能会花点时间uv会并行下载和编译依赖速度比pip快很多。接下来是最关键的配置环节。项目提供了一个config.yaml作为模板但我们需要复制它并创建本地的config.local.yaml文件这个文件会被.gitignore用于存放你的敏感信息。cp config.yaml config.local.yaml # 现在用你喜欢的编辑器打开 config.local.yaml这个配置文件结构清晰主要分为四大块我们需要逐一攻破a) 配置目标项目你要让AI开发哪个代码库在projects:部分你需要添加至少一个项目。例如你有一个名为my-awesome-app的Python Web应用projects: my-awesome-app: # 项目标识符自定义用于命令行指定 path: /home/yourname/code/my-awesome-app # 目标代码库的绝对路径 prd_path: docs/PRD.md # PRD文档在该代码库中的相对路径 channel_id: your_mattermost_channel_id_here # Mattermost频道IDpath必须是一个Git仓库的本地路径。AI将在此路径下创建独立的工作树worktree进行开发避免污染主分支。prd_path这是PM智能体的“知识库”。你需要事先在这个路径下编写好结构化的产品需求文档。文档质量直接决定了AI建议的准确性和可实现性。建议使用清晰的Markdown格式分模块描述功能。channel_id如何获取在Mattermost网页端进入你打算用于协作的频道点击频道标题在菜单里找到“查看频道信息”浏览器的地址栏URL末尾通常会有一串字符如channels/team-name/channel-id其中的channel-id就是所需ID。b) 配置大语言模型LLM项目默认配置了与MiniMax API的兼容端点但核心是使用Claude Code CLI。通常你不需要修改llm:部分的base_url和model除非你打算完全替换掉Claude Code CLI直接调用其他兼容OpenAI API的模型服务。对于大多数用户保持默认即可真正的模型调用由Claude Code CLI内部处理。c) 配置Mattermost核心交互通道这部分配置需要你在Mattermost服务器上完成一些操作创建机器人用户以管理员身份登录Mattermost系统控制台创建两个新用户例如pm-bot和dev-bot。记下他们的用户名。获取个人访问令牌分别以pm-bot和dev-bot的身份登录Mattermost网页端或使用API在“账户设置” - “安全” - “个人访问令牌”中为每个机器人创建一个令牌。这个令牌相当于机器人的密码。将机器人添加到频道把你创建的频道上面获取了channel_id的频道的pm-bot和dev-bot都加进去。完成以上操作后填写配置mattermost: url: http://your-mattermost-server.com # 你的Mattermost服务器地址 channel_id: your_channel_id # 同上也可以留空使用项目级配置 dev_bot_user_id: dev_bot的用户ID pm_bot_user_id: pm_bot的用户ID # 注意这里配置的是用户ID不是用户名。用户ID可以在Mattermost的用户管理页面查看或者通过API获取。如何获取用户ID一个简单的方法是通过浏览器开发者工具。在Mattermost网页端查看机器人用户的主页URL中通常包含类似users/user-id的片段。d) 配置Redis状态持久化如果你启动了Redis配置很简单redis_streams: url: redis://localhost:6379 # 如果Redis有密码格式为 redis://:passwordlocalhost:6379 stream: feature-requests consumer_group: orchestrator-workers保持其他默认值即可。如果不想用Redis可以将url设置为null系统会回退到文件存储。3.3 验证与首次运行配置完成后强烈建议先运行健康检查命令它能帮你发现大部分配置问题uv run python orchestrator.py --doctor这个--doctor命令会检查Python依赖是否齐全、Claude CLI是否可用且已认证、Mattermost连接和令牌是否有效、目标项目路径和PRD文件是否存在、Git配置是否正确等。根据它的报错信息逐一修正直到所有检查通过。一切就绪后你可以尝试以“响应模式”启动系统这是最接近生产环境的运行方式# 在一个终端窗口启动响应器它会监听Mattermost中的指令 uv run python responder.py # 在另一个终端窗口启动工作进程消费者它从Redis流中获取任务并执行 uv run python worker.py --consumer worker-1 # 或者启动一个包含3个工作进程的池子更健壮 uv run python worker_pool.py --workers 3现在打开Mattermost在你配置的频道里输入product-manager /suggest如果一切正常PM机器人应该会回复开始分析PRD并给出第一个功能建议。你可以回复approve来批准然后观察Dev机器人是否被触发并开始按照Spec Kit的流程工作。整个对话和代码变更都会在频道中实时可见。4. 深入核心模块与高级用法4.1 核心脚本功能解析项目由几个核心Python脚本构成理解它们的分工有助于你进行调试和定制开发。orchestrator.py编排器这是系统的大脑是一个状态机驱动的工作流引擎。它负责整个生命周期的推进触发PM建议、等待人类审批、调用Dev执行Spec Kit四阶段、处理问答、最终创建PR。你可以通过命令行参数直接运行它来驱动一次完整的流程例如uv run python orchestrator.py --project my-awesome-app这在调试和单次任务执行时非常有用。responder.py响应器这是一个常驻服务通过WebSocket长连接监听Mattermost频道。当它在频道中看到product-manager /suggest命令或被机器人时会将这个“事件”转化为一个任务消息发送到Redis Stream中。它本身不执行具体工作只负责接收和分发指令。worker.py与worker_pool.py工作进程它们是实际干活的“工人”。worker.py是一个独立的Redis Stream消费者它从指定的Stream中拉取任务即来自responder的事件然后调用orchestrator.py中的逻辑来执行具体工作流。worker_pool.py则是一个管理脚本可以启动、监控和重启多个worker.py进程提高了系统的并发处理能力和可靠性。mattermost_bridge.py桥梁封装了与Mattermost API交互的所有细节包括发送消息、接收事件、格式化消息等。它同时管理PM和Dev两个机器人的会话是系统与外界交互的唯一通道。state_redis.py状态管理器抽象了状态存储层。虽然名字叫redis但它内部实现了适配器模式如果Redis不可用会自动回退到基于本地JSON文件的存储。所有工作流的进度、中间结果都通过这个模块进行持久化和读取。4.2 命令行参数实战指南orchestrator.py提供了丰富的命令行参数让你可以灵活地控制AI的行为模式适应不同的使用场景。基础执行模式uv run python orchestrator.py最标准的流程。由PM智能体读取PRD并建议功能然后等待人类交互。uv run python orchestrator.py --dry-run强烈推荐的试运行模式。所有流程照常执行AI也会进行“思考”和“规划”但不会真正向Mattermost发送消息也不会修改任何代码文件。所有输出打印到控制台。这是验证你的PRD和配置是否会被AI正确理解的最佳方式不会产生任何副作用。uv run python orchestrator.py --feature “修复登录页面的CSS样式”跳过PM建议阶段直接让Dev智能体实现你指定的功能。适用于你已有明确、独立的任务时。流程控制模式uv run python orchestrator.py --simple --feature “添加一个README说明”使用--simple参数将跳过Spec Kit的specify、plan、tasks三个阶段直接让AI尝试实现。这适用于极其简单、不需要设计的小修改或文档更新速度更快。uv run python orchestrator.py --resume从上次中断的状态恢复执行。比如AI在实现到一半时遇到了错误你修复了问题后可以用此命令让它从中断点继续而不是重头开始。uv run python orchestrator.py --approve通常与--resume结合使用在恢复的同时自动批准所有等待中的审批环节。这在自动化测试或确认流程时有用。uv run python orchestrator.py --loop循环模式。完成一个功能后自动让PM建议下一个功能并继续流程直到PRD中所有功能被处理完或手动停止。这可以实现批量的、无人值守的自动化开发但风险较高需要密切监控。调试与信息模式uv run python orchestrator.py --doctor如前所述进行全面的环境健康检查。uv run python orchestrator.py --show-state打印出当前为指定项目保存的工作流状态从Redis或文件中方便你查看流程卡在了哪一步。uv run python orchestrator.py --verbose或--log-level DEBUG输出最详细的日志信息包括AI思考的中间过程、API调用详情等是排查复杂问题的利器。4.3 工具增强与自定义钩子项目提供了一个名为“工具增强”Tool Augmentation的实验性功能在配置文件中通过workflow.tool_augmentation.enabled: true开启。这个功能允许你在Spec Kit工作流的每个阶段specify, plan, tasks, implement前后插入自定义的Python钩子函数。这些钩子函数定义在tool_augment.py中目前主要提供两类能力发现Discovery在阶段开始前运行。例如在specify之前钩子可以自动运行代码库的测试套件将失败信息作为额外上下文提供给AI让AI知道当前代码的健康状况。或者在plan之前运行依赖分析工具将现有的接口和数据结构信息提供给AI。验证Validation在阶段结束后运行。例如在implement之后自动运行代码格式化工具如black, isort、静态类型检查如mypy或单元测试如果验证失败可以自动将错误信息反馈给AI要求它重新尝试或修正。要启用这个功能你需要在config.local.yaml中设置enabled: true。根据你的项目技术栈修改tool_augment.py文件实现pre_specify_hook,post_implement_hook等函数。这些函数需要返回一个字符串这个字符串会被作为额外提示词插入到给AI的指令中。确保你的项目环境中安装了钩子函数所需的命令行工具如pytest, black等。这是一个非常强大的扩展点能将你现有的CI/CD工具链与AI开发流程深度集成实现更高程度的自动化质量控制。5. 生产环境部署与运维考量5.1 使用Docker Compose一键部署对于希望长期运行或在服务器上部署的用户项目提供了deploy/docker-compose.yml文件可以一键启动所有依赖服务。# 进入部署目录 cd deploy # 首先你需要将之前配置好的 config.local.yaml 复制到 deploy/ 目录下 # 或者更规范的做法将配置内容转为Docker Compose的环境变量或卷挂载。 # 假设你已经调整好了docker-compose.yml中的配置指向。 # 启动所有服务Mattermost, Redis, 以及本应用的responder和worker docker compose up -d # 查看日志 docker compose logs -f speckit-agentsDocker部署将Mattermost和Redis也包含在内形成了一个完整、隔离的运行环境。你需要仔细阅读docker-compose.yml文件理解其中卷挂载、环境变量和网络配置特别是如何将你本地的代码仓库路径映射到容器内部以及如何配置Mattermost的初始化数据。5.2 监控、日志与错误处理在长期运行中监控系统的健康状况至关重要。日志管理应用默认将日志输出到控制台。在生产环境中你应该配置日志重定向到文件或像ELK、Loki这样的日志聚合系统。可以通过修改Python的logging配置或者简单地在启动命令后添加重定向例如uv run python responder.py /var/log/speckit-responder.log 21。--log-level参数可以动态调整日志详细程度平时可设为INFO排查问题时设为DEBUG。错误处理与重试AI服务Claude API和Mattermost服务都可能出现网络波动或暂时不可用。项目中的状态机设计和Redis持久化已经提供了基本的容错能力--resume。对于工作进程workerworker_pool.py提供了自动重启机制。你还可以考虑使用像supervisord或systemd这样的进程管理工具来守护responder.py和worker_pool.py确保它们崩溃后能自动重启。人工监督与审批尽管名为“自主”但人工监督是这个系统不可或缺的安全阀。务必定期查看Mattermost频道中的对话。重点关注AI的提问当Dev智能体提问时往往意味着PRD存在模糊之处。你的回答不仅影响当前任务也会被PM智能体学习记录到.agent/product-manager.md中用于优化未来的决策。生成的规格和计划SPEC.md, PLAN.md在批准进入实现阶段前花几分钟阅读AI生成的这些文档。这能提前发现错误的设计思路避免AI在错误的方向上浪费token并产生需要大量清理的代码。最终的代码变更在AI创建PR后务必进行代码审查。虽然AI能生成可运行的代码但在代码风格、架构一致性、边界情况处理上可能仍需人工优化。5.3 安全与成本控制建议安全考虑令牌与密钥config.local.yaml包含了Mattermost访问令牌和潜在的API密钥。务必确保该文件权限为600并且不会被提交到Git仓库项目已通过.gitignore排除。在Docker部署中使用Docker secrets或环境变量来传递敏感信息。代码仓库访问AI智能体拥有对你配置的代码库的写权限通过GitHub CLI。建议为AI创建一个专用的、权限受限的GitHub机器账号而不是使用你的个人主账号。将该机器账号作为协作者Collaborator添加到仓库并仅授予必要的推送和创建PR权限。Mattermost频道权限用于AI协作的Mattermost频道应设置为私有频道仅限相关开发成员加入避免敏感的项目信息和代码变更公开泄露。AI生成代码的审查永远不要盲目合并AI生成的PR。必须将其视为一位初级开发者提交的代码进行严格的安全性和逻辑审查特别是涉及用户输入、数据库操作、身份认证和授权等敏感区域。成本控制Claude API开销一次完整的Spec Kit流程specify - plan - tasks - implement会进行多轮复杂的模型对话消耗的Token数量相当可观尤其是对于大型功能。在将项目用于大型任务或开启--loop模式前最好先用--dry-run模式估算一下Token消耗。关注你的API用量账单设置预算告警。优化PRD清晰、简洁、无歧义的PRD能减少AI的困惑和来回问答从而节省Token。将大功能拆解成独立的小用户故事让AI逐个击破比让它一次性处理一个庞大的需求更高效、更便宜。合理使用--simple模式对于微不足道的小修改如修改错别字、更新配置常量使用--simple模式跳过设计阶段可以显著降低成本。6. 常见问题与故障排查实录在实际部署和运行过程中你几乎一定会遇到一些问题。下面是我踩过的一些坑以及解决方案希望能帮你快速排雷。6.1 环境与配置类问题问题1运行uv run python orchestrator.py --doctor时提示Claude Code CLI未找到或未认证。排查首先在终端直接运行claude命令看是否能正常启动交互界面。如果不能说明CLI安装或认证有问题。解决重新按照Claude Code CLI官方指南安装。确保运行claude命令的终端环境与运行uv run的环境是同一个用户、同一个Shell特别是环境变量。有时虚拟环境可能会造成路径问题可以尝试在项目目录外直接运行claude测试。问题2Mattermost连接失败错误信息包含“Invalid token”或“Unable to post”。排查检查config.local.yaml中的mattermost.url是否正确确保能从运行脚本的机器访问该URL。检查dev_bot_user_id和pm_bot_user_id填写的是否是用户ID一串长字符而不是用户名。检查为这两个机器人用户生成的“个人访问令牌”是否已正确复制到配置中注意不要有多余空格。确认机器人用户已被添加到指定的频道中。解决一个快速验证Mattermost配置的方法是使用curl命令curl -i -H Authorization: Bearer YOUR_BOT_TOKEN http://YOUR_MM_SERVER/api/v4/users/me如果返回200 OK并包含用户信息说明令牌有效。再用该令牌尝试向频道发消息。问题3AI无法读取或理解PRD.md文件。排查确认config.local.yaml中projects.xxx.prd_path配置的路径是相对于项目path的相对路径且该文件确实存在。检查PRD文件的编码和格式。确保是UTF-8编码的纯文本Markdown文件。查看Mattermost中PM机器人的回复或者使用--dry-run模式看AI输出的分析内容是否与PRD相关。如果完全不相关可能是文件路径错误如果相关但理解偏差可能是PRD书写不够清晰。解决PRD的书写至关重要。建议采用以下结构# 项目PRD ## 功能模块A * **用户故事**作为[角色]我希望[达成目标]以便[获得价值]。 * **验收标准** * [标准1] * [标准2] ## 功能模块B ...避免使用模糊的语言尽量具体。6.2 工作流执行类问题问题4Dev智能体在执行/speckit.implement时卡住或报错。排查这是最常见的问题。首先打开--verbose日志查看AI具体在执行哪个任务时出错。错误通常有两种命令执行错误AI尝试运行npm install,pytest等命令失败。可能是项目依赖未安装、测试本身失败或者环境变量缺失。代码生成错误AI生成的代码存在语法错误导致后续命令如导入检查失败。解决对于命令错误你需要确保目标项目在AI的工作上下文中是“可构建”和“可测试”的。有时需要你在项目目录下提前运行pip install -e .或npm install。对于代码错误这是Spec Kit工作流的优势所在。因为错误发生在implement阶段而specify,plan,tasks的中间产物SPEC.md, PLAN.md, TASKS.md都已经被保存下来。你可以手动阅读这些文件检查AI的设计思路是否有问题然后中断流程修正PRD或这些中间文件再使用--resume让AI重试。关键技巧充分利用Mattermost的交互。当AI卡住或报错时它有时会主动在频道中提问或报告问题。你可以直接它提供更明确的指令比如“请忽略之前的错误重新尝试实现用户登录功能”或者“请使用SQLAlchemy而不是原始的SQL语句”。问题5AI创建的PR包含了无关的更改或格式混乱。排查AI在独立的工作树worktree中工作但它的基础分支可能不是最新的main分支。或者AI在实现过程中运行了像black,isort这样的格式化工具但格式与项目原有风格不一致。解决在配置中可以确保AI在开始前先执行git pull origin main更新工作树。考虑启用tool_augmentation中的post_implement_hook强制在AI提交前运行项目的格式化工具统一代码风格。无论如何人工代码审查Code Review是必须的。将AI视为一个强大的代码助手而不是全自动的开发者。问题6--resume无法正确恢复状态或者状态混乱。排查检查Redis是否正常运行或者文件状态存储.state/目录下的JSON文件是否损坏。使用--show-state命令查看当前存储的状态是什么。解决状态管理是复杂的。如果状态混乱最直接的方法是清除状态并重新开始。对于Redis可以删除对应的key对于文件删除.state/目录下对应的JSON文件。然后重新启动流程。在关键步骤如人类批准后手动检查一下状态文件有助于理解状态机的进展。6.3 性能与优化类问题问题7流程运行速度很慢每个阶段都要等很久。分析速度慢主要受限于1) Claude API的响应速度2) Spec Kit每个阶段都需要AI进行大量思考3) 网络延迟。优化对于小型、明确的任务使用--simple模式绕过设计阶段。确保你的网络到Claude API的延迟尽可能低。将大的产品需求拆分成更小、更独立的用户故事。让AI快速完成一个个小功能比让它长时间思考一个庞大功能要更高效、更可靠。问题8Token消耗巨大成本太高。分析Token消耗与PRD的复杂度、代码库的规模AI需要阅读相关文件作为上下文、以及AI在实现过程中遇到的错误和重试次数正相关。优化精炼PRD用最简洁的语言描述需求。提供上下文在项目根目录放置一个ARCHITECTURE.md或CONTEXT.md文件简要说明技术栈、目录结构和核心模式。这能帮助AI更快理解项目减少盲目探索。限制范围通过配置可以限制AI在specify和plan阶段只关注特定的目录或文件减少它需要分析的代码量。主动干预当发现AI在某个问题上反复纠结、产生很长但无用的对话时及时在Mattermost中给出明确指令打断它的无效思考。这个项目将前沿的AI智能体技术与经典的软件工程流程相结合为我们展示了一种人机协同开发的新范式。它不是一个“取代开发者”的工具而是一个“增强开发者”的系统将开发者从重复性的、模式化的编码任务中解放出来更专注于高层的设计、复杂的逻辑和创造性的工作。最大的体会是它的成功运行极度依赖于清晰、结构化的输入PRD和积极、细致的人工监督。把它当作一个能力极强但经验尚浅的实习生你需要清晰地交代任务并耐心地检查它的工作成果。当你把这些实践固化下来你会发现整个团队的交付效率和一致性都能得到显著的提升。