# 自定义 OpenSpec 步骤改进 AI 生成结果

> 在使用 OpenSpec 管理技术提案时，我们遇到了 AI 生成文档质量不稳定的问题。其实也没别的办法，只能自己动手改提示词模板了。这篇文章就是那段日子的记录。

## 背景

OpenSpec 是一个管理技术提案的系统，核心想法很简单：输入变更描述，自动生成各种文档工件。proposal、design、specs、tasks，这些都能自动生成。听起来挺美好的，不是吗？

只是在实际使用中，我们发现了一些问题。怎么说呢，也不是什么大问题，就是生成的东西不太对味儿。

生成的 `design.md` 缺少必要的可视化元素——没有 Mermaid 流程图，没有时序图，更没有架构图。这样的设计文档，技术团队看了直摇头，毕竟谁愿意看一堆纯文字呢？

`proposal.md` 也不尽如人意，缺少代码变更表格，没有界面原型。决策者看了半天，还是不知道这变更到底改了些什么。

更让人头疼的是 `tasks.md`，里面混入了各种 Git 操作任务。职责边界变得模糊不清，开发人员看着这些任务，不知道哪些该做、哪些不该做。这也有点无奈，毕竟 AI 也不知道你的团队分工是怎么样的。

不同文档级别的可视化要求也不明确。proposal 和 design 到底应该包含哪些图表？这个问题一直困扰着团队。

这些问题的根源在哪呢？我们分析后发现了关键点：提示词模板缺少明确的约束和指导。

这也没什么好奇怪的，毕竟模板本身就是通用的，不可能完全适配每个团队的需求。

## 关于 HagiCode

本文分享的方案来自我们在 [HagiCode](https://hagicode.com) 项目中的实践经验。HagiCode 是一个 AI 代码助手项目，我们在开发过程中大量使用 OpenSpec 来管理技术提案。

正是这些实际踩坑经历，促成了这套改进方案的诞生。其实也没什么大不了的，就是遇到问题解决问题罢了。

## 分析：提示词系统架构

要解决问题，先要理解系统。让我们看看 OpenSpec 的提示词系统是怎么工作的。

OpenSpec 使用 Handlebars 模板系统，每个提示词包含两个部分：

**JSON 元数据文件**：定义参数、场景、版本信息
**Handlebars 模板文件**：包含实际的提示词内容

```
Resources/Prompts/
├── openspec-v1-ff.zh-CN.json    # 元数据
├── openspec-v1-ff.zh-CN.hbs     # 模板内容
├── openspec-v1-ff.en-US.json
└── openspec-v1-ff.en-US.hbs
```

这种分离设计的优点很明显：元数据和内容分开管理，便于维护和本地化。这也有点像写代码，逻辑和表现分离，大家都懂这个道理。

FF（Fast Forward）工作流是 OpenSpec 的核心生成流程：

```mermaid
flowchart TD
    A[用户输入变更描述] --> B[创建变更目录]
    B --> C[获取工件构建顺序]
    C --> D[按依赖顺序创建工件]
    D --> E[检查规划方向要求]
    E --> F[验证工件完整性]
    F --> G[显示最终状态]
```

这个流程看起来很完美，但问题出在"规划方向要求"这一步——它没有足够明确的指导。

这也有点无奈，毕竟系统设计的时候，也不可能考虑到所有团队的具体需求。

## 规划方向系统

规划方向系统是 OpenSpec 的核心自定义机制，允许用户选择不同的生成选项。HagiCode 项目中定义了以下方向：

| 方向 ID | 功能 | 默认启用 |
|---------|------|---------|
| `explore` | 探索模式 | 是 |
| `change-map` | 变更地图 | 是 |
| `flowchart` | 交互流程图 | 是 |
| `prototype` | UI 原型 | 是 |
| `architecture` | 架构图 | 是 |
| `sequence` | API 时序图 | 是 |

每个方向都定义了稳定的标识符、默认启用状态、显示标签，以及中英文提示词片段。

这个系统设计得很精巧，但在 HagiCode 的实践中，我们发现光有定义还不够——需要在提示词模板中明确使用这些方向。

这也有点像人生中很多事情，有了选项不等于会做出选择，还是需要有人告诉你该怎么选。

## 解决方案：明确约束和示例

我们的改进思路很直接：在提示词模板中添加明确的约束和参考示例。

其实也没什么特别的，就是把话说清楚罢了。

### 1. 添加文档可视化要求

在 `openspec-v1-ff.zh-CN.hbs` 模板中，我们添加了明确的内容范围约束：

```markdown
### tasks.md 内容范围约束

当创建 `tasks.md` 工件时，必须遵守以下内容范围约束：

必须包含：
- 业务逻辑任务（代码实现、功能开发）
- 技术实现任务（组件集成、API 开发）
- 测试任务（单元测试、集成测试）
- 文档任务（更新文档、添加注释）

禁止包含：
- Git 提交操作（git add、git commit、git push）
- 版本控制管理工作流
- 部署和发布操作
```

使用规范的"必须/禁止"语言，而不是"建议"或"可以"，这让 AI 能够更准确地理解约束。

这也有点像教导孩子，说什么就是什么，不能有歧义。

### 2. 为每个方向提供参考示例

光说"包含流程图"还不够，我们为每个启用的方向提供了具体的输出示例。

毕竟光说不练假把式，给个具体的例子，AI 就能更好地理解。

**变更地图方向示例**：
```markdown
| 文件路径 | 变更类型 | 变更原因 | 影响范围 |
|---------|---------|---------|---------|
| Path/to/file | 新增 | 说明 | 模块名 |
```

**原型方向示例**：
```
┌─────────────────────────────────────────┐
│ 用户登录                            [×] │
├─────────────────────────────────────────┤
│  邮箱地址 *                             │
│ ┌─────────────────────────────────────┐ │
│ │ user@example.com                   │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘
```

**流程图方向示例**：
```mermaid
sequenceDiagram
    participant U as 用户
    participant UI as 登录界面
    participant API as 后端API
    U->>UI: 点击登录按钮
    UI->>API: POST /api/auth/login
```

这些示例让 AI 能够准确理解期望的输出格式，而不是自己发挥。

这也有点像考试时给参考答案，虽然不能完全一样，但格式总要对吧。

### 3. 使用规范语言明确要求

对于不同文档类型的可视化要求，我们用规范语言来约束：

```markdown
对于 proposal.md：
- 必须包含代码变更表（当启用 change-map 方向）
- 必须包含 UI 原型图（当涉及 UI 变更且启用 prototype 方向）
- 禁止包含详细的架构图（这些应在 design.md 中）

对于 design.md：
- 必须包含所有 proposal.md 的内容（更详细版本）
- 必须包含架构图（当启用 architecture 方向）
- 必须包含数据流图（当启用 flowchart 方向）
```

这种明确的约束大大改善了生成质量。

其实也没别的，就是把话说清楚，不要让 AI 去猜。

## 实践：代码实现

理论说完了，来看看 HagiCode 项目中是怎么实现的。

### 定义规划方向

在 `ProposalPlanningDirections.cs` 中定义规划方向：

```csharp
public static class ProposalPlanningDirections
{
    private static readonly ProposalPlanningDirectionDefinition[] Catalog =
    [
        new(
            ChangeMapId,
            "Change map",
            DefaultEnabled: true,
            EnglishPromptFragment:
            "- Change map: include structured file-impact views...",
            ChinesePromptFragment:
            "- 变更地图：加入结构化的文件影响视图..."),
        // ... 其他方向
    ];

    public static string RenderInstructionBlock(
        IEnumerable<ProposalPlanningDirectionState> directions,
        string? locale)
    {
        var enabledDirections = directions
            .Where(direction => direction.Enabled)
            .ToArray();

        if (enabledDirections.Length == 0)
        {
            return string.Empty;
        }

        var heading = IsChineseLocale(locale)
            ? "本次生成启用以下规划方向："
            : "Apply the following planning directions:";

        return string.Join(Environment.NewLine,
            [heading, .. enabledDirections.Select(d => d.GetPromptFragment(locale))]);
    }
}
```

这段代码有几个值得注意的设计点：

1. 使用数组而不是列表，因为定义在运行时不会改变
2. 延迟渲染——只在有启用方向时才生成文本
3. 支持多语言，根据 locale 选择合适的提示词片段

其实也没什么特别的，就是一些常规的代码设计罢了。

### 模板参数化

在 Handlebars 模板中使用条件语句：

```handlebars
{{#if planningDirectionInstructions}}
## 本次生成的规划方向

{{{planningDirectionInstructions}}}
{{/if}}

**步骤**
1. **如果未提供输入，使用合理的默认值**
2. **创建变更目录**
3. **获取工件构建顺序**
4. **按顺序创建工件直到 apply-ready**
   a. 对于每个 ready 的工件：
      - 获取说明
      - 阅读依赖文件
      - 创建工件文件
```

注意那个 `{{{planningDirectionInstructions}}}`——三个花括号表示不转义 HTML，这样可以保留 Mermaid 代码块等格式。

这也有点像生活中的妥协，有时候需要保留一些原始的东西，不能什么都转义。

### 提示词加载实现

通过 `FilePromptProvider` 实现提示词的参数化加载：

```csharp
public async Task<string> GetOpenspecV1FfPromptAsync(
    string changeName,
    string changeDescription,
    string locale = "en-US",
    string? planningDirectionInstructions = null,
    CancellationToken cancellationToken = default)
{
    var parameters = new Dictionary<string, object>
    {
        { "planningDirectionInstructions",
          ResolvePlanningDirectionInstructions(locale, planningDirectionInstructions) }
    };

    if (!string.IsNullOrWhiteSpace(changeName))
    {
        parameters["changeName"] = changeName;
    }

    return await GetPromptWithParametersAsync(
        PromptScenario.OpenspecV1Ff,
        locale,
        cancellationToken,
        parameters) ?? string.Empty;
}
```

这个设计很灵活：`planningDirectionInstructions` 是可选的，如果不提供，系统会使用默认配置。

毕竟谁也不希望每次都传入一堆参数，有个默认值总是好的。

## 验证和测试

实现后，HagiCode 团队进行了全面的验证：

### 启用特定方向时

- 检查生成的 proposal.md 是否包含代码变更表
- 检查生成的 design.md 是否包含架构图
- 验证 tasks.md 不包含 Git 操作任务

### 禁用特定方向时

- 验证不会生成对应的可视化内容
- 确保不影响其他方向的输出

### 边界情况

- 所有方向都禁用时的行为
- 无效的方向 ID 时的错误处理

这些测试确保了系统的稳定性和可预测性——这对团队采用新工具至关重要。

其实也没什么特别的，就是该测的都要测到，毕竟谁也不希望上线之后出问题。

## 注意事项

在实施这套方案时，有几个坑要避开：

**模板同步**：修改模板时注意与上游保持同步。HagiCode 团队就遇到过一次模板冲突，花了半天时间才解决。这也有点无奈，毕竟升级总是会带来一些兼容性问题。

**双语一致性**：确保中英文模板的结构和约束一致。我们曾经遇到过中文版本有约束、英文版本没有的情况，导致生成的文档质量不一致。这也有点尴尬，毕竟谁知道用户会用哪种语言呢。

**性能影响**：规划方向的渲染应在微秒级完成。如果渲染时间过长，会影响用户体验。毕竟谁愿意等半天才能看到结果呢。

**向后兼容**：保留对旧版本 API 的支持。比如 `enableExploreMode` 参数，虽然我们现在用规划方向系统，但旧代码还在用。这也有点无奈，毕竟不能总是要求所有人都升级。

**清晰的表达**：使用规范语言（MUST/SHALL）而非建议性语言。这一点在 HagiCode 的实践中得到了充分验证。其实也没什么别的，就是把话说清楚罢了。

## 总结

通过自定义 OpenSpec 提示词步骤，我们成功改进了 AI 生成文档的质量。关键改进点包括：

1. 在提示词模板中添加明确的约束条件
2. 为每个规划方向提供具体的输出示例
3. 使用规范语言（MUST/MUST NOT）来约束 AI 行为
4. 通过代码实现灵活的提示词参数化加载

这套方案在 HagiCode 项目中得到了验证，生成的文档质量明显提升：设计文档包含了完整的可视化元素，提案文档有清晰的代码变更表，任务清单职责明确。

其实也没什么大不了的，就是把问题解决了罢了。

如果你也在使用类似的 AI 辅助文档生成系统，希望这些经验对你有帮助。记住：清晰的约束和具体的示例，是获得高质量输出的关键。

毕竟有些事情，还是说清楚比较好......

## 参考资料

- [HagiCode 项目地址](https://github.com/HagiCode-org/site)
- [OpenSpec 文档](https://docs.hagicode.com)
- [Handlebars 模板语法](https://handlebarsjs.com/)
- [Mermaid 图表语法](https://mermaid.js.org/)


## 原文与版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。
本内容采用人工智能辅助协作,最终内容由作者审核并确认。
- 本文作者: [newbe36524](https://www.newbe.pro)
- 原文链接: [https://docs.hagicode.com/go?platform=tencent-cloud-community&target=%2Fblog%2F2026-05-07-customizing-openspec-steps%2F](https://docs.hagicode.com/go?platform=tencent-cloud-community&target=%2Fblog%2F2026-05-07-customizing-openspec-steps%2F)
- 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

在使用 OpenSpec 管理技术提案时，我们遇到了 AI 生成文档质量不稳定的问题。其实也没别的办法，只能自己动手改提示词模板了。这篇文章就是那段日子的记录。

自定义 OpenSpec 步骤改进生成结果

后端开发工程师

人工智能

后端

开发工具

探索OpenSpec提示词优化实践，通过自定义模板改进AI生成文档质量。针对技术提案、设计文档等场景，提供明确的约束条件和可视化示例，确保生成内容包含流程图、架构图等关键元素。分享HagiCode项目中的实战经验，帮助开发者提升AI辅助文档生成效果。

单元测试

集成测试

数据流

JSON

2026采购季 | AI焕新·智启新局

ai-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

自定义 OpenSpec 步骤改进生成结果-腾讯云开发者社区-腾讯云

自定义 OpenSpec 步骤改进生成结果

自定义 OpenSpec 步骤改进生成结果

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐