Commit c43e7989d8459c6449893105037ffb242c33c26f
1 parent
b7e4fa58
docs(CLAUDE-template): drop generic principles section and orchestrator re-documentation
Showing
1 changed file
with
5 additions
and
150 deletions
skills/plan/project-init/templates/CLAUDE-template.md
| @@ -13,103 +13,17 @@ | @@ -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,62 +108,3 @@ B 阶段整体是**一个é™é»˜ Workflow 脚本 `workflows/coding.mjs`**ï¼ˆç”±ç˜ | ||
| 194 | | S1 | **æŠ€æœ¯æ ˆå¤–ç»„ä»¶å¼•å…¥** | 用 `AskUserQuestion` 给用户三选一：接å—引入 / æ¢æ–¹æ¡ˆ / æ‹’ç» | â‘ **接å—** → åŒä¼šè¯ç›´æŽ¥åœ¨ `docs/04 § 零` è¿½åŠ ä¸€è¡Œ → 继ç»æµç¨‹ â‘¡ **æ¢æ–¹æ¡ˆ / æ‹’ç»** → 视为常规æ§ä¹‰æ¾„æ¸…ï¼Œç»§ç» Q&A 收敛 â‘¢ ä¸å†™ Blockerã€ä¸ä¸æ–æµç¨‹ | | 108 | | S1 | **æŠ€æœ¯æ ˆå¤–ç»„ä»¶å¼•å…¥** | 用 `AskUserQuestion` 给用户三选一：接å—引入 / æ¢æ–¹æ¡ˆ / æ‹’ç» | â‘ **接å—** → åŒä¼šè¯ç›´æŽ¥åœ¨ `docs/04 § 零` è¿½åŠ ä¸€è¡Œ → 继ç»æµç¨‹ â‘¡ **æ¢æ–¹æ¡ˆ / æ‹’ç»** → 视为常规æ§ä¹‰æ¾„æ¸…ï¼Œç»§ç» Q&A 收敛 â‘¢ ä¸å†™ Blockerã€ä¸ä¸æ–æµç¨‹ | |
| 195 | | S2 | **跨模å—改动** | **默认ä¸æ”¹**，仅为当å‰æ¨¡å—实现所必需时å…许修改 | `coding.mjs` çš„ cross-module stage 在模å—å¾ªçŽ¯å†…è®°å½•æ”¹åŠ¨å¹¶è¡¥ã€ŒåŽŸå› / å½±å“评估ã€ï¼Œã€Œè·¨æ¨¡å—改动ã€èŠ‚完整贴入《模å—完æˆæŠ¥å‘Šã€‹ | | 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. |