moai-workflow-templates

企业级模板管理

统一的模板系统，整合代码样板、反馈模板和项目优化工作流，助力快速开发并保持模式一致。

快速参考

核心能力：

• 支持 FastAPI、React、Vue 和 Next.js 的代码模板库
• 涵盖 6 种类型的 GitHub issue 反馈模板
• 项目模板优化与智能合并
• 模板版本管理与历史记录
• 备份发现与恢复
• 模式复用与自定义

适用场景：

• 搭建新项目或功能
• 使用 /moai:9-feedback 创建 GitHub issue
• MoAI-ADK 更新后优化模板结构
• 从项目备份中恢复
• 管理模板版本和自定义项
• 生成样板代码

主要功能：

• 代码模板：FastAPI、React、Vue、Docker 和 CI/CD 模板
• 反馈模板：6 种 GitHub issue 类型，包括 bug、功能、改进、重构、文档和问题
• 模板优化器：智能合并、备份恢复和版本跟踪
• 模式库：适用于常见场景的可复用模式

快速访问模块：

• 代码模板文档：modules/code-templates.md
• 反馈模板文档：modules/feedback-templates.md
• 模板优化器文档：modules/template-optimizer.md

实现指南

功能

• 适用于常见架构的项目模板
• 遵循最佳实践的样板代码生成
• 可配置的模板变量和自定义项
• 支持 React、FastAPI 和 Spring 等多种框架
• 集成测试和 CI/CD 配置

适用场景

• 使用经过验证的架构模式搭建新项目
• 确保组织内多个项目保持一致
• 使用规范的结构快速构建新功能原型
• 通过标准化的项目布局帮助新开发者入职
• 按照团队规范生成微服务或模块

核心模式

模式 1 - 模板结构：

模板按目录层级组织。顶层 templates 目录包含特定框架的子目录。后端框架目录（如 fastapi-backend）包含用于定义变量的 template.json，以及包含 main.py、models 子目录和 tests 子目录的 src 目录。前端框架目录（如 nextjs-frontend）包含 template.json、app 目录和 components 目录。全栈模板则包含独立的 backend 和 frontend 子目录。

模式 2 - 模板变量：

模板变量在 JSON 配置文件中定义，文件包含两个主要部分。variables 部分定义键值对，例如 PROJECT_NAME、AUTHOR、LICENSE 和 PYTHON_VERSION。files 部分将文件模式映射到处理模式：标记为 substitute 的文件会替换变量，而标记为 copy 的文件则原样复制。

模式 3 - 模板生成：

模板生成过程分为五个步骤。首先，加载模板目录结构。其次，替换标记为需要替换的文件中的变量。第三，原样复制静态文件。第四，运行生成后的钩子，例如安装依赖和初始化 git。第五，验证生成的项目结构。

核心模式详解

模式 1：代码模板脚手架

概念：使用可用于生产环境的样板快速搭建项目。

要生成项目，请加载相应模板，例如 backend/fastapi。通过项目名称、所需功能（如 auth、database 和 celery）以及自定义项（如数据库类型）配置脚手架。执行脚手架以创建项目结构。

完整的模板库和示例请参阅代码模板模块文档。

---

模式 2：GitHub 反馈模板

概念：通过结构化模板，确保 GitHub 问题创建过程一致。

六种模板类型：错误报告、功能请求、改进、重构、文档和问题／讨论。

集成：由 /moai:9-feedback 命令自动触发。

有关所有模板类型和用法，请参阅反馈模板模块文档。

---

模式 3：模板优化与智能合并

概念：在保留用户自定义内容的同时，智能合并模板更新。

智能合并算法：三方合并流程如下。首先，从备份中提取用户自定义内容。其次，从当前模板中获取最新的模板默认值。第三，按适当的优先级进行合并：template_structure 使用最新默认值，user_config 保留用户设置，custom_content 保留用户修改。

有关完整的工作流和示例，请参阅模板优化器模块文档。

---

模式 4：备份发现与恢复

概念：通过智能恢复实现自动备份管理。

恢复流程：该流程分为四个步骤。首先，使用备份标识符加载备份元数据。其次，验证备份完整性；如果备份已损坏，则报错。第三，从经过验证的备份中提取自定义内容。第四，将提取出的自定义内容应用到当前项目。

有关完整实现，请参阅模板优化器模块中的“恢复流程”部分。

---

模式 5：模板版本管理

概念：跟踪模板版本并维护更新历史记录。

版本跟踪：template_optimization 配置部分存储 last_optimized 时间戳、backup_version 标识符、template_version 编号，以及 customizations_preserved 列表，其中包含 language、team_settings 和 domains 等项目。

有关完整实现，请参阅模板优化器模块中的“版本跟踪”部分。

---

模块参考

核心模块

• modules/code-templates.md 中的代码模板：样板库、脚手架模式和框架模板
• modules/feedback-templates.md 中的反馈模板：6 种 GitHub 问题类型、用法示例和最佳实践
• modules/template-optimizer.md 中的模板优化器：智能合并算法、备份恢复和版本管理

模块内容

代码模板包含 FastAPI REST API 模板、React 组件模板、Docker 和 CI/CD 模板，以及带有脚手架模式的模板变量。

反馈模板包含错误报告模板、功能请求模板、改进模板、重构模板、文档模板、问题模板，以及与 /moai:9-feedback 命令的集成。

模板优化器包含 6 阶段优化工作流、智能合并算法、备份发现与恢复，以及带历史记录的版本跟踪。

高级文档

有关详细模式和实现策略，请参阅《代码模板指南》，了解完整模板库；参阅《反馈模板》，了解问题模板参考；并参阅《模板优化器》，了解优化和合并策略。

最佳实践

核心要求

• 使用模板确保项目结构一致
• 在更新过程中保留用户自定义内容
• 在进行重大模板更改前创建备份
• 遵循模板结构约定
• 记录自定义修改
• 使用智能合并更新模板
• 在配置中跟踪模板版本
• 在生产环境使用前测试模板

质量标准

[HARD] 应用更改前，记录所有模板默认值的修改。 原因：模板默认值是所有项目的基准，未记录的更改会造成团队间的困惑和不一致。 影响：没有文档记录，团队就无法了解默认值偏离标准的原因，进而导致维护问题和相互冲突的实现。

[HARD] 执行模板优化工作流前，创建备份。 原因：模板优化涉及结构性更改，如果没有干净的还原点，这些更改可能难以撤销。 影响：缺少备份可能导致用户自定义内容永久丢失，需要手动重建项目专属配置。

[HARD] 在模板更新工作流中解决所有合并冲突。 原因：未解决的冲突会造成配置损坏，导致模板无法正常运行。 影响：忽略冲突会导致运行时错误、行为不一致和项目不稳定，并需要紧急修复。

[SOFT] 在整个项目中保持模板模式使用的一致性。 原因：混用不同的模板模式会增加认知负担，让代码库更难理解和维护。 影响：模式不一致会降低代码的可预测性，并延长新团队成员的上手时间。

[HARD] 在所有模板更新中保留完整的自定义历史记录。 原因：自定义历史记录可提供项目专属决策的审计线索，并支持回滚到之前的状态。 影响：历史记录丢失后，将无法了解更改原因，也就无法对未来的修改做出明智决策。

[HARD] 在部署到生产环境之前，通过测试验证模板功能。 原因：未经测试的模板可能包含错误，这些错误只有在生产环境中才会显现并导致系统故障。 影响：未经测试的模板导致生产环境故障，会造成停机、数据问题和紧急回滚，影响用户。

[SOFT] 将模板复杂度控制在合理范围内，以便于维护。 原因：模板过于复杂时，出现问题后会难以理解、修改和调试。 影响：模板过于复杂会降低开发效率，并增加自定义过程中出错的可能性。

[HARD] 使用内置版本管理系统跟踪模板版本。 原因：版本跟踪有助于了解模板的演变、检查兼容性以及协调更新。 影响：如果没有版本跟踪，团队就无法确定有哪些模板功能可用，也无法安全地协调跨项目更新。

配合使用效果良好

Agent：

• workflow-project：项目初始化
• core-planner：模板规划
• workflow-spec：SPEC 模板生成

技能：

• moai-project-config-manager：配置管理和验证
• moai-cc-configuration：Claude Code 设置集成
• moai-foundation-specs：SPEC 模板生成
• moai-docs-generation：文档模板搭建
• moai-core-workflow：模板驱动的工作流

命令：

• /moai:0-project：使用模板初始化项目
• /moai:9-feedback：选择反馈模板并创建问题

工作流集成

项目初始化工作流：使用模式 1 选择代码模板，搭建项目结构，应用自定义设置，并使用模式 5 初始化版本跟踪。

反馈提交工作流：执行 /moai:9-feedback 命令，使用模式 2 选择问题类型，填写模板字段，并自动生成 GitHub 问题。

模板更新工作流：检测模板版本更改，使用模式 4 创建备份，使用模式 3 运行智能合并，并使用模式 5 更新版本历史记录。

成功指标

• 脚手架搭建时间：新项目耗时 2 分钟，相比手动操作的 30 分钟
• 模板采用率：95% 的项目使用模板
• 定制内容保留率：更新期间保留 100% 的用户内容
• 反馈完整率：95% 的 GitHub 问题包含完整信息
• 合并成功率：99% 的冲突由系统自动解决

更新日志

• v3.1.0 (2026-01-11)：转换为 CLAUDE.md 文档标准，移除代码块和表格
• v3.0.0 (2026-01-08)：大版本更新，采用模块化架构
• v2.0.0 (2025-11-24)：将 moai-core-code-templates、moai-core-feedback-templates 和 moai-project-template-optimizer 合并为单个技能，包含 5 种核心模式
• v1.0.0 (2025-11-22)：原始独立技能

---

状态：已可用于生产环境（企业级） 模块化架构：SKILL.md + 3 个核心模块 集成：针对 Plan-Run-Sync 工作流进行了优化 生成工具：MoAI-ADK Skill Factory