# Workflow Skill

> Workflow Skill

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

---


# Workflow Skill

本 skill 的唯一设计来源是仓库根目录的 `WORKFLOW.md`。执行时必须优先遵守 `WORKFLOW.md`，并参考 `BUG_REP.md` 中记录的已知问题。不要把本文件理解成命令实现；它是 Claude/Codex 执行项目开发流程时的操作规约。

## 基本原则

- 全程使用用户使用的语言；用户使用中文时，全程中文。
- 任何 feature 都必须按阶段推进：研究 -> 确认 -> 规划 -> 标注 -> API 文档决策/审阅 -> 执行 -> 反馈。
- 未完成当前阶段的确认门禁前，不得提前进入下一阶段。
- 执行代码前必须已有被用户认可的 `plan.md`；如涉及 API 变动，还必须已有被用户认可的 `api.md`。
- 如果 `task/` 模板与 `WORKFLOW.md` 不一致，以 `WORKFLOW.md` 为准，在 feature 工作副本中补全缺失章节。
- 反馈要短。方向错误时，根据用户明确指示回滚并重写计划。

## 任务文件规则

新建任务时：

1. 在目标项目中创建 `feature/[YYYY]/`。
2. 从 skill 的 `task/` 目录复制 `research.md`、`plan.md`、`api.md` 到 `feature/[YYYY]/`。
3. 将文件重命名为能对应本次任务的名称。推荐格式：
   - `feature/[YYYY]/[YYYYMMDD]-[task-name]-research.md`
   - `feature/[YYYY]/[YYYYMMDD]-[task-name]-plan.md`
   - `feature/[YYYY]/[YYYYMMDD]-[task-name]-api.md`
4. 只允许先填写 research 文件。plan 和 api 文件可以先创建，但不得在研究确认前填写方案。

如果用户或项目已有命名规范，优先沿用已有规范，但必须保证三类文件可互相关联。

## 阶段 1: 研究

目标：填满 research 文件，验证 agent 是否真正理解代码库和需求。

必须完成：

- 阅读需求、相关代码、依赖关系、已有约束。
- 在 research 文件中记录：
  - 代码库深读范围：涉及模块/文件、依赖关系、已知约束。
  - 深度分析结果：核心流程、关键数据结构。
  - 风险点：潜在破坏点、兼容性问题。
  - 待确认问题：所有需要人工确认或进一步调研的假设。
  - 下一步：确认后才进入 plan 编写。
- 如果 `task/research.md` 缺失上述章节，在 feature 副本里按 `WORKFLOW.md` 补全。

研究完成后必须停下，使用 AskUserQuestion 或等价方式向用户确认待确认问题。确认完成前，不得生成或填写 plan。

## 阶段 2: 规划和标注

只有研究阶段被用户确认后，才能填写 plan 文件。

plan 文件必须包含：

- 方案概述：目标、候选方案、最终选择和理由。
- 实现细节：修改文件清单、关键逻辑片段或伪代码。
- 内联标注区：用于用户反复纠正假设、拒绝方案、添加约束。
- API 文档阶段决策：明确是否涉及 API 变动。
- Todo 清单：颗粒度极细，每项可在 5-15 分钟内完成。
- 执行指令：供执行阶段复制给执行 agent。
- 反馈记录和最终状态。

标注规则：

- 用户标注后，只更新 research/plan/api 文档，不执行代码。
- 可以循环 1-6 次或更多，直到用户明确认可。
- 批准前绝不执行。
- 如果 `task/plan.md` 缺失上述章节，在 feature 副本里按 `WORKFLOW.md` 补全。

## 阶段 3: API 文档决策和审阅

在 plan 标注结束后，判断是否涉及 API 变动。

- 不涉及 API 变动：在 plan 中明确记录“跳过 API 文档阶段”，然后进入执行审批。
- 涉及 API 变动：填写 api 文件，并进入 API 文档审阅。

API 文档必须至少包含：

- 功能概述。
- API 列表。
- 每个接口的路径、方法、功能描述。
- 请求参数、请求示例。
- 响应参数、响应示例。
- 错误码。

API 审阅规则：

- 用户未批准前，不得执行代码。
- API 设计变更可能影响 plan；如发生变更，必须同步更新 plan，并重新进入标注直到用户认可。

## 阶段 4: 执行

执行只能在以下条件全部满足后开始：

- research 已完成并被确认。
- plan 已完成标注并被批准。
- 如涉及 API，api 已完成审阅并被批准。

执行方式：

1. 将 plan 中的执行指令复制给 `plan-executor` subagent。
2. 要求执行 agent 完成全部 Todo，并在 plan 中标记完成状态。
3. 要求执行 agent 不做无关改动，不添加无必要注释。
4. 执行期间持续运行适合项目的检查，例如 typecheck、lint、test。
5. 如果当前平台没有 `plan-executor`，明确告知用户该限制；只有用户同意后，才由当前 agent 执行。

推荐执行指令：

```txt
implement it all.
mark completed in plan.
do not stop until all done.
no unnecessary comments.
continuously run typecheck...
```

## 阶段 5: 反馈

执行完成后：

- 用最短句子反馈完成情况。
- 在 plan 的反馈记录和最终状态中记录结果。
- 如用户指出方向错误，按用户明确指示执行 `git revert`，然后回到计划阶段重写方案。

## BUG_REP.md 使用

- 开始任务时读取 `BUG_REP.md`，确认是否有会影响本次流程的已知问题。
- 如果执行中发现 workflow 层面的 bug 或反复踩坑，记录到 `BUG_REP.md`，包含问题、触发条件、解决方案。
- 当前 `BUG_REP.md` 为空时，不要编造问题。

## 禁止事项

- 禁止跳过 research 直接写 plan。
- 禁止在待确认问题未确认前生成 plan。
- 禁止在 plan/api 未批准前实现代码。
- 禁止把 API 文档变更和 plan 脱节。
- 禁止用冗长反馈代替工作流文件记录。
- 禁止把本 skill 改写成虚构的 slash command 程序；实际执行应围绕文件、确认门禁和 subagent。