软件项目总控 -- 通用软件项目从需求到交付的总控流程

面向 API 服务、后台模块、插件、CLI 工具、数据处理脚本、自动化任务、中小型后端应用和非网站类功能项目。目标是在进入任务拆解前，先定义项目边界、架构方案、数据/API/集成、实现路径、验证、发布和沉淀，避免复杂需求直接落入零散代码生成。

本 Skill 不替代 task-decomposition-and-execution，而是在拆解前定义通用软件项目必须覆盖的阶段和验收项；随后调用 task-decomposition-and-execution 将阶段转为 Wave 任务。

输入要求

项目类型（必填）：API服务/后台模块/插件/CLI工具/数据脚本/自动化任务/服务端应用
业务目标（必填）：解决什么问题，交付后谁使用
运行环境（必填）：语言、框架、CMS/平台、数据库、服务器、定时任务或队列
输入输出（必填）：外部输入、数据来源、输出结果、调用方式
交付要求（可选）：上线方式、回滚要求、性能目标、安全要求、监控告警、巡检要求、验收人

执行流程

第一步：项目启动与边界确认

填充项目启动模板：按主 SKILL.md「项目启动模板」章节填写项目启动信息（含终极功能、循环轮次、改动点数），作为后续 Wave 拆解和轮次控制基准
明确项目类型、业务目标、成功标准和交付边界
判断是否属于网站项目；若是，转入 website-project
明确 In scope / Out of scope，避免需求漂移
确认运行入口：HTTP API、后台菜单、命令行、定时任务、队列消费、插件钩子

第二步：需求规格与行为契约

调用 spec-driven-development 输出需求规格，并补充：

业务对象和状态流转
输入参数、输出结果、错误码或异常类型
权限、幂等、重试、审计和日志要求
运行观测要求：关键指标、日志字段、告警阈值、巡检频率
兼容性要求：PHP版本、CMS版本、MySQL版本、浏览器或系统环境

第三步：架构与技术方案

按项目类型调用对应子技能：

API/服务：调用 api-design
数据库/SQL：调用 mysql-database
CMS/PHP二开：调用 cms-development
前端/后台页面：调用 frontend-design
技术不确定：调用 tech-selection

必须明确：

模块边界和文件组织
数据模型、接口契约、依赖服务
错误处理、日志、配置和权限
可观测性方案：日志路径、指标口径、异常上报、告警接收人
长任务是否需要 Init → Step → Poll
架构权衡留痕（复杂度门槛）：仅当本方案存在多候选方案 / 跨模块影响 / 高影响决策时必填——每项须附「候选方案 → 各自 trade-off → 选择理由 + 反选理由 + 撤销条件」（见 spec-driven-development 第四步 Design / tech-selection 第四步）。单一合理实现、低复杂度改动（如单文件小功能）不强制反选论证，避免违反"澄清过度"反模式；模糊 / 高影响决策仍须显式标注并交用户拍板。

第三步点五：模块边界审查

在进入 Wave 拆解前，对架构方案中涉及的模块边界进行合规审查，防止跨模块改动失控。

审查维度：

维度	检查项	违规信号
依赖方向	模块间依赖是否单向无环	循环依赖 / 底层模块反向依赖上层
接口契约	跨模块调用是否通过明确接口	跨模块直接访问内部实现 / 绕过接口调用私有方法
数据持有	每个数据实体是否有唯一归属模块	同一张表被多个模块直接写入 / 缓存键冲突
变更半径	单次改动是否需要同步修改 ≥ 3 个模块	一处业务规则变更需要同时改多个模块
术语一致性	跨模块是否对同一概念使用同一名称	同一概念在不同模块有不同命名

上表为工程边界维度。复杂业务系统（多子域/术语多义/跨上下文协作）应先加载 domain-driven-design 提供限界上下文语义边界（同一术语在不同上下文可有不同模型），与工程边界互补——审查时先语义后工程。CRUD 为主的项目跳过语义边界，避免过度设计。

审查输出：

绘制模块依赖图（文本箭头图即可）
违规项标注严重度（阻塞/警告/建议）和修复方向
循环依赖或数据归属冲突为阻塞级，必须在进入 Wave 拆解前解决
审查结果写入「架构决策」章节，随第八步沉淀到项目记忆

轻量模式（模块数 ≤ 3 时适用）：仅检查依赖方向和接口契约两项，其余跳过。

第四步：实现计划与 Wave 拆解

调用 task-decomposition-and-execution，按依赖拆成可验证 Wave：

Wave	内容	验证
Wave 1	环境、配置、入口、基础结构	能运行入口
Wave 2	数据模型、接口契约、核心服务	数据读写/接口返回正确
Wave 3	业务流程、权限、异常处理	主路径和异常路径通过
Wave 4	测试、安全、性能、兼容	检查清单通过
Wave 5	文档、部署、回滚、监控、巡检、交付	可交接可回滚可观测

轮次控制承接（引用主 SKILL.md「项目启动模板」和「轮次与收敛」章节）：

第一步填充的项目启动模板中「循环轮次」和「每轮改动点数」字段，在本步 Wave 拆解时落地执行
默认轮次 3 轮，安全最大轮次 6 轮，每轮改动点不超过 3 处
每轮结束时按主 SKILL.md「收敛判定逻辑」判断是否结束（终极功能完成/默认轮次到达/安全最大轮次/连续2轮P2微调）
超过安全最大轮次必须强制结束并输出未完成清单，不得无限循环

第五步：代码实现与自检

调用 code-generation 实现每个 Wave 的最小可验证切片
遵循 karpathy-coding-guidelines：先推演、少抽象、避免模板化膨胀
涉及 SQL 时遵循 mysql-database
涉及 CMS 时遵循 cms-development
每个改动必须给出验证方法

第六步：审查、测试与安全验证

调用 code-review 检查安全、性能、可维护性、规范符合性
调用 test-generation 覆盖正常路径、异常路径、边界条件和回归路径
检查 SQL 注入、XSS、CSRF、权限绕过、文件上传、反序列化等风险
长任务必须验证 Init 创建、Step 分批、Poll 查询、Cancel 取消、失败重试和僵尸检测

证据格式（必填，对齐主流程 Step 4）：

验证项	证据类型	最小字段
代码审查	命令+输出	审查命令 + 问题分级清单（阻塞/严重/一般/建议）
单元/集成测试	测试报告	测试用例数、通过数、失败用例清单
安全验证	命令+输出	扫描命令 + 扫描结果 + 阻塞级问题清单
长任务验证	API 响应	Init 创建响应 + Step 进度响应 + Poll 最终状态 + Cancel 响应 + 失败重试响应 + 僵尸检测扫描结果（Poll 检测 `running` 超阈值 → 标记 `failed`/`resume`）

未声明证据类型的验证视为未完成。

第七步：发布、回滚、监控与交付

明确发布方式：文件覆盖、插件启用、命令部署、数据库迁移、计划任务
输出上线前检查：配置、权限、依赖、缓存、日志、备份
数据库变更必须有备份和回滚 SQL
输出监控方案：核心可用性、错误率、慢查询、队列积压、任务失败数、磁盘/内存等运行指标
输出告警方案：触发阈值、通知渠道、值班/负责人、升级路径、误报处理
输出巡检方案：日/周巡检项、日志检查点、数据一致性检查、备份可恢复性检查
输出交付材料：使用说明、部署说明、回滚说明、已知限制

第八步：项目记忆沉淀

调用 project-memory-management 记录：

项目类型、入口、运行环境和部署方式
架构决策、数据结构、接口契约和权限规则
验证证据、发布记录、回滚方案、监控告警、巡检方案和已知限制
后续维护注意事项

构建与发布流水线（CI/CD）

本节定义通用软件项目必须覆盖的构建、发布和回滚流水线要点，作为第七步的工程化落地。

流水线阶段

阶段	输入	输出	验证
构建	源码、依赖锁文件、构建配置	可部署产物（包/镜像/静态文件）	构建成功且产物校验通过
测试	产物 + 测试套件	测试报告（通过率/覆盖率）	单元+集成测试通过，无阻塞失败
静态检查	源码	lint/类型检查/安全扫描报告	无阻塞级问题
部署	产物 + 环境配置	线上版本	健康检查通过，旧版本可回退
验证	线上环境	烟雾测试结果	关键路径可达，错误率低于阈值
回滚	上一稳定版本	线上版本回退	健康检查通过

强制要求

依赖锁定：构建必须基于 composer.lock / package-lock.json / pnpm-lock.yaml 等锁文件，禁止使用 latest / * / dev-main
环境隔离：构建、测试、生产环境配置必须分离，敏感配置通过环境变量注入，不写入代码库
产物可追溯：每次构建产物必须关联 commit、构建时间、构建号、依赖版本
发布可回滚：每次发布必须保留前一稳定版本，并能在 5 分钟内回退
健康检查：部署后必须执行烟雾测试，验证关键接口和页面可达
变更窗口：业务高峰期禁止发布，DDL/数据库迁移单独走审核流程

失败回退

失败场景	回退动作
构建失败	不进入测试；修复依赖或构建配置后重试
测试失败	不进入部署；标注失败用例并修复
部署后健康检查失败	立即触发自动回滚到上一稳定版本
回滚后仍失败	切换到应急流程，通知负责人，保留现场日志

输出格式

## 软件项目交付方案

### 1. 项目启动

- 项目类型:
- 业务目标:
- 成功标准:
- In scope:
- Out of scope:

### 2. 行为契约

| 场景 | 输入 | 输出 | 异常/错误 | 验收标准 |
| ---- | ---- | ---- | --------- | -------- |

### 3. 技术方案

| 层级 | 方案                  | 说明   |
| ---- | --------------------- | ------ |
| 入口 | [API/CLI/插件/任务]   | [说明] |
| 数据 | [MySQL/文件/外部服务] | [说明] |
| 集成 | [依赖服务]            | [说明] |

### 4. Wave执行计划

| Wave | 任务 | 依赖 | 验证 |
| ---- | ---- | ---- | ---- |

### 5. 验证与发布

- 测试:
- 安全:
- 性能:
- 发布:
- 回滚:
- 监控:
- 告警:
- 巡检:

### 6. 交付材料

- 使用说明:
- 部署说明:
- 回滚说明:
- 运维说明:
- 已知限制:

质量标准

必须先定义项目类型、入口、业务目标和成功标准
必须明确输入、输出、错误处理和验收标准
必须说明架构边界、数据/API/集成方案
涉及数据库必须调用 mysql-database
涉及 CMS/PHP 二开必须调用 cms-development
涉及长任务必须采用 Init → Step → Poll
每个 Wave 必须有验证方法
发布前必须有备份、回滚、监控告警、巡检方案和已知限制
发布交付必须说明日志位置、关键指标、告警阈值、巡检频率和负责人
无验证证据不得标记为完成

失败回退机制

步骤	失败条件	回退目标	最大重试	不可恢复时升级路径
第一步：项目启动与边界确认	类型或边界不清	输出澄清清单和默认假设	1	等待用户确认
第二步：需求规格与行为契约	输入输出不完整	生成最小行为契约草案	1	标注待确认字段
第三步：架构与技术方案	技术栈不确定	调用技术选型输出候选矩阵	1	由用户决策
第四步：实现计划与 Wave 拆解	依赖复杂或任务过大	重新按模块/入口/数据域拆分	2	输出依赖图
第五步：代码实现与自检	验证失败	缩小到最小可复现切片修复	2	标记阻塞
第六步：审查、测试与安全验证	环境不可用	输出手动验证清单	1	标注未实测项
第七步：发布、回滚、监控与交付	无发布权限、环境信息或监控接收人	输出部署包、回滚步骤和运维清单	1	由有权限人员执行并确认监控告警
第八步：项目记忆沉淀	项目记忆不可用	输出本地交付记录	1	标注未沉淀

关联 reference

website-project（网站项目总控）— 若项目属于网站、CMS站点、企业官网或营销页，转入网站总控
spec-driven-development（Spec驱动开发）— 生成需求规格、行为契约和验收标准
task-decomposition-and-execution（任务拆解与执行）— 将项目阶段拆成 Wave 并逐步验证
tech-selection（技术选型）— 技术栈、框架、数据库、队列、缓存和部署方案选型
api-design（API设计）— HTTP API、错误码、认证、分页和接口契约
mysql-database（MySQL数据库）— 表结构、索引、SQL安全、事务、慢查询和迁移回滚
cms-development（CMS二次开发）— PHP/CMS 插件、模板、后台模块和数据访问层
frontend-design（前端设计）— 后台页面、交互状态、响应式和浏览器验证
code-generation（代码生成）— 生成入口、服务、接口、脚本和业务代码
code-review（代码审查）— 审查安全、性能、可维护性和规范符合性
test-generation（测试用例生成）— 生成单元、集成、回归和边界测试
doc-generation（文档生成）— 生成 README、部署说明、使用说明、回滚说明和运维巡检文档
project-memory-management（项目记忆管理）— 沉淀项目配置、架构决策、发布记录和维护规范

software-project.md 16 KB Cronologia Originale