朱子纯 / erp-workflow-plugin

Commit c43e7989d8459c6449893105037ffb242c33c26f

Authored by zichun
1 parent b7e4fa58

docs(CLAUDE-template): drop generic principles section and orchestrator re-documentation

Inline Side-by-side
Showing 1 changed file with 5 additions and 150 deletions
skills/plan/project-init/templates/CLAUDE-template.md
  View file @c43e798
... ... @@ -13,103 +13,17 @@
13 13  
14 14 ---
15 15  
16   -## 🔄 B 阶段开å‘æµç¨‹ï¼ˆåŽç«¯æ¨¡å—循环 → å‰ç«¯æ•´ä½“阶段）
  16 +## 🔄 B 阶段开å‘æµç¨‹
17 17  
18   -B 阶段整体是**一个é™é»˜ Workflow 脚本 `workflows/coding.mjs`**ï¼ˆç”±ç˜¦å…¥å£ skill å¯åŠ¨ï¼‰ã€‚å…¥å£ï¼š`/erp-workflow:coding-start`。å­ä»£ç†æ— æ³•å¼¹çª— → 缺值å³å†™é˜»å¡žç‚¹å¹¶ halt（结构性é™é»˜ï¼‰ã€‚
19   -
20   -### å…¥å£ä¸Žè·¯ç”±ï¼ˆcoding-start skill → coding.mjs Router）
21   -
22   -`/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。
23   -
24   -| `backend_done` | `frontend_done` | 行为 |
25   -|---|---|---|
26   -| `false` | ä»»æ„ | Router 列出待跑åŽç«¯æ¨¡å—，进入åŽç«¯æ¨¡å—循环 |
27   -| `true` | `false` | 进入å‰ç«¯é˜¶æ®µï¼ˆ`feItems` éžç©ºçš„模å—） |
28   -| `true` | `true` | "所有阶段已完æˆ" |
29   -
30   -### åŽç«¯é˜¶æ®µï¼ˆæ¯æ¨¡å—一个里程碑 tag）
31   -
32   -- **模å—循环（顶层 `for module`，fail-fast）**：`featureLoop(reqs,'backend')` → `testGate('backend')`（红色自动é‡è¯• 1 次防 flaky，ä»çº¢ → HALT）→ 跨模å—改动记录 → 模å—报告 → milestone（本地 `git merge --no-ff` 进默认分支 + 打 `milestone/<id>` tag + 回写 docs/08 § 二）→ 下一模å—（无人工介入）
33   -- **åŠŸèƒ½å¾ªçŽ¯ï¼ˆå†…ï¼Œæ¯ REQ-XXX-NNN 一é，åŒæž„ `featureLoop`）**：spec → plan → tdd → verify → review（`reviewWithFixLoop` 有界 5 轮：approve å³è¿‡ï¼›request-changes → fix → é‡å®¡ï¼›ç¬¬ 5 è½®ä»æœªè¿‡ → HALT）
34   -- åŽç«¯é˜¶æ®µä»»åŠ¡ä¸¥æ ¼è½åœ¨ `backend/` 路径下；docs/01 REQ å¡ç‰‡çš„ UI æ述在此阶段忽略，UI 推迟到å‰ç«¯é˜¶æ®µã€‚
35   -
36   -### å‰ç«¯é˜¶æ®µï¼ˆæ•´ä½“一个里程碑 tag，所有åŽç«¯æ¨¡å—打里程碑åŽå¯åŠ¨ï¼‰
37   -
38   -- **FE 清å•ï¼ˆAI 自主推导，无审阅断点）**：FE 业务功能清å•åœ¨ Plan 阶段 A6 + Router 阶段确定并写入 `docs/08 § 三`。**FE 是业务功能粒度，与 prototype HTML 文件数无关**——一个 HTML å¯æ‹†å¤šä¸ª FE，多个 HTML 也å¯åˆæˆä¸€ä¸ª FE。
39   -- **FE 循环（外）**：`featureLoop(feItems,'frontend')` → `testGate('frontend')` → milestone（分支 `frontend-phase`，docs/08 § 三 整体里程碑）。
40   -- **FE 功能循环（内，æ¯ä¸ª FE-NN 一é，åŒæž„ `featureLoop`）**：spec → plan → tdd → verify → review（统一 `code-reviewer` agent，`phase=frontend` 附加 7 ç»´ checklist）
41   -- å‰ç«¯é˜¶æ®µä»»åŠ¡ä¸¥æ ¼è½åœ¨ `frontend/` 路径下；布局以 `prototype/` 为æƒå¨ã€‚
42   -
43   -### 里程碑å‰æµ‹è¯•é—¸é—¨
44   -
45   -- `coding.mjs` çš„ **testGate** stage：åŽç«¯é˜¶æ®µå­ä»£ç†è·‘ `scripts/test.mjs`（å«æœ¬æ¨¡å—新增 + å·²åˆå¹¶æ¨¡å—回归）；å‰ç«¯é˜¶æ®µè·‘ vitest + playwright（命令å–自 docs/04 § 零）。
46   -- testGate 是打里程碑 tag å‰å”¯ä¸€çš„硬测试门；红色é‡è¯• 1 次ä»çº¢ → HALT，ä¸å¾—跳过进入 report / milestone stage。
47   -
48   ----
49   -
50   -## ✅ 阶段完æˆåˆ¤å®šè§„则
51   -
52   -`docs/08-模å—任务管ç†.md` 分两段：
53   -- `§ 二`：åŽç«¯æ¨¡å—元数æ®è¡¨ï¼ˆæ¯ä¸ªæ¨¡å—一行 bullet，记录ä¾èµ– / 路径 / 里程碑 tag / 功能å­é¡¹ï¼‰
54   -- `§ 三`：å‰ç«¯é˜¶æ®µå…ƒæ•°æ®ï¼ˆæ•´ä½“里程碑 + FE å­é¡¹æ¸…å•ï¼Œç”± Plan 阶段 A6 + `coding.mjs` 在所有åŽç«¯æ¨¡å—打里程碑åŽå¡«å…¥ï¼‰
55   -
56   -**阶段完æˆåˆ¤å®š**统一以 `里程碑:` 字段（§ 二 å„模å—） / `整体里程碑:` 字段（§ 三）+ 本地 `git tag -l 'milestone/<id>'` 判定；å­é¡¹å‹¾é€‰åªä½œå¯è§†åŒ–进度，ä¸å‚与完æˆåˆ¤å®šã€‚
57   -
58   -### åŽç«¯æ¨¡å—æ ¼å¼
59   -
60   -æ¯ä¸ªåŽç«¯æ¨¡å—在 docs/08 § 二 中长这样：
61   -
62   -```markdown
63   -- module_sys 系统管ç†
64   - - ä¾èµ–: —
65   - - 路径: backend/module/sys/
66   - - 里程碑: —
67   - - 功能:
68   - - [ ] REQ-SYS-001 用户登录
69   - - [ ] REQ-SYS-002 用户注册
70   -```
71   -
72   -- `里程碑:` 字段由 `coding.mjs` çš„ milestone stage 在打里程碑 tag 时从 `—` 改为 `milestone/<module_id>`。
73   -- æ¯ä¸ª `REQ-*` å­é¡¹ç”± `coding.mjs` çš„ review stage 在 `verdict=approve` 时自动勾选为 `[x]`。
74   -- 路径é™å®šä¸ºåŽç«¯ç›®å½•ï¼ˆå¦‚ `backend/module/sys/`）；å‰ç«¯ä»£ç ä¸åœ¨æ­¤é˜¶æ®µäº§ç”Ÿã€‚
75   -
76   -### å‰ç«¯é˜¶æ®µæ ¼å¼ï¼ˆÂ§ 三）
77   -
78   -```markdown
79   -- 整体里程碑: —
80   -- 功能:
81   - - [ ] FE-01 用户登录与注册 ｜ å…³è” REQ：REQ-SYS-001, REQ-SYS-002 ｜ å…³è”原型：prototype/auth.html
82   - - [ ] FE-02 仪表盘总览 ｜ å…³è” REQ：REQ-DASH-001 ｜ å…³è”原型：prototype/dashboard.html
83   -```
84   -
85   -- `整体里程碑:` 字段由 `coding.mjs` çš„ milestone stage 在打å‰ç«¯é‡Œç¨‹ç¢‘ tag 时从 `—` 改为 `milestone/frontend-phase`。
86   -- "功能:" 列表由 Plan 阶段 A6（`frontend-scope-lock`）+ `coding.mjs` 推导写入（无人工审阅断点）。FE 是业务功能粒度，与 prototype HTML 文件数无关。
87   -- æ¯ä¸ª `FE-NN` å­é¡¹ç”± `coding.mjs` çš„ review stage 在 `verdict=approve` 时自动勾选为 `[x]`。
88   -- prototype/ é—¨ç¦åœ¨ Plan 阶段 A6 `frontend-scope-lock` 强制检查项目根 `prototype/` è‡³å°‘å« 1 个 `*.html` mockup。
89   -
90   -### 状æ€è¯­ä¹‰ï¼ˆåŽç«¯æ¨¡å— + å‰ç«¯é˜¶æ®µå…±ç”¨ï¼‰
91   -
92   -| `里程碑:` 字段 | `git tag -l` | å«ä¹‰ | 你（Claude Code）的行为 |
93   -|---|---|---|---|
94   -| `—` | tag ä¸å­˜åœ¨ | 该阶段未开始 / 进行中（未打里程碑） | ✅ 开始 / ç»§ç»­è¯¥é˜¶æ®µå¼€å‘ |
95   -| `milestone/<id>` | tag 存在 | 阶段**已完æˆ** | 🟢 åŽç«¯ï¼šè¿›å…¥ä¸‹ä¸€æœªå®Œæˆæ¨¡å—ï¼›åŽç«¯å…¨å®Œ → å‰ç«¯é˜¶æ®µï¼›å‰ç«¯å·²æ‰“里程碑 → å…¨éƒ¨å®Œæˆ |
96   -
97   -### 模å—完æˆæŠ¥å‘Š
98   -
99   -ç”± `coding.mjs` çš„ report stage 产出（12 节标准化，å«è·¨æ¨¡å—改动等 CLAUDE.md 软规则映射节）。CC ä¸æ‰‹å†™æ¨¡å—报告。
  18 +B 阶段由 `/erp-workflow:coding-start` å¯åŠ¨ `workflows/coding.mjs`：按模å—循环跑 spec → plan → tdd → verify → review（åŒæž„ `featureLoop`），åŽç«¯æ¯æ¨¡å—一个里程碑 tag，å‰ç«¯æ•´ä½“一个里程碑 tag。里程碑字段与å­é¡¹æ¸…å•è®°å½•åœ¨ `docs/08 § 二`（åŽç«¯ï¼‰/ `§ 三`（å‰ç«¯ï¼‰ï¼›é˜¶æ®µå®Œæˆåˆ¤å®šä»¥ `里程碑:` / `整体里程碑:` 字段 + 本地 `git tag -l 'milestone/<id>'` 为准，å­é¡¹å‹¾é€‰åªä½œå¯è§†åŒ–进度。详细路由 / testGate / ä¸­æ–­è¡Œä¸ºè§ `README.md` 与 `workflows/coding.mjs`。
100 19  
101 20 ---
102 21  
103 22 ## ðŸ·ï¸ å ä½ç¬¦ç»Ÿä¸€çº¦å®š
104 23  
105   -项目文档里有 **2 ç§å¡«å†™å ä½** + **1 ç§æ示å ä½**：
106   -
107   -| æ ¼å¼ | è°å¡« | 使用阶段 | 说明 |
108   -|------|-----|---------|------|
109   -| `ã€äººå·¥å¡«å†™ï¼š<简短说明>】` | 人 | ä»… A 阶段文档 | 密钥 / 账密 / 包å / 命å约定 / å°ç‰ˆæœ¬å·ç­‰äººå·¥æ‰èƒ½å†³å®šçš„值；B 阶段 plan/spec ç¦æ­¢å‡ºçŽ°ï¼ŒæŸ¥ä¸åˆ°çœŸå€¼æ—¶ç”¨ `AskUserQuestion` 问用户 |
110   -| `TBD(<责任人>)` | CC 自动 | A 或 B | åŽç¼€é™„带责任方（如 `TBD(A3 自动补)` / `TBD(A5 自动补)`）；由对应 skill / `coding.mjs` stage 就地补填，模å—完æˆæŠ¥å‘Š § ⑦ 检查 `TBD(CC è¡¥)` 残留 |
111   -
112   -**HTML 注释 `<!-- ... -->`**：æ示å ä½ï¼Œæ˜¯**æ’件内部大纲模æ¿**里给 LLM çš„**填空æ示 / 章节引导**，指引 LLM 按结构填实际内容。skill 生æˆæ—¶ä¼š**剥除**这些注释，最终产物里注释ä¸ä¼šä¿ç•™ã€‚
  24 +项目文档里两ç§äººå·¥å¡«å†™å ä½ï¼š
  25 +- `ã€äººå·¥å¡«å†™ï¼š<简短说明>】` — ä»… A 阶段文档；B 阶段 plan/spec ç¦æ­¢å‡ºçŽ°ï¼ŒæŸ¥ä¸åˆ°çœŸå€¼æ—¶ç”¨ `AskUserQuestion` 问用户。
  26 +- `TBD(<责任人>)` — 由对应 skill / `coding.mjs` stage 自动就地补填（如 `TBD(A3 自动补)`）；模å—完æˆæŠ¥å‘Š § ⑦ 检查 `TBD(CC è¡¥)` 残留。
113 27  
114 28 ---
115 29  
... ... @@ -194,62 +108,3 @@ B 阶段整体是**一个é™é»˜ Workflow 脚本 `workflows/coding.mjs`**（由ç˜
194 108 | S1 | **技术栈外组件引入** | 用 `AskUserQuestion` 给用户三选一：接å—引入 / æ¢æ–¹æ¡ˆ / æ‹’ç» | â‘  **接å—** → åŒä¼šè¯ç›´æŽ¥åœ¨ `docs/04 § 零` 追加一行 → 继续æµç¨‹ â‘¡ **æ¢æ–¹æ¡ˆ / æ‹’ç»** → 视为常规歧义澄清，继续 Q&A 收敛 â‘¢ ä¸å†™ Blockerã€ä¸ä¸­æ–­æµç¨‹ |
195 109 | S2 | **跨模å—改动** | **默认ä¸æ”¹**，仅为当å‰æ¨¡å—实现所必需时å…许修改 | `coding.mjs` çš„ cross-module stage 在模å—循环内记录改动并补「原因 / å½±å“评估ã€ï¼Œã€Œè·¨æ¨¡å—改动ã€èŠ‚完整贴入《模å—完æˆæŠ¥å‘Šã€‹ |
196 110  
197   ----
198   -
199   -## 🧭 通用工作准则（General Principles）
200   -
201   -### 1. Think Before Coding
202   -
203   -**Don't assume. Don't hide confusion. Surface tradeoffs.**
204   -
205   -Before implementing:
206   -- State your assumptions explicitly. If uncertain, ask.
207   -- If multiple interpretations exist, present them - don't pick silently.
208   -- If a simpler approach exists, say so. Push back when warranted.
209   -- If something is unclear, stop. Name what's confusing. Ask.
210   -
211   -### 2. Simplicity First
212   -
213   -**Minimum code that solves the problem. Nothing speculative.**
214   -
215   -- No features beyond what was asked.
216   -- No abstractions for single-use code.
217   -- No "flexibility" or "configurability" that wasn't requested.
218   -- No error handling for impossible scenarios.
219   -- If you write 200 lines and it could be 50, rewrite it.
220   -
221   -Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
222   -
223   -### 3. Surgical Changes
224   -
225   -**Touch only what you must. Clean up only your own mess.**
226   -
227   -When editing existing code:
228   -- Don't "improve" adjacent code, comments, or formatting.
229   -- Don't refactor things that aren't broken.
230   -- Match existing style, even if you'd do it differently.
231   -- If you notice unrelated dead code, mention it - don't delete it.
232   -
233   -When your changes create orphans:
234   -- Remove imports/variables/functions that YOUR changes made unused.
235   -- Don't remove pre-existing dead code unless asked.
236   -
237   -The test: Every changed line should trace directly to the user's request.
238   -
239   -### 4. Goal-Driven Execution
240   -
241   -**Define success criteria. Loop until verified.**
242   -
243   -Transform tasks into verifiable goals:
244   -- "Add validation" → "Write tests for invalid inputs, then make them pass"
245   -- "Fix the bug" → "Write a test that reproduces it, then make it pass"
246   -- "Refactor X" → "Ensure tests pass before and after"
247   -
248   -For multi-step tasks, state a brief plan:
249   -```
250   -1. [Step] → verify: [check]
251   -2. [Step] → verify: [check]
252   -3. [Step] → verify: [check]
253   -```
254   -
255   -Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
... ...