diff --git a/.claude/skills/openspec-superpowers-bridge/SKILL.md b/.claude/skills/openspec-superpowers-bridge/SKILL.md index 59e430c..c36f5e8 100644 --- a/.claude/skills/openspec-superpowers-bridge/SKILL.md +++ b/.claude/skills/openspec-superpowers-bridge/SKILL.md @@ -10,6 +10,18 @@ description: Use when starting feature or change work to route the request throu `.claude/skills/openspec-*`(propose/apply-change/archive-change/…)与 `/opsx:*` 命令 负责;本技能只负责过程编排。 +## 工作流五步(唯一权威) + +任何功能/变更请求,按以下流程推进: + +1. **brainstorming 分类**:用 `superpowers:brainstorming` 将请求分为 spike / bounded / architectural。 +2. **architectural → 开 change**:走 `/opsx:propose`(proposal → specs → design → tasks), + 配合 `.claude/skills/openspec-*` 技能。 +3. **写计划**:用 `superpowers:writing-plans` 生成实施计划(存 `docs/superpowers/plans/`)。 +4. **应用**:按 `/opsx:apply` 落地任务,执行期遵循 TDD、systematic-debugging、 + requesting-code-review、verification-before-completion。 +5. **归档**:`/opsx:archive` 把增量 spec 合并回主 spec。 + ## 何时开 change(而非直接写) 1. 任何功能/变更请求,先用 `superpowers:brainstorming` 分类为 spike / bounded / architectural。 diff --git a/CLAUDE.md b/CLAUDE.md index 4a69092..4a3c798 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,53 +6,37 @@ 待定(占位,后续在 PRD 中明确) -## 开发工作流(三支柱编排) +## 铁律(必须遵守,违反即返工) -本项目用三件工具协作,请按此顺序理解其分工: +1. **需求文档(PRD)是约束/规范的唯一权威,原型仅作视觉参考**;PRD 内部冲突以全局规范为准。 +2. **数据库 schema 是字段一致性的唯一锚点**:`data-model` spec(字段字典)先行,前后端引用同一字段名,禁止各自命名。 +3. **前端先行 + Mock**:前端对 Mock 验收,后端对 `api-contract` 契约实现。 +4. **字段/接口变更先改 `shared/`,再改对应 spec**。 -| 支柱 | 定位 | 载体 | -|---|---|---| -| harness (Claude Code) | 执行环境:规范、权限 | 本文件、`.claude/settings.json` | -| openspec | 需求与变更单一事实源 | `openspec/`(spec-driven schema) | -| superpowers | 过程方法论驱动 | 全局插件 + `.claude/skills/` | +## 开发工作流 -**任何功能/变更请求,按以下流程推进:** +本项目用三支柱协作:**openspec** 管「要做什么」、**superpowers** 管「怎么一步步做对」、 +**harness** 管「环境怎么配合」。任何功能/变更请求都按此推进。 -1. 用 `superpowers:brainstorming` 将请求分类为 spike / bounded / architectural。 -2. architectural 工作 → 走 `/opsx:propose`(proposal → specs → design → tasks), - 配合 `.claude/skills/openspec-*` 技能;入口由 - `.claude/skills/openspec-superpowers-bridge/` 将 openspec 各阶段映射到 - superpowers 过程技能。 -3. 用 `superpowers:writing-plans` 生成实施计划(存 `docs/superpowers/plans/`)。 -4. 执行期遵循 superpowers 过程技能:TDD、systematic-debugging、 - requesting-code-review、verification-before-completion,并按 `/opsx:apply` 落地任务。 -5. 完成并归档:`/opsx:archive` 更新主 spec。 - -**分工口诀**:openspec 管「要做什么」,superpowers 管「怎么一步步做对」, -harness 管「环境怎么配合」。 - -## Spec 约定(新会话必须遵守) - -规范详情见 `docs/spec-conventions.md`,此处为必守要点。 - -### 三层结构(前后端分离,独立验收) -- `specs/shared/`:跨前后端公共契约——`platform`(全局规范) / `data-model`(数据模型) / `api-contract`(API 契约) -- `specs/frontend/`:前端 spec,按「页面 → 功能块」拆分,用 Mock 独立验收 -- `specs/backend/`:后端 spec,按「实体/域」拆分,用 API 测试独立验收 - -### 编号 -格式 `<层>-<端/域>-<页面/实体>[.<功能块>]`,顺序即构建顺序(SH→FE→BE);详见 `docs/spec-conventions.md`。 - -### 铁律 -- **需求文档(PRD)是约束/规范的唯一权威,原型仅作视觉参考** -- **数据库 schema 是字段一致性的唯一锚点**:`data-model` spec(字段字典)先行,前后端引用同一字段名,禁止各自命名 -- **前端先行 + Mock**:前端对 Mock 验收,后端对 api-contract 实现 -- **字段/接口变更先改 `shared/`,再改对应 spec** +- **怎么走流程**(分类 → 开 change → 计划 → 应用 → 归档,含 openspec↔superpowers 映射):权威见 + `.claude/skills/openspec-superpowers-bridge/SKILL.md`。 +- **三支柱架构与分工**:见 `docs/architecture.md`。 +- **spec 组织/粒度/编号/四段式结构**:见 `docs/spec-conventions.md`。 ## 约定 - 提交信息遵循 Conventional Commits(feat/fix/chore/docs/refactor)。 -- 不直接手改 `openspec/` 下手动生成的文件,优先用 `openspec` CLI。 +- 不直接手改 `openspec/` 下由 CLI 生成的文件,优先用 `openspec` CLI。 + +## 文档地图 + +| 文档 | 内容 | +|---|---| +| `docs/spec-conventions.md` | spec 组织/粒度/编号/四段式结构(唯一权威) | +| `docs/architecture.md` | 三支柱架构图(职责/协作/技术分层/变更生命周期) | +| `.claude/skills/openspec-superpowers-bridge/SKILL.md` | 工作流五步 + openspec↔superpowers 映射(唯一权威) | +| `docs/requirements/` | 产品方案 + PRD + 原型 | +| `docs/superpowers/plans/` / `specs/` | 实施计划 / 设计文档 | ## 当前进度 diff --git a/docs/architecture.md b/docs/architecture.md index 2d8709e..68c115d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -113,11 +113,6 @@ flowchart TB ## openspec 阶段 → superpowers 技能(桥接映射) -| openspec 阶段 | superpowers 技能 | -|---|---| -| proposal / specs / design | brainstorming → writing-plans | -| tasks 编排与执行 | writing-plans 产物 → executing-plans / subagent-driven-development | -| 实现 | test-driven-development · systematic-debugging | -| 收尾 | requesting-code-review · verification-before-completion · finishing-a-development-branch | - -> 桥接由 `.claude/skills/openspec-superpowers-bridge` 负责:把 openspec 各阶段映射到对应 superpowers 过程技能。 +openspec 各阶段到 superpowers 过程技能的完整映射,以及工作流五步 +(brainstorming → propose → plan → apply → archive)的唯一权威,见 +`.claude/skills/openspec-superpowers-bridge/SKILL.md`。此图(图 3)仅示意生命周期主线。