/ 目录 / 演练场 / pilot-shell
← 全部服务器 ↗ GitHub
● 社区 maxritter ⚡ 即开即用

pilot-shell

作者 maxritter · maxritter/pilot-shell

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

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

▶ 观看演示 📦 安装 💡 使用场景

为什么要用

核心特性

实时演示

实际使用效果

就绪

安装

作者仓库 · Claude Skills 官方文档

使用场景

实战用法： pilot-shell

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

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

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

步骤
  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