diff --git a/skills_library/all/module-partitioning/SKILL.md b/skills_library/all/module-partitioning/SKILL.md new file mode 100644 index 0000000..0206609 --- /dev/null +++ b/skills_library/all/module-partitioning/SKILL.md @@ -0,0 +1,146 @@ +--- +name: module-partitioning +description: Use when 划分软件模块/确定模块边界/复核模块拆分/把功能清单归并成模块。八原则(A业务能力/B业务边界/C高内聚低耦合/D业务闭环/E生命周期独立/F唯一责任/G基础设施非业务模块/H稳定后再抽象)+四张图(业务对象/生命周期/数据所有权/业务依赖)判定边界,优先复用已有模块。 +category: software-development +tags: [module, architecture, boundary, partitioning, design, requirement] +trigger_conditions: + - 需求分析/设计阶段要把功能清单划分成模块 + - 复核或重做已有模块划分,判断模块边界是否合理 + - 判断某个功能该归入哪个模块、是否该独立成模块 + - 模块拆分过细(1~2表一模块)或过粗(巨型模块)需要重新归并 +related_skills: [function-point-counting, feature-granularity-and-testing, module-development-spec, web-application-spec] +--- + +# 模块划分(八原则 + 四张图) + +把「功能清单」归并成「模块清单」的判定方法。模块 = 一个可独立开发/复用/部署挂载的业务能力单元 +(Host-Agnostic Python 包,见 module-development-spec;不独立部署,挂在应用伞下)。 + +**铁律(用户强调)**: +1. **模块划分面向概念聚合,禁止 1~2 张表就切一个模块**——按业务能力聚合,不按表/页面/CRUD 机械切。 +2. **能用已有模块实现的功能,必须用已有模块**,不重复造(基础模块 apppublic/sqlor/ahserver/ + accounting/appbase/rbac,以及平台已有业务模块)。先查已有模块清单再划分。 +3. 模块划分是**架构决策**:requirement 阶段出初步划分(八原则+四张图),design 阶段复核+细化。 +4. 产出必须含:模块清单 + 每模块的业务能力/边界/唯一责任 + 模块间依赖 + 开发顺序(拓扑序)。 + +## 输入与输出 + +- **输入**:功能清单(来自 function-point-counting 的功能明细表,或 propose_feature 落库的 sd_features)。 +- **输出**:`modules/{模块名}.md` 清单(功能/仓库/依赖/开发顺序/关联应用)+ architecture.md 的模块划分章节 + (落点见 sdlc-repo-standard / project-directory-spec)。 + +## 工作流(六步,先画图后切块) + +### 第 1 步:列功能清单并标注业务对象 +逐条功能问「它操作/产生哪个核心业务对象」(如 订单、工单、发票、人员、世界快照)。 +一个功能可能涉及多个对象,全列出。这是四张图的原料。 + +### 第 2 步:画四张图(判边界的唯一客观依据,详见 references/diagrams-guide.md) + +| 图 | 画什么 | 读出什么边界信号 | +|---|---|---| +| ① 业务对象图 | 核心业务对象 + 对象间关系(1:1/1:N/聚合/引用) | 强聚合(组合/父子)的对象**同模块**;仅引用(外键/ID)的对象**可分属不同模块** | +| ② 业务生命周期图 | 每个核心对象的状态机(状态+迁移+触发者) | 共享同一状态机/状态流转紧密耦合的功能**同模块**;生命周期各自独立的**可拆** | +| ③ 数据所有权图 | 每张表/数据「谁创建、谁写、谁读、谁是权威源」 | **所有权一致**(同一主体全权 CRUD)的数据归**同模块**;跨主体读写=耦合点,需接口而非共表 | +| ④ 业务依赖图 | 功能/对象间的调用与数据依赖(有向) | 依赖**单向且稀疏**=好边界;**双向/环状**依赖=切错了,需重新归并或抽接口 | + +### 第 3 步:按四张图聚出候选模块 +- 把「业务对象图里强聚合 + 生命周期共享 + 数据所有权一致」的功能聚成一个候选模块。 +- 在「业务依赖图」上检查:候选模块之间应尽量单向依赖、无环。有环 → 合并环上模块或抽出共享接口。 + +### 第 4 步:八原则逐条校验每个候选模块(机械判定,见下) + +### 第 5 步:复用判定——能用已有模块的,删掉候选、改为「引用已有模块」 +对照平台已有模块清单(基础模块 + 已上线业务模块)。候选模块的能力若已有模块覆盖 → +不新建,在 architecture.md 写明「复用 {已有模块},通过 load_{module}() 挂载 / API 调用」。 + +### 第 6 步:定依赖与开发顺序 +- 模块间依赖画成有向图,求拓扑序:被依赖的先开发。 +- 基础模块/已复用模块不列为待开发。 +- 一个模块 = 一个 develop 任务(PM 据此派发,见 task 技能)。 + +## 八原则(逐条机械判定,命中反例即重划) + +**A. 一个模块代表一个「业务能力」** +- 判定:能否用一句「动词+业务宾语」概括模块职责(如「管理工单全生命周期」「计算并落账消费」)? +- 反例:职责描述需要「和/以及/还有」连接多个不相关能力 → 拆分。 +- 反例:模块名是技术词(utils/common/base/helper)而非业务词 → 多半违反 G。 + +**B. 明确的业务边界** +- 判定:模块的输入/输出/触发场景能否清晰列举?边界外的事它一概不管? +- 反例:说不清「什么不属于这个模块」→ 边界模糊,重划。 + +**C. 高内聚,低耦合** +- 内聚判定:模块内功能是否都围绕同一业务能力/同一组核心对象(看业务对象图+数据所有权图)? +- 耦合判定:模块间依赖是否少而单向(看业务依赖图)?是否靠共享数据库表直接读写对方数据(强耦合,禁止)? +- 反例:模块内功能各干各的(低内聚);两模块互相直接读写对方的表(高耦合)→ 重划或抽接口。 + +**D. 能独立完成一个业务闭环** +- 判定:模块单独存在能否完成一个完整业务动作(输入→处理→产出/落库),不依赖另一个模块才能跑通主流程? +- 反例:A 模块的每个功能都必须先调 B 模块才能产生任何业务结果 → A、B 应合并。 +- 注意:闭环≠孤立。允许通过**接口**依赖其他模块(如调记账模块落账),但主业务逻辑自洽。 + +**E. 生命周期相对独立** +- 判定:模块能否独立地新增/修改/废弃,而不强制牵动其他模块同步改?版本/演进节奏是否独立? +- 反例:改 A 必须同时改 B、C 才能编译/运行(非接口耦合)→ 生命周期绑死,应合并或解耦。 + +**F. 明确的「唯一责任」** +- 判定:每类业务数据/每个核心能力,是否**有且仅有一个**模块对其负责(创建+维护+权威源)? +- 反例:两个模块都能写同一张核心表 / 都声称负责「用户管理」→ 责任重叠,合并或明确分工。 +- 与数据所有权图交叉验证:一份数据只有一个 owner 模块。 + +**G. 不要把「基础设施」误认为业务模块** +- 基础设施 = 与具体业务无关、被各业务模块共用的技术能力:数据库访问、HTTP 框架、认证鉴权、 + 日志、缓存、文件存储、ID 生成、加解密、消息队列。 +- 判定:去掉具体业务场景,这个能力是否依然成立且被多方复用?是 → 基础设施,**不是业务模块**。 +- 处置:基础设施用平台已有基础模块(apppublic/sqlor/ahserver/appbase/rbac/accounting), + **不要为它新建业务模块**,更不要把它和业务功能混进同一个业务模块。 +- 反例:建一个「数据库模块」「工具模块」「公共模块」当业务模块开发 → 违反 G。 + +**H. 共享能力要「稳定后」再抽象** +- 判定:两个以上模块出现的相似逻辑,是否已**稳定**(接口/语义不再频繁变)? +- 稳定 → 抽象成共享能力(基础模块或独立共享模块)。 +- 未稳定(还在快速变、各处需求不一致)→ **先各自实现,不要过早抽象**(过早抽象=错误抽象, + 日后改不动)。记录为「候选共享能力,待稳定后抽取」,不在本期强行合并。 +- 反例:第一期就把两个还在变的功能抽成「通用 XX 服务」,结果两边需求一分叉就得加一堆参数 → 违反 H。 + +**I. 用「四张图」判断模块边界** +- 见第 2 步。四张图是 A~H 的客观证据来源:边界争议回到图上找答案,不靠主观感觉。 +- 任何模块划分结论,都要能指出「依据哪张图的哪个信号」。 + +## 模块粒度(防过细/过粗) + +- **过细信号**:一个模块只有 1~2 张表、只有一个 CRUD、职责一句话说不满 → 合并进相邻同业务能力模块。 +- **过粗信号**:一个模块覆盖多个不相关业务对象、职责要「和/以及」连接、内部能拆出多个独立闭环 → 拆分。 +- **合适粒度**:一个模块 = 一个业务能力 = 一组强聚合业务对象 + 其完整生命周期 + 一致的数据所有权。 + +## 复用已有模块(铁律 2 的落地) + +划分前必须先拿到「已有模块清单」: +- 基础模块(不重复开发):apppublic、sqlor、ahserver、accounting、appbase、rbac。 +- 平台已有业务模块:查目标应用 pkgs/ 下已挂载模块 + 平台模块文档。 +- 判定:候选模块能力 ⊆ 已有模块能力 → 复用(load_{module}() 挂载 / HTTP API 调用),不新建。 +- 部分重叠 → 复用已有 + 新模块只做增量,通过接口对接,禁止 fork 已有模块代码。 + +## 输出模板(architecture.md 模块划分章节 + modules/{模块名}.md) + +architecture.md 写: +1. 四张图(业务对象/生命周期/数据所有权/业务依赖,文字或 mermaid)。 +2. 模块清单表:模块名 | 业务能力(A) | 唯一责任(F) | 核心对象 | 依赖模块 | 开发顺序 | 复用/新建。 +3. 复用判定:哪些能力复用已有模块、如何挂载。 +4. 模块依赖图 + 拓扑开发顺序。 + +modules/{模块名}.md 写(格式见 sdlc-repo-standard):功能/仓库/技术栈/状态/依赖模块/开发顺序/关联应用。 + +## 反模式速查(命中即重划) + +| 反模式 | 违反原则 | 修法 | +|---|---|---| +| 1~2 张表切一个模块 | A/D/粒度 | 按业务能力聚合 | +| 建「数据库/工具/公共」业务模块 | G | 用基础模块,不新建 | +| 两模块共写一张核心表 | C/F | 定唯一 owner,另一方走接口 | +| A、B 互相直接读写对方数据 | C/E | 抽接口,单向依赖 | +| 模块间依赖成环 | C/I(依赖图) | 合并环上模块或抽共享接口 | +| 第一期就抽「通用XX服务」 | H | 待稳定再抽,先各自实现 | +| 已有模块能实现却新建 | 铁律2 | 复用 load_{module}()/API | +| 巨型模块覆盖多业务 | A/B/粒度 | 按业务对象拆 | diff --git a/skills_library/all/module-partitioning/references/diagrams-guide.md b/skills_library/all/module-partitioning/references/diagrams-guide.md new file mode 100644 index 0000000..a8d1cd9 --- /dev/null +++ b/skills_library/all/module-partitioning/references/diagrams-guide.md @@ -0,0 +1,99 @@ +# 四张图绘制指南(模块边界判定的客观依据) + +四张图是模块划分的**证据层**:任何「这两个功能该不该同模块」的争议,回到图上找信号, +不靠主观感觉。文字描述即可(必要时 mermaid),关键是**信号读法**。 + +## ① 业务对象图 + +**画什么**:系统全部核心业务对象(名词:订单/工单/客户/发票/人员/快照…),对象间关系及类型。 + +**关系类型(决定聚合强度)**: +- 组合/父子(强聚合):A 由 B 组成,B 离开 A 无意义。如 工单—工单消息、订单—订单行。 +- 关联(中):A 引用 B,两者各有生命周期。如 工单→受理人、订单→客户。 +- 仅引用(弱):A 只存 B 的 ID 做查询过滤。如 业务流水→机构ID。 + +**怎么画(文字模板)**: +``` +对象: 工单 + ├─组合─ 工单消息(离开工单无意义) + ├─组合─ 转派流水(append-only,工单专属) + ├─关联─ 客户(提单人,独立生命周期) + └─引用─ 机构ID(仅过滤) +``` + +**边界信号**:组合关系的对象**必须同模块**(拆开=一个业务闭环被劈两半); +仅引用的对象**分属不同模块没问题**。 + +## ② 业务生命周期图 + +**画什么**:每个核心对象的状态机——状态清单、迁移事件、触发者(角色/系统)。 + +**怎么画(文字模板)**: +``` +工单: new →(agent认领) agent_processing →(回复) agent_replied + →(客户确认) closed / →(追问超限) human_pending →(认领) human_processing + →(客服回复) staff_replied →(客户确认) closed +触发者: 客户(建单/确认/追问)、agent(自动答复)、运维(认领/回复/转派) +``` + +**边界信号**: +- 操作**同一状态机**的功能(建单/追问/确认/认领/转派)→ 同模块(状态机是模块的内聚核)。 +- 两个对象的状态机**互相触发迁移**(A 到某态必须改 B 的态)→ 强耦合,优先考虑同模块; + 确实要拆则必须走接口/事件,禁止跨模块直改对方状态列。 +- 生命周期完全独立、互不触发 → 可分属不同模块(原则 E 的证据)。 + +## ③ 数据所有权图 + +**画什么**:每张表(或每组逻辑数据)的 CRUD 归属——谁创建(C)、谁更新(U)、谁读(R)、谁是权威源。 + +**怎么画(表格模板)**: +| 表/数据 | 创建者 | 更新者 | 读取者 | 权威源(owner) | +|---|---|---|---|---| +| tk_tickets | ticket模块 | ticket模块 | ticket/报表 | ticket模块 | +| users | rbac | rbac | 全部模块(只读) | rbac | +| 余额流水 | accounting | accounting | 业务模块(只读) | accounting | + +**边界信号**: +- 一张表有且仅有一个 owner 模块(原则 F 唯一责任的直接证据)。 +- **两个模块都写同一张表 = 边界切错**:要么合并模块,要么把写权收归 owner、另一方走接口。 +- 「读取者=全部模块」的表是基础设施数据(users/权限/参数),owner 是基础模块,业务模块只读—— + 这也验证原则 G(别为它建业务模块)。 + +## ④ 业务依赖图 + +**画什么**:模块/候选模块间的调用与数据依赖,有向边 A→B 表示「A 的业务过程需要 B 的能力/数据」。 + +**怎么画(文字模板)**: +``` +工单模块 → rag模块(检索知识库) [单向,接口调用] +工单模块 → pipeline-service(待办注册) [单向,provider机制] +记账模块 → 产品模块(取定价) [单向] +产品模块 → 记账模块(?) [若存在=环,必须消除] +``` + +**边界信号**: +- **无环 + 稀疏**(每个模块出边≤3 条左右)= 边界健康。 +- **环状依赖(A→B 且 B→A)= 边界切错**:合并环上模块,或抽出共享接口/事件把环打断。 +- 依赖边标注**实现方式**(接口调用/事件/只读数据)——凡是「直接读写对方数据库表」的边都是 + 坏味道(原则 C 高耦合证据),改为接口。 +- 依赖图直接给出**开发顺序拓扑序**:无入边的先开发(基础/被依赖模块),依赖别人的后开发。 + +## 四张图 → 模块划分的推导顺序 + +1. ①②定「聚合核」:强聚合对象+共享状态机 = 候选模块的内核。 +2. ③定「唯一责任」:每个候选模块核对数据所有权,冲突即调整边界。 +3. ④定「模块间关系」:依赖成环→回调 1/2 重新聚合;无环→拓扑序=开发顺序。 +4. 最后过八原则 A~H 逐条校验(I 就是本指南)。 + +## 迷你示例(工单系统的正确推导) + +功能清单:建单/agent自动答复/追问/转人工/认领/客服回复/转派/客户确认关闭/附件上传下载/ +工单知识库沉淀/用户登录/权限校验/文件存储。 + +- ①:工单—消息—转派流水 组合;附件挂在消息上(组合)。 +- ②:全部工单功能操作同一状态机(new→…→closed)。 +- ③:tk_* 三表 owner 唯一;users/permission 是 rbac 的;files 是文件存储的。 +- ④:工单→rag(检索/沉淀,接口)、工单→待办中枢(provider)、工单→文件存储(webpath)。 +- 结论:**一个 ticket 业务模块**(建单~关闭全生命周期+附件+知识库沉淀); + 登录/权限/文件存储是基础设施→复用 rbac/filemgr 基础能力(原则 G),**不建模块**; + rag 检索是已有模块→接口复用(铁律2)。 diff --git a/skills_library/all/sdlc-repo-standard/SKILL.md b/skills_library/all/sdlc-repo-standard/SKILL.md index e35b0f6..2740218 100644 --- a/skills_library/all/sdlc-repo-standard/SKILL.md +++ b/skills_library/all/sdlc-repo-standard/SKILL.md @@ -54,17 +54,31 @@ projects/{项目名}/docs/01-design/modules/{模块名}/ - 完成后用 `deliver` 交付,`files` 列出所有产出文件路径——这是 QC/PM 核验「实际产出」的依据,别只写文档不列文件 - git 提交由 PM 审核通过后系统统一执行,角色无需自己提交(develop 例外:模块/应用仓库本地 commit 是 QC 核验的硬证据,见下) +- **复杂度评估(所有角色必附,2026-09-14 起)**:每个任务开工先自评复杂度,deliver 时必须在 + summary 或交付文档末尾附「复杂度评估」段—— + 1. **判定**:本任务及后续派生工作是否复杂。复杂信号:涉及多个模块/应用、多个独立交付单元、 + 工作量超单 agent 一次产出(预估 >1 个聚焦交付件)、存在可并行的独立子工作。 + 2. **简单** → 写明「复杂度评估:简单,单交付单元,无需拆分」。 + 3. **复杂** → 给出**建议拆分方案**:子任务清单(每条 title/role/description/依赖关系, + 能并行的标并行、有依赖的标 depends_on 前序),供 PM 编排派发。 + 4. **执行中发现任务过大** → 立即用 ask_question/raise_problem 上报 PM 请求拆分, + 禁止硬撑巨型任务导致探索死循环(30 轮耗尽无产出)。 + - 编排决策权在 PM(create_tasks/create_sub_tasks),角色只提供评估+建议,不越权派发。 ## 各角色产出内容(落点路径见 project-directory-spec) ### requirement(需求分析师) - **内容**: 项目概述、用户角色及权限、功能列表(含验收标准)、非功能需求、业务流程 +- **功能清单 + IFPUG 功能点计算**: 按 `function-point-counting` 技能产出 `docs/00-requirement/fp-report.md`(功能明细/汇总 UFP/待确认/假设 四件套,fp_calc.py 规则引擎计算,禁 LLM 心算) +- **模块初步划分**: 按 `module-partitioning` 技能(八原则+四张图)产出 `docs/00-requirement/module-partition.md`(四张图 + 模块清单 + 复用判定 + 开发顺序拓扑);能用已有模块的必须复用已有模块,禁止 1~2 表一模块 - **不划分 app**: 一个项目有几个 app(应用)是架构决策,由 design 阶段设计师根据需求分析划分——requirement 只描述功能、不定 app 数量、不写 `{应用名}_spec.json` -- **不划分模块**: 模块划分是架构决策,由 design 阶段设计师完成 +- **小功能点落库**: 按 `feature-granularity-and-testing` 粒度用 propose_feature 落库 sd_features(测试/验收锚点,与 IFPUG 规模度量是两套口径都要产出) ### design(系统设计师) +- **模块划分复核+细化**: 以 requirement 的 module-partition.md 为上游,按 `module-partitioning` 八原则+四张图复核细化(调整必须写明依据,禁止无证据推翻),落定模块间接口契约 + 依赖图 + 开发顺序 +- **功能细化**: 把需求功能点细化到模块内可开发规格(页面交互/数据表归属/CRUD/接口契约),产出功能点→模块→接口三级追溯表,覆盖核对无遗漏 - **应用划分**: 根据需求分析划分一个项目有几个 app(应用)——需求只描述功能、不定 app 数量,设计师按「部署单元 / 功能聚合 / 用户边界」划到 N 个 app(每个 app = 一个入口一个端口),产出对应的 `{应用名}_spec.json` -- **应用级**: `architecture.md`(系统架构、模块划分、模块间依赖、开发顺序)+ `ui-design.md`(视觉风格/主页面/交互模式/弹窗规范) +- **应用级**: `architecture.md`(系统架构、模块划分复核结论、模块间依赖、开发顺序)+ `ui-design.md`(视觉风格/主页面/交互模式/弹窗规范) - **模块级**: 每个模块在 `projects/{项目名}/docs/01-design/modules/{模块名}/` 下产出 design.md(数据设计/CRUD/处理逻辑)+ skill/SKILL.md - **更新**: `docs/01-design/modules/` 下各模块的技术栈、依赖关系、开发顺序 diff --git a/skills_library/pipelines/sdlc_general/common/task/SKILL.md b/skills_library/pipelines/sdlc_general/common/task/SKILL.md index 35b56e5..44ea30d 100644 --- a/skills_library/pipelines/sdlc_general/common/task/SKILL.md +++ b/skills_library/pipelines/sdlc_general/common/task/SKILL.md @@ -88,7 +88,7 @@ submitted ──claim──▶ running ──submit──▶ review ──approv PM 派发任务时先评估复杂度,复杂任务自动分解并编排执行顺序(能并行并行、不能并行串行),同时记录父子关系。 1. **先评估**:判断当前任务是否「过于复杂」(涉及多个模块/应用、多个独立交付单元、工作量超单 agent 一次产出)。简单任务直接派发单个任务,不强行拆分。 -2. **模块化拆分原则(design 阶段定模块,PM 按模块派发)**:模块划分由 design 阶段的设计师完成(架构能力更强)——概念相近的功能组合成一个独立模块,每个模块独立设置仓库,归入应用伞仓库(pkgs/<模块>),并在模块定义里写明模块间依赖关系 + 开发顺序。PM 派发 develop 任务时按设计师划分好的模块清单:一个模块 = 一个 develop 任务;按模块间依赖编排(无依赖并行、有依赖串行)。基础模块(apppublic、sqlor、ahserver、accounting、appbase、rbac 等)已存在、可直接引用,不派发「重新开发基础模块」的任务。 +2. **模块化拆分原则(requirement 初划,design 定稿,PM 按模块派发)**:模块划分在 requirement 阶段按 `module-partitioning` 技能(八原则+四张图)初步完成(产出 module-partition.md),design 阶段复核+细化+定稿(模块清单/依赖/开发顺序,调整须写明依据)——概念相近的功能组合成一个独立模块,每个模块独立设置仓库,归入应用伞仓库(pkgs/<模块>),并在模块定义里写明模块间依赖关系 + 开发顺序。PM 派发 develop 任务时按设计定稿的模块清单:一个模块 = 一个 develop 任务;按模块间依赖编排(无依赖并行、有依赖串行)。基础模块(apppublic、sqlor、ahserver、accounting、appbase、rbac 等)已存在、可直接引用,不派发「重新开发基础模块」的任务。 3. **任务粒度控制(巨型任务拆小)**:单个任务必须聚焦单一交付单元,禁止派发「一次性实现全部 N 个模块 / 全部表契约 / 脚手架 + DDL 全套」这种巨型任务——任务过大时 agent 会因工作量大、方向迷失而陷入探索死循环(反复 read_file/run_shell 却不 write_file/deliver,30 轮耗尽无产出)。按模块/单元拆成多个小任务(每个模块一个 develop 子任务),能并行就并行(不填 depends_on),有依赖就串行(depends_on)。 4. **自动分解**:复杂任务 → 拆成多个子任务,每个子任务含 title、role、description;用 `create_tasks` 一次批量派发。子任务默认挂当前里程碑任务名下(`parent_id` 由系统自动记录),任务树(/task)据此分层显示。 5. **自动编排**: diff --git a/skills_library/pipelines/sdlc_general/roles/agent.design/role/SKILL.md b/skills_library/pipelines/sdlc_general/roles/agent.design/role/SKILL.md index 51864b2..86e0224 100644 --- a/skills_library/pipelines/sdlc_general/roles/agent.design/role/SKILL.md +++ b/skills_library/pipelines/sdlc_general/roles/agent.design/role/SKILL.md @@ -1,22 +1,50 @@ --- name: role -description: 系统设计师角色定义。接到「应用架构」或「模块级设计」任务时先 load_skill 加载本技能——本技能规定该加载哪个规范:project-directory-spec(目录落点)、web-application-spec(应用=唯一部署单元一入口一端口)、module-development-spec(模块不独立部署)、database-design/database-table-definition-spec(库设计)。不先加载会把单体设计成多服务、把模块设计成带 app.py 的应用。 +description: 系统设计师角色定义。接到「应用架构」或「模块级设计」任务时先 load_skill 加载本技能——本技能规定:复核+细化 requirement 阶段的模块划分(module-partitioning 八原则+四张图)、功能细化(功能点→模块内接口/数据/交互细化)、应用(app部署单元)划分、模块级详细设计。该加载哪个规范:project-directory-spec(目录落点)、web-application-spec(应用=唯一部署单元一入口一端口)、module-development-spec(模块不独立部署)、database-design/database-table-definition-spec(库设计)。不先加载会把单体设计成多服务、把模块设计成带 app.py 的应用、推翻需求阶段的模块划分重造。 capability: task_capability --- # 系统设计师(design)角色定义 ## 职责 -- 应用级设计:architecture.md(架构、模块划分、模块间依赖、开发顺序)+ ui-design.md(视觉风格/布局/交互模式) -- **应用划分**:一个项目有几个 app(应用),由设计师根据需求分析来设计/划分——需求只描述功能、不限定 app 数量;设计师按「部署单元 / 功能聚合 / 用户边界」把需求功能划到 N 个 app(每个 app = 一个入口一个端口),在 architecture.md 里写明 app 清单与划分理由,并产出对应的 {应用名}_spec.json -- 模块级设计:每个模块的 modules/{模块名}.md + design.md + skill/SKILL.md -- 模块划分 + 模块间依赖关系 + 开发顺序由设计师完成,PM 按此派发 develop 任务 -- 基础模块(apppublic/sqlor/ahserver/accounting/appbase/rbac)已存在,不列为待开发模块 + +### 1. 模块划分复核 + 细化(上游是 requirement 的 module-partition.md,不推翻重造) +- **先 load_skill 加载 `module-partitioning` 全文**,用它复核需求阶段的初步模块划分: + - 读 `projects/{项目名}/docs/00-requirement/module-partition.md`(四张图+模块清单+复用判定)。 + - 八原则 A~I 逐条复核 + 四张图补全细化(需求阶段画不全的依赖边/所有权在设计期落定)。 + - **调整必须写明理由**(哪条原则/哪张图的哪个信号),禁止无证据推翻需求阶段划分; + 发现划分根本性错误(如环依赖、责任重叠)→ 修正并在 architecture.md 记录变更对照。 +- 细化产出:模块间依赖图(有向无环)+ 开发顺序拓扑序 + 每模块的接口契约草案 + (模块对外暴露什么、依赖谁的什么)。PM 按此派发 develop 任务(一个模块=一个任务)。 +- 复用判定复核:requirement 标注的「复用已有模块」逐个核实真实存在且能力覆盖; + 基础模块(apppublic/sqlor/ahserver/accounting/appbase/rbac)已存在,不列为待开发模块。 + +### 2. 功能细化(需求功能点 → 模块内可开发规格) +- 输入:requirement 的功能清单(fp-report.md 功能明细 + list_features 落库的小功能点)。 +- 把每个功能点细化到模块内实现规格:页面/交互(ui-design.md)、数据表归属、CRUD 定义、 + 处理逻辑(接口契约:入参/出参/错误分支)、功能点→模块→接口三级追溯表。 +- **覆盖核对**:每个需求功能点必须落到某个模块的某个接口/页面,无遗漏; + 新增的镀金功能(需求没有的)必须写明理由,否则删除。 +- 功能细化不改需求口径:发现需求矛盾/缺口 → 冒泡 ask_question,不自行改需求。 + +### 3. 应用划分(app 部署单元,design 专属职责) +- 一个项目有几个 app(应用),由设计师划分——按「部署单元 / 功能聚合 / 用户边界」把模块 + 归到 N 个 app(每个 app = 一个入口一个端口),architecture.md 写明 app 清单与划分理由, + 产出对应的 {应用名}_spec.json(referenced_modules / generated_modules)。 + +### 4. 模块级详细设计 +- 每个模块产出 modules/{模块名}.md + modules/{模块名}/design.md + skill/SKILL.md + (数据设计 DDL/CRUD/处理逻辑,格式见 sdlc-repo-standard 的 templates)。 + +### 5. 交付必附复杂度评估(所有角色统一约定,见 sdlc-repo-standard) +- deliver 时附「复杂度评估」段:后续 develop 工作是否需拆分 + 建议的任务编排 + (每模块一个任务、依赖串并行关系)。编排决策权在 PM。 ## 应遵守的规范(设计前先 load_skill 加载对应全文,不要凭记忆瞎写) -- `project-directory-spec`:机构工作空间结构(projects/apps/modules)+ 设计文档落点路径(projects/{项目}/docs/01-design/)+ 应用与模块的关系(应用=唯一部署单元,模块不独立部署;app 划分见职责「应用划分」) +- `module-partitioning`:模块划分八原则+四张图(复核/细化 requirement 划分的判定依据) +- `project-directory-spec`:工作空间结构 + 设计文档落点路径 + 应用与模块的关系(应用=唯一部署单元,模块不独立部署) - `sdlc-repo-standard`:设计交付件的内容格式(templates/module-design.md、templates/module-skill.md) - `web-application-spec`:应用规范(应用结构、应用如何通过 load_{module}() 导入模块、一个入口一个端口) - `module-development-spec`:模块规范(模块是 Host-Agnostic Python 包、不是独立部署单元,无独立 app.py/端口) -- `database-design`:数据库设计规范(字段语义→类型映射、系统不加外键、编码字典设计,设计阶段产出时遵守) +- `database-design`:数据库设计规范(字段语义→类型映射、系统不加外键、编码字典设计) - `database-table-definition-spec`:表定义四段式格式 diff --git a/skills_library/pipelines/sdlc_general/roles/agent.qc/review-design/SKILL.md b/skills_library/pipelines/sdlc_general/roles/agent.qc/review-design/SKILL.md index 4719ecb..9ebb6d9 100644 --- a/skills_library/pipelines/sdlc_general/roles/agent.qc/review-design/SKILL.md +++ b/skills_library/pipelines/sdlc_general/roles/agent.qc/review-design/SKILL.md @@ -34,24 +34,31 @@ capability: task_capability ## B 组:设计专家维度 -6. **应用/模块划分**(对照技能映射表加载): +6. **模块划分复核+细化**(对照技能映射表加载 `module-partitioning`): + - **上游衔接**:design 的模块划分以 requirement 的 `docs/00-requirement/module-partition.md` 为上游。核对 architecture.md 有「复核结论」——沿用或调整;**每处调整必须写明依据**(八原则哪条/四张图哪个信号)。无证据推翻需求阶段划分 = 不过;完全没提 module-partition.md(凭空重划)= 不过。 + - 八原则抽查:模块清单逐条能对应业务能力(A)、唯一责任(F);无 1~2 表过细模块、无巨型模块;基础设施未当业务模块(G);标注复用的已有模块真实存在(铁律:能用已有模块必须用)。 + - 模块间依赖图无环 + 开发顺序拓扑可行(依赖在前)。 +7. **功能细化覆盖**: + - 有「功能点→模块→接口」三级追溯表(或等价映射),每个需求功能点(list_features + fp-report 明细)落到某模块某接口/页面,无遗漏。 + - 新增镀金功能(需求没有的)有书面理由,无理由 = 不过。 +8. **应用/模块划分**(对照技能映射表加载): - 应用是唯一部署单元:一个应用 = 一个入口(app/{应用名}.py)= 一个端口;architecture.md 写明 app 清单 + 单体/多应用划分理由。把功能模块设计成独立服务/微服务/独立端口 → 不过。 - 模块是应用内 Python 包,无独立 app.py / 端口 / Dockerfile。 -7. **数据库设计**(对照技能映射表加载): +9. **数据库设计**(对照技能映射表加载): - 字段语义→抽象类型映射正确(名称 str 255、金额 double 18/2、状态 str 16、业务日期 date) - 禁原生类型 varchar/bigint/boolean/int(11) - 表间无外键,关联靠字段存 id + codes 段声明 - 枚举字段进编码字典(appcodes/appcodes_kv,init/data.json 定义) - 表定义四段式(summary/fields/indexes/codes) -8. **架构合理性逐项**(把主观判断转成「有无论证」的机械核对): - - 模块间依赖方向无环、开发顺序可行(依赖在前、被依赖在后) +10. **架构合理性逐项**(把主观判断转成「有无论证」的机械核对): - 设计说明写明**预期数据量/并发量及对应选型理由**——写不出规模假设 = 不过(无论证的架构选型不采信) - 无微服务化倾向(「每模块一个端口/容器」类设计 = 不过) ## C 组:合规项 -9. **文档落点**:architecture.md / ui-design.md / modules/{模块}.md + {模块}/design.md 齐全(对照 project-directory-spec)。 -10. **模块清单明确**:模块划分 + 模块间依赖 + 开发顺序明确(PM 据此派发 develop 任务);基础模块(apppublic/sqlor/ahserver/accounting/appbase/rbac)不列为待开发模块。 +11. **文档落点**:architecture.md / ui-design.md / modules/{模块}.md + {模块}/design.md 齐全(对照 project-directory-spec)。 +12. **模块清单明确**:模块划分 + 模块间依赖 + 开发顺序明确(PM 据此派发 develop 任务);基础模块(apppublic/sqlor/ahserver/accounting/appbase/rbac)不列为待开发模块。 +13. **复杂度评估已附**:交付件有「复杂度评估」段(简单写明无需拆分 / 复杂给出建议拆分方案:每模块一个 develop 任务+依赖编排)。缺失 = 不过。 ## 技能映射表(按核对内容必载,不凭记忆) diff --git a/skills_library/pipelines/sdlc_general/roles/agent.qc/review-requirement/SKILL.md b/skills_library/pipelines/sdlc_general/roles/agent.qc/review-requirement/SKILL.md index 4293cfc..8e3d110 100644 --- a/skills_library/pipelines/sdlc_general/roles/agent.qc/review-requirement/SKILL.md +++ b/skills_library/pipelines/sdlc_general/roles/agent.qc/review-requirement/SKILL.md @@ -19,7 +19,7 @@ capability: task_capability ## 必读文件 - 原始需求:`projects/{项目}/docs/00-requirement/requirement-spec.md`(需求规格说明书)+ 需求采集任务的原始输入(任务描述/用户上传材料) -- 需求分析交付件:`projects/{项目}/docs/00-requirement/` 下分析产出(需求细化/功能化描述) +- 需求分析交付件:`projects/{项目}/docs/00-requirement/` 下分析产出(fp-report.md 功能点报告、module-partition.md 模块初步划分、需求细化/功能化描述) - 路径权威来源:先 load_skill 加载 `project-directory-spec`,不要凭记忆找路径 ## A 组:原始需求逐条契合(主体核对项) @@ -35,9 +35,23 @@ capability: task_capability ## B 组:合规项 4. **功能清单真实落库**:用 `list_features` 查 sd_features——应 ≥1 条记录(状态 proposed 或之后),且功能点覆盖全部业务域(如三大业务域都要有对应 feature)。只在文档里写了、库里 0 条 → 不过。 -5. **文档落点**:需求文档在 `project-directory-spec` 规定的路径(对照技能,不凭记忆)。 -6. **部署环境需求明确**:测试/生产环境的资源规格、依赖服务、端口、环境变量、高可用、备份、监控告警是否写清。空泛写「按标准配置」= 不过。 -7. **无越权划分**:requirement 阶段不划分 app、不产出 apps/{应用名}.md(app 划分是 design 职责)。越权 → 不过。 +5. **IFPUG 功能点计算真实产出**:`docs/00-requirement/fp-report.md` 存在,且含四件套(功能明细表带 DET/RET/FTR/复杂度/FP/证据、UFP 汇总、待确认清单、计算假设)。核对项: + - 明细表每行有 evidence(需求章节/原文摘要)与 calc_basis(档位→复杂度→权重)——无证据行 = 不过。 + - **必须过规则引擎**:报告里的复杂度/FP 应与 `function-point-counting` 的权重矩阵一致(抽查 2~3 行按矩阵复核)。明显是 LLM 心算(复杂度与 DET/FTR 档位对不上、UFP 加总不等于各行 FP 之和)→ 不过。 + - 需求含糊处已进待确认清单而非猜数(抽查有无「低置信度却给了数」)。 +6. **模块初步划分真实产出**:`docs/00-requirement/module-partition.md` 存在,且: + - **四张图齐全**(业务对象/业务生命周期/数据所有权/业务依赖)——缺任一张 = 不过。 + - 模块清单表每模块写明业务能力(一句话动词+宾语)、唯一责任、核心对象、依赖、开发顺序、复用or新建。 + - **粒度铁律核对**:无「1~2 张表一个模块」(对照数据所有权图,一个模块只有 1~2 张表且职责说不满 = 过细,不过);无巨型模块(一个模块覆盖多个不相关业务对象 = 不过)。 + - **复用判定核对**:标注复用的已有模块真实存在(基础模块 apppublic/sqlor/ahserver/accounting/appbase/rbac 或平台已上线业务模块);能力已有模块覆盖却新建 = 不过。 + - **基础设施误判核对**:无「数据库模块/工具模块/公共模块」当业务模块(违反原则 G)= 不过。 + - 依赖图无环(有环且未说明如何消除 = 不过)。 + - 判定依据先 load_skill 加载 `module-partitioning` 全文,逐条对照八原则,不凭记忆。 +7. **文档落点**:需求文档在 `project-directory-spec` 规定的路径(对照技能,不凭记忆)。 +8. **部署环境需求明确**:测试/生产环境的资源规格、依赖服务、端口、环境变量、高可用、备份、监控告警是否写清。空泛写「按标准配置」= 不过。 +9. **复杂度评估已附**:交付件(deliver summary 或文档末尾)有「复杂度评估」段——简单需写明「无需拆分」,复杂需给出建议拆分方案(子任务清单+依赖)。缺失 = 不过。 +10. **无越权划分**:requirement 阶段不划分 app、不产出 apps/{应用名}.md 或 {应用名}_spec.json(app 划分是 design 职责)。越权 → 不过。 + ⚠️ 模块**初步**划分是 requirement 的合法职责(module-partition.md),不算越权;design 阶段复核细化。 ## 真实性核查(所有核对项通用) diff --git a/skills_library/pipelines/sdlc_general/roles/agent.requirement/role/SKILL.md b/skills_library/pipelines/sdlc_general/roles/agent.requirement/role/SKILL.md index ae8eade..2976655 100644 --- a/skills_library/pipelines/sdlc_general/roles/agent.requirement/role/SKILL.md +++ b/skills_library/pipelines/sdlc_general/roles/agent.requirement/role/SKILL.md @@ -1,20 +1,64 @@ --- name: role -description: 需求分析师角色定义。接到需求分析任务时先 load_skill 加载本技能——本技能规定:拆需求提功能落库 sd_features、识别应用(部署单元)、落成 env/test.json+env/prod.json(部署信息单一事实源)、需求不明确的端口/主机/账号禁止编造(标注待明确或 ask_question 冒泡问)。不先加载会编造端口/子域名等具体值。 +description: 需求分析师角色定义。接到需求分析任务时先 load_skill 加载本技能——本技能规定:①功能清单编制+IFPUG功能点计算(function-point-counting技能+fp_calc.py规则引擎,禁LLM心算) ②模块初步划分(module-partitioning技能,八原则+四张图,优先复用已有模块) ③拆小功能点落库sd_features ④部署环境信息落env/*.json(禁止编造) ⑤交付必附复杂度评估。不先加载对应技能会凭记忆瞎写、编造端口、模块划分无依据。 capability: feature_propose_capability --- # 需求分析师(requirement)角色定义 -## 职责 -- **拆解需求提功能(落库,别只写文档)**:用 `propose_feature` 把需求拆解成功能点,落库 sd_features(状态 proposed),每个业务域都要有对应 feature。**功能点粒度按 `feature-granularity-and-testing` 技能**——必须是单次操作级小功能点(一个按钮/一个接口/一个后台逻辑单元),禁止模块级大功能清单;先 load_skill 加载该技能再拆 -- 产出需求规格说明书(requirement-spec.md)+ 需求评审记录(requirement-review.md) -- 不划分 app:一个项目有几个 app(应用)是 design 阶段的架构决策,requirement 只描述功能、不定 app 数量、不产出 apps/{应用名}.md 或 {应用名}_spec.json -- 明确部署环境需求,并**落成 `env/test.json` + `env/prod.json`**(工作空间根目录,集中保存主机/SSH/端口/DB/路径/域名,是部署信息的单一事实源,见 project-directory-spec)——部署信息只在这里一份,不散落到需求/设计/代码各处,改配置只改这里 -- 需求阶段不划分 app、不划分模块(app 划分和模块划分都是 design 阶段的架构决策) -- **需求不明确时禁止编造具体值**:端口、IP、域名、账号、资源规格等需求未给出或含糊的值,**不得自己编**(编造端口 9286/编造子域名等都是错的)。做法:① 在需求文档中该处标注「待明确」,并在文档末尾列出「需向用户确认的问题清单」;② 关键信息(如部署端口/环境)用 `ask_question` 冒泡问用户,暂停等答复。宁可标注待明确,不可编一个看似合理的值。 +## 职责(按序完成,产出落点见 project-directory-spec) + +### 1. 功能清单编制 + IFPUG 功能点计算(规模度量) +- **先 load_skill 加载 `function-point-counting` 全文**,按它的十步工作流做: + 读需求全文 → 定应用边界 → 列角色与外部系统 → 识别业务过程 → 判 ILF/EIF/EI/EO/EQ → + 去重 → 逐功能提 DET/RET/FTR + 证据 → 写 input.json → **跑 fp_calc.py 规则引擎算 FP**。 +- **铁律:LLM 只做语义识别,复杂度判定与 FP 加权必须跑规则引擎**,禁止心算 FP、禁止直接报总数。 +- 规则引擎用法(fp_calc.py 是纯 stdlib 脚本,环境无关): + 1. `load_skill(name='function-point-counting', file_path='scripts/fp_calc.py')` 取脚本全文; + 2. `write_file` 存到 `projects/{项目名}/docs/00-requirement/tools/fp_calc.py`; + 3. input.json 按技能里的 schema 写好,`run_shell` 执行 + `python3 .../tools/fp_calc.py input.json --json` 得复杂度与 FP。 +- 输出四件套(功能明细/汇总/待确认/假设)存 + `projects/{项目名}/docs/00-requirement/fp-report.md`。 +- 信息不足的功能**进待确认清单,不猜**(状态/原因/需要确认 三要素)。 +- 证据链:每个功能点带需求原文章节引用,无证据不入账。 + +### 2. 模块初步划分(八原则 + 四张图) +- **先 load_skill 加载 `module-partitioning` 全文**(含 references/diagrams-guide.md 四张图画法)。 +- 按六步工作流:功能标注业务对象 → 画四张图(业务对象/生命周期/数据所有权/业务依赖)→ + 聚候选模块 → **八原则 A~I 逐条机械校验** → **复用判定(能用已有模块必须用已有模块)** → + 定依赖与开发顺序(拓扑序)。 +- **粒度铁律:面向概念聚合,禁止 1~2 张表切一个模块**;基础设施(DB访问/认证/日志/文件存储等) + 不是业务模块,用平台基础模块(apppublic/sqlor/ahserver/appbase/rbac/accounting)。 +- 产出 `projects/{项目名}/docs/00-requirement/module-partition.md`: + 四张图 + 模块清单表(模块名/业务能力/唯一责任/核心对象/依赖/开发顺序/复用or新建)+ 复用判定 + 反模式自查表。 +- **这是初步划分**:design 阶段设计师会复核+细化+定 app(应用/部署单元划分仍归 design, + requirement 不划分 app、不写 {应用名}_spec.json)。 + +### 3. 拆小功能点落库(测试锚点) +- 用 `propose_feature` 把需求拆解成**操作级小功能点**落库 sd_features(status=proposed), + 每个业务域都要有对应 feature。**粒度按 `feature-granularity-and-testing` 技能**—— + 单次操作级(一个按钮/一个接口/一个后台逻辑单元),禁止模块级大功能清单;先 load_skill 再拆。 +- 用 `list_features` 核对落库完整性。 +- 与第 1 步的关系:IFPUG 功能点是**规模度量**(计价/工作量),小功能点是**验收锚点** + (测试用例/Bug/迭代 scope)——两套都要产出,口径不同不互替。 + +### 4. 需求规格说明书 + 部署环境 +- 产出 requirement-spec.md:项目概述、用户角色及权限、功能列表(含验收标准,引用 fp-report + 的功能明细)、非功能需求、业务流程、模块初步划分引用(module-partition.md)。 +- 部署环境需求落 `env/test.json` + `env/prod.json`(单一事实源,见 project-directory-spec 第八章)。 +- **需求不明确时禁止编造具体值**:端口/IP/域名/账号/资源规格未给出或含糊 → 标注「待明确」+ + 文末「需向用户确认的问题清单」;关键信息用 `ask_question` 冒泡问,暂停等答复。宁标注不编造。 + +### 5. 交付必附复杂度评估(所有角色统一约定,见 sdlc-repo-standard) +- deliver 的 summary 或交付文档末尾必须附「复杂度评估」段: + 本任务/后续工作是否复杂(多模块/多交付单元/超单 agent 一次产出)+ 建议拆分方案 + (子任务清单:title/role/依赖关系,能并行并行)。**编排决策权在 PM**,你只提供评估+建议。 ## 应遵守的规范(产出前先 load_skill 加载对应全文,不要凭记忆瞎写) -- `feature`:功能状态机规范(propose_feature 提功能的流转规则,读本 skill 判断合法性) -- `project-directory-spec`:机构工作空间结构(projects/apps/modules)+ 需求文档落点路径(projects/{项目}/docs/00-requirement/) -- `sdlc-repo-standard`:需求规格说明书的内容格式与产出行为准则 +- `function-point-counting`:IFPUG 功能点计算十步工作流 + fp_calc.py 规则引擎用法(职责1) +- `module-partitioning`:模块划分八原则 + 四张图 + 复用判定 + 反模式速查(职责2) +- `feature-granularity-and-testing`:小功能点粒度唯一正确口径(职责3) +- `feature`:功能状态机规范(propose_feature 流转规则) +- `project-directory-spec`:工作空间结构 + 交付件落点路径 + env/*.json 规范 +- `sdlc-repo-standard`:交付件内容格式 + 通用交付约定(含复杂度评估)