diff --git a/skills/plan/project-init/templates/CLAUDE-template.md b/skills/plan/project-init/templates/CLAUDE-template.md index 776a923..2f9b875 100644 --- a/skills/plan/project-init/templates/CLAUDE-template.md +++ b/skills/plan/project-init/templates/CLAUDE-template.md @@ -13,103 +13,17 @@ --- -## 🔄 B 阶段开发流程（后端模块循环 → 前端整体阶段） +## 🔄 B 阶段开发流程 -B 阶段整体是**一个静默 Workflow 脚本 `workflows/coding.mjs`**（由瘦入口 skill 启动）。入口：`/erp-workflow:coding-start`。子代理无法弹窗 → 缺值即写阻塞点并 halt（结构性静默）。 - -### 入口与路由（coding-start skill → coding.mjs Router） - -`/erp-workflow:coding-start` 是瘦入口：校验 Plan 终结闸（docs/08 § 一 全勾、git 在默认分支、工作树干净）后，调用 `Workflow({scriptPath:"…/workflows/coding.mjs", args:{projectRoot}})` 启动整个编码阶段。`coding.mjs` 的 **Router** stage 扫描 docs/08 § 二/§ 三 里程碑字段 + 本地 `git tag -l`，产出结构化模块清单（`{id, done, reqs[], feItems[]}`），过滤待跑模块；docs/08 字段与 git tag 不一致 → halt。 - -| `backend_done` | `frontend_done` | 行为 | -|---|---|---| -| `false` | 任意 | Router 列出待跑后端模块，进入后端模块循环 | -| `true` | `false` | 进入前端阶段（`feItems` 非空的模块） | -| `true` | `true` | "所有阶段已完成" | - -### 后端阶段（每模块一个里程碑 tag） - -- **模块循环（顶层 `for module`，fail-fast）**：`featureLoop(reqs,'backend')` → `testGate('backend')`（红色自动重试 1 次防 flaky，仍红 → HALT）→ 跨模块改动记录 → 模块报告 → milestone（本地 `git merge --no-ff` 进默认分支 + 打 `milestone/` tag + 回写 docs/08 § 二）→ 下一模块（无人工介入） -- **功能循环（内，每 REQ-XXX-NNN 一遍，同构 `featureLoop`）**：spec → plan → tdd → verify → review（`reviewWithFixLoop` 有界 5 轮：approve 即过；request-changes → fix → 重审；第 5 轮仍未过 → HALT） -- 后端阶段任务严格落在 `backend/` 路径下；docs/01 REQ 卡片的 UI 描述在此阶段忽略，UI 推迟到前端阶段。 - -### 前端阶段（整体一个里程碑 tag，所有后端模块打里程碑后启动） - -- **FE 清单（AI 自主推导，无审阅断点）**：FE 业务功能清单在 Plan 阶段 A6 + Router 阶段确定并写入 `docs/08 § 三`。**FE 是业务功能粒度，与 prototype HTML 文件数无关**——一个 HTML 可拆多个 FE，多个 HTML 也可合成一个 FE。 -- **FE 循环（外）**：`featureLoop(feItems,'frontend')` → `testGate('frontend')` → milestone（分支 `frontend-phase`，docs/08 § 三 整体里程碑）。 -- **FE 功能循环（内，每个 FE-NN 一遍，同构 `featureLoop`）**：spec → plan → tdd → verify → review（统一 `code-reviewer` agent，`phase=frontend` 附加 7 维 checklist） -- 前端阶段任务严格落在 `frontend/` 路径下；布局以 `prototype/` 为权威。 - -### 里程碑前测试闸门 - -- `coding.mjs` 的 **testGate** stage：后端阶段子代理跑 `scripts/test.mjs`（含本模块新增 + 已合并模块回归）；前端阶段跑 vitest + playwright（命令取自 docs/04 § 零）。 -- testGate 是打里程碑 tag 前唯一的硬测试门；红色重试 1 次仍红 → HALT，不得跳过进入 report / milestone stage。 - ---- - -## ✅ 阶段完成判定规则 - -`docs/08-模块任务管理.md` 分两段： -- `§ 二`：后端模块元数据表（每个模块一行 bullet，记录依赖 / 路径 / 里程碑 tag / 功能子项） -- `§ 三`：前端阶段元数据（整体里程碑 + FE 子项清单，由 Plan 阶段 A6 + `coding.mjs` 在所有后端模块打里程碑后填入） - -**阶段完成判定**统一以 `里程碑:` 字段（§ 二 各模块） / `整体里程碑:` 字段（§ 三）+ 本地 `git tag -l 'milestone/'` 判定；子项勾选只作可视化进度，不参与完成判定。 - -### 后端模块格式 - -每个后端模块在 docs/08 § 二 中长这样： - -```markdown -- module_sys 系统管理 - - 依赖: — - - 路径: backend/module/sys/ - - 里程碑: — - - 功能: - - [ ] REQ-SYS-001 用户登录 - - [ ] REQ-SYS-002 用户注册 -``` - -- `里程碑:` 字段由 `coding.mjs` 的 milestone stage 在打里程碑 tag 时从 `—` 改为 `milestone/`。 -- 每个 `REQ-*` 子项由 `coding.mjs` 的 review stage 在 `verdict=approve` 时自动勾选为 `[x]`。 -- 路径限定为后端目录（如 `backend/module/sys/`）；前端代码不在此阶段产生。 - -### 前端阶段格式（§ 三） - -```markdown -- 整体里程碑: — -- 功能: - - [ ] FE-01 用户登录与注册 ｜ 关联 REQ：REQ-SYS-001, REQ-SYS-002 ｜ 关联原型：prototype/auth.html - - [ ] FE-02 仪表盘总览 ｜ 关联 REQ：REQ-DASH-001 ｜ 关联原型：prototype/dashboard.html -``` - -- `整体里程碑:` 字段由 `coding.mjs` 的 milestone stage 在打前端里程碑 tag 时从 `—` 改为 `milestone/frontend-phase`。 -- "功能:" 列表由 Plan 阶段 A6（`frontend-scope-lock`）+ `coding.mjs` 推导写入（无人工审阅断点）。FE 是业务功能粒度，与 prototype HTML 文件数无关。 -- 每个 `FE-NN` 子项由 `coding.mjs` 的 review stage 在 `verdict=approve` 时自动勾选为 `[x]`。 -- prototype/ 门禁在 Plan 阶段 A6 `frontend-scope-lock` 强制检查项目根 `prototype/` 至少含 1 个 `*.html` mockup。 - -### 状态语义（后端模块 + 前端阶段共用） - -| `里程碑:` 字段 | `git tag -l` | 含义 | 你（Claude Code）的行为 | -|---|---|---|---| -| `—` | tag 不存在 | 该阶段未开始 / 进行中（未打里程碑） | ✅ 开始 / 继续该阶段开发 | -| `milestone/` | tag 存在 | 阶段**已完成** | 🟢 后端：进入下一未完成模块；后端全完 → 前端阶段；前端已打里程碑 → 全部完成 | - -### 模块完成报告 - -由 `coding.mjs` 的 report stage 产出（12 节标准化，含跨模块改动等 CLAUDE.md 软规则映射节）。CC 不手写模块报告。 +B 阶段由 `/erp-workflow:coding-start` 启动 `workflows/coding.mjs`：按模块循环跑 spec → plan → tdd → verify → review（同构 `featureLoop`），后端每模块一个里程碑 tag，前端整体一个里程碑 tag。里程碑字段与子项清单记录在 `docs/08 § 二`（后端）/ `§ 三`（前端）；阶段完成判定以 `里程碑:` / `整体里程碑:` 字段 + 本地 `git tag -l 'milestone/'` 为准，子项勾选只作可视化进度。详细路由 / testGate / 中断行为见 `README.md` 与 `workflows/coding.mjs`。 --- ## 🏷️ 占位符统一约定 -项目文档里有 **2 种填写占位** + **1 种提示占位**： - -| 格式 | 谁填 | 使用阶段 | 说明 | -|------|-----|---------|------| -| `【人工填写：<简短说明>】` | 人 | 仅 A 阶段文档 | 密钥 / 账密 / 包名 / 命名约定 / 小版本号等人工才能决定的值；B 阶段 plan/spec 禁止出现，查不到真值时用 `AskUserQuestion` 问用户 | -| `TBD(<责任人>)` | CC 自动 | A 或 B | 后缀附带责任方（如 `TBD(A3 自动补)` / `TBD(A5 自动补)`）；由对应 skill / `coding.mjs` stage 就地补填，模块完成报告 § ⑦ 检查 `TBD(CC 补)` 残留 | - -**HTML 注释 ``**：提示占位，是**插件内部大纲模板**里给 LLM 的**填空提示 / 章节引导**，指引 LLM 按结构填实际内容。skill 生成时会**剥除**这些注释，最终产物里注释不会保留。 +项目文档里两种人工填写占位： +- `【人工填写：<简短说明>】` — 仅 A 阶段文档；B 阶段 plan/spec 禁止出现，查不到真值时用 `AskUserQuestion` 问用户。 +- `TBD(<责任人>)` — 由对应 skill / `coding.mjs` stage 自动就地补填（如 `TBD(A3 自动补)`）；模块完成报告 § ⑦ 检查 `TBD(CC 补)` 残留。 --- @@ -194,62 +108,3 @@ B 阶段整体是**一个静默 Workflow 脚本 `workflows/coding.mjs`**（由 | S1 | **技术栈外组件引入** | 用 `AskUserQuestion` 给用户三选一：接受引入 / 换方案 / 拒绝 | ① **接受** → 同会话直接在 `docs/04 § 零` 追加一行 → 继续流程 ② **换方案 / 拒绝** → 视为常规歧义澄清，继续 Q&A 收敛 ③ 不写 Blocker、不中断流程 | | S2 | **跨模块改动** | **默认不改**，仅为当前模块实现所必需时允许修改 | `coding.mjs` 的 cross-module stage 在模块循环内记录改动并补「原因 / 影响评估」，「跨模块改动」节完整贴入《模块完成报告》 | ---- - -## 🧭 通用工作准则（General Principles） - -### 1. Think Before Coding - -**Don't assume. Don't hide confusion. Surface tradeoffs.** - -Before implementing: -- State your assumptions explicitly. If uncertain, ask. -- If multiple interpretations exist, present them - don't pick silently. -- If a simpler approach exists, say so. Push back when warranted. -- If something is unclear, stop. Name what's confusing. Ask. - -### 2. Simplicity First - -**Minimum code that solves the problem. Nothing speculative.** - -- No features beyond what was asked. -- No abstractions for single-use code. -- No "flexibility" or "configurability" that wasn't requested. -- No error handling for impossible scenarios. -- If you write 200 lines and it could be 50, rewrite it. - -Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. - -### 3. Surgical Changes - -**Touch only what you must. Clean up only your own mess.** - -When editing existing code: -- Don't "improve" adjacent code, comments, or formatting. -- Don't refactor things that aren't broken. -- Match existing style, even if you'd do it differently. -- If you notice unrelated dead code, mention it - don't delete it. - -When your changes create orphans: -- Remove imports/variables/functions that YOUR changes made unused. -- Don't remove pre-existing dead code unless asked. - -The test: Every changed line should trace directly to the user's request. - -### 4. Goal-Driven Execution - -**Define success criteria. Loop until verified.** - -Transform tasks into verifiable goals: -- "Add validation" → "Write tests for invalid inputs, then make them pass" -- "Fix the bug" → "Write a test that reproduces it, then make it pass" -- "Refactor X" → "Ensure tests pass before and after" - -For multi-step tasks, state a brief plan: -``` -1. [Step] → verify: [check] -2. [Step] → verify: [check] -3. [Step] → verify: [check] -``` - -Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.