/ 目录 / 演练场 / pilot-shell
● 社区 maxritter ⚡ 即开即用

pilot-shell

作者 maxritter · maxritter/pilot-shell

内置质量门的规格驱动 Claude Code——每次变更都经过「计划 → 规格 → 实现 → 验证」流程才能落地。

pilot-shell 用规格驱动循环包裹 Claude Code:功能从计划开始,变成规格,按验收标准实现,并只在所有质量门通过(lint、类型检查、测试、文档)后才允许发布。它还自动维护项目知识——不变量、决策、坑点——确保质量跨会话保持一致。

为什么要用

核心特性

实时演示

实际使用效果

就绪

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "pilot-shell-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "pilot-shell-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/maxritter/pilot-shell",
        "~/.claude/skills/pilot-shell"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "pilot-shell-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/maxritter/pilot-shell",
          "~/.claude/skills/pilot-shell"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add pilot-shell-skill -- git clone https://github.com/maxritter/pilot-shell ~/.claude/skills/pilot-shell

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: pilot-shell

以规格优先的纪律交付功能

👤 厌倦了 AI 写出半成品功能的开发者 ⏱ ~90 min intermediate

何时使用: PM 提了一个模糊的功能需求;你想把它做对,而不只是做快。

前置条件
  • Skill 已安装 — git clone https://github.com/maxritter/pilot-shell ~/.claude/skills/pilot-shell
步骤
  1. 计划
    Use pilot-shell. Plan the feature 'export usage CSV per workspace per month'. List unknowns + risks.✓ 已复制
    → 含明确未知项的计划;你在下一步之前填补空白
  2. 写规格
    From the plan, write a spec with acceptance criteria + non-goals + edge cases.✓ 已复制
    → 规格已保存到 /specs/<feature>.md
  3. 实现
    Implement against the spec. Tests first, then code. Stop at any unmet criterion.✓ 已复制
    → 测试 + 实现;未通过的测试可见,直到实现满足条件
  4. 运行质量门
    Run all gates: lint, type, tests, docs. Block PR if any red.✓ 已复制
    → 质量门报告;全绿才是 PR 候选

结果: 功能按规格完整交付,附带测试和文档。

注意事项
  • 规格阶段拖成规划马拉松 — 将规格阶段限时 30 分钟;强制就未知项做出决策,而非追求完美规格
搭配使用: filesystem

不再开出首次 CI 就失败的 PR

👤 PR 经常在基础检查上挂掉的开发者 ⏱ ~30 min intermediate

何时使用: 这周你开了 3 个 PR,全部因为基础问题 CI 失败。

步骤
  1. 配置质量门
    Use pilot-shell. Configure quality gates to mirror our CI: eslint, tsc, vitest, prettier.✓ 已复制
    → .pilot.config.json 中列出了质量门
  2. 失败时阻塞
    Set policy: don't open PR until all gates green locally.✓ 已复制
    → 策略已应用
  3. 度量效果
    After 2 weeks, compare CI first-run pass rate before/after.✓ 已复制
    → 通过率提升

结果: PR 首次 CI 即通过;审查者减少无谓的反复。

注意事项
  • 本地质量门与 CI 存在细微差异(Node 版本) — 用 .nvmrc 固定本地 Node 版本;完全镜像 CI 的确切命令
搭配使用: github

随团队成长保留项目知识

👤 正在交接/共享项目的项目负责人 ⏱ ~30 min beginner

何时使用: 你在交接或共享项目;想把决策和不变量记录下来。

步骤
  1. 初始化知识文件
    Use pilot-shell. Initialize project knowledge with: architecture, key invariants, decisions log.✓ 已复制
    → /.pilot/knowledge.md 已创建,含各章节
  2. 边工作边记录
    Whenever a decision is made (chose Postgres over MySQL), record with date + reason.✓ 已复制
    → 决策不断积累;新协作者可以查阅历史
  3. 用于入职
    When a new collaborator starts, point Claude Code to this file as primary context.✓ 已复制
    → 上手更快;「为什么是这样」的疑问减少

结果: 知识在团队变动中得以保留。

注意事项
  • 知识文件变成琐事流水账 — 保持简洁:不变量、决策、坑点。不是日报

组合

与其他 MCP 搭配,撬动十倍杠杆

pilot-shell-skill + github

从规格自动填充 PR 模板;CI 验证质量门

When opening a PR, populate the body from the spec markdown; CI checks gates match.✓ 已复制
pilot-shell-skill + filesystem

规格和知识提交到仓库

Persist /specs/ and /.pilot/knowledge.md in repo for review history.✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
plan feature_description 任何新功能的第一步 0
spec plan_id 计划未知项解决后 0
implement spec_id 规格审批后 0
run_gates scope? PR 前;CI 镜像检查 0
knowledge_update decision_or_invariant 记录项目级决策 0

成本与限制

运行它的成本

API 配额
无——本地
每次调用 Token 数
规格文档约 500–2000 token;知识文件上限约 3000 token 以保持可管理
费用
免费
提示
将 knowledge.md 控制在约 3000 token 以内;定期整合旧条目

安全

权限、密钥、影响范围

最小权限: filesystem-write
凭据存储:
数据出站:

故障排查

常见错误与修复

本地质量门通过但 CI 失败

固定 Node 版本,处理 OS 特定依赖;完全镜像 CI 命令

验证: 对比本地与 CI 命令输出
实现步骤跳过了测试优先

在 .pilot.config 中设置 strict_tdd=true;工具将拒绝在测试之前编写实现

规格阶段拖延

使用 --time-box 30m;强制就未知项做出决策,而非追求完美规格

知识文件过长

运行 knowledge_consolidate;将旧条目归档到 /.pilot/archive/

替代方案

pilot-shell 对比其他方案

替代方案何时用它替代权衡
spec-workflow-mcp你想要以 MCP 服务器形式实现跨工具的规格流程(而非 Claude Code skill)配置更多;部署更灵活
Plain CLAUDE.md + manual TDD个人项目,你不需要自动化依赖自律;缺少护栏

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills