# Project Refine

> Use when a project idea, feature request, product direction, or problem statement is too vague to plan or implement safely, and the next step should be a verifiable specification rather than code or an implementation plan.

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

---


# Project Refine

## 概述

本技能用于把模糊想法收敛成可验证规格。它的目标不是继续闲聊需求，而是在进入 `project-planning` 前确认目标是否足够清楚。

## 何时使用

- 用户只有方向、愿望、痛点或一句话想法，还不能安全规划开发。
- 需求里缺少用户、问题、成功标准、约束、外部事实或最终产物类型。
- 用户要求“帮我想清楚”“收敛一下”“先整理规格”“不要急着实现”。
- 进入 `project-planning` 前，需要先确认规格是否可验证。

不适用：
- 已有清晰需求、验收标准和技术边界时，直接使用 `project-planning`。
- 已有批准计划并要求执行时，使用 `project-workflow`。
- 用户只想自由发散点子且暂时不需要规格时，使用 `brainstorming`。

## 核心原则

- 收敛优先：每轮推进一个关键缺口，避免无边界访谈。
- 事实分层：区分已确认事实、合理假设、待补外部事实。
- 可验证优先：所有成功标准都应能被测试、观察或人工验收。
- 不越阶段：本阶段不产出任务级实施计划，不进入编码。
- 最小充分：只补齐进入下一阶段所需的信息，不扩展未来功能。
- 图谱不前置：本阶段不注册、更新或查询 Code Review Graph；只识别后续 planning 是否必须进行代码影响分析。

## 工作流程

1. 复述当前想法，用一句话标出“看起来要解决的问题”。
2. 检查六个必填字段：
   - 问题是什么
   - 用户是谁
   - 成功标准是什么
   - 约束有哪些
   - 当前缺哪些外部事实
   - 最终产物类型是什么
3. 若字段缺失，一次只问一个最关键问题；优先给 2-3 个选项和推荐。
4. 若方向空间太大，可结合 `brainstorming` 发散候选方向。
5. 发散后必须回到收敛，输出可验证规格。
6. 如果规格涉及现有公共契约、跨模块流程、数据模型或重要界面流程，在产出中标记：`project-planning` 必须执行 `code-review-graph` 影响分析。
7. 明确下一步：进入 `project-planning`、继续补外部事实，或停止。

## 与 Brainstorming 的关系

`brainstorming` 是可选辅助，不是必经步骤。

使用条件：
- 用户还没有明确目标用户或问题边界。
- 存在多个合理方向，需要先比较。
- 当前想法过窄，可能遗漏更好的问题定义。

使用后必须收敛：
- 选择一个方向，或明确保留哪些候选。
- 标注被放弃的方向和原因。
- 回到 refine 输出模板，不停留在想法列表。

## 输出契约

默认以内联 Markdown 输出规格；只有用户明确要求沉淀文档时，才写入 `docs/specs/*.md`。

```markdown
# [项目/功能名] 可验证规格

## 1. 问题定义

- 当前要解决的问题：
- 为什么现在要解决：
- 非目标：

## 2. 目标用户

- 主要用户：
- 使用场景：
- 当前替代方案：

## 3. 成功标准

| AC-ID | 可验证标准 | 验证方式 | 通过条件 |
|---|---|---|---|
| AC-01 | [标准] | 自动/手动/观察 | [通过条件] |

## 4. 约束

- 技术约束：
- 业务约束：
- 时间/资源约束：
- 合规/安全约束：

## 5. 外部事实缺口

| 缺口ID | 待确认事实 | 为什么重要 | 建议获取方式 | 阻塞级别 |
|---|---|---|---|---|
| F-01 | [事实] | [影响] | [调研/用户确认/数据验证] | 高/中/低 |

## 6. 最终产物类型

- 产物类型：代码功能 / 文档 / 原型 / 调研结论 / 设计方案 / 其他
- 推荐下一步：project-planning / 继续 refine / 先补外部事实 / 暂停

## 7. 已确认事实与假设

- 已确认：
- 假设：
- 需要用户确认：

## 8. 下游代码影响分析要求

- 是否需要 `code-review-graph`：是 / 否
- 触发原因：公共契约 / 跨模块流程 / 数据模型 / 重要界面流程 / 不适用
- 交给 `project-planning` 的候选模块或契约：
```

## 退出条件

只有满足以下条件，才能建议进入 `project-planning`：

- 问题、用户、成功标准、约束和产物类型已明确。
- 高阻塞外部事实已确认，或已明确标注为 planning 前置任务。
- 成功标准至少有一条可验证 AC。
- 非目标已写清，避免后续范围漂移。

如果不满足，输出“当前不能进入 planning”的原因和最小补齐问题。

## 常见错误

- 把 refine 写成实施计划：应停止在规格层，不拆开发任务。
- 把 brainstorming 当作结果：发散后必须做选择或标注缺口。
- 假装外部事实已知：未知事实必须进入缺口表。
- 成功标准不可验证：把“体验更好”改写为可观察条件。
- 问题和方案混在一起：先定义问题，再允许讨论方案。