@captain_z/zsk-skills 1.0.1 → 1.1.0

package/README.md

@@ -1,31 +1,21 @@
 # @captain_z/zsk-skills
 
-ZNorth Standard Kit 的内容包：**46 颗原子 skill**，按领域分簇组织，通过 `npx @captain_z/zsk add` 可安装到 Claude / Codex / Gemini 等多 harness。
+ZNorth Standard Kit 的内容包：**47 颗原子 skill**，按领域分簇组织，通过 `npx @captain_z/zsk add` 可安装到 Claude / Codex / Gemini 等多 harness。
 
 ## 合规审查（ARCHITECTURE §4.4 硬指标）
 
 | 检查项                                                                                   | 结果    | 说明                                                  |
 | ---------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
-| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 46/46 | 结构化 lint 通过                                      |
-| `name` 以 `zsk:` 前缀，扁平 slug                                                         | ✓ 46/46 | 命名空间统一                                          |
-| `description` 以 `Use when…` 开头（trigger-optimized）                                   | ✓ 46/46 | 触发匹配句式                                          |
-| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 46/46 | stage/workflow/standard/resource/meta · core/optional |
-| `triggers` 数组非空                                                                      | ✓ 46/46 | 每颗至少 4 个关键词                                   |
+| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 47/47 | 结构化 lint 通过                                      |
+| `name` 以 `zsk:` 前缀，扁平 slug                                                         | ✓ 47/47 | 命名空间统一                                          |
+| `description` 使用直接陈述风格，触发词放入 `triggers`                                   | ✓ 47/47 | 触发语义由 description + triggers 共同承担            |
+| `category` / `domain` / `tier` 枚举值合法                                                | ✓ 47/47 | stage/workflow/standard/resource/meta · core/optional |
+| `triggers` 数组非空                                                                      | ✓ 47/47 | 每颗至少 4 个关键词                                   |
 | 无硬编码项目名 / 技术栈（统一 `{{config.*}}` 占位符）                                    | ✓       | harness-neutral                                       |
 | `related:` 相对路径合法（build 已重写）                                                  | ✓       | 无孤儿引用                                            |
-| 单文件 ≤ 300 行                                                                          | ⚠ 41/46 | 5 个 frontend skill 超标（见技术债）                  |
+| 单文件 ≤ 300 行                                                                          | ✓ 47/47 | `lint-frontmatter` 作为 error 强制                    |
 
-**技术债**（不阻塞 CI，`tools/lint-frontmatter.ts` 当前降级 warn）：
-
-| 文件                                | 行数 |
-| ----------------------------------- | ---- |
-| `frontend/a11y-web/SKILL.md`        | 370  |
-| `frontend/testing-web/SKILL.md`     | 351  |
-| `frontend/nfr-web/SKILL.md`         | 352  |
-| `frontend/security-web/SKILL.md`    | 311  |
-| `frontend/performance-web/SKILL.md` | 305  |
-
-清理手法见 `memory/project_tech_debts_lint_frontmatter.md`；完成后把 `max-lines` 从 `warn` 升回 `error`。
+当前 `max-lines` 已由 `tools/lint-frontmatter.ts` 作为 error 强制；新增或修改 skill 不应超过 300 行。
 
 ## 使用方法通则
 
@@ -46,13 +36,13 @@ zsk skill 是 LLM **按需自动触发**的资产：
 
 | 领域              | skill 数 | 职责                                       |
 | ----------------- | -------- | ------------------------------------------ |
-| `sdlc/`           | 17       | 7 阶段 SDLC + 3 变更工作流 + task 执行框架 |
+| `sdlc/`           | 18       | 7 阶段 SDLC + 3 变更工作流 + task 执行框架 |
 | `frontend/`       | 16       | React + Web 层实现规范                     |
 | `quality/`        | 5        | 跨栈质量原则                               |
 | `design-handoff/` | 2        | 设计交付方法论                             |
 | `system/`         | 5        | 工程宪法级资源                             |
 | `meta/`           | 1        | 元信息                                     |
-| **总计**          | **46**   |                                            |
+| **总计**          | **47**   |                                            |
 
 ## 安装套件（bundles.yaml）
 
@@ -63,21 +53,13 @@ zsk skill 是 LLM **按需自动触发**的资产：
 | `frontend-with-design-handoff` | 31     | frontend-project + Figma 交付 2               |
 | `custom`                       | 交互   | 通过 `zsk add` 任意多选                       |
 
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 46 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 46 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 46 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 46 skills -->
-
-<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 46 skills -->
+<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 47 skills -->
 
 ## Skill 清单（按领域）
 
 > 内容由 `tools/catalog.ts` 从各 SKILL.md frontmatter 生成。重生成：`pnpm catalog`。
 
-### `sdlc/` — SDLC · 7 阶段 + 3 变更工作流 + task 框架 (17)
+### `sdlc/` — SDLC · 7 阶段 + 3 变更工作流 + task 框架 (18)
 
 - **`zsk:proposal`** *[stage 1 · stage · core]*
   New-change framing (feature / bugfix / refactor) before spec work — why, success criteria, out-of-scope boundary, alternatives considered, and risks. Always the first stage of the 7-stage SDLC.
@@ -96,8 +78,8 @@ zsk skill 是 LLM **按需自动触发**的资产：
   触发：`implementing design` · `task by task delivery` · `local quality gates` · `smallest viable change`
 
 - **`zsk:reviewing`** *[stage 5 · stage · core]*
-  PR code review — self-checklist, reviewer checklist, Conventional Comments prefixes, technical-rigor-over-performative-agreement when receiving feedback, dispute escalation path. Stage 5 of the 7-stage SDLC. This is the code-view (does the diff look right); the contract-view is zsk:verify.
-  触发：`code review` · `PR review` · `conventional comments` · `receiving feedback`
+  PR 代码审查与 AI 多维审查核心规范。包含 Scope 偏移检测、多视角 Sub-Agent 审查、测试执行流分析、代码整洁/重构纪律、置信度校准以及按严重性排序的判定协议。
+  触发：`code review` · `PR review` · `审查合并请求` · `review this PR`
 
 - **`zsk:verify`** *[stage 6 · stage · core]*
   Acceptance verification before merge — independent contract check, FR/NFR coverage, AC evidence, gate records, and verdict with reproducible proof. Stage 6 of the 7-stage SDLC.
@@ -112,7 +94,7 @@ zsk skill 是 LLM **按需自动触发**的资产：
   触发：`bugfix task template` · `TDD bug fix` · `red green regression` · `bug confidence questions`
 
 - **`zsk:dor-dod`** *[core]*
-  DoR/DoD gates between SDLC stages — generic DoR/DoD for all change types; frontend-specific rows (UE matrix / ue-mcp / 三语 i18n / 视觉回归 / axe) are in frontend:dor-dod-frontend.
+  DoR/DoD gates between SDLC stages — generic DoR/DoD for all change types; frontend-specific rows (UE matrix / ue-mcp / 三语 i18n / 视觉回归 / axe) are in zsk:dor-dod-frontend.
   触发：`definition of ready` · `definition of done` · `DoR DoD` · `task gate`
 
 - **`zsk:refactor-tasks`** *[core]*
@@ -147,6 +129,10 @@ zsk skill 是 LLM **按需自动触发**的资产：
   Behavior-preserving refactor discipline — Fowler catalog, characterization tests as baseline, small atomic commits, Parallel Change / Strangler Fig for large refactors. Enforces "behavior preserved" as a hard contract (any behavior change means it is not a refactor).
   触发：`refactor workflow` · `Fowler refactoring` · `characterization test` · `Parallel Change`
 
+- **`zsk:standard-dev-flow`** *[workflow · core]*
+  交互式标准开发工作流，包含 9 个核心节点（Prepare, Proposal, Spec, Design, Task, Coding, Review, Verify, Commit）。通过强门禁和 Sub-Agent 审查机制，保障高质量的开发落地。
+  触发：`standard dev flow` · `start a new feature workflow` · `execute enterprise workflow` · `9 node development`
+
 ### `frontend/` — Frontend · React + Web 层实现规范 (16)
 
 - **`zsk:spec-frontend`** *[stage 2 · stage · optional]*
@@ -264,7 +250,7 @@ zsk skill 是 LLM **按需自动触发**的资产：
   触发：`NFR baseline` · `non functional requirements` · `quality attributes` · `ISO 25010`
 
 - **`zsk:project-constraints-template`** *[optional]*
-  Project constraints template for new-project bootstrap — captures import origins, forbidden libraries/patterns, required wrappers, naming conventions, quality gates, branch/release conventions in one SYSTEM-SPEC chapter. The project-side constitutional constraint table, complementary to project-config.yaml (mechanical values).
+  Project constraints template for new-project bootstrap — captures import origins, forbidden libraries/patterns, required wrappers, naming conventions, quality gates, branch/release conventions in one SYSTEM-SPEC chapter. The project-side constitutional constraint table, complementary to project-config.md (mechanical values).
   触发：`project constraints` · `SYSTEM-SPEC` · `import origins` · `forbidden packages`
 
 ### `meta/` — Meta · 元信息 (1)

package/frontend/design-frontend/SKILL.md

@@ -32,10 +32,23 @@ triggers:
 # Stage 3: Design · Frontend 补丁
 
 > **用途**：当模块是**前端组件 / 页面**时，在 [`zsk:design`](../../sdlc/design/SKILL.md) 通用骨架上追加的实现映射
-> **范围**：Props 映射、UE 状态 → 结构、Figma → 实现、性能预算 (CWV)、ErrorBoundary
+> **范围**：Props 映射、UE 状态 → 结构、Figma → 实现、前端分层/抽离、性能预算 (CWV)、ErrorBoundary
 
 ## 追加章节
 
+### 0. 前端分层与抽离约束
+
+在通用 [`zsk:design`](../../sdlc/design/SKILL.md) 的代码组织表上，前端模块还要明确：
+
+- 页面 / 容器只做组合、路由参数适配和数据装配
+- 纯 UI 组件不直接请求接口，不持有跨页面业务状态
+- 复杂状态、异步流程、事件编排优先抽到 hooks / composables
+- 数据归一化、过滤、排序、权限判断等可测试逻辑优先抽到 utils / services / models
+- 样式与布局遵循项目样式系统，不把业务判断散落在 class 拼接里
+- 预计变长的列表、树、表单、权限矩阵等必须预先设计子组件和测试边界
+- 目录保持浅层：页面/容器、components、hooks/composables、services、utils/models 足够表达时，不继续嵌套
+- 子组件拆分以“可命名职责 + 可独立测试/复用/替换”为准，不按视觉小块机械拆分
+
 ### A. Props / 状态 / 事件实现映射
 
 Spec 的每个公开 Props 必须说明：
@@ -153,6 +166,8 @@ Spec 的每个 UE 状态必须说明**由哪个容器 / class / 分支渲染**
 
 ## 质量门禁（前端补丁）
 
+- [ ] 页面 / 容器 / UI / hooks / services / utils 职责边界明确
+- [ ] 目录层级扁平，子组件拆分不过碎
 - [ ] Props / UE 状态全部映射到文件
 - [ ] Figma → 实现映射表与 `ue-mcp.md` 一致
 - [ ] 性能预算量化（LCP / INP / CLS / bundle）

package/meta/philosophy/SKILL.md

@@ -24,7 +24,7 @@ triggers:
 
 - **通用**：不绑定任何具体项目、技术栈、组件库
 - **LLM 友好**：frontmatter + 小文件 + 交叉引用
-- **可适配**：项目通过 `PROJECT-CONFIG.yaml` 挂接，不 fork skills
+- **可适配**：项目通过 `zsk.config.yaml` + `project-config.md` 挂接，不 fork skills
 - **有纪律**：Superpowers 硬原则（证据先于断言、TDD、置信度质疑）
 
 ## 四股思想的贡献
@@ -94,28 +94,30 @@ Karpathy 原文是**"LLM 持续自维护的活知识库"**；本 skill set 是**
 | Reflect | `zsk:design` | 怎么做（设计 / ADR） |
 | Engage | `zsk:coding` → `zsk:reviewing` → `zsk:verify` → `zsk:archive` | 动手执行 + 审代码 + 验收 + 沉淀 |
 
-### 4. 项目 SYSTEM-SPEC — 适配层
+### 4. 项目适配层
 
 项目总有定制需求（路径 / 技术栈 / 命名 / 环境）。适配层保证：
 
-- **占位符系统**：`{{config.*}}` 在 skill 内作为抽象变量
+- **资源配置**：`zsk.config.yaml` 描述 `.raws`、模块、工具和同步来源
+- **占位符系统**：`project-config.md` frontmatter 提供 `{{config.*}}`
 - **优先级层级**：项目覆写 > 通用 skill
 - **不 fork**：通过配置文件覆盖，而非修改 skill 本体
 
-## 合成：5 条设计原则
+## 合成：6 条设计原则
 
 ### 原则 1：通用方法 × 项目配置
 
 ```text
  方法论（WHAT / HOW 抽象）      配置（WHERE / WHICH 具体）
         ↓                            ↓
-    .best-practices/      ×     PROJECT-CONFIG.yaml
+    .best-practices/      ×   zsk.config.yaml + project-config.md
         ↘                        ↙
           运行时解析 → 具体产物（模块 proposal.md / spec.md 等）
 ```
 
 - **方法论** → zsk skills（跨项目通用，npm 包）
-- **路径 / 工具 / 命名** → `PROJECT-CONFIG.yaml`（项目本地）
+- **资源 / 模块 / 同步** → `zsk.config.yaml`（项目本地）
+- **技术栈 / 脚本 / 阈值 / 命名** → `project-config.md`（项目本地）
 
 ### 原则 2：LLM 优先的组织
 
@@ -138,6 +140,8 @@ Karpathy 原文是**"LLM 持续自维护的活知识库"**；本 skill set 是**
 - TDD 是 Bugfix / Refactor 默认；Feature 视复杂度
 - 修 bug 前必问三问（Superpowers 置信度质疑）
 - Review 分歧时先验证技术，再讨论情感
+- Issue / Bug 先读日志与复现事实，确认根因后再改代码
+- 多 Agent 只按独立问题域拆分，输入必须自包含，结论必须由主 Agent 复核
 
 ### 原则 5：编号化交叉引用
 
@@ -167,23 +171,33 @@ Archive   Postmortem / ADR 引用原编号保留追溯
 - Bugfix 的"受影响契约项"、Refactor 的"行为不变"都用同一套编号
 - DoR/DoD/质量门禁把编号完整性作为硬性门禁
 
+### 原则 6：项目约束优先，最佳实践按需选择
+
+通用 skill 不预设任何项目一定使用某个语言、框架、目录名或工具。执行时按此顺序落地：
+
+1. 读用户目标和模块事实源
+2. 读 `zsk.config.yaml` 找资源、模块、工具入口
+3. 读 `SYSTEM-SPEC.md`、`project-config.md`、`docs/system/*` 找项目约束
+4. 再选择适用的最佳实践：TDD、Clean Code、重构之道、SOLID、安全、性能、a11y、领域专项
+
+不适用的最佳实践不强行套；适用但项目约束未定义时，先用通用原则提出建议或向用户确认。
+
 ## 优先级层级（冲突时上位胜出）
 
 1. **用户显式指令**（CLAUDE.md / 会话中的直接请求）
-2. **项目 PROJECT-CONFIG.yaml**（本项目的配置覆写）
-3. **项目 SYSTEM-SPEC.md**（本项目的系统规约）
-4. **项目 docs/system/\***（本项目 ADR / architecture / NFR）
-5. **zsk skills**（通用方法论，本目录）
-6. **`~/.claude/skills/*` 平台级 skill**（如 Superpowers）
-7. **工具默认行为**
+2. **项目 `zsk.config.yaml`**（资源、模块、工具和同步入口）
+3. **项目 `project-config.md`**（技术栈、脚本、阈值、命名等占位符配置）
+4. **项目 SYSTEM-SPEC.md**（本项目的系统规约）
+5. **项目 docs/system/\***（本项目 ADR / architecture / NFR）
+6. **zsk skills**（通用方法论，本目录）
+7. **`~/.codex/skills/*` / 平台级 skill**（如 Superpowers）
+8. **工具默认行为**
 
 ## 占位符系统
 
-Skill 文件引用项目特定内容时，一律用 `{{config.*}}` 占位符，由 `project-config.yaml`（CLI `zsk project-init` 产出）填充：
+Skill 文件引用项目特定内容时，一律用 `{{config.*}}` 占位符，由 `project-config.md` 填充；资源入口与同步方式由 `zsk.config.yaml` 填充：
 
 ```text
-{{config.paths.srs}}             原始需求文档
-{{config.paths.figma_index}}     设计索引（如有）
 {{config.stack.ui_lib}}          UI 库
 {{config.stack.state_async}}     异步状态库
 {{config.stack.state_shared}}    共享状态
@@ -203,19 +217,20 @@ Skill 文件引用项目特定内容时，一律用 `{{config.*}}` 占位符，
 以下情况立即停止并修正：
 
 1. Skill 里出现硬编码项目路径（如 `.raws/SRS.md`）→ 必须改为 `{{config.*}}`
-2. Skill 里推荐特定 UI 库名 → 改为 `{{config.stack.ui_lib}}`
-3. 同一份 skill 做 3+ 件事 → 拆分
-4. 单文件 > 300 行 → 拆分或精简
-5. 文档没 frontmatter → 补齐
-6. `description` 以 "Use when…" 开头 → 重写为直接陈述风格（主题名词短语 — 关键要点）
-7. 引用其他 skill 但没写在 `related:` → 补齐
-8. 模板用了未在 `project-config.yaml` 声明的变量 → 补齐配置模板
+2. Skill 里硬编码资源路径 → 改为读取 `zsk.config.yaml.sources.*`
+3. Skill 里推荐特定 UI 库名 → 改为 `{{config.stack.ui_lib}}`
+4. 同一份 skill 做 3+ 件事 → 拆分
+5. 单文件 > 300 行 → 拆分或精简
+6. 文档没 frontmatter → 补齐
+7. `description` 以 "Use when…" 开头 → 重写为直接陈述风格（主题名词短语 — 关键要点）
+8. 引用其他 skill 但没写在 `related:` → 补齐
+9. 模板用了未在 `project-config.md` 声明的变量 → 补齐配置模板
 
 ## 输出承诺
 
 最终的 skill set 通过 `@captain_z/zsk` CLI 发布，允许：
 
 - ✅ 任意新项目通过 `npx @captain_z/zsk project-init` 接入
-- ✅ 不需要修改 skill 内容，只改 `project-config.yaml`
+- ✅ 不需要修改 skill 内容，只改 `project-config.md` 或 `zsk.config.yaml`
 - ✅ 允许项目通过 `SYSTEM-SPEC.md` 本地覆写个别规则
 - ✅ 上游 skill 更新不破坏项目（版本化 + config 向后兼容）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@captain_z/zsk-skills",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "ZNorth Standard Kit — skill content package (SDLC + frontend + quality + design-handoff + system + meta)",
   "license": "MIT",
   "files": [

package/quality/code-hygiene/SKILL.md

@@ -112,6 +112,16 @@ triggers:
 - **文件长度**：超阈值必拆（推荐 300-500 行按语言）
 - **深度嵌套**：推荐 ≤ 3-4 层
 
+## 组织与抽离原则
+
+- **相关性优先**：目录按业务能力和变化原因组织，不按随手创建的技术桶无限堆叠。
+- **边界先于复用**：抽离首先为了清晰边界和可测试，其次才是减少行数。
+- **单文件单主责**：一个文件同时承担入口编排、UI、业务规则、数据访问、工具函数时，必须拆。
+- **抽离形式适配项目**：纯计算用 util，状态/副作用用 hook/composable，外部 IO 用 service/repository，复杂领域规则用 domain object/class/service。
+- **扁平优先**：目录深度默认保持浅层；只有职责边界、权限边界、发布边界或复用边界明确时才加一层。
+- **不过度碎片化**：拆分后如果调用链更难追踪、文件名无法表达稳定职责、测试收益很低，应合并回邻近模块。
+- **避免过早抽象**：只被一个地方使用且很小的逻辑可以留在局部，但要保持命名清楚、测试可达。
+
 具体到栈：
 - TypeScript 红线：见 [`frontend/typescript`](../../frontend/typescript/SKILL.md)
 - React 命名规范：见 [`frontend/react-naming`](../../frontend/react-naming/SKILL.md)

package/quality/testing-pyramid/SKILL.md

@@ -74,6 +74,17 @@ Bugfix 与 Refactor 默认使用 TDD；Feature 视情况（复杂逻辑建议 TD
 
 ## 测试用例设计
 
+### 事实源匹配
+
+测试用例必须能追溯到原始资源和设计约束：
+
+- 原始测试资产：`.raws/testing`、SRS、提测用例、历史缺陷
+- 行为契约：`spec.md` 的 FR / NFR / AC / 场景
+- 设计约束：`design.md` 的关键流程、状态机、数据流、错误处理、回滚策略
+- 模块映射：`docs/{module}/module.yaml` 的 `tests.raw_cases` / `derived_cases` / `automated`
+
+缺少追溯来源的测试可作为补充，但不能替代契约测试。
+
 ### 结构：AAA 或 GWT（语言无关）
 
 ```text
@@ -101,6 +112,13 @@ GWT（Given - When - Then）
 4. **契约边界**：公开接口的每个参数组合
 5. （若涉及）并发 / 幂等 / 重入
 
+## 场景覆盖目标
+
+- **目标：100% 场景覆盖**。`spec.md` 中每个 Scenario / AC、`.raws/testing` 中每个原始用例、`design.md` 中每条关键流程分支都应映射到测试或人工验证证据。
+- 无法 100% 覆盖时，必须在 `verification.md` 记录缺口、风险、原因、补测计划和用户/负责人豁免。
+- 覆盖率按“场景与分支”计算，不只看语句覆盖率。语句 100% 但缺失业务场景，仍视为测试缺口。
+- P0/P1 业务路径、权限路径、数据一致性路径和历史缺陷回归不得豁免。
+
 ### 独立性与确定性
 
 - **不共享状态**：每个 test 独立 setup / teardown
@@ -134,6 +152,8 @@ GWT（Given - When - Then）
 - [ ] 代码合并到主干
 - [ ] 单元测试通过，覆盖关键分支
 - [ ] 集成 / E2E 测试通过（如适用）
+- [ ] 原始测试资产、Spec 场景、Design 分支均已映射
+- [ ] 场景覆盖目标为 100%；不足项有风险和豁免记录
 - [ ] `lint` / `type-check` / `build` 零 error
 - [ ] PR 自检清单全部勾选
 

package/sdlc/bugfix/SKILL.md

@@ -59,7 +59,7 @@ Bug报告         复现+期望        5 Whys        Red→Green       相邻回
 **Addendum**:
 - 按 [`zsk:proposal`](../proposal/SKILL.md) 的 Bugfix 型模板
 - 严重度 P0–P3 明确
-- 是否 Hotfix 决策在此做出（见 [`quality:release`](../../quality/release/SKILL.md)）
+- 是否 Hotfix 决策在此做出（见 [`zsk:release`](../../quality/release/SKILL.md)）
 
 **Exit**: 严重度 / 影响范围 / 复现步骤明确 · 证据完整（截图 / 录屏 / 日志 / trace）
 
@@ -139,7 +139,7 @@ Bug报告         复现+期望        5 Whys        Red→Green       相邻回
 - 边界条件测试
 - 相关质量维度核对（前端：a11y / i18n / 性能；后端：幂等 / 并发 / 权限）
 - **证据归档**：log 前后对照、测试报告、复现步骤回归
-- **P0 / P1 → Hotfix 流程**（见 [`quality:release`](../../quality/release/SKILL.md)）
+- **P0 / P1 → Hotfix 流程**（见 [`zsk:release`](../../quality/release/SKILL.md)）
 - **P2 / P3 → 常规发布**
 
 **Output**: 修复代码 + 回归测试 · 证据链（前后对照截图 / 报告）

package/sdlc/coding/SKILL.md

@@ -37,7 +37,7 @@ triggers:
 > **阶段定位**：实施 / Execution
 > **回答的问题**：按什么顺序实现、如何控制改动、何时可以提交评审
 > **不回答的问题**：需求边界是否成立（看 `spec`）、方案是否合理（看 `design`）、是否满足契约（看 `verify`）
-> **项目/框架约束放哪里**：仓库结构、提交规范、分支规则、必用封装、禁用模式都来自 `SYSTEM-SPEC.md`、`project-config.yaml` 或 [`zsk:project-constraints-template`](../../system/project-constraints-template/SKILL.md)
+> **项目/框架约束放哪里**：仓库结构、提交规范、分支规则、必用封装、禁用模式都来自 `SYSTEM-SPEC.md`、`project-config.md` 或 [`zsk:project-constraints-template`](../../system/project-constraints-template/SKILL.md)
 
 ## 阶段职责
 

package/sdlc/design/SKILL.md

@@ -34,7 +34,7 @@ triggers:
 > **阶段定位**：方案设计 / Solution Design
 > **回答的问题**：在当前系统约束下，如何把 Spec 落成可执行方案
 > **不回答的问题**：新增未在 Spec 声明的公开行为；写实现代码
-> **项目/框架约束放哪里**：团队、语言、框架、仓库规则来自 `SYSTEM-SPEC.md`、`project-config.yaml` 或 [`zsk:project-constraints-template`](../../system/project-constraints-template/SKILL.md)；Design 只引用并落实
+> **项目/框架约束放哪里**：团队、语言、框架、仓库规则来自 `SYSTEM-SPEC.md`、`project-config.md` 或 [`zsk:project-constraints-template`](../../system/project-constraints-template/SKILL.md)；Design 只引用并落实
 
 ## 核心输入
 
@@ -49,10 +49,11 @@ Design 应沉淀以下内容：
 1. 当前状态与约束
 2. 关键决策与理由
 3. 目标结构 / 流程 / 数据或交互流
-4. FR / NFR 到实现的映射
-5. 错误处理、降级、兼容、迁移与回滚
-6. 可观测性与验证策略
-7. 交付切片 / 依赖顺序
+4. 代码组织、分层与抽离策略
+5. FR / NFR 到实现的映射
+6. 错误处理、降级、兼容、迁移与回滚
+7. 可观测性与验证策略
+8. 交付切片 / 依赖顺序
 
 ## 变更类型差异
 
@@ -108,19 +109,33 @@ Design 可以决定实现方式，不能追加新的对外契约。发现 Spec
 - 失败时如何止损
 - 是否需要兼容期或双跑期
 
+### 6. 代码组织必须先设计后实现
+
+Design 必须说明代码如何组织，避免 coding 阶段自然长成“单文件堆积”：
+
+- **按相关性聚合**：同一业务能力放在同一模块边界内；不同业务能力不要混放。
+- **目录尽量扁平**：优先 2-3 层可读结构；没有明确职责收益时，不新增深层目录。
+- **分层清晰**：入口 / UI 或接口适配 / 业务逻辑 / 数据访问 / 工具函数边界明确。
+- **逻辑与表现分离**：可复用业务规则、状态推导、数据转换不要埋在 UI、controller 或路由入口里。
+- **按稳定职责抽离**：跨入口复用或可独立测试的逻辑抽为 `utils` / `hooks` / `services` / `models` / class / domain service 等项目适配形式。
+- **模块化但不过碎**：拆分围绕业务相关性、复用边界、测试边界和变更原因；不要把只服务一个小分支的微逻辑拆成难追踪文件。
+- **控制文件体量**：预计超过项目阈值、出现多个职责或深层嵌套时，设计阶段就给出拆分方案。
+- **依赖方向单向**：底层逻辑不反向依赖 UI / 入口层；共享层不依赖具体业务页面。
+
 ## 推荐结构
 
 1. 模块映射与事实源
 2. 当前状态与关键约束
 3. 目标结构 / 关键流程
 4. 决策记录（ADR 级或局部设计决策）
-5. FR 实现映射
+5. 代码组织 / 分层 / 抽离策略
+6. FR 实现映射
 > **核心映射原则**：方案产出必须呈现一张明确的矩阵（FR编号 -> 代码模块），此为设计与现实实现的锚点。
-6. NFR 落地策略
-7. 错误处理 / 降级 / 安全边界
-8. 迁移 / 回滚 / 发布策略
-9. 可观测性 / 测试策略
-10. 交付切片与依赖
+7. NFR 落地策略
+8. 错误处理 / 降级 / 安全边界
+9. 迁移 / 回滚 / 发布策略
+10. 可观测性 / 测试策略
+11. 交付切片与依赖
 
 ## Feature 型模板
 
@@ -140,6 +155,25 @@ Design 可以决定实现方式，不能追加新的对外契约。发现 Spec
 - 目标结构：
 - 关键流程：
 
+## 代码组织 / 分层 / 抽离策略
+| 层 / 职责 | 文件或目录 | 放入内容 | 不放入内容 |
+| --- | --- | --- | --- |
+| 入口 / 组合 |  | 编排、依赖注入、路由/页面组装 | 复杂业务规则 |
+| UI / 表现 |  | 渲染、交互状态、样式适配 | 数据访问、跨模块业务规则 |
+| 业务逻辑 |  | 规则、状态推导、流程判断 | UI 细节 |
+| 数据 / 服务 |  | API、仓储、DTO 归一化 | 展示逻辑 |
+| 工具 / 共享 |  | 纯函数、格式化、通用转换 | 具体业务流程 |
+
+## 目录形态
+| 目录 | 层级 | 职责 | 保持/新增理由 |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+## 抽离决策
+| 候选逻辑 | 抽离形式 | 理由 | 测试方式 |
+| --- | --- | --- | --- |
+|  | util / hook / service / class / component |  |  |
+
 ## 关键决策
 | 决策 | 选项 | 结论 | 理由 |
 | --- | --- | --- | --- |
@@ -230,6 +264,9 @@ Design 里不必写完整 `tasks.md`，但必须给出：
 - [ ] 已扫描当前状态与关键约束
 - [ ] 未新增 Spec 未声明的行为
 - [ ] 关键决策有理由，有主要替代方案对照
+- [ ] 代码组织、分层和抽离策略明确
+- [ ] 目录结构尽量扁平，没有无理由深层嵌套
+- [ ] 拆分粒度合理，既没有单文件堆积，也没有过度碎片化
 - [ ] FR / NFR 均有落地方式
 - [ ] 错误处理、回滚、验证策略明确
 - [ ] 高风险改动已说明兼容 / 迁移方案

package/sdlc/dor-dod/SKILL.md

@@ -2,7 +2,7 @@
 name: zsk:dor-dod
 description: DoR/DoD gates between SDLC stages — generic DoR/DoD for all change
   types; frontend-specific rows (UE matrix / ue-mcp / 三语 i18n / 视觉回归 / axe) are
-  in frontend:dor-dod-frontend.
+  in zsk:dor-dod-frontend.
 category: resource
 domain: sdlc
 tier: core
@@ -27,7 +27,7 @@ triggers:
 # DoR & DoD — 任务启动与关闭门禁
 
 > **用途**：启动一个任务前跑 DoR；交付 / 关闭前跑 DoD
-> **通用版 + 变更类型专用**；前端项目的额外条款（UE / Figma / 三语 / a11y / 视觉回归）见 [`frontend:dor-dod-frontend`](../../frontend/dor-dod-frontend/SKILL.md)
+> **通用版 + 变更类型专用**；前端项目的额外条款（UE / Figma / 三语 / a11y / 视觉回归）见 [`zsk:dor-dod-frontend`](../../frontend/dor-dod-frontend/SKILL.md)
 
 ## Definition of Ready（DoR）— 启动前门禁
 
@@ -44,7 +44,7 @@ triggers:
 - [ ] NFR 六类（性能 / 可靠性 / 安全 / 国际化 / 兼容性 / 可观测性）全覆盖
 - [ ] 后端契约目录（若涉及接口）已对齐
 
-> 前端模块额外：UE 状态矩阵覆盖、`ue-mcp.md` 登记、Props / Event Contract 完整 — 见 [`frontend:dor-dod-frontend`](../../frontend/dor-dod-frontend/SKILL.md)
+> 前端模块额外：UE 状态矩阵覆盖、`ue-mcp.md` 登记、Props / Event Contract 完整 — 见 [`zsk:dor-dod-frontend`](../../frontend/dor-dod-frontend/SKILL.md)
 
 ### Bugfix 专用
 
@@ -75,7 +75,7 @@ triggers:
 - [ ] **FR 覆盖矩阵**所有 P0 FR 都有"覆盖任务 + 验收证据"（见 [`zsk:task-evidence`](../task-evidence/SKILL.md)）
 - [ ] **校验记录**每行有证据链接（证据先于断言）
 
-> 前端模块额外：视觉回归 / i18n 三语 / a11y / CWV — 见 [`frontend:dor-dod-frontend`](../../frontend/dor-dod-frontend/SKILL.md)
+> 前端模块额外：视觉回归 / i18n 三语 / a11y / CWV — 见 [`zsk:dor-dod-frontend`](../../frontend/dor-dod-frontend/SKILL.md)
 
 ### Feature 专用
 

package/sdlc/feature/SKILL.md

@@ -66,7 +66,7 @@ triggers:
 - User Stories 满足 INVEST
 - BDD Given/When/Then ≥ 1 Happy + 1 Edge
 - FR / NFR / US / AC 编号完整
-- **前端模块补** [`frontend:spec-frontend`](../../frontend/spec-frontend/SKILL.md)：Props / Event Contract / UE 状态矩阵 / Figma 引用
+- **前端模块补** [`zsk:spec-frontend`](../../frontend/spec-frontend/SKILL.md)：Props / Event Contract / UE 状态矩阵 / Figma 引用
 
 **Output**: `docs/{module}/spec.md`（+ 前端模块的 `ue-mcp.md` / `api-contract.md`）
 
@@ -82,7 +82,7 @@ triggers:
 - 按 [`zsk:design`](../design/SKILL.md) 的 Feature 型模板
 - 关键决策都走 ADR（模板 [`zsk:adr`](../../system/adr/SKILL.md)）
 - 上下文图 + 时序图（Mermaid 内联）
-- **前端模块补** [`frontend:design-frontend`](../../frontend/design-frontend/SKILL.md)：Props/UE 实现映射 + Figma → 实现 + 性能预算（CWV）
+- **前端模块补** [`zsk:design-frontend`](../../frontend/design-frontend/SKILL.md)：Props/UE 实现映射 + Figma → 实现 + 性能预算（CWV）
 - 错误 / 降级 / 回滚策略
 - 未新增 Spec 未声明的行为
 
@@ -97,9 +97,9 @@ triggers:
 **Primary Skill**: `superpowers:executing-plans` · `superpowers:test-driven-development` · `zsk:coding` · `superpowers:using-git-worktrees`（需隔离时）· `code-commit` · GSD: Engage
 
 **Addendum**:
-- 任务模板：通用用 [`zsk:task-structure`](../task-structure/SKILL.md)；组件/前端用 [`frontend:feature-tasks-frontend`](../../frontend/feature-tasks-frontend/SKILL.md)（7 类强制任务）
+- 任务模板：通用用 [`zsk:task-structure`](../task-structure/SKILL.md)；组件/前端用 [`zsk:feature-tasks-frontend`](../../frontend/feature-tasks-frontend/SKILL.md)（7 类强制任务）
 - 遵循 [`zsk:coding`](../coding/SKILL.md) 的分支 / commit / 依赖卫生
-- 遵循 [`quality:testing-pyramid`](../../quality/testing-pyramid/SKILL.md)
+- 遵循 [`zsk:testing-pyramid`](../../quality/testing-pyramid/SKILL.md)
 - 契约驱动：类型引自 Spec / 后端契约（`system/project-constraints-template`）
 
 **Exit**: 测试金字塔三层均有任务且绿 · 本地 lint / type-check / test 零 error · Commit 遵循 Conventional Commits
@@ -111,7 +111,7 @@ triggers:
 **Primary Skill**: `superpowers:requesting-code-review` · `superpowers:receiving-code-review` · `zsk:reviewing` / `review` / `merge-review` / `codex review`
 
 **Addendum**:
-- 自评清单（通用见 [`zsk:reviewing`](../reviewing/SKILL.md)；前端补 [`frontend:review-frontend`](../../frontend/review-frontend/SKILL.md)）全绿
+- 自评清单（通用见 [`zsk:reviewing`](../reviewing/SKILL.md)；前端补 [`zsk:review-frontend`](../../frontend/review-frontend/SKILL.md)）全绿
 - 至少 1 轮 Code Review 通过（高风险改动 ≥ 2 人）
 - Conventional Comments：`blocking:` / `issue:` / `suggestion:` / `nitpick:`
 - 分歧验证技术事实再决策
@@ -128,7 +128,7 @@ triggers:
 - DoD 全绿（见 [`zsk:dor-dod`](../dor-dod/SKILL.md)）
 - FR 覆盖矩阵完整（Spec 每条 P0 FR 都有任务 + 验收证据）
 - AC 逐条勾选，每条有证据链接
-- 校验记录全绿（通用 + 前端项目补 `frontend:nfr-web` 的视觉 / a11y / i18n / 性能 / 安全）
+- 校验记录全绿（通用 + 前端项目补 `zsk:nfr-web` 的视觉 / a11y / i18n / 性能 / 安全）
 
 **Output**: `docs/{module}/tasks.md`（全程更新）· 代码 + 测试 · PR / MR · Changelog 条目 · 证据链
 
@@ -144,7 +144,7 @@ triggers:
 - Changelog `Added` 条目引用 Spec FR 编号
 - 归档入 `SYSTEM-SPEC.md`（如有系统级约定）
 - 历史快照保存到 `docs/{module}/archive/{YYYY-MM-DD}-{需求名}/`
-- 遵循 [`quality:release`](../../quality/release/SKILL.md)（SemVer / Changelog / 回滚预案）
+- 遵循 [`zsk:release`](../../quality/release/SKILL.md)（SemVer / Changelog / 回滚预案）
 - 发布后 30 分钟 canary 观察（若适用）
 
 ## Skip 规则

package/sdlc/refactor/SKILL.md

@@ -172,7 +172,7 @@ triggers:
 **Addendum**:
 - 更新 `design.md` 中的 ADR（Proposed → Accepted）
 - Changelog 仅 **Changed** / **Removed** 章节（**不在** Added / Fixed）
-- 遵循 [`quality:release`](../../quality/release/SKILL.md)
+- 遵循 [`zsk:release`](../../quality/release/SKILL.md)
 - 大重构若用 feature flag，登记 flag 清理计划
 - 大重构归档到 `docs/{module}/archive/{YYYY-MM-DD}-refactor-{简述}/`