Pilot Shell：基于规格驱动开发的Claude Code工程化框架实践

1. 项目概述：Pilot Shell，一个让Claude Code真正“可用”的工程化框架

如果你和我一样，在Claude Code刚出来那会儿兴奋地试了几天，然后就被它那“想到哪写到哪”的风格给劝退了——写个小函数还行，一遇到正经项目，代码质量参差不齐、测试全靠随缘、上下文说丢就丢，最后还得自己手动收拾烂摊子。那感觉就像找了个才华横溢但极其随性的助手，灵感来了能写出惊世之作，但大多数时候你得跟在后面擦屁股。

Pilot Shell的出现，彻底改变了这个局面。它不是一个“另一个AI编码工具”，而是一个工程化框架，专门解决Claude Code在生产环境中的核心痛点：缺乏结构、质量不可控、上下文断裂、成本高昂。简单说，它把Claude Code从一个“聪明的代码生成器”，变成了一个能遵循软件工程规范、可预测、可协作的“AI工程师”。

它的核心思路非常清晰：用规范驱动开发，用自动化保障质量，用持久化保存知识。你不再需要和AI反复拉扯“这里要加个测试”、“那里格式不对”，Pilot Shell通过一套内置的、可强制执行的“质量关卡”（Quality Gates），在AI写代码的每一个环节自动进行代码检查、测试运行和规范验证。更关键的是，它引入了/spec（规格驱动开发）工作流，要求AI在动键盘之前，必须先和你一起制定详细的实施计划，包括测试场景，然后像真正的工程师一样，在隔离的Git工作树中，以测试驱动开发（TDD）的方式完成任务，最后再进行自动化验证。

我花了近一周时间深度使用Pilot Shell，从零搭建了一个全栈应用，并并行开发了三个功能。我的结论是：这是目前将Claude Code用于严肃项目开发的最佳实践框架。它适合任何希望将AI编码助手规模化、流程化地融入日常工作的开发者、技术负责人或小团队。无论你是想快速原型验证，还是维护一个大型代码库，Pilot Shell提供的那套“护栏”和“自动化流水线”，能极大提升产出代码的可靠性和你的心理安全感。

2. 核心设计哲学：为什么是“Spec-Driven Development”？

在深入细节之前，我们必须先理解Pilot Shell的基石：规格驱动开发（Spec-Driven Development）。这不仅仅是把Claude Code内置的“计划模式”（Shift+Tab）换个名字，而是一套完整的、强制性的工作方法论。其核心目的是解决AI编码的“黑盒”与“随意性”问题。

2.1 从“对话式编码”到“契约式协作”

传统的Claude Code交互是线性的、对话式的。你提要求，它生成代码，你再提修改意见，如此循环。这种模式有两个致命缺陷：

1. 目标漂移：在多次来回中，最初的需求可能被遗忘或曲解。
2. 质量后置：测试、代码规范等质量保障活动往往被放在最后，甚至被忽略。

/spec工作流将这种松散对话转变为一种契约式协作。当你输入/spec “添加用户登录功能”时，你启动的不是一个代码生成任务，而是一个需求澄清、计划制定、评审批准、实施验证的完整流程。AI会首先扮演“系统分析师”和“测试工程师”的角色，而不是直接跳进去写代码。

这个流程强制建立了一份“契约”（即规格说明书），明确了“做什么”、“怎么做”以及“怎么算做完”。这份契约成为了后续所有活动的唯一依据。AI在实现阶段，必须严格遵循契约中的任务分解和测试场景；在验证阶段，也必须对照契约逐项检查。这从根本上杜绝了“跑题”和“偷工减料”。

2.2/spec双模式解析：功能开发 vs. 缺陷修复

Pilot Shell的聪明之处在于，它能自动识别你的意图，并在两种高度优化的模式下运行/spec：

功能模式（Feature Mode）：用于新功能开发、重构或架构变更。这是最完整的流程：

1. 探索与规划：AI会先用语义搜索（Probe）分析你的代码库，理解现有结构和模式。然后，它会向你提出澄清性问题，确保理解无误。接着，它会生成一份详细的规格说明书，包含范围、任务列表和“完成定义”。最关键的一步：对于涉及UI的功能，它会编写端到端（E2E）测试场景——这些是可被浏览器自动化工具执行的、步骤明确的测试用例，它们将成为验证阶段的“合同”。
2. 评审与批准：生成计划后，一个独立的“规格评审子代理”会检查计划的完整性。你可以在Pilot Shell控制台的“规格”页面，以可视化标注模式直接在高亮文本上添加批注。AI会读取这些批注，修订计划，并再次等待你的批准。这相当于一次轻量级的、人机协作的PRD评审。
3. 实施与测试：一旦批准，AI会创建一个隔离的Git工作树。在这个独立的分支环境中，它开始逐个实现任务，并且强制采用TDD（红-绿-重构）循环：先写一个失败的测试，再实现代码让测试通过，最后重构代码。每一次编辑后，内置的“质量钩子”会自动运行代码检查、格式化和类型检查。
4. 验证与合并：所有任务完成后，运行完整的测试套件。对于UI功能，会自动执行之前编写的E2E测试场景，一步步在浏览器中操作并记录结果。最后，一个“统一评审子代理”会进行合规性、质量和目标达成度的综合审查。全部通过后，代码才会被压缩合并（squash merge）到主分支。

缺陷修复模式（Bugfix Mode）：用于针对性问题修复。其哲学是“先调查，后修改”，避免盲目改动引入新问题。

1. 根因调查：AI首先尝试复现Bug，然后反向追踪调用链，定位到具体的文件:行号级别的根本原因。它会对比正常工作的代码模式，给出修复方案并附上置信度。如果连续3个假设都失败，它会将其升级为架构问题。
2. 测试先行修复：在修改任何代码前，AI会先写一个回归测试，这个测试在当前有Bug的代码上必须失败。然后，它实施最小化的修复，确保这个回归测试通过。如果Bug涉及共享代码路径，还会进行多层防御性验证。
3. 轻量级验证：验证环节只包含回归测试确认、完整测试套件运行以及代码检查。没有复杂的评审子代理——因为回归测试本身已经证明了修复的有效性，完整测试套件则证明了没有破坏其他功能。

这种模式区分体现了深刻的工程智慧：对新功能，强调全面的规划和预防；对已知缺陷，强调精准的定位和修复。这远比让AI在一种模式下处理所有问题要高效和可靠得多。

3. 核心组件深度拆解与实操要点

Pilot Shell由多个相互协作的组件构成。理解每个组件的作用和它们之间的联动，是高效利用它的关键。

3.1 Pilot Shell 控制台：你的本地任务指挥中心

安装后，在浏览器打开http://localhost:41777，你就进入了Pilot Shell控制台。这不仅仅是一个“状态面板”，而是一个功能完整的本地Web应用，数据存储在本地SQLite中，所有数据不离线，保障了隐私和速度。

核心视图与使用场景：

• 仪表盘：全局概览。八个可点击的数据卡片（如活跃会话、待批准规格等）让你快速掌握全局。最近的活动记录（规格、需求、会话、记忆）以卡片形式呈现，点击“显示全部”可进入对应详情页。顶部导航栏会显示所有进行中的/spec任务，像看板一样清晰。
• 会话：浏览所有历史会话。这里有一个杀手级功能：复制任意会话的ID，回到终端，输入/resume <会话ID>，Claude Code就能瞬间恢复到那个会话的完整上下文。这彻底解决了AI对话“健忘”的问题，让你可以随时中断、随时续上。
• 规格：所有/spec计划的家园。在这里，你可以看到每个计划的任务进度、阶段状态和迭代历史。当计划处于“待批准”状态时，页面会自动进入标注模式。你可以像在Google Docs里一样，选中任何一段文本添加评论，或者直接在任何代码块、段落旁点击“+”号添加批注。AI在下一轮迭代中会直接读取这些批注并据此修改计划。这实现了真正的人机协作式规划评审。
• 变更：一个内置的Git差异查看器。在/spec验证阶段，当AI完成所有自动化检查后，它会提示你在此页面进行代码审查。开启“审查模式”，你就可以在具体的代码差异行上添加行内注释。AI会读取每一条注释，并在标记规格为“已验证”之前解决它们。这相当于在代码合并前，增加了一道人工质量关卡。
• 扩展：管理所有规则、命令、技能和MCP服务器的地方。界面清晰地按“项目”、“全局”、“插件”分类。对于团队，可以通过连接Git仓库来实现扩展的共享、推送、拉取和差异对比。

实操心得：控制台是你的“第二大脑”不要只把控制台当监控面板用。我的习惯是：启动一个/spec后，立即打开控制台的“规格”页面。在AI生成计划时，我同步浏览，并用标注功能快速提出疑问或修改意见（比如“这个任务的优先级是不是反了？”、“这里需要考虑错误处理”）。这比在终端里用文字描述要直观高效得多。同样，在“变更”页面做代码审查，比在终端里滚动查看git diff要舒服得多，尤其是对于大型改动。

3.2 扩展系统：规则、技能与团队共享

Pilot Shell的强大，很大程度上源于其高度模块化和可定制的扩展系统。所有扩展都是纯Markdown文件，位于.claude/（项目级）或~/.claude/（全局级）目录下。

1. 规则：项目的“宪法”规则是Claude Code在每次会话（或针对特定文件类型）时自动加载的指令集。Pilot Shell预置了10条核心规则，涵盖工作流、测试、验证、调试、代码审查等。例如，testing.md规则会强制要求为任何新逻辑编写测试；verification.md规则定义了代码合并前的检查清单。 你可以运行/setup-rules命令，让AI自动分析你的代码库，发现现有的代码规范和模式，并为你生成一套模块化的、针对性的项目规则。对于Monorepo，它还能智能地按产品或团队组织规则到子目录，并用paths前端元数据将规则作用域限定到特定文件类型。

2. 技能：可复用的工作流技能是比规则更复杂的、可触发的工作流程。Pilot Shell内置了/spec、/prd等核心技能。每个技能是一个文件夹，包含一个SKILL.md文件（描述和触发条件）以及可能的步骤脚本、参考资料。 你可以使用/create-skill命令，将任何你经常执行的复杂操作（例如“自动化部署流程”、“生成API客户端SDK”）封装成一个技能。AI会引导你探索代码库、定义技能结构、编写触发描述，并经过质量门禁测试。一旦创建，这个技能就可以在任何项目中通过简单的命令调用来复用。

3. 团队共享与APM兼容性这是Pilot Shell团队版（Team Tier）的亮点。你可以在控制台的“扩展”页面，将一个Git仓库连接为团队的“远程扩展库”。

• 推送/拉取：可以将本地的优秀规则或技能推送到团队仓库，供所有成员拉取使用。
• 差异对比：内置的并排差异视图，让你清晰看到本地版本和远程版本的区别。
• APM格式：勾选一个选项，你的团队仓库就能自动转换为APM包。这意味着，不仅Pilot Shell用户，任何使用Copilot、Cursor、OpenCode或Claude Code的开发者，都可以通过apm install owner/repo直接安装你的团队扩展。Pilot Shell会自动将文件结构转换为APM约定（如rules/->instructions/），并注入兼容的前端元数据。

注意事项：规则的作用域与冲突规则加载有优先级：项目规则（.claude/rules/）会覆盖全局规则（~/.claude/rules/）。如果你和团队共享了某个规则文件（例如python-standards.md），但本地修改了它，在拉取远程更新时可能会遇到冲突。控制台的“扩展”页面提供了清晰的冲突解决界面。最佳实践是：将团队通用规范放在团队仓库中，将个人偏好或项目特有规则放在本地。使用/setup-rules可以很好地帮你梳理和迁移现有规则。

3.3 上下文优化与成本控制：让每一分Token都花在刀刃上

使用大型语言模型，尤其是Claude这样的长上下文模型，成本是一个无法回避的问题。Pilot Shell在上下文管理和成本优化上做了大量精细的工作，宣称能减少60-90%的Token消耗。

1. 智能模型路由Pilot Shell不会在所有场景下都使用最强大（也最贵）的Claude Opus模型。它的默认策略是：

• 规划阶段：使用Claude Opus。因为规划需要深度理解、创造性思考和复杂推理，Opus的能力值得付出更高成本。
• 实施与验证阶段：切换到Claude Sonnet。Sonnet在代码生成、问题解决和遵循指令方面已经非常出色，且成本远低于Opus。 你可以在控制台的“设置”中，为/spec工作流的每个阶段（计划、实施、验证）以及不同的子代理（如评审代理）分别指定模型。甚至可以手动输入特定的Anthropic模型ID来锁定版本。

2. 精益上下文策略这是成本节约的大头。Pilot Shell采用了多种策略来保持上下文“瘦身”：

• 条件规则加载：不是一次性加载所有规则。规则文件的开头有paths或file_types等元数据，只有当AI操作到相关文件时，对应的规则才会被加载进上下文。
• 渐进式技能披露：技能文件夹中的SKILL.md文件（约100个Token）始终加载，它包含了技能描述和触发条件。只有当技能被触发时，技能文件夹内详细的步骤文件才会被加载。
• 惰性MCP工具加载：MCP服务器提供了大量工具（如文件系统、Git、浏览器控制）。Pilot Shell不会一次性宣告所有工具，而是按需加载工具描述，减少上下文中的工具列表噪音。
• 上下文模式沙箱：对于大型输出（如生成的代码文件），Pilot Shell会使用一种“沙箱”技术，使其不直接进入对话上下文，而是通过引用方式访问，极大减少了重复性内容对上下文的占用。

3. RTK输出压缩Pilot Shell集成了RTK（一种输出压缩代理）。当AI生成冗长的代码或文本时，RTK会尝试用更简洁的方式表达相同的意思，从而减少输出Token。控制台状态栏会实时显示“Savings: N%”，让你直观看到节省的效果。

4. 针对200K上下文窗口的“抗压”设计即使Claude支持200K的长上下文，填满它依然昂贵且可能影响模型表现。Pilot Shell的“上下文模式”和规则设计，确保了即使在超长会话中，有效上下文也能保持精简，维持模型的响应质量。

实操心得：监控与调优务必关注控制台“使用情况”页面和终端状态栏。状态栏的第二行会显示“5h / 7d usage”，这是你Claude订阅的速率限制使用情况。箭头向上变红表示使用速度超过了配额节奏，需要留意。如果成本上升过快，可以去“设置”中检查模型路由策略，或许可以将“实施”阶段也调整为Sonnet。对于探索性、非关键任务，直接使用pilot命令进入“快速模式”，避免触发完整的/spec流程，也是一个节约成本的好办法。

4. 完整工作流实操：从零构建一个全栈待办事项应用

理论说得再多，不如亲手做一遍。让我们用一个完整的例子，串联起Pilot Shell的核心功能。我们的目标是：构建一个具有用户认证、任务增删改查的全栈待办事项应用。

4.1 环境准备与项目初始化

首先，确保你的系统满足前提条件：安装了原生安装器版本的Claude Code（不是npm或brew版），并且拥有有效的Claude订阅（个人开发者建议Max 5x或Max 20x）。

打开终端，执行一键安装命令：

curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash

这个安装脚本大约需要2分钟，它会完成7个步骤：检查并安装基础依赖（如Node.js, Python）、设置Claude插件目录、安装核心工具（Probe语义搜索、CodeGraph代码知识图、RTK等）、配置Shell别名、安装推荐的VSCode扩展。所有文件都会放在~/.pilot/和~/.claude/目录下。

安装完成后，创建一个新的项目目录并进入：

mkdir todo-app && cd todo-app git init # 初始化Git仓库，这对Pilot Shell的Git工作树功能至关重要

现在，运行pilot命令，你会进入Claude Code的对话界面，但状态栏已经变成了Pilot Shell的增强版，显示着模型、上下文使用率、Git状态等信息。

4.2 阶段一：使用/prd明确产品需求

我们的想法是“做一个待办事项应用”。但这个需求太模糊。直接上/spec可能会让AI做出不符合预期的设计。因此，我们先使用/prd来生成一份产品需求文档。

在pilot对话中输入：

/prd “开发一个全栈待办事项Web应用，需要用户注册登录，能创建、查看、编辑、删除任务，任务可以标记完成。希望界面简洁现代。”

AI会开始与你对话，首先询问研究深度：“Quick”（跳过研究）、“Standard”（标准网页搜索）或“Deep”（深度并行研究）。对于这个常见项目，选择“Quick”即可。

接着，AI会扮演产品经理的角色，向你提出一系列澄清性问题，例如：

• “用户注册需要邮箱验证吗？还是简单的用户名/密码即可？”
• “任务除了标题和完成状态，还需要优先级、截止日期、标签等属性吗？”
• “前端你倾向于使用什么技术栈？React、Vue还是纯HTML/JS？后端呢？Node.js + Express，还是Python Flask？”
• “数据需要持久化吗？使用数据库还是本地存储？”

你需要一一回答。这个过程强迫你思考项目的细节。对话结束后，AI会生成一份结构清晰的PRD文档，保存在docs/prd/目录下，并自动在Pilot Shell控制台的“需求”页面中展示。这份文档包含了问题陈述、用户画像、核心用户流程、功能范围、非功能需求以及技术选型建议。

关键点：/prd的价值在于前置沟通。它把模糊的想法转化为双方（你和AI）都有清晰共识的书面契约。你可以随时在控制台中回顾和修改这份PRD。

4.3 阶段二：使用/spec并行开发核心功能

基于PRD，我们有了明确的技术选型：前端用React + Vite，后端用Node.js + Express，数据库用SQLite。现在，我们可以开始并行开发了。Pilot Shell的Git工作树功能让这成为可能。

我们同时开启三个/spec会话，分别负责不同的模块。你需要打开三个终端标签页或使用cmux这类分屏终端。

终端1 - 用户认证模块：

cd todo-app pilot > /spec “实现用户认证系统，包括用户模型、注册、登录、JWT令牌生成与验证、密码哈希加密（使用bcrypt）。提供RESTful API端点。”

AI进入功能模式。它会分析项目（目前是空的），然后生成计划：设计数据库Schema（用户表）、创建Express路由和控制器、实现密码哈希逻辑、编写JWT中间件、编写单元测试和集成测试。你批准计划后，AI会在一个独立的Git工作树中开始TDD开发。

终端2 - 后端任务API模块：

cd todo-app pilot > /spec “实现任务（Todo）的CRUD API。任务属于用户，包含标题、描述、完成状态、创建时间等字段。提供对应的RESTful端点，并确保所有操作都经过JWT认证。”

AI会识别到这是一个与终端1相关的功能。在它的计划中，会包含“与用户模型关联”、“复用JWT中间件”等任务。它同样会在另一个独立的工作树中开发。

终端3 - 前端React界面模块：

cd todo-app pilot > /spec “使用React和Vite创建前端界面。需要登录页面、注册页面、主任务管理页面（显示任务列表、添加表单、操作按钮）。调用后端API，使用axios进行HTTP通信，管理用户登录状态。”

AI会为这个UI功能编写详细的E2E测试场景，例如：“1. 访问首页，重定向到登录页。2. 输入正确凭证登录，跳转到任务列表页。3. 点击‘添加任务’，填写表单并提交，新任务出现在列表中。”

并行开发的魔法：这三个/spec会话相互独立，不会污染对方的上下文。它们都基于同一个Git主分支（目前是空的）创建各自的工作树。Pilot Shell的状态栏会清晰显示每个会话的计划名称和进度（如auth-system [feature/implement] [=====>] 3/5 tasks）。你可以在Pilot Shell控制台的“规格”页面总览所有进行中的任务。

4.4 阶段三：代码审查、验证与集成

当每个/spec会话完成“实施”阶段，进入“验证”阶段时，AI会运行完整的测试套件。对于前端/spec，它还会自动启动浏览器（通过集成的Chrome DevTools MCP或Playwright），执行之前编写的E2E测试场景，并记录每一步的通过/失败结果。

人工审查介入：所有自动化检查通过后，AI会提示你进行代码审查。此时，你切换到Pilot Shell控制台的“变更”页面。

1. 选择对应的/spec任务。
2. 打开“审查模式”开关。
3. 浏览代码差异。如果你发现某个API响应格式不一致，或者前端组件缺少错误处理，可以直接在对应的代码行上点击“+”添加行内注释，比如：“这里应该统一返回{ success, data, message }格式” 或 “需要添加加载状态和错误提示”。
4. 提交注释。AI会立即读取这些注释，修改代码，并重新运行相关的测试。

最终合并：当你对审查结果满意后，在终端里确认验证。AI会将对应Git工作树中的所有更改，压缩合并（squash merge）到主分支（main）上。由于工作树是隔离的，合并冲突的概率很低。即使有冲突（比如两个模块都修改了package.json），Pilot Shell也会提示你解决。

至此，三个功能模块陆续开发、审查、合并完毕。一个具备完整功能的全栈应用就构建完成了。你可以在主分支上启动应用，进行端到端的测试。

避坑指南：并行开发的协调

1. 依赖管理：如果模块B依赖模块A的API，最好等模块A的/spec完成并合并到main后，再启动模块B的/spec。这样模块B的AI在分析代码库时就能看到模块A已完成的代码。
2. 通用配置：像package.json中的依赖、数据库连接配置等，最好由一个/spec（比如“项目初始化与基础配置”）先行完成，合并到main，其他模块基于此开发。
3. 频繁合并：鼓励小步快跑，完成一个相对独立的功能就合并一次，减少后续集成的复杂度。

5. 高级功能与定制化：打造属于团队的AI工作流

当你和团队深度使用Pilot Shell后，一定会产生定制化需求。Pilot Shell提供了强大的定制化能力，甚至允许你覆盖其核心工作流。

5.1 Pilot Bot：24/7自动化代理

除了交互式的/spec开发，Pilot Shell还提供了pilot bot命令，启动一个持久化的自动化代理。它就像一个常驻后台的智能助手，可以处理计划任务、监控系统健康。

pilot bot

首次运行会进行初始化，之后它会持续运行。你可以通过技能与它交互，例如：

• bot-jobs：管理定时任务。你可以让它“每天上午9点运行测试套件并报告结果”或“每小时检查一次依赖库的安全更新”。
• bot-heartbeat：设置心跳检测。Bot会定期检查你定义的服务（如数据库、API端点）是否健康，仅在发现问题时通知你。
• 如果安装了Telegram插件，Bot还能与你进行双向消息通信，接收指令和发送通知。

这与OpenClaw等外部自动化框架类似，但优势在于它深度集成在Pilot Shell生态中，可以直接利用已有的规则、技能和MCP工具，无需额外配置和成本。

5.2 深度定制化：覆盖默认行为

对于团队或企业，Pilot Shell允许你安装一个“定制化包”，来覆盖或扩展其默认行为。这个包可以是一个Git仓库，也可以是一个本地文件夹。

pilot customize install https://github.com/your-team/pilot-customizations

安装后，你的定制化配置会与Pilot Shell的默认配置进行深度合并。

你可以定制什么？

• 技能：修改内置的/spec工作流。例如，在“实施”阶段后，强制插入一个“安全代码审查”步骤。你可以在customization.json中定义insert_after、replace等操作。
• 规则：添加团队专属的编码规范（如team-security-rules.md），或覆盖默认的测试规则。
• 钩子：注册自定义的“质量钩子”脚本。例如，在代码提交前运行一个团队特有的安全扫描工具。
• 代理：添加自定义的评审代理，在/spec的评审阶段引入团队专家的检查逻辑。
• MCP/LSP服务器：完全替换默认的工具服务器列表，集成团队内部开发的工具。
• Claude设置：深度合并团队的默认模型偏好、环境变量、权限设置到每个成员的settings.json中。

结构示例：

my-team-custom/ ├── customization.json # 定义如何覆盖/spec技能 ├── rules/ │ └── team-standards.md # 添加团队规则 ├── hooks/ │ ├── team-security-scan.sh │ └── hooks.json # 注册自定义钩子 └── agents/ └── senior-reviewer.md # 添加高级评审代理

通过pilot customize status可以查看当前生效的定制化源和是否有更新冲突。pilot customize diff可以对比本地定制与Pilot上游更新的差异，方便你合并改进。

5.3/create-skill：将知识沉淀为资产

这是我最喜欢的功能之一。在开发过程中，你可能会让AI重复执行一些复杂的、项目特有的操作。例如：“每次发布前，运行一套特定的集成测试，生成版本变更日志，并打上Git Tag”。与其每次都手动描述，不如将其封装成一个技能。

pilot > /create-skill “自动化发布流程：运行集成测试、生成CHANGELOG、创建Git版本标签、更新版本号”

AI会引导你完成整个过程：探索当前项目的发布相关文件、询问流程细节、检查是否已有类似技能、然后在一个独立的技能文件夹中创建SKILL.md文件以及可能的辅助脚本。它会确保技能的描述包含明确的触发短语（例如“准备发布”或“run release”），并且技能本身是确定性的、可移植的。

创建完成后，这个技能就保存在了.claude/skills/目录下。未来，在任何会话中，只要你说出触发短语，Claude就会自动加载并执行这个完整的发布流程。这是将个人或团队的“ tacit knowledge”（隐性知识）转化为可复用、可共享的“ explicit knowledge”（显性知识）的强大工具。

6. 常见问题与故障排查实录

在实际使用中，你可能会遇到一些问题。以下是我和社区遇到的一些典型情况及解决方法。

Q1: 安装失败，提示Claude Code未安装或版本不对。A1:Pilot Shell强依赖原生安装器版本的Claude Code。如果你通过npm install -g @anthropic-ai/claude或brew install claude安装，需要先卸载它们。前往Claude Code官网下载对应操作系统的原生安装包。安装脚本会尝试自动检测并安装Claude Code，但最好手动确保其已正确安装且命令行claude可用。

Q2: 运行/spec时，AI似乎没有正确分析我的代码库，计划很空泛。A2:这通常是因为Probe（语义搜索）或CodeGraph（代码知识图）没有正确索引你的项目。首先，确保你是在项目根目录（有.git文件夹）下运行pilot。其次，对于大型或新项目，可以手动运行一次索引：

# 在项目根目录下 npx @probe.cli index . --verbose

这可能需要一些时间。索引完成后，AI在规划时就能更好地理解你的代码结构。

Q3: 状态栏显示的“成本”飙升很快，超出了我的预期。A3:检查以下几点：

1. 模型路由：去控制台“设置”里，确认“实施”和“验证”阶段是否错误地配置成了“Opus”。对于大多数编码任务，Sonnet足够好且便宜得多。
2. 会话残留：长时间不结束的会话会积累大量上下文。对于已经完成的任务，及时使用/end或退出对话。利用“会话”列表和/resume功能来管理长期上下文，而不是让一个会话无限延长。
3. 规则膨胀：检查你的项目.claude/rules/目录下是否有过于庞大或冗余的规则文件。规则文件应该简洁、有明确的作用域。使用/setup-rules可以帮你优化和模块化规则。

Q4: Git工作树合并时出现冲突。A4:这是并行开发中可能遇到的问题。Pilot Shell使用Git工作树来隔离更改，但最终合并回main分支时，如果多个工作树修改了同一文件的同一区域，就会冲突。

• 预防：在规划阶段，通过清晰的/spec描述和PRD，让AI明确各模块的职责和接口，减少交叉修改。
• 解决：当AI提示合并冲突时，它会尝试自动解决简单冲突。对于复杂冲突，你需要手动介入。Pilot Shell会暂停，让你在终端或IDE中解决冲突，完成后再告诉AI继续。关键：在并行开发高度耦合的模块时，考虑串行化或加强模块间的接口约定。

Q5: E2E测试失败，但手动测试又是好的。A5:浏览器自动化测试（通过Chrome DevTools MCP或Playwright）有时不稳定。

1. 元素选择器：AI生成的测试可能使用了不稳定的CSS选择器（如:nth-child(3)）。在审查E2E测试场景时，可以建议AI使用更稳定的选择器，如>export VERSION=8.3.0 # 替换成你想要的版本号 curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/install.sh | bash
2. 卸载：运行卸载脚本将清除二进制文件、插件文件、管理的命令/规则、设置和Shell别名。

   curl -fsSL https://raw.githubusercontent.com/maxritter/pilot-shell/main/uninstall.sh | bash

   注意：这不会卸载Claude Code本身。

Pilot Shell代表了一种新的AI辅助编程范式：它不是替代开发者，而是通过引入严格的工程纪律和自动化流程，将AI的创造力引导到可预测、高质量、可协作的产出轨道上。从模糊的需求到可运行的、经过测试的生产级代码，/spec工作流提供了一条清晰的路径。而其扩展系统、成本控制、团队协作功能，则让它具备了在真实团队环境中规模化应用的能力。

我个人最大的体会是，它改变了我和AI协作的“心理模式”。以前是“我下指令，它出代码，我挑错”，充满了不确定性和反复。现在更像是“我们一起制定蓝图，它负责按图施工并自我质检，我负责关键节点的评审和决策”。这种模式下，我的时间更多地花在了高层次的设计和决策上，而不是低层次的语法纠错和调试上。如果你已经受够了AI编码的“玩具”感，渴望将其用于真正的生产工作，Pilot Shell是目前最值得投入时间学习和整合的工具，没有之一。