Back to Details

moai-workflow-templates

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Enterprise Template Management

企业级模板管理

Unified template system combining code boilerplates, feedback templates, and project optimization workflows for rapid development and consistent patterns.
整合代码模板、反馈模板和项目优化工作流的统一模板系统，助力快速开发并确保模式一致性。

Quick Reference

快速参考

Core Capabilities:
  • Code template library for FastAPI, React, Vue, and Next.js
  • GitHub issue feedback templates covering 6 types
  • Project template optimization and smart merging
  • Template version management and history
  • Backup discovery and restoration
  • Pattern reusability and customization
When to Use:
  • Scaffolding new projects or features
  • Creating GitHub issues with /moai:9-feedback
  • Optimizing template structures after MoAI-ADK updates
  • Restoring from project backups
  • Managing template versions and customizations
  • Generating boilerplate code
Key Features:
  • Code Templates: FastAPI, React, Vue, Docker, and CI/CD templates
  • Feedback Templates: 6 GitHub issue types including bug, feature, improvement, refactor, docs, and question
  • Template Optimizer: Smart merge, backup restoration, and version tracking
  • Pattern Library: Reusable patterns for common scenarios
Quick Access to Modules:
  • Code Templates documentation in modules/code-templates.md
  • Feedback Templates documentation in modules/feedback-templates.md
  • Template Optimizer documentation in modules/template-optimizer.md
核心功能：
  • 支持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

Implementation Guide

实施指南

Features

功能特性

  • Project templates for common architectures
  • Boilerplate code generation with best practices
  • Configurable template variables and customization
  • Multi-framework support including React, FastAPI, and Spring
  • Integrated testing and CI/CD configurations
  • 适用于常见架构的项目模板
  • 遵循最佳实践的样板代码生成
  • 可配置的模板变量与自定义选项
  • 多框架支持，包括React、FastAPI和Spring
  • 集成测试与CI/CD配置

When to Use

适用场景

  • Bootstrapping new projects with proven architecture patterns
  • Ensuring consistency across multiple projects in an organization
  • Quickly prototyping new features with proper structure
  • Onboarding new developers with standardized project layouts
  • Generating microservices or modules following team conventions
  • 使用经过验证的架构模式启动新项目
  • 确保组织内多个项目的一致性
  • 快速搭建结构规范的新功能原型
  • 以标准化项目布局完成新开发人员入职
  • 遵循团队规范生成微服务或模块

Core Patterns

核心模式

Pattern 1 - Template Structure:
Templates are organized in a directory hierarchy. The top-level templates directory contains framework-specific subdirectories. A backend framework directory such as fastapi-backend contains template.json for variables and a src directory with main.py, models subdirectory, and tests subdirectory. A frontend framework directory such as nextjs-frontend contains template.json, app directory, and components directory. A fullstack template contains separate backend and frontend subdirectories.
Pattern 2 - Template Variables:
Template variables are defined in a JSON configuration file with two main sections. The variables section defines key-value pairs such as PROJECT_NAME, AUTHOR, LICENSE, and PYTHON_VERSION. The files section maps file patterns to processing modes: files marked as substitute have variables replaced, while files marked as copy are transferred unchanged.
Pattern 3 - Template Generation:
The template generation process follows five steps. First, load the template directory structure. Second, substitute variables in files marked for substitution. Third, copy static files as-is. Fourth, run post-generation hooks such as dependency installation and git initialization. Fifth, validate the generated project structure.
模式1 - 模板结构：
模板按目录层级组织。顶层templates目录包含各框架专属子目录。例如fastapi-backend这类后端框架目录包含用于定义变量的template.json，以及包含main.py、models子目录和tests子目录的src目录。nextjs-frontend这类前端框架目录包含template.json、app目录和components目录。全栈模板则包含独立的后端和前端子目录。
模式2 - 模板变量：
模板变量在JSON配置文件中定义，包含两个主要部分。variables部分定义键值对，如PROJECT_NAME、AUTHOR、LICENSE和PYTHON_VERSION。files部分将文件模式映射到处理模式：标记为substitute的文件会替换变量，标记为copy的文件则直接原样复制。
模式3 - 模板生成：
模板生成流程分为五步。第一步，加载模板目录结构。第二步，在标记为替换的文件中替换变量。第三步，原样复制静态文件。第四步，运行生成后钩子，如依赖安装和git初始化。第五步，验证生成的项目结构。

Core Patterns in Detail

核心模式详解

Pattern 1: Code Template Scaffolding

模式1：代码模板脚手架

Concept: Rapidly scaffold projects with production-ready boilerplates.
To generate a project, load the appropriate template such as backend/fastapi. Configure the scaffold with the project name, desired features such as auth, database, and celery, and customizations such as database type. Execute the scaffold to create the project structure.
For complete library and examples, see the Code Templates module documentation.
概念：使用生产就绪的样板代码快速搭建项目。
生成项目时，加载合适的模板（如backend/fastapi）。配置脚手架的项目名称、所需功能（如认证、数据库、celery）以及自定义选项（如数据库类型）。执行脚手架命令创建项目结构。
完整的库与示例请查看代码模板模块文档。

Pattern 2: GitHub Feedback Templates

模式2：GitHub反馈模板

Concept: Structured templates for consistent GitHub issue creation.
Six Template Types: Bug Report, Feature Request, Improvement, Refactor, Documentation, and Question/Discussion.
Integration: Auto-triggered by the /moai:9-feedback command.
For all template types and usage, see the Feedback Templates module documentation.
概念：用于创建一致GitHub issue的结构化模板。
六种模板类型：Bug报告、功能请求、改进建议、重构需求、文档更新和问题咨询。
集成方式：通过/moai:9-feedback命令自动触发。
所有模板类型与使用方法请查看反馈模板模块文档。

Pattern 3: Template Optimization and Smart Merge

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

Concept: Intelligently merge template updates while preserving user customizations.
Smart Merge Algorithm: The three-way merge process works as follows. First, extract user customizations from the backup. Second, get the latest template defaults from the current templates. Third, merge with appropriate priority where template_structure uses the latest defaults, user_config preserves user settings, and custom_content retains user modifications.
For complete workflow and examples, see the Template Optimizer module documentation.
概念：在保留用户自定义内容的同时，智能合并模板更新。
智能合并算法：三方合并流程如下。第一步，从备份中提取用户自定义内容。第二步，获取当前模板的最新默认配置。第三步，按优先级合并：template_structure使用最新默认值，user_config保留用户设置，custom_content保留用户修改内容。
完整工作流与示例请查看模板优化器模块文档。

Pattern 4: Backup Discovery and Restoration

模式4：备份发现与恢复

Concept: Automatic backup management with intelligent restoration.
Restoration Process: The process follows four steps. First, load backup metadata using the backup identifier. Second, validate backup integrity and raise an error if the backup is corrupted. Third, extract customizations from the validated backup. Fourth, apply the extracted customizations to the current project.
For complete implementation, see the Template Optimizer module section on Restoration Process.
概念：自动备份管理与智能恢复。
恢复流程：分为四步。第一步，使用备份标识符加载备份元数据。第二步，验证备份完整性，若备份损坏则抛出错误。第三步，从已验证的备份中提取自定义内容。第四步，将提取的自定义内容应用到当前项目。
完整实现请查看模板优化器模块中的恢复流程章节。

Pattern 5: Template Version Management

模式5：模板版本管理

Concept: Track template versions and maintain update history.
Version Tracking: The template_optimization configuration section stores last_optimized timestamp, backup_version identifier, template_version number, and customizations_preserved list containing items like language, team_settings, and domains.
For complete implementation, see the Template Optimizer module section on Version Tracking.
概念：跟踪模板版本并维护更新历史。
版本跟踪：template_optimization配置部分存储last_optimized时间戳、backup_version标识符、template_version编号，以及包含language、team_settings和domains等项的customizations_preserved列表。
完整实现请查看模板优化器模块中的版本跟踪章节。

Module Reference

模块参考

Core Modules

核心模块

  • Code Templates in modules/code-templates.md: Boilerplate library, scaffold patterns, and framework templates
  • Feedback Templates in modules/feedback-templates.md: 6 GitHub issue types, usage examples, and best practices
  • Template Optimizer in modules/template-optimizer.md: Smart merge algorithm, backup restoration, and version management
  • modules/code-templates.md中的代码模板：样板库、脚手架模式与框架模板
  • modules/feedback-templates.md中的反馈模板：6种GitHub issue类型、使用示例与最佳实践
  • modules/template-optimizer.md中的模板优化器：智能合并算法、备份恢复与版本管理

Module Contents

模块内容

Code Templates include FastAPI REST API template, React component template, Docker and CI/CD templates, and template variables with scaffolding patterns.
Feedback Templates include Bug Report template, Feature Request template, Improvement template, Refactor template, Documentation template, Question template, and integration with /moai:9-feedback command.
Template Optimizer includes 6-phase optimization workflow, smart merge algorithm, backup discovery and restoration, and version tracking with history.
代码模板包含FastAPI REST API模板、React组件模板、Docker和CI/CD模板，以及带脚手架模式的模板变量。
反馈模板包含Bug报告模板、功能请求模板、改进建议模板、重构需求模板、文档更新模板、问题咨询模板，以及与/moai:9-feedback命令的集成。
模板优化器包含6阶段优化工作流、智能合并算法、备份发现与恢复，以及带历史记录的版本跟踪。

Advanced Documentation

进阶文档

For detailed patterns and implementation strategies, refer to the Code Templates Guide for complete template library, Feedback Templates for issue template reference, and Template Optimizer for optimization and merge strategies.
如需详细的模式与实施策略，请参考《代码模板指南》获取完整模板库信息、《反馈模板》获取issue模板参考、《模板优化器》获取优化与合并策略。

Best Practices

最佳实践

Core Requirements

核心要求

  • Use templates for consistent project structure
  • Preserve user customizations during updates
  • Create backups before major template changes
  • Follow template structure conventions
  • Document custom modifications
  • Use smart merge for template updates
  • Track template versions in config
  • Test templates before production use
  • 使用模板确保一致的项目结构
  • 更新时保留用户自定义内容
  • 重大模板变更前创建备份
  • 遵循模板结构规范
  • 记录自定义修改内容
  • 使用智能合并进行模板更新
  • 在配置中跟踪模板版本
  • 生产环境使用前测试模板

Quality Standards

质量标准

[HARD] Document all template default modifications before applying changes. WHY: Template defaults serve as the baseline for all projects and undocumented changes create confusion and inconsistency across teams. IMPACT: Without documentation, teams cannot understand why defaults deviate from standards, leading to maintenance issues and conflicting implementations.
[HARD] Create backups before executing template optimization workflows. WHY: Template optimization involves structural changes that may be difficult to reverse without a clean restoration point. IMPACT: Missing backups can result in permanent loss of user customizations, requiring manual reconstruction of project-specific configurations.
[HARD] Resolve all merge conflicts during template update workflows. WHY: Unresolved conflicts create broken configurations that prevent proper template functionality. IMPACT: Ignored conflicts lead to runtime errors, inconsistent behavior, and project instability requiring emergency fixes.
[SOFT] Maintain consistent template pattern usage throughout the project. WHY: Mixing different template patterns creates cognitive overhead and makes the codebase harder to understand and maintain. IMPACT: Inconsistent patterns reduce code predictability and increase onboarding time for new team members.
[HARD] Preserve complete customization history across all template updates. WHY: Customization history provides an audit trail of project-specific decisions and enables rollback to previous states. IMPACT: Lost history makes it impossible to understand why changes were made, preventing informed decisions about future modifications.
[HARD] Validate template functionality through testing before production deployment. WHY: Untested templates may contain errors that only surface in production environments, causing system failures. IMPACT: Production failures from untested templates result in downtime, data issues, and emergency rollbacks affecting users.
[SOFT] Design templates within reasonable complexity limits for maintainability. WHY: Excessive template complexity makes them difficult to understand, modify, and debug when issues arise. IMPACT: Overly complex templates slow down development velocity and increase the likelihood of errors during customization.
[HARD] Track template versions using the built-in version management system. WHY: Version tracking enables understanding of template evolution, compatibility checking, and coordinated updates. IMPACT: Without version tracking, teams cannot determine which template features are available or coordinate updates across projects safely.
[硬性要求] 应用变更前记录所有模板默认值修改。 原因：模板默认值是所有项目的基准，未记录的变更会导致团队困惑与不一致。 影响：无文档记录的情况下，团队无法理解默认值偏离标准的原因，进而引发维护问题与冲突性实现。
[硬性要求] 执行模板优化工作流前创建备份。 原因：模板优化涉及结构变更，若无干净的恢复点则难以回退。 影响：缺失备份可能导致用户自定义内容永久丢失，需要手动重建项目特定配置。
[硬性要求] 模板更新工作流中解决所有合并冲突。 原因：未解决的冲突会导致配置损坏，影响模板正常功能。 影响：忽略冲突会引发运行时错误、行为不一致与项目不稳定，需要紧急修复。
[软性要求] 项目中保持一致的模板模式使用。 原因：混合不同模板模式会增加认知负担，降低代码库的可理解性与可维护性。 影响：不一致的模式会降低代码可预测性，延长新团队成员的入职时间。
[硬性要求] 所有模板更新中保留完整的自定义历史。 原因：自定义历史提供项目特定决策的审计轨迹，支持回退到之前的状态。 影响：丢失历史会导致无法理解变更原因，影响未来修改的决策。
[硬性要求] 生产部署前通过测试验证模板功能。 原因：未测试的模板可能包含仅在生产环境才会暴露的错误，导致系统故障。 影响：未测试模板引发的生产故障会导致停机、数据问题与影响用户的紧急回滚。
[软性要求] 设计模板时控制复杂度以保证可维护性。 原因：过度复杂的模板难以理解、修改与调试。 影响：过于复杂的模板会降低开发速度，增加自定义过程中的出错概率。
[硬性要求] 使用内置版本管理系统跟踪模板版本。 原因：版本跟踪支持理解模板演进、兼容性检查与跨项目的协调更新。 影响：无版本跟踪的情况下，团队无法确定可用的模板功能，也无法安全地跨项目协调更新。

Works Well With

适配集成

Agents:
  • workflow-project: Project initialization
  • core-planner: Template planning
  • workflow-spec: SPEC template generation
Skills:
  • moai-project-config-manager: Configuration management and validation
  • moai-cc-configuration: Claude Code settings integration
  • moai-foundation-specs: SPEC template generation
  • moai-docs-generation: Documentation template scaffolding
  • moai-core-workflow: Template-driven workflows
Commands:
  • /moai:0-project: Project initialization with templates
  • /moai:9-feedback: Feedback template selection and issue creation
Agents：
  • workflow-project：项目初始化
  • core-planner：模板规划
  • workflow-spec：SPEC模板生成
Skills：
  • 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：反馈模板选择与issue创建

Workflow Integration

工作流集成

Project Initialization Workflow: Select code template using Pattern 1, scaffold project structure, apply customizations, and initialize version tracking using Pattern 5.
Feedback Submission Workflow: Execute /moai:9-feedback command, select issue type using Pattern 2, fill template fields, and auto-generate GitHub issue.
Template Update Workflow: Detect template version change, create backup using Pattern 4, run smart merge using Pattern 3, and update version history using Pattern 5.
项目初始化工作流：使用模式1选择代码模板，搭建项目结构，应用自定义配置，使用模式5初始化版本跟踪。
反馈提交工作流：执行/moai:9-feedback命令，使用模式2选择issue类型，填写模板字段，自动生成GitHub issue。
模板更新工作流：检测模板版本变更，使用模式4创建备份，使用模式3运行智能合并，使用模式5更新版本历史。

Success Metrics

成功指标

  • Scaffold Time: 2 minutes for new projects compared to 30 minutes manual
  • Template Adoption: 95% of projects use templates
  • Customization Preservation: 100% user content retained during updates
  • Feedback Completeness: 95% GitHub issues with complete information
  • Merge Success Rate: 99% conflicts resolved automatically
  • 搭建时间：新项目从手动30分钟缩短至2分钟
  • 模板采用率：95%的项目使用模板
  • 自定义内容保留率：更新时100%保留用户内容
  • 反馈完整性：95%的GitHub issue信息完整
  • 合并成功率：99%的冲突自动解决

Changelog

更新日志

  • v3.1.0 (2026-01-11): Converted to CLAUDE.md documentation standards, removed code blocks and tables
  • v3.0.0 (2026-01-08): Major version with modular architecture
  • v2.0.0 (2025-11-24): Unified moai-core-code-templates, moai-core-feedback-templates, and moai-project-template-optimizer into single skill with 5 core patterns
  • v1.0.0 (2025-11-22): Original individual skills
Status: Production Ready (Enterprise) Modular Architecture: SKILL.md + 3 core modules Integration: Plan-Run-Sync workflow optimized Generated with: MoAI-ADK Skill Factory
  • 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合并为单一skill，包含5个核心模式
  • v1.0.0（2025-11-22）：初始独立skill版本
状态：生产就绪（企业级） 模块化架构：SKILL.md + 3个核心模块 集成：优化后的Plan-Run-Sync工作流 生成工具：MoAI-ADK Skill Factory