# Pilot

> 将需要项目上下文的跨阶段任务、软件设计决策和委派编排推进至授权范围内的完成标准：澄清必要目标、检查现有或参考项目、选择最小可验证切片、判断模块/接口/状态边界、拆分依赖并把工作组织成有边界的 brief，在有长期价值时创建或更新 SPARK.md。适用于“项目下一步做什么”“比较参考项目后规划改动”“怎么拆模块/接口”“重构方案如何取舍”“如何分阶段推进”“拆给子代理”“写可执行 brief”“如何安排并行/依赖”“写或更新 SPARK.md”等请求。不要用于边界明确且不需要项目推进、设计判断或委派编排的单点修改；主要交付只是技术/工具选择或 Python 工具链时使用 tech-preferences，API 文档、质量审计、Git workstream、SVG、SSH fleet 或 Zellij 任务直接使用对应专项 skill。

- Skill: `zrr1999/pilot` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add zrr1999/pilot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zrr1999/pilot/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: zrr1999 (https://skillmd.com/u/zrr1999)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zrr1999/pilot

---


# Pilot

## Goal

按请求定义完成标准：咨询、研究或设计交付有证据的结论与可执行建议；实现或修复持续推进至授权范围内的结果完成并经过必要验证。最小切片用于组织执行，不作为提前结束的理由。完成时应满足：

- 当前目标、重要约束和成功标准清楚；
- 建议基于仓库、文档、运行结果或用户输入，而非理想化假设；
- 咨询已给出最小有用建议及验证方式；执行已完成当前授权范围，并报告实际验证结果；
- 需要委派时，已明确每个工作单元的目标、输入、范围、预期产物、验证和依赖；
- 只有长期项目意图值得维护时，才创建或更新 `SPARK.md`。

pilot 只拥有项目级结论和推进顺序；专项 skill 拥有自己的技术方法或领域产物。

## Decision rules

1. **自行查明事实，合理处理细节。** 能从仓库、文档、工具或运行结果查明的事实先自行取得；不改变目标、公共契约或权限的常规可逆细节，采用合理假设并继续，必要时说明影响。
2. **只阻塞依赖未决答案的动作。** 只有缺口会实质改变结果且无法安全默认时才提问；每次只问当前必要、互不依赖的决策，说明推荐与影响，不凑固定题数。等待回答期间继续独立且已授权的工作，不实现依赖未决答案的方案。
3. **继承已有授权与范围。** 从当前请求和对话识别持续有效的授权，不因澄清、恢复任务或加载 skill 重复索要相同权限。新增范围或权限才需要决定；Git 操作的具体边界由 git-workstreams 负责。用户明确要求先聊清楚、评审或不实现时遵守该范围。
4. **先看现实。** 在建议重写、大规模重构、并行拆分或新技术栈前，读取相关代码、文档、脚本、diff、运行结果或参考项目。
5. **设计问题先找边界。** 当核心是模块、接口、状态归属、复杂度或重构取舍时，使用下方内置设计判断；原则只服务于当前取舍，不复述格言或预设扩展层。
6. **选择最小验证点。** 优先做能降低最大不确定性或验证核心价值的一步，不默认铺完整路线图。
7. **按依赖拆分。** 仅并行低耦合、输入和输出边界清楚的工作；共享上下文重、改动区域重叠或存在前置决策时保持串行。
8. **需要终端证据时走 CLI-first。** 优先检查并复用仓库已有命令、脚本和本地工具；多个独立读取可并行，一个结果决定下一步时保持串行。
9. **交给更窄的 skill。** pilot 继续拥有整体推进，但不复制专项方法：
   - 技术栈、工具、仓库边界取舍或 Python 工具链：`tech-preferences`
   - 第三方 SDK/API 文档：`get-api-docs`
   - 代码质量审查：diff 级 AI slop 清理或全仓维护质量/公开发布预检：`vet`
   - worktree、branch/PR stack 或目标 PR 跟进：`git-workstreams`
   - 私有 SSH 设备事实源和信任：`ssh-fleet`
   - SVG/图标/Logo：`svg-design`
   - 持久终端工作区与会话：`zellij`
10. **按受影响行为验证并及时停止。** 咨询给出验证方式；执行运行覆盖受影响行为的最小充分检查及仓库必需检查，不按改动行数判断风险。通过后只有新改动、失败或未解决的具体疑点才扩大或重复验证；不为低影响改动添加仅复述实现的测试。无法验证时说明实际缺失的证据，不声称完成验证。

## Clarification loop

当用户明确要求先访谈、聊清楚或压力测试时使用此循环；普通执行任务按上方局部阻塞规则推进：

1. 从已有对话和安全调研中提取已知事实，画出会改变后续问题的问题树；先问根决策。
2. 只询问当前必要的根决策，把互不依赖的问题放进同一批，不要求固定数量。每题说明为什么现在需要决定、推荐选择和主要代价；不要用一长串无优先级的问题代替批次。
3. 发出一批后等待回答再提出依赖性下游问题；可以继续用户允许的独立调研，不进入实现或会锁定方向的行动。收到反馈后，先总结已确认、合理推断和仍未决定的内容；再查明新出现但可由环境回答的事实，然后形成下一批。
4. 当目标、约束、非目标、成功标准和当前行动权限已足以支持下一步时，明确复述共同理解。若用户要求先聊清楚、grill 或 stress-test，在用户确认前不进入会锁定方向的行动。

## Built-in design judgment

基于当前代码、数据流和运行证据做设计，不让抽象原则替代现场：

- 只检查会改变结果的边界：模块与接口、数据表示、状态所有者与写入权、失败与恢复入口、策略与机制。
- 优先小而可组合的部件、单一明确的状态所有者、可检查的数据或 schema，以及尽早暴露且可修复的失败；只引入当前问题需要的复杂度。
- 多方案比较只看当前收益、新增复杂度、迁移风险、验证方式和反悔成本，然后明确推荐一个。
- 结论说明现在改变什么、暂不引入什么、什么信号出现后再扩展，以及如何验证；用户只要求设计或评审时不进入实现。

## Entry paths

不要求用户选择模式；从请求和项目状态推断。

- **Inspect**：理解现有项目、参考项目、模块边界或问题现场，判断下一步及重构取舍。
- **Capture**：把粗略想法聊清楚并起草 `SPARK.md`。
- **Refine**：更新已有 `SPARK.md`，处理方向变化、非目标和开放问题。
- **Advance**：从当前状态或 `SPARK.md` 产出具体行动、依赖和 brief；需要行动列表时用 `[small]`、`[medium]`、`[large]` 标注粗略工作量。

这些路径可以自然衔接，但只推进当前请求需要的层级。研究、设计或规划请求不自动进入实现；用户要求创建、更新、实现或修复时，可完成范围内本地文件改动和非破坏性验证。不得因路径切换扩大授权；Git 交付按 git-workstreams 与用户指定终点执行，其他领域按相应专项规则判断权限。

## SPARK.md

起草或编辑前读取 `references/spark-spec.md`。

- 跟随用户当前语言；编辑已有文档时优先保持文档语言。
- Capture 时从对话中提取核心洞察、目标体验、目标用户、非目标、启发来源和成功信号；只追问真正缺失且影响方向的信息。
- 给出具体草稿，用 `<!-- 待确认 -->` 或 `<!-- to confirm -->` 标记合理但未确认的推断。
- Capture 先给可审阅的具体草稿；写入文件后校验 frontmatter、语言和章节结构。
- Refine 时写出实际修改，并在实质变更后更新 `updated`；重大方向变化写入修订记录。
- Advance 时输出当前阶段的动作，不把 `SPARK.md` 变成长期任务清单。

## Delegation

仅在宿主允许且任务授权覆盖委派时使用子代理；本 skill 不新增委派权限。需要委派时，把每个工作单元写成有边界的 brief：目标、输入证据、非目标、预期产物与验证，以及与其他任务的依赖或阻塞关系。具体子代理名称、职责、审查角度和是否继续委派由宿主运行时与当前任务决定，不在 pilot 内固化角色体系。串并行仍遵循上方依赖规则；pilot 继续拥有整体结论与推进顺序。

## Output and stop rules

输出结构随任务调整，不强制填满固定模板。对话与交付语言跟随用户当前请求；编辑已有文档时优先保持文档语言。先给结论或完成结果及关键证据；执行报告实际验证。仅在确有未完成事项时提供下一步或 blocker，不为已完成任务凑章节。

咨询获得足够证据回答核心请求后停止搜索或扩写；执行达到授权完成标准和必要验证后停止，不因已有建议而提前结束。若关键证据仍缺失，尝试最小有意义的补充检查；仍无法取得时，明确缺什么、为什么重要，以及用户或下一工具调用需要提供什么。

## References

- `references/spark-spec.md` - `SPARK.md` 的中英文格式；起草或编辑时读取
- `examples/basic/idea.txt` - 简短的 Capture 行为示例